#
# UNICORE XUUDB
#


Contents
********

1. Overview
2. XUUDB Server
3. Normal vs. DN mode
4. Clients for the XUUDB
5. Security
6. The admin client
7. Contact information


1. Overview
***********

The UNICORE XUUDB is a user authorisation component for UNICORE 6.

It is used to map user credentials (such as an X509 certificate or
X500 distinguished name) to authorisation attributes.  The attributes
are: a list of Unix logins, a role and a list of projects (which is used
to provide optional list of Unix groups).  The XUUDB stores either 
X509 certificates ('normal' mode) or distinguished names ('dn' mode), 
see section 3.

The XUUDB offers two web services, one for querying, and one for 
administration of the user database.

Multiple Grid sites can share the XUUDB, even if the attributes are
different per Grid site. Grid sites are grouped by the so-called GCID
(grid component ID).

Both admin and client access to the XUUDB is protected by 
client-authenticated SSL.


2. The XUUDB server
*******************

2.1) Configuration

By default, the configuration is defined in the file
"conf/xuudb_server.conf". Review the settings. To use a
different config file, edit the start script, or use
"--start <config_file>" as commandline arguments when
starting.

2.2) Starting the XUUDB server

Start the server with

  bin/start.sh

2.3) Stopping the server

Stop the server with

  bin/stop.sh
 
This sends a TERM signal to the xuudb process. Please do not "kill -9"
it, to avoid corrupting the database.

2.4) Logging

The logging settings are controlled in 'conf/logging.properties', and
changes to this file take effect at runtime.


3. Normal mode vs. DN mode
**************************

The XUUDB Database supports two mode, 'normal' and 'dn', controlled by
a setting in the server configuration file 'conf/xuudb_server.conf'.
Running in normal mode uses the whole x509 PEM encoded certificate of
the users to perform a match. This particularly means, if a user
certificate is not valid any more the user has to be readded with a
new certificate.  When running in dn mode, only the DN of the x509
certificate is stored in the database, so a user can access unicore
with a new certificate, if the DN is equal to the old one.

The admin tool has a command "adddn" which will add an XUUDB entry using
just the DN.

NOTE: when extracting the DN from a certificate file using OpenSSL,
make sure to use the "RFC2253" option, for example

  openssl x509 -in demouser.pem -noout -subject -nameopt RFC2253


4. Clients for the XUUDB
************************

4.1) Admin client (see also Section 6)

The admin client is used to add, remove, list and update certificates
and user information. It is configured in the file
conf/xuudb_client.conf To use the client, do

  bin/admin.sh <command> <options>

You can get detailed usage info by calling the admin script without
any options.

NOTE: to switch on the confirmation message asked by the "add"
command, edit the admin.sh script (so that the "xuudb.batch" property
is set to "false").

4.2) UNICORE 6

UNICORE 6 includes the XUUDB as default authorisation component.

4.3) UNICORE Rich client plugin

There is a plugin for the UNICORE Rich client that allows to edit the
XUUDB remotely.


5. Security
***********

5.1 Basic SSL
*************

Client-authenticated SSL is used to protect the XUUDB. Therefore you
will need certificates for the XUUDB and all Grid components that want
to talk to the XUUDB.  In general the XNJS and the XUUDB-admin need to
connect to the XUUDB-server. To grant them access, you have to put the
following certificates as trusted certs into the XUUDB's server
truststore:

- CA certificate(s) of the UNICORE/X server(s) that query the XUUDB
- CA certificate(s) of the XUUDB-admin user certificate(s)

5.2 Administrative access
*************************

The XUUDB provides two web service interfaces, one for querying the XUUDB 
(i.e. mapping certificates or DNs to user information), and a second
one for administration of the XUUDB (i.e. adding and editing entries).
All access to the XUUDB (including the admin.sh script!) is through these
web services. To prevent arbitrary Grid users from modifying the XUUDB, 
the administrative interface has to be protected. 

Starting with UNICORE 6.3, the access control mechanism
of the administrative interface has been simplified. An ACL file is used, 
which is a text file containing the distinguished names of the 
administrators. At least it has to contain the DN of the certificate used by 
the admin.sh script.

An example ACL file (conf/xuudb.acl) is part of the distribution, which
contains the DN of the default XUUDB server certificate.

The ACL file can be changed at runtime to easily add or remove administrators.

To change the location of the ACL file, edit the server
configuration and set a configuration parameter, e.g.:

  xuudb_acl_file=conf/xuudb.acl

The ACL entries are expected in RFC2253 format. To get the name 
from a certificate in the correct format using openssl, you can use the 
following OpenSSL command:

  openssl x509 -in demouser.pem -noout -subject -nameopt RFC2253

6. The admin client
*******************

The admin client is used to edit the XUUDB, using a web service interface.

6.1) Commands

 add         <gcID>  <pemfile>  <xlogin> <role> [project1[,project2[,...]]]
 adddn       <gcID>  <DN>  <xlogin> <role> [project1[,project2[,...]]]
 remove      ALL|gcID=x|pemfile=file|dn="DN"|role=x|xlogin=x|project=x
 list        gcID=x|pemfile=file|dn="DN"|role=x|xlogin=x|project=x
 update      <gcID> <pemfile or DN> gcID=x|pemfile=file|dn="dn"|role=x|xlogin=x|project=x
 export      <csv-file> [overwrite]
 import      <csv-file> [clearDB]
 check-cert  <gcid> <pemfile>
 check-dn    <gcid> <dn>
 --init      creates a new admin client configuration in ./conf if not existing


NOTE: when the server runs in dn mode you can use 'dn=' parameter for remove,
list and update

Common options:

gcID : the so-called "grid component ID" is used to group entries, and
          must match the setting in the UNICORE/X configuration file
          "uas.config".  For example if you have two systems with
          different user name mappings, you can handle both with a
          single XUUDB, since you can store two user name mappings for
          each certificate, by choosing a different gcID for both
          systems.
          When updating xuudb entries, the special gcid '*' can be used as
          wildcard for updating user entries on all systems.

pemfile : a file containing the public key in PEM format 

DN : the distinguished name of a user

xlogin : the UNIX login to map to. Multiple logins can be specified
using a ":"

role : The usual roles in UNICORE are "user" for a normal user, and
      "admin" for an administrator. Custom roles can be added, and can
      be assigned permissions in the UNICORE/X security policy file.

[project : currently unused ]


6.2) adding entries using "add" or (in DN mode) "adddn"

Example using a pem file:

$> ./bin/admin.sh add DEMO-SITE /path/to/usercert.pem userlogin user

Example using the DN (works only if server runs in DN mode):

$> ./bin/admin.sh adddn DEMO-SITE "CN=John Doe, O=Test Inc" userlogin user


6.3) checking the content

Apart from "list", you can use the "check-cert" and "check-dn"
commands to see what the XUUDB contains for a certain certificate or
DN.


6.4) removing entries

HINT: before removing you can check with the list command which takes
the same parameters, that your are removing the correct entries. 

To remove all entries from xuudb (you will have to confirm this)

$> ./bin/admin.sh remove ALL 

To remove some entries, you have to specify attributes

 - to remove a user with cert cert.pem at gcid MYSITE:
   $> ./bin/admin.sh remove gcid=id001 pemfile=/path/cert.pem

 - to remove all users from gcid OLDMACHINE
   $> ./bin/admin.sh remove gcid=OLDMACHINE

 - to removes user with xlogin jdoe from all gcids
   $> ./bin/admin.sh remove xlogin=jdoe

etc...


6.5) exporting/importing 

The export command creates a csv file, which will contain the complete
XUUDB database:

$> ./bin/admin.sh export uudb.csv

If the file already exists, the export tool will complain. To override
this, please specify the "overwrite" option, e.g.

$> ./bin/admin.sh export uudb.csv overwrite

The import command takes the a csv file (as generated by "export") and
imports all entries. Already existing entries will not be changed.  To
do updates, execute "admin.sh remove ALL" before, or specify "clearDB" as a second
argument

$> ./bin/admin.sh import uudb.csv


6.6) updating entries

The "update" command can be used to modify existing entries, for example to
replace the certificate or the login. For example,

$> ./bin/admin.sh update DEMO-SITE certs/demouser.pem xlogin=jb007

would update the entry identified by the gcID 'DEMO-SITE' and the given pem
file, and assign a new xlogin. If you want to update a user's entry on all 
the sites, you would use

$> ./bin/admin.sh update \* certs/demouser.pem xlogin=jb007

Note that the wildcard '*' is a special character for the shell and needs to be
escaped with a backslash.


7. CONTACT INFO
***************

Web:            http://www.unicore.eu
Mailing lists:  http://sourceforge.net/mail/?group_id=102081
