NORDUGRID-MEMO-12

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 to resources. It was originally developed for the EU DataGrid project, and for complete information refer to the 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 capabilities. 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 a 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 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 a new password - pick any you like. Here cert.p12 is the name of new browser-ready certificate (pick any name and location, but keep extension .p12).
  3. Load the result (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 set in Step 2.

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 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. VOMS provides a special tool that creates VOMS-extended proxy certificates.

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

The commands try to be as similar as possible to the more familiar grid-proxy-init 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 file $HOME/.voms/vomses 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.

VOMS client versions v1.8.4 and higher require VOMS server credentials to be installed. There are two ways of doing this: either download the public key of your VOMS server, or create a special file containing server's DN and its CA DN. The step by step procedure follows:

The last example may be preferrable for many, because DNs change much less frequently than certificates. Some VOs provide ready .lsc files.

vomses file example

Download a working vomses file (save as $HOME/.voms/vomses when using an ARC client, or $HOME/.glite/vomses when using a gLite UI).
"gin.ggf.org" "kuiken.nikhef.nl" "15050" "/O=dutchgrid/O=hosts/OU=nikhef.nl/CN=kuiken.nikhef.nl" "gin.ggf.org"
"pamela" "voms.cnaf.infn.it" "15013" "/C=IT/O=INFN/OU=Host/L=CNAF/CN=voms.cnaf.infn.it" "pamela"
"desy" "grid-voms.desy.de" "15104" "/O=GermanGrid/OU=DESY/CN=host/grid-voms.desy.de" "desy"
"atlas" "voms.cern.ch" "15001" "/DC=ch/DC=cern/OU=computers/CN=voms.cern.ch" "atlas"
"nordugrid.org" "voms.uninett.no" "15015" "/O=Grid/O=NorduGrid/CN=host/voms.ndgf.org" "nordugrid.org"
"testers.eu-emi.eu" "emitestbed07.cnaf.infn.it" "15002" "/C=IT/O=INFN/OU=Host/L=CNAF/CN=emitestbed07.cnaf.infn.it" "testers.eu-emi.eu"
"testers.eu-emi.eu" "emitestbed01.cnaf.infn.it" "15002" "/C=IT/O=INFN/OU=Host/L=CNAF/CN=emitestbed01.cnaf.infn.it" "testers.eu-emi.eu"
"playground" "arthur.hep.lu.se" "15002" "/O=Grid/O=NorduGrid/CN=host/arthur.hep.lu.se" "playground.knowarc.eu"

Usage examples

When using voms-proxy- 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 steps above.

Server side setup

In order to identify VOs system wide they should be listed in the file /etc/vomses. Each VO should be written on one line in the format (download an example vomses file):

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

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

You have to make sure that certificates of trusted VOMS servers are installed in /etc/grid-security/vomsdir (preferably,named by their hashes, for backward compatibility). If you happened to get the certificate file named differently, rename it to its hash as displayed by

openssl x509 -in cert-filename -hash -noout

appended with the suffix of .0, e.g. 96a311cb.0. If you use a reasonably new VOMS client, certificates can have any name.

Currently, there is no easy way to obtain such certificates, except of asking VO managers. Some VOMS Admin Web interfaces can be helpful, but not older versions. From the NorduGrid Web site you can get the following VOMS server certificates:

Please note that this is not an official source of these certificates! Please always contact the respective VO managers to obtain the latest certificates. In particular, WLCG VOMS server (ATLAS, ALICE etc) certificates are distributed as lcg-vomscerts package with gLite.

If you are desperate still, there is a way to get any certificate as long as you know server address. The procedure has three steps: fetch the certificate, calculate its hash, copy it with the correct name to /etc/grid-security/vomsdir, as shown below.

openssl s_client -CApath /etc/grid-security/certificates -status -cert $X509_USER_CERT -key $X509_USER_KEY \
-connect <server:port> 2>/dev/null | openssl x509 > tmp.0
openssl x509 -in tmp.0 -noout -hash
mv tmp.0 /etc/grid-security/vomsdir/<hashvalue>.0

Here <port> is typically the standard VOMS https interface port, 8443 (port listed in vomses file can also be used).

Note that you may place VOMS server certificates in any arbitrary place, provided it is defined in the X509_VOMS_DIR environment variable

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 midlewares. Typically, the necessary contact strings are available via "Configuration Information" option in VOMS Web interface. Different mapping utilities use such contact srtings in slightly different manner; below are some examples for ARC:

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

source="vomss://arthur.hep.lu.se:8443/voms/knowarc.eu" #get all members of vo knowarc.eu
source="vomss://arthur.hep.lu.se:8443/voms/knowarc.eu?/knowarc.eu/testers" #get all members of vo knowarc.eu that are members of the group testers
source="vomss://arthur.hep.lu.se:8443/voms/knowarc.eu?/knowarc.eu/Role=VO-Admin" #get all members of vo knowarc.eu that have the role VO-Admin

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

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

[vo]
id="vo_1"
vo="nordugrid.org"
source="vomss://voms.ndgf.org:8443/voms/nordugrid.org"
mapped_unixid="griduser"
file="/etc/grid-security/grid-mapfile"

[vo]
id="vo_3"
vo="testers.knowarc.eu"
source="vomss://arthur.hep.lu.se:8443/voms/knowarc.eu?/knowarc.eu/testers"
mapped_unixid="tester"
file="/etc/grid-security/grid-mapfile"

[vo]
id="vo_5"
vo="admin.knowarc.eu"
source="vomss://arthur.hep.lu.se:8443/voms/knowarc.eu?/knowarc.eu/Role=VO-Admin"
mapped_unixid="master"
file="/etc/grid-security/grid-mapfile"

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

To test your configuration, run

nordugridmap --test
NorduGrid homepage