VOMS Admin 2.7.0 User's guide

Introduction

The VOMS Admin service is a web application providing tools for administering member databases for VOMS, the Virtual Organization Membership Service.

VOMS serves as a central repository for user authorization information, providing support for sorting users into a general group hierarchy, keeping track of their roles, etc.

VOMS Admin provides an intuitive web user interface for daily administration tasks, and a SOAP interface for remote clients. The Admin package includes a simple command-line SOAP client that is useful for automating frequently occurring batch operations, or simply to serve as an alternative to the full-blown web interface. It is also useful for bootstrapping the service.

Installation

VOMS server

Detailed installation instructions can be found in the VOMS System administrator's guide:

https://wiki.italiangrid.it/twiki/bin/view/VOMS/VOMSSystemAdministratorGuide

VOMS admin client

To install the voms-admin-client package, just type:

yum install voms-admin-client

having the EMI 2 repository in place.

Installing, upgrading and configuring VO instances

For general use cases that leverage the YAIM configuration tool, see the

https://wiki.italiangrid.it/twiki/bin/view/VOMS/VOMSSystemAdministratorGuide

If you want to use directly the voms-admin-configure utility to configure your VOs read ahead.

Creating a new VO

MySQL VO Configuration

The MySQL VO installation procedure depends on whether a MySQL database has already been created for you by you MySQL administrator or you want to create it when configuring VOMS for the first time.

Usually, you do not have a dedicated MySQL administrator working for you,so you will use voms- admin tools to create the database schema, configure the accounts and deploy the voms database. If this is the case, you need to run the following command:

voms-admin-configure install --dbtype mysql 
--vo <vo name> 
--createdb 
–deploy-database  
--dbauser <mysql root admin  username>
--dbapwd <mysql root admin  password>
--dbusername <mysql voms username>
--dbpassword  <mysql voms password>
--port <voms core service port>
--smtp-host <STMP relay host>
--mail-from <Sender address for service-generated emails>

Note that the above command is entered as a single command; it has been broken up into multiple lines for clarity. The command creates and initializes a VOMS database, and configures the VOMS core and admin services that use such database. The required options are described below:

Option name	Meaning
dbauser, dbapwd	These options are MySQL specific and are used to set the MySQL root user account username and password respectively. These credentials are needed to create the MySQL database for VOMS, and thus required when the createdb option is set. If MySQL is configured with an empty password for the root account, the dbapwd option may be omitted.
dbusername, dbpassword	These options are used to specify the MySQL account that VOMS will use when contacting the database. If the createdb option is set, voms-admin creates the account for you.
mail-from, smtp-host	These options specify, respectively, the address that must be used for service-generated emails and the SMTP service that must be used to send them.
createdb	This option is MySQL specific and is used to specify that the MySQL database for VOMS must be created by the script.
port	This option specifies on which port the VOMS core server will listen for requests.
deploy-database	This option tells the script that it must create the tables for VOMS and fill in the necessary bootstrap information (e.g., admin accounts, supported CAs, ...)

An example MySQL VO installation command is shown below:

/usr/sbin/voms-admin-configure install --dbtype mysql \ 
--vo test_vo_mysql --createdb --deploy-database \ 
--dbauser root --dbapwd pwd \ 
--dbusername voms_admin_20 --dbpassword pwd \ 
--port 54322 --mail-from ciccio@cnaf.infn.it \ 
–smtp-host iris.cnaf.infn.it

Oracle VO Configuration

Oracle VO configuration is different from MySQL configuration. In Oracle you need to setup the database account for VOMS before launching voms-admin configure. Moreover, Oracle instant client libraries must be installed and configured before running voms-admin configuration.

Once you have configured Oracle stuff, you can install a new Oracle VO using the following command:

voms-admin-configure install --dbtype oracle 
--vo <VO name> 
--dbname <TNS alias of the database backend> 
--deploy-database
--dbusername <voms db account username> 
--dbpassword <voms db account password> 
--port <voms core service port> 
--smtp-host <SMTP relay host> 
--mail-from <Sender address for service-generated emails>

Note that the above command is entered as a single command; it has been broken up into multiple lines for clarity. This command is indeed very simliar to the one used to configure a MySQL VO. The main difference lies in the dbname option, that is used to specify the TNS alias for the Oracle database backend. This TNS alias is needed to build the connection string that VOMS will use to communicate with the database backend.Usually, TNS aliases are maintained in the tnsnames.ora file, located in a directory that is usually exported to applications via the TNS_ADMIN Oracle environment variable. For more information regarding TNS aliases, consult the Oracle online documentation (http://www.oracle.com/pls/db102/homepage).

An example Oracle VO installation command is shown below:

voms-admin-configure install --dbtype oracle \ 
--vo test_vo --dbname test --deploy-database \ 
--dbusername voms_admin_20 --dbpassword pwd \ 
--dbhost datatag6.cnaf.infn.it --port 54321 \ 
--mail-from ciccio@cnaf.infn.it --smtphost iris.cnaf.infn.it

Deploying the database

When configuring a VO for the first time on a machine, voms-admin-configure by default tries to deploy the database, unless the skip-database option is set. Before overwriting tables and information, voms-admin-configure checks whether an existing VOMS database is already deployed. In case one is found, a warning is issued and the database is not touched by the installation procedure.

Starting up the VOMS core service

After a succesful configuration, you can start the VOMS core service by typing the following command:

/etc/init.d/voms start

Deploying the VOMS Admin service

You can deploy the just configured VO to Tomcat by typing the following command:

/etc/init.d/voms-admin start

(If you have created other VOs and want to start only one of them, list the VO name to start at the end of the command.)

Provided that Tomcat is running, you should now have a VOMS Admin service deployed, and ready to serve requests. If you forgot to start Tomcat, do it now. You do not need to type in the above command again unless you explicitly undeploy the service later, or create new VOs. Tomcat will automatically remember to run your VOMS Admin service across server reboots.

The recommended way to start and stop VOMS Admin

Adding yourself as a VO administrator

VOMS-Admin provides two ways of adding yourself as an administrator for VO. You can either add yourself as a VO user and assign to yourself the VO-Admin role, or use the voms-db-deploy.py command to interact directly with the voms database.

Using the voms-db-deploy.py script

In case you have root access on the machine where you are configuring VOMS/VOMS-Admin, you can use the voms-db-deploy.py command to add yourself as administrator.

/usr/sbin/voms-db-deploy.py add-admin 
--vo <VO name> 
--cert <certificate>

Using the VOMS Admin client

In case the VO is already active, you can add yourself as an administrator using the voms-admin comand:

voms-admin --vo <VO name> create-user <certificate> assign-role VO VO-Admin

where VO name is the name of one of the VO you have configured, and certificate is an X509 certificate in PEM format.

Upgrading an existing VO

The upgrade of a VO is needed in order to migrate existing VOMS Admin 1.2.19 or 2.0.18 installations to the 2.5 version.

In order to upgrade an existing 1.2.19 or 2.0.18 installation, one has to launch the command:

voms-admin-configure upgrade --vo  <VO name>

The upgrade affects both configuration files and database structure, so be sure to backup the contents of the database before running the upgrade procedure. You can do the upgrade of the configuration files (without touching the database) by giving the --skip-database option:

voms-admin-configure upgrade --vo test_vo --skip-database

The database can be upgraded afterwards using the voms-db-deploy.py command, issuing a command like:

voms-db-deploy.py deploy --vo <VO name>

Testing the service

To test wheter the voms-admin service is active for your VO, you can point your browser to the following URL:

https://<voms-admin server hostname>:8443/voms/<VO name> 

To get a list of all the VOs configured on the host, use the following URL:

https://<voms-admin server hostname>:8443/vomses

Note that you must have a suitable certificate already imported in your browser to access the voms- admin interface.

The VOMS Admin authorization framework

In VOMS-Admin, each operation that access the VOMS database is authorized via the VOMS-Admin Authorization framework. For instance, only authorized admins have the rights to add users or create groups for a specific VO.

More specifically, Access Control Lists (ACLs) are linked to VOMS contexts to enforce authorization decisions on such contexts. In this framework, a Context is either a VOMS group, or a VOMS role within a group. Each Context as an ACL, which is a set of access control entries, i.e., (VOMS Administrator, VOMSPermission) couples.

A VOMS Administrator may be:

• A VO administrator registered in the VO VOMS database;
• A VO user;
• A VOMS FQAN;
• Any authenticated user (i.e., any user who presents a certificate issued by a trusted CA).

A VOMS Permission is a fixed-length sequence of permission flags that describe the set of permissions a VOMS Administrator has in a specific context. The following table explains in detail the name and meaning of these permission flags:

• CONTAINER_READ, CONTAINER_WRITE: These flags are used to control access to the operations that list/alter the VO internal structure (groups and roles list/creations/deletions, user creations/deletions).
• MEMBERSHIP_READ, MEMBERSHIP_WRITE: These flags are used to control access to operations that manage/list membership in group and roles.
• ATTRIBUTES_READ,ATTRIBUTES_WRITE: These flags are used to control access to operations that mange generic attributes (at the user, group, or role level).
• ACL_READ,ACL_WRITE,ACL_DEFAULT: These flags are used to control access to operations that manage VO ACLs and default ACLs.
• REQUESTS_READ, REQUESTS_WRITE: These flags are used to control access to operations that manage subscription requests regarding the VO, group membership, role assignment etc...
• PERSONAL_INFO_READ, PERSONAL_INFO_WRITE: The flags are used to control access to user personal information stored in the database.
• SUSPEND: This flag controls who can suspend other users.

Each operation on the VOMS database is authorized according to the above set of permissions, i.e., whenever an administrator tries to execute such operation, its permissions are matched with the operation's set of required permission in order to authorize the operation execution.

ACL inheritance and default ACL

Children groups, at creation time, inherit parent's group ACL. However, VOMS Admin implements an override mechanims for this behaviour via Default ACLs. When the Default ACL is defined for a group, children groups inherit the Default ACL defined at the parent level instead of the parent's group ACL. So, Default ACLs are useful only if an administrator wants the ACL of children groups to be different from the one of the parent's group.

VOMS Administrative operations and required permissions

In the following, we describe the required permissions for the most comon voms-admin operations according to this notation:

Symbol	Meaning
/vo	The VO root group
(g,R)	The context identified by role R within group g
(g ➝ g')	All the voms groups that lie in the path from group g to group g' included according to the parent-child relationship defined between voms groups
parent(g)	Group g's parent group
r,w,d,s	Read permission, Write permission, default permission (applies only to ACL permissions), suspend permission
C:, M:, Attrs:, Acl:, Req:, PI:	Container, Membership, Attributes, ACL, Requests and Personal Information permissions short names

The table below lists operations on the left and required permissions on the right, expressed in the form of (VOMSContext, VOMSPermission) couples.

Operation	Required permissions	Explanation
Create/delete user	(/vo,C:rw M:rw)	Container and membership read and write access on the root group
Create/delete group g	(/vo,C:rw) , (/vo → parent(parent(g)), C:r) , (parent(g), C:rw)	Container rw access on the root group, container read access on all to groups leading to g's parent group and Container rw access in g's parent group
List group g subgroups	(/vo → g, C: r)	Container read access on all the groups leading to g
Create/delete role	(/vo, C:rw)	Container read/write access on the VO root group
List VO roles	(/vo, C:r)	Container read access on the VO root group
Add remove/member to group g	(/vo → parent(parent(g)), C:r), (g, M:rw)	Container read access on all the groups leading to g's parent, and Membership rw access on g
List group g members	(/vo → parent(parent(g)), C:r), (g, M:r)	Container read access on all the groups leading to g's parent and Membership read access on g
Assign/dismiss role R in group g	(/vo → parent(parent(g)), C:r), ((g,R), M:rw)	Container read access on all the groups leading to g's parent and Membership rw access on role R within g
List members wirh role R in group g	(/vo → parent(parent(g)), C:r), ((g,R), M:r)	Container read access on all the groups leading to g's parent and Membership read access on role R within g
Set/delete user generic attribute	(/vo, Attrs:rw)	Attribute rw access on the VO root group
List user generic attributes	(/vo, Attrs: r)	Attribute read access on the VO root group
List group g generic attributes	(/vo → parent(parent(g)), C:r), (/vo, Attrs:r), (g, Attrs:r)	Container read access on all the groups leading to g's parent, Attributes read access on the VO root group and on group g
Set/delete group g attributes	(/vo → parent(parent(g)), C:r), (/vo, Attrs:rw), (g, Attrs:rw)	Container read access on all the groups leading to g's parent, Attributes read access on the VO root group and on group g
Set/delete role R attributes within group g	(/vo → parent(parent(g)), C:r), (/vo, Attrs:rw), ((g,R), Attrs:rw)	Container read access on all the groups leading to g's parent, Attributes rw access on the VO root group and on role R withing g
Edit ACL for group g	(/vo → parent(parent(g)), C:r), (g, ACL:rw)	Container read access on all the groups leading to g's parent, ACL rw access on group g
List ACL for group g	(/vo → parent(parent(g)), C:r), (g, ACL:r)	Container read access on all the groups leading to g's parent, ACL read access on group g
Suspend a user	(/vo, s)	Suspend flag on the VO root group

The VOMS Admin web application

The VOMS-Admin web application provides a usable and intuitive interface towards VO management tasks. A screenshot of the main page of the web application is given above.

In the top part of the page, the header provides information about the current user accessing the interface and the name of the VO that is being managed. The two navigations bars provide access to the main sections of the web application.

The Home page

By clicking on the home link in the main navbar one can reach his home page.

The Administrator home page

If the current client has administrator rights, he/she will be directed to the admins home page. User requests for membership and group/role assignments can be managed from this page, as shown in the image below.

An administrator that is also a VO user will have a link to his user home page in the upper right part of the page.

The VO user home page

The VO user home page shows information about the user membership. From this page, the user can request group membership and role assignment and update his personal information. The page also shows information about AUP acceptance records and an history record of user's requests.

Requesting the addition of a new certificate to the membership

VO members can request the addition of a new certificate to their membership by clicking on the "Request new certificate" button in the Certificates panel, as shown in the picture below:

The member can upload a PEM encoded certificate or type its certificate subject and select the CA subject from the certificate request page, pictured below:

The certificate subject should be entered following the usual /-separated openssl rendering, like in:

/C=IT/O=INFN/OU=Personal Certificate/L=CNAF/CN=Andrea Ceccanti

After this step a notification is sent to the VO admin who has to approve the member's request. The user will be informed via email of the VO admin decision on the request.

Managing users

The user management section of the VOMS-Admin web interface allows administrators to manage all the information regarding VO membership, i.e., membership status, certificates, groups, roles, generic attributes etc.

Suspending users

It is now possible to suspend users. Suspended users will still be part of the VO, but will not be able to obtain VOMS attribute certificates from the VOMS server.

When suspending a user a reason for the suspension must be given. This reason will be included in a supension notification that will be sent to the user, and shown at voms-proxy-init time to suspended users that attempt to get a VOMS proxy.

ACL Management

The ACL link the navigation bar leads to the ACL management page. The ACL management pane displays ACL entries in the form of (Voms Administrator, Set of permissions) couples. The display uses the compact representation for VOMS permissions that has been already introduced earlier.

Adding access control entries

ACL entries can be added to ACL or default ACLs by clicking on the “add entry” link. Permissions can be set for:

• VO users;
• non VO users;
• Anyone having a specific role within a specific group;
• Anyone belongin to a specific VO group;
• Any authenticated user, i.e., everyone with a certificate issued by a trusted CA

Entries added to a group ACL can be propagated to existing context's ACLs by ticking the “Propagate to children context” tick box at the bottom of the page. Similarly, when editing or deleting an ACL entry from a group ACL, it is possible to propagate the deletion or editing to children groups by selecting the “Propagate to children context" tick box.

Managing VOMS generic attributes

Generic attributes (GAs) are (name, value) pairs that that can be assigned to VO users and that end up in the Attribute Certificate issued by VOMS. GAs extend the range of attributes that VOMS can issue besides Fully Qualified Attributes Names (FQAN), i.e., allow VOMS to issue any kind of VO membership information that can be expressed as (name, value) pairs. Such information can then be leveraged by Grid applications to take authorization decisions.

For their nature, GAs are issued to VO users. VOMS however provides a way to quickly assign GAs to all the VO members that belong to a specific VOMS group or that are assigned a specific VOMS role within a group. For this reason, you find GA management in user, group and role management pages in VOMS Admin.

To assign GA to users, the VO admin must first create the corresponding Generic Attribute class. This Generic Attribute class is used to define the name and possibly a description for the GA. VOMS Admin also implements a configurable uniqueness check on GA values that can be set when creating a GA class. This uniqueness check ensures that two users cannot share the same value for a specific GA. This check is enforced at the GA class level, so you can have GAs that are checked for uniqueness and others that allow users to share the same value for the same GA.

Generic Attribute classes management

The GA classes management page can be reached by clicking on the “Attributes” link in the navbar, and then clicking on the “Manage attribute classes” link. GA classes can then be created, specifying the GA name, description and whether uniqueness must be enforced on the GA values assigned directly to users.

Managing GAs at the user, group and role level

Once a GA class has been created, GA values can be assigned to users, groups and role within groups. As mentioned above, when one GA is assigned directly to a user, the (name,value) couple is added by VOMS to the attribute certificate returned to user. When a GA is assigned to a group, or role within a group, such (name, value) pair ends up in the Attribute Certificate of all the VO members belonging to that group (or that have such role within a group).

Search GA assignments

VOMS Admin implements search over user GA assignments, so that an administrator can easily know the status of GA assignments. The search functions deal only with GA assigned directly to user, i.e., group and role assignements search and centralized display is currently not supported.

Acceptable Usage Policies (AUP) management

Starting with version 2.5, VOMS Admin implements AUP management. AUP acceptance records are linked to each VO membership, to keep track of which version of the AUP was accepted and when.

Each AUP in VOMS Admin has a reacceptance period. Each user's acceptance record is checked against this period and if the record has expired the user is requested to sign again the AUP.

When the user fails to sign the AUP in the allotted time, he/she is suspended.

Finally, VOMS admin provides the possibility to request re-acceptance from users at any time.

How to disable AUP management

AUP management can be disabled by disabling the VOMS Admin registration service. To disable the registration service add the --disable-webui-requests flag when configuring a VO with the voms-admin-configure command, or put the following setting:

voms.request.webui.enabled = false

in the /etc/voms/<vo_name>/voms.service.properties.

AUP management page

From the AUP management page is possible to add/remove new versions of the AUP, update the AUP reacceptance period, set which of the managed version is the active one (i.e., the one presented to VO users at signing time) and request reacceptance of the current version from users.

For VOMS Admin basically an AUP is the URL of a text file, so any file on the local filesystem or on a remote web server can be used for the AUP text.

Setting the VO AUP url at VO configuration time

The voms-admin-configure --vo-aup-url option can be used to set the URL for the initial version of the VO acceptable usage policy. If this option is not set a template vo-aup file will be created in vo runtime configuration directory

 /etc/voms-admin/<vo-name>/vo-aup.txt

The Configuration Info section

The Configuration info section shows configuration information useful for voms clients, like the vomses string for the VO or a mkgridmap example configuration.

The Other VOs section

This section provides links to the other VOs configured on the server.

The VOMS Admin command line utilities

The VOMS Admin command line client

VOMS Admin comes with a python command line client utility, called voms-admin, that can be used to perform most of the operations on the VOMS database that are implemented by the Web interface.

voms-admin uses the UNIX effective user ID to choose which X509 credential it must use to connect to a (possibly remote) VOMS Admin instance. When ran as root, voms-admin uses the host credentials found in /etc/gridsecurity.

When running as a normal user, voms-admin does the following:

• if the X509_USER_PROXY environment variable is set, voms-admin uses the credentials pointed by such environment variable,
• otherwise If a proxy exists in /tmp, the proxy is used,
• otherwise if the X509_USER_CERT environment variable is set, voms-admin uses the credentials pointed by X509_USER_CERT and X509_USER_KEY environment variables,
• otherwise the usercert.pem and userkey.pem credentials from the $HOME/.globus are used.

A user can get the list of supported commands by typing:

voms-admin --list-commands

The output will be something like:

Supported commands list:

ROLE ASSIGNMENT COMMANDS:

  assign-role
  dismiss-role
  list-users-with-role
  list-user-roles

ROLE MANAGEMENT COMMANDS:

  list-roles
  create-role
  delete-role

ATTRIBUTE CLASS MANAGEMENT COMMANDS:

  create-attribute-class
  delete-attribute-class
  list-attribute-classes

GROUP MEMBERSHIP MANAGEMENT COMMANDS:

  add-member
  remove-member
  list-members

USER MANAGEMENT COMMANDS:

  list-users
  create-user
  delete-user

ACL MANAGEMENT COMMANDS:

  get-ACL
  get-default-ACL
  add-ACL-entry
  add-default-ACL-entry
  remove-ACL-entry
  remove-default-ACL-entry

GENERIC ATTRIBUTE ASSIGNMENT COMMANDS:

  set-user-attribute
  delete-user-attribute
  list-user-attributes
  set-group-attribute
  set-role-attribute
  delete-group-attribute
  list-group-attributes
  list-role-attributes
  delete-role-attribute

GROUP MANAGEMENT COMMANDS:

  list-groups
  list-sub-groups
  create-group
  delete-group
  list-user-groups

Detailed help about individual commands can be obtained issuing the following command:

voms-admin --help-command <command name>

The help message contains examples for typical use cases. For example, asking help about the create-user command produces the following output:

macceccanti:~ andrea$ voms-admin --help-command create-user

create-user CERTIFICATE.PEM
	
        Registers a new user in VOMS. 
        
        If you use the --nousercert  option, then four parameters are 
        required (DN CA CN MAIL) to create the user. 
        
        Otherwise these parameters are extracted automatically from the
        certificate. 
        
        Examples: 
        
        voms-admin --vo test_vo create-user .globus/usercert.pem 
        
        voms-admin --nousercert --vo test_vo create-user \ 
        'My DN' 'My CA' 'My CN' 'My Email'

A user can get help about all the commands provided by voms-admin by typing:

voms-admin --help-commands

The voms-admin-configure script

voms-admin-configure is the script used to configure voms-admin and voms. Its usage has already been introduced in Section 2.2. The syntax of the command is:

voms-admin-configure COMMAND [OPTIONS]

Available commands are:

• install: is used to configure a VO
• remove: is used to unconfigure a VO
• upgrade: is used to upgrade the configuration of a VO installed with an older version of voms-admin.

Installation commands have already been covered here.

Removing a VO

To remove an already configured VO, type:

voms-admin-configure remove --vo VONAME

Available options are:

option name	meaning
undeploy-database	Undeploys the VOMS database. By default when removing a VO the database is left untouched. All the database content is lost.
dropdb (MySQL only)	This flag is used to drop the mysql database schema created for MySQL installations using the --createdb option

The voms-db-deploy.py command

The voms-db-deploy.py command is used to manage the deployment of the VOMS database and to add/remove administrators without requriing voms-admin VOs to be active.

[root@emitestbed18 ~]# voms-db-deploy.py 

Usage:
    
voms-db-deploy.py deploy --vo [VONAME]
voms-db-deploy.py undeploy --vo [VONAME]
voms-db-deploy.py upgrade --vo [VONAME]

voms-db-deploy.py add-admin [--ignore-cert-email] --vo [VONAME] --cert [CERT_FILE]
voms-db-deploy.py add-admin --vo [VONAME] --dn [ADMIN_DN] --ca [ADMIN_CA] --email [EMAILADDRESS]

voms-db-deploy.py remove-admin --vo [VONAME] --cert [CERT_FILE]
voms-db-deploy.py remove-admin --vo [VONAME] --dn [ADMIN_DN] --ca [ADMIN_CA]

voms-db-deploy.py check-connectivity --vo [VONAME]

voms-db-deploy.py grant-read-only-access --vo [VONAME]

The init-voms-admin.py command

The init-voms-admin.py (linked by the /etc/init.d/voms-admin) command is used to start, stop and check the status of configured VOs.

Usage:
    init-voms-admin.py [--context=CONTEXT_FILE] [--use-manager] start [VONAME]
    init-voms-admin.py [--use-manager] (stop|reload|status) [VONAME]
    init-voms-admin.py [--use-manager] (start-siblings|stop-siblings)
    
    VONAME is the name of the vo. 
    CONTEXT_FILE is a a file that contains the web application context descriptor
    use-manager uses of the tomcat manager application to manage vo apps.
    
    The start-siblings and stop-siblings commands are used to start/stop the 
    siblings webapp indipendently from other vos.

-- AndreaCeccanti - 2012-07-12