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_1' hibernate.connection.driver_class='com.mysql.jdbc.Driver' .../>
This says is to use a MySQL database at 'mydb.mysite.org/GUMS_1_1' 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:
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.