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
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.
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:
Installation of the GridShib SAML Tools is now complete.
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, testproxy.pem, and testproxy2.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 (and similarly for testproxy2.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 <saml:AuthenticationStatement>
element is to be issued
-c,--x509 Indicates the <saml:Assertion> element is
to be bound to an X.509 proxy certificate
-d,--debug Indicates debugging mode
-E,--x509Lifetime <secs> Lifetime (in seconds) of the proxy
certificate(requires --x509 option)
-e,--lifetime <secs> Lifetime (in seconds) of the SAML
assertion
-f,--config <URL> A configuration file (given as a file:
URL)
-h,--help Displays help message
-m,--authnMethod <URI> SAML AuthenticationMethod URI (requires
--authn option)
-n,--address <IPAddress> Subject IP address (requires --authn
option)
-o,--outfile <path> File to output the SAML assertion (or
proxy certificate if --x509 option specified)
-q,--quiet Indicates quiet mode
-R,--ssoResponse <URL> A SAML Web Browser SSO Response (given as
a file: URL)
-t,--authnInstant <dateTime> SAML AuthenticationInstant (requires
--authn option)
-u,--user <name> 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.
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.
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 \
--authnInstant 2007-08-02T12:10:34-0400 \
--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
--authnInstant 2007-08-02T12:10:34-0400
--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 \
--authnInstant 2007-08-02T12:10:34-0400 \
--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
--authnInstant 2007-08-02T12:10:34-0400
--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.
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
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 IdP.entityID in the properties file. The Issuer Tool sets the Issuer XML attribute of every issued SAML assertion to the value of the IdP.entityID property. If the IdP.entityID 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 IdP.entityID property be configured as a URI. For example:
IdP.entityID=https://gridshib.example.org/idp
In the previous example, the IdP.entityID property has been configured as a URL (which is a kind of URI). It is recommended that the IdP.entityID 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.
Note: SAML metadata will become a required configuration step in the final release of GridShib SAML Tools v0.2.0.
Three config file properties determine the syntax of the <saml:NameIdentifier> element in the assertion:
NameID.Format=urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified NameID.Format.template=%PRINCIPAL% #NameID.NameQualifier=https://idp.example.org/shibboleth
By default, the NameIdentifier has an unspecified format. Other formats are possible, for example:
NameID.Format=urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName NameID.Format.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 NameID.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 NameID.NameQualifier property for IdP Discovery, so its use is advisable in some deployment scenarios.
dateTime PatternThe --authnInstant option takes a dateTime value on the command line (see above for an example). The default format of this dateTime value is given by the following pattern:
dateTime.pattern=yyyy-MM-dd'T'HH\:mm\:ssZ
This line is commented out in the configuration file. To specify an alternative dateTime pattern, uncomment the above line and modify the pattern to taste:
dateTime.pattern=yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
The latter pattern is precisely the pattern used by OpenSAML, but any pattern may be used. The pattern syntax is identical to that used by the SimpleDateFormat Java class.
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.mail.Name=urn:mace:dir:attribute-def:mail Attribute.mail.Value=trscavo@gmail.com
Note that the Namespace property of each attribute is optional. If omitted, the standard value
Attribute.mail.Namespace=urn:mace:shibboleth:1.0:attributeNamespace:uri
is used to construct the SAML Attribute.
Multi-valued attributes are supported. In the case of multiple values, separate each value by a tab character on the righthand side of the Attribute.label.Value line.
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.
The GridShib SAML Tools exposes a Java API for developers. Javadoc documentation will be found at location file://GRIDSHIB_HOME/doc/api/ where GRIDSHIB_HOME is a placeholder for the absolute path to the GridShib installation directory. For example:
UNIX: file:///usr/local/gridshib-saml-tools-0_2_0/doc/api/index.html
Windows: file:/C:/gridshib/gridshib-saml-tools-0_2_0/doc/api/index.html
The corresponding classes are contained in JAR file gridshib-common-0_2_0.jar in the lib directory.
Known limitations of the GridShib SAML Tools include:
xsd:normalizedString.