This page describes how to configure the GUMS mappings.
The mapping configuration has six main parts:
These may all be added, modified, and removed from the web interface. Changes from the web interface ultimately end up in the XML file, gums.config, located in WEB-INF/config, which can also be edited by hand. It is easy to see the correlation of the configuration as seen in the web interface with the configuration as seen in the XML file. These settings do not affect data stored in the persistence factories, which are used for storing individual user information.
On the left side of the web interface you see the following options under 'Configuration':
On the more detailed page from clicking add or edit, you see various fields to fill in. Most of these are straight forward. The text to the left of the fields reads as a sentence to help clarify the purpose of each field. Most fields provide an example. You will see a 'type' drop down menu, which when changed, changes what other fields are available since not all fields are appropriate for each type.
Let's go through an example to understand the mappings logic by analyzing the configuration XML. A request comes in to map user DN="/DC=org/DC=doegrids/OU=People/CN=John Smith" FQAN="/atlas/usatlas" coming from gatekeeper "/DC=org/DC=doegrids/OU=Services/CN=mygk.usatlas.bnl.gov". Gums will first look through the hostToGroupMappings section to find a match to the gatekeeper CN. Say we have:
<hostToGroupMappings> <!-- RHIC gatekeepers --> <hostToGroupMapping cn='star*.*.bnl.gov' ... /> <hostToGroupMapping cn='phenix*.*.bnl.gov' ... /> <!-- ATLAS test gatekeeper --> <hostToGroupMapping cn='mygk.usatlas.bnl.gov' ... /> <!-- Rest of ATLAS gatekeepers --> <hostToGroupMapping cn='*.usatlas.bnl.gov' ... /> </hostToGroupMappings>
GUMS will go through that list in the order specified, and find the first match to the "wildcard" attribute. In this case, we match the third hostToGroupMapping specification. Notice that if you put the third hostToGroupMapping last, it would never actually be used, because mygk.usatlas.bnl.gov also matches "*.usatlas.bnl.gov", which covers a broader range of hosts. If you have broader match together with more specific cases, the more specific cases must preceed the broader case.
Let's look at what was hidden in the hostToGroupMapping entry; there are additional attributes, in particular "groups". This attribute refers to group mappings. In our case it is:
<hostToGroupMapping cn='mygk.usatlas.bnl.gov' groups='atlasProd,usatlasPool,ivdglPool, ...' />
GUMS will now go through the list of groups (i.e. groupToAccountMappings) in the order specified and choose the first one that matches the given credentials. GUMS will check whether the credentials are part of atlasProd; if not, then usatlasPool, and so on, until either a match is found or the list ends. The first match will define the mapping, and the user will get mapped accordingly. As before, if you have both a broad default and a more specific case, the specific case must come first.
In a correct configuration, each group (e.g., atlasProd, usatlasPool,...) must be defined in the groupToAccountMappings section in a groupToAccountMapping element. GUMS first checks the first one listed, e.g., atlasProd. A groupToAccountMapping element contains userGroup elements. Let's look at the atlasProd group mapping:
<groupToAccountMapping name='atlasProd' userGroups='osgusatlas, osgusatlasBackup' .../>
The userGroups defines the member which are allowed to be part of this map. GUMS will go through the list of user groups in the order specified. If the user is a member of osgusatlas, it will be done with this step; if not, it will check for membership in osgusatlasBackup. If this also fails, this groupToAccountMapping will not be chosen to perform the mapping and GUMS tries additional groupToAccountMappings if they are defined in the hostToGroupMapping.
Let's look at what was hidden in the groupToAccountMapping entry; there are additional attributes, in particular "accountMappers", which map a grid identity to a local account:
<groupToAccountMapping name='atlasProd' userGroups='osgusatlas, osgusatlasBackup' accountMappers='bnlLdap, usatlasProd'/>
GUMS will go through the list of account mappers in order. It will first try bnlPool, which as it turns out in our case will attempt to lookup the user in BNL's LDAP server. If the user is found, it returns the local account and this is the final result of the request. If not, it looks up whether the user is a member of usatlasProd. If this succeeds, this is the final result of the request. If not, since there are no more account mappers, the final result returned is 'null', meaning this user cannot be mapped.
Now let's look at a user group which was referred to in the groupToAccountMapping:
<vomsUserGroup name='osgusatlas' vomsServer='bnlVoms' remainderUrl='/atlas/services/VOMSAdmin' voGroup="/atlas/usatlas" acceptProxiesWithoutFQAN="true"/>
This says all the people in USATLAS, retrieved through the server specified by the VOMS server element 'bnlVoms', are part of this group. The attribute 'remainderUrl' will be described below. The attribute 'acceptProxiesWithoutFQAN="true"' means standard/non-VOMS proxies are allowed. Our case, DN='/DC=org/DC=doegrids/OU=People/CN=John Smith' FQAN='/atlas/usatlas', is clearly part of /atlas/usatlas. Even if it came in with no FQAN, however, it would still be considered a match, and get mapped. If it came with a different FQAN, though, it wouldn't have matched the FQAN; if present, it needs to match. One can use matchFQAN to change how the FQAN is matched. The persistenceFactory attribute refers to a persistence factory that has been defined that will cache the users of this VO. There are other types of user groups besides vomsUserGroup which will be explained later.
Let's also look at an account mapper which was referred to in the groupToAccountMapping:
<gecosLdapAccountMapper name='bnlLdap' jndiLdapUrl='ldap://ldap.bnl.gov/dc=domain,dc=mysite,dc=gov'/>
This says to query ldap at 'ldap://ldap.bnl.gov' in the domain 'dc=domain,dc=mysite,dc=gov'. If the user's CN matches a gecos field in ldap, the respective account is returned. There are other types of account mappers besides gecosLdapAccountMapper which are explained later.
Almost done with this example. Let's look at the persistence factory referred to in the user group:
<hibernatePersistenceFactory name='mysql' hibernate.connection.url='jdbc:mysql://mydb.mysite.org/GUMS_1_3' hibernate.connection.driver_class='com.mysql.jdbc.Driver' .../>
This says is to use a MySQL database at 'mydb.mysite.org/GUMS_1_3' to cache user information. Note that besides being referred to by user groups to store users, persistence factories are referred to by some account mapper types to store mappings.
Finally, let's look at the VOMS server referred to in the user group:
<vomsServer name='bnlVoms' baseUrl='https://griddev01.usatlas.bnl.gov:8443/voms' persistenceFactory='mysql' sslCertfile='/etc/grid-security/gumscert.pem' sslKey='/etc/grid-security/gumskey.pem' sslCAFiles='/etc/grid-security/certificates/*.0' .../>
This says to lookup VO membership at the server 'griddev01.usatlas.bnl.gov' and to cache the users in persistence factory 'mysql'. The actual URL used for the request is the baseUrl concatenated with the remainderUrl specified in the VOMS user group. This allows for sharing a server serving multiple VOs. Also, be sure that the certificates referenced in sslCertfile, sslKey, and sslCAFiles have read access by Tomcat (e.g. readable by user 'daemon' in VDT/OSG).
You should now understand the basic way GUMS makes mapping decisions.
The configuration elements with more than one type will first be described.
There are currently three types of persistence factores:
Below are the steps to enable GSSAPI and Kerberos in the LDAP/local persistence factory (from Richard Jones):
1. Use kadmin to create a credential for a new service principal called gums/<your gums host FQDN> 2. Use kadmin to store this new credential in a file called ldapgums.keytab, as in "ktadd -k ldapgums.keytab gums/<your gums host FQDN>" 3. Save the keytab file you created in the previous step in the $VDT_LOCATION/tomcat/v55/conf directory. Make the owner daemon:daemon and disable all of its group/world access bits. 4. Edit your ldap configuration (usually /etc/openldap/slapd.conf) and add access permissions for the new principal to grant read/write permission to the GUMS portion of the ldap tree. The following example should be customized to fit your own ldap installation: access to dn.subtree="ou=GUMS,dc=pan,dc=phys,dc=uconn,dc=edu" by dn="uid=gums/pan.phys.uconn.edu,cn=phys.uconn.edu,cn=gssapi,cn=auth" write by users auth by anonymous auth access to * by * read Then restart the ldap server to reread the configuration. 5. Create a keytab called ldaproot.keytab containing the principal that the ldap server accepts as its root identity -- root/pan.phys.uconn.edu in my case -- and save it in the tomcat/v55/conf directory. Make the owner daemon:daemon and disable all of its group/world access bits. 6. Create a file called jaas.conf containing the lines listed below and save it in the tomcat/v55/conf directory. It must be readable by user daemon, but otherwise has no specific required permissions. 7. Edit the script tomcat/v55/bin/catalina.sh and add the if clause listed below to point the jgss security layer to the jaas.conf file, if it exists. This modification should be backwards compatible. 8. Edit the vdt-app-data/gums/config/gums.config xml file and change java.naming.security.authentication from 'simple' to 'GSSAPI'. The arguments java.naming.security.principal and java.naming.security.credentials can be anything (are ignored), and the principal to be passed to the ldap server is the one identified (see below) in the jaas.conf file. No plaintext passwords are needed any more. Listing of jaas.conf: com.sun.security.jgss.initiate { com.sun.security.auth.module.Krb5LoginModule required useKeyTab=true keyTab="/usr/local/osg/tomcat/v55/conf/ldaproot.keytab" storeKey=true principal="root/pan.phys.uconn.edu" doNotPrompt=true; }; Listing of new if-clause in catalina.sh: # Load the configuration for the JAAS security context if [ -r "$CATALINA_HOME"/conf/jaas.conf ]; then JAVA_OPTS="$JAVA_OPTS \ -Djavax.security.auth.useSubjectCredsOnly=false \ -Djava.security.krb5.conf=/etc/krb5.conf \ -Djava.security.auth.login.config=$CATALINA_HOME/conf/jaas.conf" fi
Currently, except for the ldap persistence factory, you can select the "Store Configuration" box to have the configuration stored in that persistence factory. This allows multiple GUMS servers to share the same configuration for clustering purposes. A copy of the configuration is still kept current in .../WEB-INF/config/gums.config. To change the configuration stored in the persistence factory, simply change .../WEB-INF/config/gums.config (either directly by hand or indirectly through the web interface) and the databases configuration will automatically be updated. This, in turn will update the configuration on all other GUMS servers also configured to use the same underlying storage used by the persistence factory.
There are currently five types of account mappers:
Keep in mind that GUMS does not create accounts, it only returns the account name. Therefore, a prerequisite to using GUMS is to create all the accounts that GUMS can map to at your local site.
There are currently four types of user groups:
Keep in mind that GUMS does not create accounts, it only returns the account name. Therefore, a prerequisite to using GUMS is to create all the accounts that GUMS maps to at your local site.
You may choose whether users of this user group have "read self", "read all", or "write" access to GUMS. At least one should be configured with "write" access so that GUMS can be administered.
For 'voms' user groups, the vo/group and role affect what users are retrieved from the VOMS server and put into the database (regardless of other options):
These values along with whether non-VOMS certificates are allowed (acceptProxyWithoutFQAN) and how a VOMS certificate's FQAN is matched (matchFQAN) determine how users are matched. FQAN stands for Fully Qualified Attribute Name and comprises the string: /VO/group/Role=role.
As you can see, there is a lot of flexibility for matching and user retrieval.
If you need to generate an OSG-user-VO-map, which is used for VO accounting purposes, you should create a 'group to account mapping' for each VO you want to show up in this file and fill in the the 'Accounting VO' and 'Accounting VO Subgroup' fields.