GridShib SAML Tools
Version 0.2.0 Technology Preview 1
July 30, 2007

The GridShib SAML Tools issue or request SAML assertions and optionally bind these assertions to X.509 proxy certificates. Consult the readme document accompanying this distribution for a brief introduction to GridShib.

Contents

Getting Started
Installation
Testing
Error Handling
Using the SAML Assertion Issuer Tool
Configuration
Known Limitations

Getting Started

GridShib SAML Tools is a standalone software package requiring only Java and Ant. To issue assertions and certificates, an issuing credential is required. For testing purposes, a sample credential is included, which the Tool uses by default. For production deployments, you should configure the Tool to use a trusted X.509 credential. See the Configuration section for instructions how to do this.

In what follows, GRIDSHIB_HOME is an environment variable set to the absolute path of the installation directory. When installing the GridShib SAML Tools, choose an installation directory that does not have any spaces in its path name; otherwise the commands below will fail.

Installation

To install the GridShib SAML Tools, download the distribution file into a working directory (e.g., /tmp/gridshib-saml-tools-0_2_0-src.tar.gz) and perform the following two-step installation process:

Unpack the GridShib SAML Tools distribution file. For example, on UNIX systems type:
```
  UNIX:
  $ cd /usr/local
  $ gunzip /tmp/gridshib-saml-tools-0_2_0-src.tar.gz
  $ tar xvf /tmp/gridshib-saml-tools-0_2_0-src.tar
```
In the case of Windows, simply double-click the ZIP archive to install the distribution. In what follows, we assume the GridShib SAML Tools are installed in directory c:\gridshib.
Run 'ant install' on the GridShib SAML Tools build file (/tmp/gridshib-saml-tools-0_2_0/build.xml). This creates a JAR file and runs a test script. For example, on UNIX or Windows systems type:
```
  UNIX:
  $ cd /usr/local/gridshib-saml-tools-0_2_0
  $ ant install
```
```
  Windows:
  > cd c:\gridshib\gridshib-saml-tools-0_2_0
  > ant install
```

As a result of step 2 above, the following operations are performed by the install script:

A bootstrap properties file is written to the src/conf directory.
A log4j properties file is written to the etc directory.
A JAR file (gridshib-saml-tools.jar) is created and written to the lib directory.
A logs directory is created and an empty log file (saml-tools.log) is created.
A test script is run and a SAML assertion is written to the console.
The test script issues another SAML assertion and writes it to file testassertion.xml in the home directory.
The test script issues yet another SAML assertion, binds it to an X.509 proxy certificate, and writes the certificate to file testproxy.pem in the home directory.

Installation of the GridShib SAML Tools is now complete.

Testing

As indicated in the previous section, the installer runs a test script that issues assertions and a certificate. Before proceeding, make sure the test files (testassertion.xml and testproxy.pem) were actually created in the home directory. The SAML assertion (testassertion.xml) is an ordinary text file that can be read with any text editor. The proxy certificate (testproxy.pem) can be viewed with openssl as follows:

  UNIX:
  $ openssl x509 -text -noout -in testproxy.pem

Now let's test the shell scripts. Depending on your platform, type one of the following sets of commands:

  UNIX:
  $ export GRIDSHIB_HOME=/usr/local/gridshib-saml-tools-0_2_0
  $ $GRIDSHIB_HOME/bin/gridshib-saml-issuer --help

  Windows:
  > set GRIDSHIB_HOME=c:\gridshib\gridshib-saml-tools-0_2_0
  > %GRIDSHIB_HOME%\bin\gridshib-saml-issuer --help
  usage: gridshib-saml-issuer [options]
   -a,--authn                 Indicates a 
                              element is to be issued
   -c,--x509                  Indicates the  element is to
                              be bound to an X.509 proxy certificate
   -d,--debug                 Indicates debugging mode
   -E,--x509Lifetime    Lifetime (in seconds) of the proxy
                              certificate(requires --x509 option)
   -e,--lifetime        Lifetime (in seconds) of the SAML assertion
   -f,--config           A configuration file (given as a file: URL)
   -h,--help                  Displays help message
   -m,--authnMethod      SAML AuthenticationMethod URI (requires
                              --authn option)
   -n,--address    Subject IP address (requires --authn option)
   -o,--outfile         File to output the SAML assertion (or proxy
                              certificate if --x509 option specified)
   -q,--quiet                 Indicates quiet mode
   -R,--ssoResponse      A SAML Web Browser SSO Response (given as a
                              file: URL)
   -t,--authnInstant    SAML AuthenticationInstant (requires --authn
                              option)
   -u,--user            Local principal name (i.e., username)

Now check the log file:

  UNIX:
  $ more $GRIDSHIB_HOME/logs/saml-tools.log

  Windows:
  > more < %GRIDSHIB_HOME%\logs\saml-tools.log

By default, the log level is set to INFO (in the log4j.properties file). To set the log level to DEBUG on-the-fly, type:

  UNIX:
  $ export GRIDSHIB_HOME=/usr/local/gridshib-saml-tools-0_2_0
  $ $GRIDSHIB_HOME/bin/gridshib-saml-issuer --help --debug

  Windows:
  > set GRIDSHIB_HOME=c:\gridshib\gridshib-saml-tools-0_2_0
  > %GRIDSHIB_HOME%\bin\gridshib-saml-issuer --help --debug

The --debug command-line option may be added to any invocation of the gridshib-saml-issuer script.

Error Handling

Specifying --debug on the command-line affects the verbosity of error messages written to the log file. If you set the log level to DEBUG in the log4j.properties file, the --debug command-line option has no effect.

In addition to logging, the gridshib-saml-issuer script writes short error messages to the terminal (stderr) by default. To run the script in quiet mode, add the --quiet option to any command-line invocation. In quiet mode, if the command fails, it will return a nonzero error code but it will not send any output to stderr. Instead, all output will be written to the log file.

Note: Other than the --help option, the gridshib-saml-issuer script never sends output to stdout.

Using the SAML Assertion Issuer Tool

To help you get started using the Issuer Tool, we now give some sample invocations of the gridshib-saml-issuer command-line script.

The only required command-line option is --user. For example, type:

  UNIX:
  $ $GRIDSHIB_HOME/bin/gridshib-saml-issuer --user trscavo

  Windows:
  > %GRIDSHIB_HOME%\bin\gridshib-saml-issuer --user trscavo

The output of the above command (a SAML assertion) will be written to stdout. To direct the output to a file, type:

  UNIX:
  $ $GRIDSHIB_HOME/bin/gridshib-saml-issuer --user trscavo \
      --outfile $GRIDSHIB_HOME/testassertion.xml

  Windows:
  > %GRIDSHIB_HOME%\bin\gridshib-saml-issuer --user trscavo
      --outfile %GRIDSHIB_HOME%\testassertion.xml

The above command will overwrite the SAML assertion issued by the test script. If you inspect the output SAML assertion with a text editor, you'll notice that the assertion contains a SAML AttributeStatement element. The names and values of the attributes are defined in a Java properties file:

  UNIX:
  $ more $GRIDSHIB_HOME/etc/gridshib-saml-issuer.properties

  Windows:
  > more < %GRIDSHIB_HOME%\etc\gridshib-saml-issuer.properties

To alter the configuration of the Tool, modify the default properties file or create a new one (see the Configuration section for details).

An AuthenticationStatement is easily added to the SAML assertion:

  UNIX:
  $ $GRIDSHIB_HOME/bin/gridshib-saml-issuer --user trscavo \
      --authn --outfile $GRIDSHIB_HOME/testassertion.xml

  Windows:
  > %GRIDSHIB_HOME%\bin\gridshib-saml-issuer --user trscavo
      --authn --outfile %GRIDSHIB_HOME%\testassertion.xml

Options that modify the content of the AuthenticationStatement include --authnMethod, --authnInstant and --address. For example, try:

  UNIX:
  $ $GRIDSHIB_HOME/bin/gridshib-saml-issuer --user trscavo \
      --authn --outfile $GRIDSHIB_HOME/testassertion.xml \
      --authnMethod urn:oasis:names:tc:SAML:1.0:am:password \
      --address 255.255.255.255

  Windows:
  > %GRIDSHIB_HOME%\bin\gridshib-saml-issuer --user trscavo
      --authn --outfile %GRIDSHIB_HOME%\testassertion.xml
      --authnMethod urn:oasis:names:tc:SAML:1.0:am:password
      --address 255.255.255.255

To bind the SAML assertion to an X.509 proxy certificate, add the --x509 command-line option:

  UNIX:
  $ $GRIDSHIB_HOME/bin/gridshib-saml-issuer --user trscavo \
      --authn --x509 --outfile $GRIDSHIB_HOME/testproxy.pem \
      --authnMethod urn:oasis:names:tc:SAML:1.0:am:password \
      --address 255.255.255.255

  Windows:
  > %GRIDSHIB_HOME%\bin\gridshib-saml-issuer --user trscavo
      --authn --x509 --outfile %GRIDSHIB_HOME%\testproxy.pem
      --authnMethod urn:oasis:names:tc:SAML:1.0:am:password
      --address 255.255.255.255

Again, you can use openssl to view the contents of the certificate:

  UNIX:
  $ openssl x509 -text -noout -in testproxy.pem

In lieu of an AuthenticationStatement, you can include the contents of an SSO Response issued by a SAML identity provider (such as a Shibboleth IdP):

  UNIX:
  $ $GRIDSHIB_HOME/bin/gridshib-saml-issuer --user trscavo \
      --x509 --outfile $GRIDSHIB_HOME/testproxy.pem \
      --ssoResponse file:///tmp/sso-response.xml

  Windows:
  > %GRIDSHIB_HOME%\bin\gridshib-saml-issuer --user trscavo
      --x509 --outfile %GRIDSHIB_HOME%\testproxy.pem
      --ssoResponse file:/c:/temp/sso-response.xml

The above commands extract any SAML assertions from the Response and nest them in an Advice element of the X.509-bound SAML assertion.

Configuration

The default GridShib SAML Tools configuration properties file is located at

  $GRIDSHIB_HOME/etc/gridshib-saml-issuer.properties

You can modify the default properties file to suit your needs, or you can create a new properties file altogether (recommended):

  UNIX:
  $ cp $GRIDSHIB_HOME/etc/gridshib-saml-issuer.properties \
       /tmp/my.properties
  $ $GRIDSHIB_HOME/bin/gridshib-saml-issuer --user trscavo \
      --authn --outfile $GRIDSHIB_HOME/testassertion.xml \
      --config file:///tmp/my.properties

  Windows:
  > copy %GRIDSHIB_HOME%\etc\gridshib-saml-issuer.properties
       c:\temp\my.properties
  > %GRIDSHIB_HOME%\bin\gridshib-saml-issuer --user trscavo
      --authn --outfile %GRIDSHIB_HOME%\testassertion.xml
      --config file:/c:/temp/my.properties

Configuring an Identifier for the SAML Assertion Issuer Tool

Every SAML entity is assigned a unique identifier called an entityID. Since the GridShib SAML Assertion Issuer Tool assumes an IdP role, there is an optional configuration property called IDPEntityID in the properties file. The Issuer Tool sets the Issuer XML attribute of every issued SAML assertion to the value of the IDPEntityID property. If the IDPEntityID property is omitted, the unique identifier of the SAML Issuer defaults to the X.509 Issuer, that is, the Subject DN of the signing credential.

The format of a SAML entityID is usually a URI. Where SAML metadata is concerned, the entityID MUST be a URI. Thus it is recommended that the IDPEntityID property be configured as a URI. For example:

  IDPEntityID=https://gridshib.example.org/idp

In the previous example, the IDPEntityID property has been configured as a URL. It is recommended that the IDPEntityID property be set to a resolvable URL and that this URL resolve to SAML metadata describing the deployed instance of the SAML Assertion Issuer Tool.

SAML metadata will become a required configuration step in the final release of GridShib SAML Tools v0.2.0.

Configuring the SAML Name Identifier

Three config file properties determine the syntax of the <saml:NameIdentifier> element in the assertion:

  Format=urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
  formatting.template=%PRINCIPAL%
  #NameQualifier=https://idp.example.org/shibboleth

By default, the NameIdentifier has an unspecified format. Other formats are possible, for example:

  Format=urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
  formatting.template=uid=%PRINCIPAL%,dc=example,dc=org

Regardless of the format, the Tool replaces the %PRINCIPAL% placeholder with the user name (--user) passed to the application on the command line.

Note: The NameQualifier property SHOULD be omitted in most cases (which is why it's commented out in the config file). However, some relying parties use the NameQualifier property for IdP Discovery, so its use is advisable in some instances.

Configuring SAML Attributes

A single attribute is defined by three properties:

  Attribute.label.Namespace=format
  Attribute.label.Name=name
  Attribute.label.Value=value

where name and value are the Name and Value of the attribute to be asserted. The label is an arbitrary string that distinguishes a triple (Namespace, Name, Value). Any number of such triples are possible, each with its own unique label. Here's an example:

  Attribute.EMAIL.Name=urn:mace:dir:attribute-def:mail
  Attribute.EMAIL.Value=trscavo@gmail.com

Note that the Namespace property of each attribute is optional. If omitted, the standard value

  Attribute.label.Namespace=urn:mace:shibboleth:1.0:attributeNamespace:uri

is used to construct the SAML Attribute.

Configuring the X.509 Issuing Credential

As mentioned in the Getting Started section, the Tool is pre-configured to use a test issuing credential out of the box. For production deployments, you should configure the Tool to use a trusted X.509 credential instead.

The locations of the PEM-encoded certificate and private key of the issuing credential are specified in the config file:

  certLocation=file:/C:/Documents%20and%20Settings/tom%20scavo/Local%20Settings/Temp/x509up_u_tom%20scavo
  keyLocation=file:/C:/Documents%20and%20Settings/tom%20scavo/Local%20Settings/Temp/x509up_u_tom%20scavo

In the above example, the certificate and key are contained in a single file (issued by the GridShib CA, in fact). Usually, however, the PEM-encoded certificate and key are contained in separate files:

  certLocation=file:/C:/shibboleth-idp-1.3/etc/idp-example.crt
  keyLocation=file:/C:/shibboleth-idp-1.3/etc/idp-example.key

See the comments in the default GridShib SAML Tools configuration properties file for more information about issuing credentials.

Known Limitations

Known limitations of the GridShib SAML Tools include:

The SAML Assertion Issuer Tool only supports statically defined SAML attributes (in the config file of choice), all having type xsd:string.
The SAML Assertion Issuer Tool only supports single-valued SAML attributes.
The SAML Attribute Query Client is not fully integrated nor ready for testing.
The Shibboleth Attribute Resolver is not yet integrated.

The GridShib Project
http://gridshib.globus.org/

GridShib SAML Tools Version 0.2.0 Technology Preview 1July 30, 2007