Science Gateway Credential with Attributes
From TeraGrid Wiki
Contents |
A Brief Introduction
This document shows how to use the TeraGrid Science Gateway SAML Extension bundled with the GridShib SAML Tools to bind a SAML token to a proxy certificate signed by a gateway's community credential. The SAML token contains the following information:
- entityID: a globally unique identifier for the SAML issuer (i.e., the gateway)
- name identifier: a globally unique identifier for the authenticated user
- authentication statement: a description of the act of authentication at the gateway
- authentication method: an identifier specifying the method of authentication (e.g., password)
- authentication instant: a date-time stamp indicating the exact time the authentication took place
- IP address: the IP address of the user agent involved in the authentication event
- attribute statement: a collection of user attributes
- mail attribute: the user's e-mail address (optional)
The X.509-bound SAML token helps to increase the information flow from the gateway to the resource provider (RP) to meet requirements for attribute-based auditing and authorization for Science Gateways. See a recent paper [SGWAuthZ] for detailed background information regarding this enhancement to the Community Account Model.
This document focuses on the gateway side of the community account model. The current status of this effort to deploy attribute-based authentication in the TeraGrid Science Gateway program is tracked in a separate wiki article.
Note that the technology described here permits both sides (gateway and RP) to progress independently of one another. A SAML-enabled science gateway can interact with any RP, while a SAML-enabled RP can choose to accept requests from any gateway.
This approach is intended for gateways that submit jobs via (various versions of) GRAM to community accounts. Gateways that submit jobs via ssh and qsub/bsub to community accounts should instead call Gateway-Submit-Attributes. Gateways that submit jobs to individual user accounts on TeraGrid, rather than to community accounts, can ignore this altogether.
Current Status
See the Science Gateway Credential with Attributes Status page for the current status of the effort to deploy attribute-based authentication in the TeraGrid Science Gateway program.
Getting Started
The table below suggests various ways to use this document. For example, to simply evaluate the software, complete the first two sections (Installing and Using).
| Installing | Using | Configuring | Deploying | Integrating | ||
|---|---|---|---|---|---|---|
| Evaluate: | (< 1 hr) | |||||
| Customize: | (< 1/2 hr) | |||||
| Investigate: | (< 1 hr) | |||||
| Develop: | ? |
Assuming you have Java and Ant already installed on your system, the times in parentheses are estimates of the incremental person-hours required to complete the activity (which builds on the previous activity).
The time to full integration depends on the underlying gateway infrastructure. Java-based portal developers will use the Java API to integrate the GridShib SAML Tools. Other portal developers will use the command-line interface. Java-based portals are expected to be somewhat easier to integrate than non-Java portals, if only because the GridShib SAML Tools are written in Java.
Installing the SAML Tools
The GridShib SAML Tools is a standalone software package requiring only Java and Ant. Refer to the following online documentation for simple, step-by-step instructions on how to download, install, and test the SAML Tools:
http://gridshib.globus.org/docs/gridshib-saml-tools/install.html
By the way, if you prefer to work offline, the above install document is included in the distribution ($GRIDSHIB_HOME/doc/install.html).
In the GridShib home directory, you'll find a build.properties file with various configuration properties defined. Locate the gridshib.SAMLToolsConfigPath property in the build.properties file, comment it out, and redefine it as follows:
#gridshib.SAMLToolsConfigPath=etc/gridshib-saml-tools-config.properties gridshib.SAMLToolsConfigPath=etc/tg-gateway-config.properties
This configures a new properties file designed specifically for Science Gateways. Now save the build.properties file and re-install the SAML Tools according to the instructions in the above install document.
A successful installation results in a number of test credentials written to the GridShib home directory. One credential, in particular, will be of interest to gateway developers:
UNIX:
$ $GRIDSHIB_HOME/bin/gridshib-saml-info --debug --verbose \
--infile $GRIDSHIB_HOME/testgatewayproxy.pem
Windows:
> %GRIDSHIB_HOME%\bin\gridshib-saml-info --debug --verbose
--infile %GRIDSHIB_HOME%\testgatewayproxy.pem
SAMLAssertion {
<Assertion
xmlns="urn:oasis:names:tc:SAML:1.0:assertion"
xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
AssertionID="_2beccd2815ee17e0ef4432a83b070599"
IssueInstant="2008-02-25T15:39:29.141Z"
Issuer="https://saml.teragrid.org/gateway/aaatest"
MajorVersion="1" MinorVersion="1">
<AuthenticationStatement
AuthenticationInstant="2008-02-25T15:39:26.000Z"
AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password">
<Subject>
<NameIdentifier
Format="http://teragrid.org/names/nameid-format/principalname">
trscavo@aaatest.teragrid.org
</NameIdentifier>
<SubjectConfirmation>
<ConfirmationMethod>
urn:oasis:names:tc:SAML:1.0:cm:sender-vouches
</ConfirmationMethod>
</SubjectConfirmation>
</Subject>
<SubjectLocality
IPAddress="255.255.255.255"></SubjectLocality>
</AuthenticationStatement>
<AttributeStatement>
<Subject>
<NameIdentifier
Format="http://teragrid.org/names/nameid-format/principalname">
trscavo@aaatest.teragrid.org
</NameIdentifier>
<SubjectConfirmation>
<ConfirmationMethod>
urn:oasis:names:tc:SAML:1.0:cm:sender-vouches
</ConfirmationMethod>
</SubjectConfirmation>
</Subject>
<Attribute
AttributeName="urn:oid:0.9.2342.19200300.100.1.3"
AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri">
<AttributeValue xsi:type="xsd:string">
trscavo@gmail.com
</AttributeValue>
</Attribute>
</AttributeStatement>
</Assertion>
}
(untrusted) SAMLIdentity {
issuer='https://saml.teragrid.org/gateway/aaatest'
nameID='<NameIdentifier
xmlns="urn:oasis:names:tc:SAML:1.0:assertion"
Format="http://teragrid.org/names/nameid-format/principalname">
trscavo@aaatest.teragrid.org
</NameIdentifier>'
}
(untrusted) SAMLAuthnContext {
issuer='https://saml.teragrid.org/gateway/aaatest'
authnMethod='urn:oasis:names:tc:SAML:1.0:am:password'
authnInstant='2008-02-25T15:39:26Z'
ipAddress='255.255.255.255'
dnsName='null'
}
(untrusted) BasicAttribute {
issuer='https://saml.teragrid.org/gateway/aaatest'
name='urn:oid:0.9.2342.19200300.100.1.3'
nameFormat='urn:mace:shibboleth:1.0:attributeNamespace:uri'
value #1='trscavo@gmail.com'
}
In the above output, the bold text indicates the security information that you, the gateway developer, put into the SAML token. In the next two sections, we show how to use and configure the SAML Tools so that the assertion content is similar to the above, but customized for your gateway.
Using the SAML Tools
After installing the GridShib SAML Tools, refer to the online User Guide:
http://gridshib.globus.org/docs/gridshib-saml-tools/user-guide.html
In particular, read the section entitled Using the SAML Assertion Issuer Tool, which shows how to use the command-line interface to issue SAML tokens and bind them to X.509 proxy certificates. For instance, a gateway developer might use the following command to issue a SAML token:
UNIX:
$ $GRIDSHIB_HOME/bin/gridshib-saml-issuer --debug \
--user trscavo --sender-vouches \
--authn --authnMethod urn:oasis:names:tc:SAML:1.0:am:password \
--authnInstant 2007-08-02T12:10:34-0400 \
--address 255.255.255.255 \
--config $GRIDSHIB_HOME/etc/tg-gateway-config.properties
Windows:
> %GRIDSHIB_HOME%\bin\gridshib-saml-issuer --debug
--user trscavo --sender-vouches
--authn --authnMethod urn:oasis:names:tc:SAML:1.0:am:password
--authnInstant 2007-08-02T12:10:34-0400
--address 255.255.255.255
--config %GRIDSHIB_HOME%\etc\tg-gateway-config.properties
In the following section, we show how to configure the SAML Tools to issue the required SAML token. As you make a configuration change, rerun the above command line to see the effect of each configuration change.
Configuring the SAML Tools
The GridShib SAML Tools ships with a gateway configuration file ($GRIDSHIB_HOME/etc/tg-gateway-config.properties) that largely determines the content of the SAML token bound to the proxy certificate. See the User Guide for basic information about configuring the SAML Tools. The following sections give specific instructions how to configure the SAML Tools to customize a gateway.
Updating the TeraGrid gateway configuration
First, update your gateway configuration file ($GRIDSHIB_HOME/etc/tg-gateway-config.properties) to the latest version:
$ curl http://viewcvs.globus.org/viewcvs.cgi/gridshib/saml/teragrid/java/etc/tg-gateway-config.properties?view=co \ -o $GRIDSHIB_HOME/etc/tg-gateway-config.properties
Configuring the X.509 issuing credential
The issuing credential is either the community credential itself or a proxy signed by the community credential. To configure the community credential as the issuing credential, set the certLocation and keyLocation properties in the configuration file to the locations of the certificate and private key components of the community credential (resp.):
# the location of the community credential: certLocation=file:///etc/grid-security/communitycert.pem keyLocation=file:///etc/grid-security/communitykey.pem
In the above example, the certPath and keyPath properties can be used instead of certLocation and keyLocation. See the User Guide for more information about how to configure the X.509 issuing credential.
To configure a proxy credential as the issuing credential, set each of the certPath and keyPath properties to the location of the proxy credential:
# the location of the proxy credential: certPath=/tmp/x509up_u201 keyPath=/tmp/x509up_u201
In the above example, the certLocation and keyLocation properties can be used instead of certPath and keyPath.
Choosing an entityID
Every gateway has a unique identifier, namely, the subject DN of their community certificate. Now since the issuer of the proxy certificate and the issuer of the SAML token bound to the proxy certificate are one and the same entity (i.e., the gateway), one would expect the Issuer attribute of the SAML token to be the subject DN of the community credential. This is exactly what the SAML Issuer Tool does by default.
In the SAML world, however, entities are identified by URIs, not DNs. So the gateway administrator must choose a globally unique URI (called an entityID) that identifies the gateway as a SAML issuer. This entityID is configured into the configuration file as follows:
IdP.entityID=https://saml.teragrid.org/gateway/gisolve
In the above example, the chosen URI is in fact a URL, which we strongly recommend for at least two reasons:
- The above
entityIDis globally unique since presumably the gateway controls the indicated community account (gisolve). - At a future date, the gateway might publish signed SAML metadata at the above location, which the RP could use to establish trust.
All TeraGrid gateways have been assigned an entityID.
Please use the entityID assigned to your gateway
according to the table on the Science Gateway Credential with Attributes Status page.
Choosing the name identifier format
The most important piece of information a gateway can provide to an RP is the name of the authenticated user. This name must be a globally unique, persistent, non-reassignable identifier for the user:
- Global uniqueness is achieved by qualifying the portal user's login identifier. For example, GISolve user trscavo is uniquely identified to the RP as trscavo@gisolve.org.
- If the name identifier is based on the user's login, persistence is a natural consequence of the portal's login account process. Note that we do not require a portal user's login identifier to persist for all time; that is, a user may be assigned a new login identifier at any time, subject to gateway policy.
- However, a portal must not recycle login identifiers. If a user's login account is disabled or orphaned, that user's login identifier must never be reassigned to another user.
To formulate a globally unique identifier for the user, configure the NameID properties in the configuration file as follows:
NameID.Format=http://teragrid.org/names/nameid-format/principalname NameID.Format.template=%PRINCIPAL%@gisolve.teragrid.org
TeraGrid Resource Provider software is configured to look for TeraGrid Entity Name Identifiers in this format.
In particular, the following format should not be used for TeraGrid identifiers:
NameID.Format=urn:oid:1.3.6.1.4.1.5923.1.1.1.6
This is an older configuration that should be updated to use the TeraGrid-specific format.
A note about scope
A scope value appeared in the above configuration while configuring the name identifier:
NameID.Format.template=%PRINCIPAL%@gisolve.teragrid.org
In the above example, the scope value is "gisolve.teragrid.org". In general, the scope value is the concatenation of the gateway's community account name (gisolve in this case) and ".teragrid.org". Such a scope value is guaranteed to be globally unique and consistent throughout the TeraGrid.
Deploying the SAML Tools
This section investigates important deployment issues confronting the gateway developer. We use the command-line interface to illustrate and motivate these issues.
After configuring the GridShib SAML Tools as outlined in the previous section, use the following commands to issue and inspect a proxy credential containing the required SAML token:
UNIX:
$ $GRIDSHIB_HOME/bin/gridshib-saml-issuer --debug \
--user trscavo --sender-vouches \
--authn --authnMethod urn:oasis:names:tc:SAML:1.0:am:password \
--authnInstant 2007-08-02T12:10:34-0400 \
--address 255.255.255.255 \
--config $GRIDSHIB_HOME/etc/tg-gateway-config.properties \
--properties \
Attribute.mail.Name=urn:oid:0.9.2342.19200300.100.1.3 \
Attribute.mail.Value=trscavo@gmail.com \
--x509 --outfile /tmp/testproxy.pem
$ $GRIDSHIB_HOME/bin/gridshib-saml-info \
--infile /tmp/testproxy.pem
Windows:
> %GRIDSHIB_HOME%\bin\gridshib-saml-issuer --debug
--user trscavo --sender-vouches
--authn --authnMethod urn:oasis:names:tc:SAML:1.0:am:password
--authnInstant 2007-08-02T12:10:34-0400
--address 255.255.255.255
--config %GRIDSHIB_HOME%\etc\tg-gateway-config.properties
--properties
Attribute.mail.Name=urn:oid:0.9.2342.19200300.100.1.3
Attribute.mail.Value=trscavo@gmail.com
--x509 --outfile %TEMP%\testproxy.pem
> %GRIDSHIB_HOME%\bin\gridshib-saml-info
--infile %TEMP%\testproxy.pem
In the previous commands, note that some of the command-line options take arguments whose values are determined on-the-fly. For example, the login identifier of the authenticated user is a required argument of the --user option. We discuss some these arguments in the following sections.
Determining the IP address of the authenticated user
Including the IP address of the authenticated user in the SAML token is optional but highly desirable. The RP can use the IP address to track the request and restrict future access if something goes wrong. This is important since it allows the RP to focus its access restrictions (if needed) on individual IP addresses instead of using a shotgun approach affecting the entire gateway.
Depending on your portal environment, obtaining the IP address of the authenticated user on-the-fly is either very easy or very hard. Normally, the IP address can be obtained from the CGI variable REMOTE_ADDR, but if you're running a portlet inside a JEE container, the equivalent Java expression
String ipAddress = request.getRemoteAddr();
always returns null, as required by the portal specification. We have yet to find a suitable workaround for this problem.
Determining the authentication context of the authenticated user
Unlike the IP address, both the authentication method and the authentication instant are required. If either is omitted on the command line, no <AuthenticationStatement> is included in the SAML token. Consequently, the RP will receive no indication of the authentication context associated with the authenticated user.
The authentication method shown above is one of several standard URIs used just for this purpose (see section 7.1 of [SAMLCore]). The authentication instant is the precise point in time the user was authenticated according to the given authentication method.
In practice, the authentication instant is somewhat difficult to reproduce accurately. In particular, the authentication instant is not "NOW," that is, it is not the time the assertion is issued. Rather it is some past point in time.
One idea is to use a client-side cookie to record the authentication instant. Alternatively, you could add the authentication instant to the portal's native session, assuming that were extensible. Whatever method you use to maintain state, we ask that you document your technique on the discussion page associated with this wiki topic so that other developers can benefit from your work.
Note that the input format of the authentication instant on the command line is configurable. See the User Guide for more information about how to configure the dateTime pattern associated with the authentication instant.
Determining the e-mail address of the authenticated user
The user's e-mail address is a dynamic quantity, and like the username (--user), the e-mail address must be configured on-the-fly as indicated in the above example.
According to the eduPerson specification [eduPerson], the OID associated with the user's e-mail address is 0.9.2342.19200300.100.1.3. Thus, according to the MACE-Dir SAML Attribute Profile [MACEAttrib], the attribute name is that given on the command line above. The attribute value (the non-static portion of the attribute) must be determined on-the-fly.
Integrating the SAML Tools
At this point, you should have a working deployment and be ready to integrate the SAML Tools into the gateway infrastructure. This requires a modest amount of development effort. If your portal solution is Java-based, or can otherwise take advantage of a Java library (PHP has a Java interface, for example), you can use the provided Java API to incorporate the SAML Tools functionality into your workflow. Non-Java portals can use the command-line interface discussed in the previous section.
Deploying the SAML Tools into Tomcat
To deploy the GridShib SAML Tools into your JEE container, complete the following steps:
- Re-install the SAML Tools.
- This will incorporate the changes you made to the configuration properties file (tg-gateway-config.properties) into a JAR file.
- Endorse Xerces and Xalan.
- For Tomcat 5.5: Copy the JAR files in the $GRIDSHIB_HOME/endorsed directory into Tomcat's $CATALINA_HOME/common/endorsed directory. If the Tomcat endorsed directory already contains JAR files related to JAXP or XML, please delete them first.
- For Tomcat 6: Create the directory $TOMCAT_HOME/endorsed and copy the JAR files in the $GRIDSHIB_HOME/endorsed directory into this new directory.
- For other JEE containers, please consult your container's documentation.
- Copy a subset of the JAR files in the $GRIDSHIB_HOME/lib directory to a Tomcat lib directory. You have two choices:
- Copy the GridShib JAR files to the $CATALINA_HOME/common/lib directory, or
- Copy the GridShib JAR files to your webapp's WEB-INF/lib directory
Where you choose to copy the GridShib JAR files depends on your Java environment.
Developing with the SAML Tools
From the developer's point of view, the integration boils down to the following five-step development process:
- create the credential
- add the e-mail address
- set the authentication context
- issue the proxy credential
- output the proxy credential
Important! See the Java source file GatewayCredentialTest in directory
$GRIDSHIB_HOME/tests/org/teragrid/ncsa/gridshib/security
for a complete, working example.
Creating the credential
Creating a gateway credential is easy:
GatewayCredential credential = new GatewayCredential("trscavo");
The input to the GatewayCredential constructor is the portal login of the authenticated user.
Adding the e-mail address
Call the addEmailAddress method to add an e-mail address to the credential:
credential.addEmailAddress("trscavo@gmail.com");
Any number of e-mail addresses can be added in this way, but one is sufficient.
Setting the authentication context
Setting the authentication context is the most difficult step. Three pieces of information are needed:
- authentication method
- authentication instant
- IP address (optional)
If the user was authenticated by presenting a password, set the authnMethod variable to the exact value shown below. If the user was authenticated by some other means, consult the Java API for the corresponding authentication method URI.
String authnMethod = SAMLAuthenticationStatement.AuthenticationMethod_Password;
The authentication instant is the precise point in time the user was authenticated. This requires some state to be maintained, perhaps using a client-side cookie and/or a server-side session attribute. The code below shows that the authnInstant variable is a Java Date instance, but other than that the example is totally bogus. It will require some work on your part to determine an accurate value for authnInstant.
// wholly contrived authnInstant, 5 mins in the past: Date authnInstant = new Date(new Date().getTime() - 1000*60*5);
The ipAddress is just what you'd expect:
String ipAddress = "255.255.255.255";
In a Java portlet environment, the IP address of the authenticated user is not readily available. For this reason, the ipAddress is optional, and may in fact be null:
String ipAddress = null;
Once you've assembed these three values, call the setAuthnContext method:
credential.setAuthnContext(authnMethod, authnInstant, ipAddress);
As a result of this call, a SAML <AuthenticationStatement> will be added to the credential.
Issuing the proxy credential
To issue the credential, invoke the issue method:
GlobusCredential proxy = credential.issue();
The resulting object is an ordinary GlobusCredential instance. If your framework happens to be based on GSSCredential instead of GlobusCredential, the GSIUtil utility class has convenience methods that convert between these two types. See the Java API for details.
Outputing the proxy credential
This step is optional. What you do with the GlobusCredential instance depends on your environment. For example, to output the proxy credential with bound SAML token to disk, the following will suffice:
String path = "testgatewayproxy2.pem"; GSIUtil.writeCredentialToFile(proxy, path);
There are many static methods in the GSIUtil utility class for moving credentials around. If you don't see what you need, please ask.
Testing with the SAML Tools
There is a server setup at https://gstest.ncsa.uiuc.edu to test whether your SAML decorated credential is working. Example GRAM job submission methods:
GRAM4:
globusrun-ws -submit -F gstest.ncsa.uiuc.edu -s -c /bin/date
GRAM5:
globusrun -o -r gstest.ncsa.uiuc.edu '&(executable=/bin/date)'
Condor-G pre-WS GRAM:
grid_resource = gt2 gstest.ncsa.uiuc.edu/jobmanager
Condor-G WS GRAM:
grid_resource = gt4 gstest.ncsa.uiuc.edu:8443 Fork
After submitting, visit the the website: https://gstest.ncsa.uiuc.edu/ to confirm that the attributes are available in the server's GRAM audit database by looking at the gram-audit.txt. If the attributes were successfully written to the GRAM audit database, you will see a pair of entries in gram-audit.txt similar to:
5 http://globus.org/names/attribute/gram/audit_v1/job_grid_id https://gstest.ncsa.uiuc.edu:50384/16073824431554770251/3206699450424662149/ 5 http://globus.org/names/attribute/gram/audit_v1/gateway_user jbasney@aaatest.teragrid.org
You've successfully decorated your credential if you see a line similar to the second shown above (with the gateway_user name). If testing is successful, please update your status.
If testing was unsuccessful, first check that the SAML bindings on the credentials used to submit the job are as you expect. This can be accomplished with the gridshib-saml-info command, for example:
$ export X509_USER_PROXY=/path/to/your/decorated/credential
$ export GRIDSHIB_HOME=/usr/local/gridshib-saml-tools
$ $GRIDSHIB_HOME/bin/gridshib-saml-info -f $X509_USER_PROXY
(untrusted) SAMLToken {
id='_0a891a2768a917abd7c566e13d10bbb5'
issuer='https://saml.teragrid.org/gateway/aaatest'
}
(untrusted) SAMLIdentity {
id='_0a891a2768a917abd7c566e13d10bbb5'
issuer='https://saml.teragrid.org/gateway/aaatest'
name='jsiwek@aaatest.teragrid.org'
nameQualifier='null'
format='http://teragrid.org/names/nameid-format/principalname'
}
(untrusted) SAMLAuthnContext {
id='_0a891a2768a917abd7c566e13d10bbb5'
issuer='https://saml.teragrid.org/gateway/aaatest'
authnMethod='urn:oasis:names:tc:SAML:1.0:am:password'
authnInstant='2010-03-08T15:53:17Z'
ipAddress='141.142.234.164'
dnsName='null'
}
If you have questions or problems, please contact jbasney@illinois.edu or post to gateways@teragrid.org.
Digging Deeper
See the GridShib SAML Tools Developer Guide for pointers and further details:
http://gridshib.globus.org/docs/gridshib-saml-tools/dev-guide.html
References
[SGWAuthZ] T. Scavo and V. Welch. A Grid Authorization Model for Science Gateways. International Workshop on Grid Computing Environments, 2007. See http://library.rit.edu/oajournals/index.php/gce/article/view/99
[MACEAttrib] S. Cantor and K. Hazelton. MACE-Dir SAML Attribute Profiles. Internet2 MACE-Dir Working Group, 2 December 2007. See http://middleware.internet2.edu/dir/docs/draft-internet2-mace-dir-saml-attributes-latest.pdf
[SAMLCore] E. Maler et al. Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V1.1. OASIS Standard, September 2003. Document ID oasis-sstc- saml-core-1.1. See http://www.oasis-open.org/committees/download.php/3406/oasis-sstc-saml-core-1.1.pdf
[eduPerson] eduPerson Object Class Specification (200712). Internet2 MACE-Dir Working Group, 12 December 2007. Document: internet2-mace-dir-eduPerson-200712. See http://www.educause.edu/eduperson/
