VOMS Usage Notes

VOMS stands for Virtual Organisation Management Service and is one of the most commonly used grid technologies needed to provide user access control to grid resources. It was originally developed for the EU DataGrid project. For complete information please refer to the EMI VOMS Web page. This manual is not a part of official VOMS documentation, but simple notes collected by users.

VOMS is a set of tools to assist authorisation of users based on their affiliation. A group of users united by some common goal, e.g., working on a same project, and requesting access to Grid resources, is often referred to as a Virtual Organisation (VO). In order to authorise them by group, VOMS keeps a database of users, providing information on the user's relationship with Virtual Organisations: membership, group attachments, roles and attributes. It also provides a set of tools to retreive and store such information.

You will need VOMS client tools if your access to various Grid resources is granted on the basis of your Virtual Organisation affiliation, and/or if your VO has a complex membership structure. Typically, VOMS clients are included in all Grid middleware distributions. ARC offers arcproxy command line tool (found in nordugrid-arc-client package) which performs most common operations like VOMS proxy creation and inspection. Native VOMS CLI voms-clients is available in many Linux distributions.

VOMS works with users that have valid grid certificates. It keeps databases of users grouped as Virtual Organizations (VOs). Such databases can be used by grid resource owners in order to authorise VO members at their resources. VOMS allows to create fine-grained VO structures that can be used to allocate different privileges to different users.

VOMS technology provides interfaces for users to apply for VO membership, for administrators to manage the users, and for other grid services to query stored information (user lists, roles etc).

Preliminary steps and VO membership application

Before starting using VOMS, make sure you have a valid personal grid certificate (see more details on grid security and certificates e.g. from NorduGrid or check the Grid Certificates Howto). Then proceed to the steps needed to use the VOMS Web interface:

  1. For convenience, you may want to define X509_USER_CERT and X509_USER_KEY to point to your certificate and key:
    export X509_USER_CERT=$HOME/.globus/usercert.pem
    export X509_USER_KEY=$HOME/.globus/userkey.pem
  2. Convert your Grid certificate to the PKCS #12 format accepted by Web browsers:
    openssl pkcs12 -export -in $X509_USER_CERT -inkey $X509_USER_KEY -out cert.p12
    This procedure will ask you for an export password -- pick any you like. Here cert.p12 is the name of new browser-ready certificate file (pick any name and location, but keep extension .p12 of .pfx).
  3. Load the PKCS #12 file (cert.p12 in the example above) into your favorite browser (use Security or Certificates menu or similar); you will have to enter the password you have set in Step 2. It is no longer needed.

You are now ready to apply for VO memberships via VOMS. Here are some relevant VOMS servers:

VOMS servers typically offer "New User Registration" from the menu; proceed there. Make sure you read and agree to the VO's Usage Rules and the Acceptable Use Contract, if such are available. If requested, please fill in your contact person name (e.g. site admin or research project leader) in the "comment" field.

You typically will receive an automatic e-mail that is meant to confirm validity of your e-mail address. Follow the link in the message, or instructions how to use the Web interface for validations.

Authorized VO manager will study your request and may contact you or your supervisor in order to make the judgement. You will be notified of the decision by e-mail. In case of a positive outcome, you will be able to access resources granted to the VO.

Usage: VOMS-extended proxies

Many grid services rely on VOMS extensions in user proxies in order to identify a user with a VO and to assess user privileges.

To request VOMS-extended proxy certificates one can make use of either the arcproxy or the voms-proxy-init commands. They have somewhat different syntax, and different versions may have slight variations in behaviour. Please always consult the respective man-pages when in doubt.

The commands try to be as similar as possible to the more familiar grid-proxy-init command and will produce regular grid proxy certificates if one fails to instruct it which VO to contact.

Before requesting a VOMS-extended proxy, the relevant VO should be specified in the VOMSesfile where each VO is listed on one row as:

"alias" "machine address" "tcp port" "host dn" "official vo name"

Here alias is any name you prefer to associate with the VO, machine address and tcp port is the VOMS server address and port, host dn is VOMS server subject (DN) as listed in its certificate (see Certificates How-to for details), and official vo name is the official name of the VO as defined at the server.

It is advised to have alias the same as official vo name: several VOMS client versions mix them.

You can specify more than one line with the same alias. Both clients will load balance between servers in that case and will try another server if one fails.

Usually vomses string can be found in the "Configuration" section of VOMS-Admin interface labeled as "VOMSES string for this VO"

Default system-wide VOMSes file is /etc/vomses. When using an ARC arcproxy client user configuration of VOMSes could be saved into $HOME/.voms/vomses or $HOME/.arc/vomses or redefined with $X509_VOMSES environmental variable.

Native VOMS clients use $HOME/.voms/vomses so this is a prefered path to get both clients operational.

VOMSes file example

You can download an example working vomses file listed below:

"" "" "15050" "/O=dutchgrid/O=hosts/" ""
"pamela" "" "15013" "/C=IT/O=INFN/OU=Host/L=CNAF/" "pamela"
"desy" "" "15104" "/O=GermanGrid/OU=DESY/CN=host/" "desy"
"atlas" "" "15001" "/DC=ch/DC=cern/OU=computers/" "atlas"
"" "" "15015" "/O=Grid/O=NorduGrid/CN=host/" ""
"" "" "15002" "/C=IT/O=INFN/OU=Host/L=CNAF/" ""
"" "" "15002" "/C=IT/O=INFN/OU=Host/L=CNAF/" ""
"playground" "" "15002" "/O=Grid/O=NorduGrid/CN=host/" ""

Credentials verification

VOMS client versions v1.8.4 and higher require VOMS server credentials to be installed as well as arcproxy tool. Such credentials are used to verify the digital signature of VOMS server that sign your proxy.

There are two relevant pathes that affect credentials verification:

You may want to redefine defaults to have your own independent configuration within your home directory:

mkdir $HOME/.vomsdir
export X509_CERT_DIR=$HOME/nordugrid-arc-standalone/share/certificates
export X509_VOMS_DIR=$HOME/.vomsdir

You can find instructions how to create X509_VOMS_DIR content below (see Configuring trusted VOMS servers).

CA certificates directory usually contains IGTF distribution. In case you are using non-IGTF certificate authorities, you may want to cross-check that you have installed CA certificates of the VOMS server you are going to use, especially for very new or test-level VOMS servers.

You also may want to confirm that the VOMS server has your CA credentials installed in turn. There is no automatic way to check this, apart of try-and-fail or human communication with user support team or VOMS server administrator.

Usage examples

When using client commands, you may get the following message:
WARNING: Unable to verify signature! Server certificate possibly not installed.
This is a harmless warning, and should not occur if you made all configuration steps described above.

Configuring trusted VOMS servers

Historically the first method of VOMS server signature verification was based on forehanded retrieval of servers' public keys.

Method of server public keys retrieval is now obsolete and UNSUPPORTED since ARC 1.0.0! You should use LSC files instead.

The actual method of trusted VOMS servers configuration is the Lists of Certificates (LSC). The purpose of the LSC is to describe the trust chain from Certificate Authority (CA) to the VOMS server. Then server signature in clients' proxies verified in accordance with the trust chain.

Generally, VOMS server certificate is signed by CA directly, so there are only two certificates in the chain of trust, but it can be much longer in other cases.

LSC files has the following format. Each line of the file lists a single certificate DN starting from the VOMS server and continues up the trust chain ending with the root CA certificate DN.

Example LSC file for server:

/O=Grid/O=NorduGrid/CN=NorduGrid Certification Authority

To get a trust chain DNs for the VOMS server you can contact the VO manager or use openssl for known VOMS servers:

echo | openssl s_client -connect <server:port> 2>/dev/null \
| openssl x509 -noout -subject -issuer

You can also find information about VOMS servers that supports VOs registered in EGI at the EGI Central Operations Portal(look for the "VOMS information" section at the "VO info" page for VO you are interested for).

Here <server> is the host name of the VOMS server (as in vomses configuration), and <port> is typically the standard VOMS https interface port 8443 (port listed in vomses file can also be used).

The default location of VO's LSC files for ARC (compatible with other EMI software default setup) is:


NOTE: For ARC 11.05 location of LSC files is fixed to default and cannot be redefined with X509_VOMS_DIR!

Server side setup

A-REX provides several configuration methods that rely on VOMS proxies:

VOMS proxies cannot be properly used without signature verification. As like client configuration, LSC files are used to configure trusted VOMS servers. Refer Configuring trusted VOMS servers part of this notes to find how to create LSC files.

Another A-REX-specific way to configure trust chains without creation of LSC files per each VOMS server is to define a voms_trust_chain configuration option that is designed to contain information about all trusted issuers in one place. This approach will be much useful with A-REX standalone installation that provide resources for a few VOs. In contrast, LSC files based solution is more scalable and compatible with other EMI software.

This option should be specified in [common] configuration block or redefined in [grid-manager] and/or [gridftpd] blocks:

voms_trust_chain="/O=Grid/O=NorduGrid/CN=host/" "/O=Grid/O=NorduGrid/CN=NorduGrid Certification Authority"
voms_trust_chain="/O=Grid/O=NorduGrid/CN=host/" "/O=Grid/O=NorduGrid/CN=NorduGrid Certification Authority"

NOTE! The voms_trust_chain option will override the information in the LSC files if it is defined.

Unlike LSC files, voms_trust_chain option support regular expressions syntax.

More information about A-REX configuration with VOMS proxies can be found in the ARC Computing Element System Administrator Guide

Map VO members to local account

The information from the VOMS server should also be used to implement VO-based user mapping in the arc.conf file or analogous configuration file of other grid middleware. Typically, the necessary contact strings are available via "Configuration Information" option in the VOMS Web interface. Different mapping utilities use such contact strings in slightly different manner; below are some examples for ARC.

In the file /etc/arc.conf, inside [vo] blocks, one can then use the following constructions to map entire VO, a group or a role to a local user account:

#get all members of VO
#get all members of VO that are members of the group testers
#get all members of VO that have the role VO-Admin

Note that e.g. the group "testers" should be written / even though some might construe this as an unnecessary redundancy.

Example of some useful [vo] blocks making use of VOMS are such:




Make sure there are no more than one block with a given id!

To test your configuration, run

nordugridmap --test
NorduGrid homepage