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, the install script generates a Java KeyStore containing a test credential, 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.
To install the GridShib SAML Tools, download the distribution file into a working directory (e.g., /tmp/gridshib-saml-tools-0_1_2.tar.gz) and perform the following two-step installation process:
Unpack the GridShib SAML Tools distribution file. For example, on UNIX systems type:
$ cd /tmp $ gunzip /tmp/gridshib-saml-tools-0_1_2.tar.gz $ tar xvf /tmp/gridshib-saml-tools-0_1_2.tar
Run 'ant install' on the GridShib SAML Tools build file (/tmp/gridshib-saml-tools-0_1_2/build.xml). This creates a JAR file and runs a test script. For example, on UNIX systems type:
$ cd /tmp/gridshib-saml-tools-0_1_2 $ 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.
To get started using the Tool, adjust the permissions on the scripts in the bin directory (if necessary) and type:
UNIX: $ export GRIDSHIB_HOME=/tmp/gridshib-saml-tools-0_1_2 $ $GRIDSHIB_HOME/bin/gridshib-saml-issuer --help
Windows: > set GRIDSHIB_HOME=c:\temp\gridshib-saml-tools-0_1_2 > %GRIDSHIB_HOME%\bin\gridshib-saml-issuer --help
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. You can read the output SAML assertion with an ordinary 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/tools/gridshib-saml-issuer.properties
Windows: > more < %GRIDSHIB_HOME%\etc\gridshib\tools\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 below).
An AuthenticationStatement may be 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 and --authnInstant (which we do not illustrate here).
To bind the SAML assertion to an X.509 proxy certificate, type:
UNIX:
$ $GRIDSHIB_HOME/bin/gridshib-saml-issuer --user trscavo \
--authn --x509 --outfile $GRIDSHIB_HOME/testcert.pem
Windows:
> %GRIDSHIB_HOME%\bin\gridshib-saml-issuer --user trscavo
--authn --x509 --outfile %GRIDSHIB_HOME%\testcert.pem
You can use openssl to view the content of the certificate:
UNIX: $ openssl x509 -text -noout -in testcert.pem
The default GridShib SAML Tools configuration properties file is located at
$GRIDSHIB_HOME/etc/gridshib/tools/gridshib-saml-issuer.properties
You can modify the default config properties file to suit your needs, or you can create a new properties file altogether (recommended):
UNIX:
$ cp $GRIDSHIB_HOME/etc/gridshib/tools/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\tools\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
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 (which is why it's commented out in the config file).
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.
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.
As mentioned in the Getting Started section, the Tool is pre-configured to use a script-generated Java KeyStore out of the box. For production deployments, you should configure the Tool to use a trusted X.509 credential.
The locations to 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 scavo keyLocation=file:/C:/Documents%20and%20Settings/tom%20scavo/Local%20Settings/Temp/x509up_u_tom scavo
In the above example, the certificate and key are contained in the same file (issued by the GridShib CA). Usually, however, the 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
Alternatively, the issuing credential might be contained in a secure Java KeyStore:
keyStoreLocation=file:/C:/shibboleth-idp-1.3/etc/gridshib-idp/idp-example.jks keyStorePassword=exampleorg keyStoreKeyAlias=tomcat keyStoreKeyPassword=exampleorg
In the previous example, the keyStorePassword and keyStoreKeyPassword are the same, but in general the two passwords can (and should) be distinct.
See the default GridShib SAML Tools configuration properties file for more information.
Known limitations of the GridShib SAML Tools include:
--authnInstant and --quiet are not yet supported.xsd:string.