Introduction

This page explains what identities and credentials are and how they are related when working within federations.

Definitions

IDP_HOME

This is where the IdP is installed, e.g.

/web/WWW/guanxi_idp

Where the identity and credential information is stored

The IdP stores its identity and credential information in the file:

IDP_HOME/WEB-INF/guanxi_idp/config/idp.xml

Identity

The IdP's identity determines the ID used to issue SAML assertions and it depends on which Service Provider the IdP is talking to. This is necessary as sometimes the IdP is forced to use a specific identity given to it by a federation. This was common in the early days of Shibboleth federations but is thankfully not so common now. The link between a Service Provider and an IdP identity is specified in the idp.xml file:

<service-provider name="urn:scaramanga:den:of:thieves" identity="mi5SelfSignedIdentity" creds="mi5SelfSignedCreds"/>

if we look at the corresponding identity "mi5SelfSignedIdentity", we see that it is defined as:

<identity name="mi5SelfSignedIdentity">
  <issuer>urn:bond:hq:self:signed</issuer>
  <name-qualifier>urn:bond:hq:self:signed</name-qualifier>
  <format>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</format>
</identity>

issuer and name-qualifier are normally the same, while format is always set to urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified when working in a Shibboleth federation.

Using this identity to issue SAML Assertions results in the following assertion:

<saml:Assertion AssertionID="5efc717e11c0d933881778f" MajorVersion="1" MinorVersion="1" Issuer="urn:bond:hq:self:signed" IssueInstant="2008-09-01T08:29:18Z">

Credentials

Before a SAML Assertion can be issued, using the identity described above, the assertion must be digitally signed and this is where credentials come in. Looking again at the example Service Provider configuration in idp.xml:

<service-provider name="urn:scaramanga:den:of:thieves" identity="mi5SelfSignedIdentity" creds="mi5SelfSignedCreds"/>

we look at the creds block in idp.xml:

<creds name="mi5SelfSignedCreds">
  <keystore-type>jks</keystore-type>
  <keystore-file>IDP_HOME/WEB-INF/guanxi_idp/keystore/guanxi_idp.jks</keystore-file>
  <keystore-password>-1166844024</keystore-password>
  <private-key-alias>idp</private-key-alias>
  <private-key-password>-1166844024</private-key-password>
  <certificate-alias>idp</certificate-alias>
  <key-type>dsa</key-type>
</creds>

and we can see that the IdP will load the credentials stored in the file:

IDP_HOME/WEB-INF/guanxi_idp/keystore/guanxi_idp.jks

and will use the private key contained in it to sign the SAML Assertion. So there are two parts to issuing a SAML Assertion. First, there is the identity used which determines the Issuer of the Assertion and there are the credentials, which are used to digitally sign the Assertion. Credentials are important as some federations only accept certificates issued by certain commercial Certificate Authorities (CA), so it's important the IdP can pick 'n mix credentials to match federations.

Using a commercial grade certificate with the IdP

The default keystore that the IdP creates on first startup contains a self signed certificate, which is not suitable for production use. Therefore, it's necessary to get hold of a commercial grade certificate, issued by a CA that is supported by the federation in which the IdP intends to operate. Let's follow the process from scratch.

First, create the initial IdP certificate:

keytool -genkey -keyalg RSA -alias bond.hq.ac.uk -keystore bond.hq.ac.uk.jks
 
Enter keystore password:  secretpassword
What is your first and last name?
  [Unknown]:  bond.hq.ac.uk
What is the name of your organizational unit?
  [Unknown]:  Special Ops
What is the name of your organization?
  [Unknown]:  MI5
What is the name of your City or Locality?
  [Unknown]:  London
What is the name of your State or Province?
  [Unknown]:  England
What is the two-letter country code for this unit?
  [Unknown]:  GB
Is CN=bond.hq.ac.uk, OU=Special Ops, O=MI5, L=London, ST=England, C=GB correct?
  [no]:  yes
 
keep the keystore and private key passwords the same.

next, create a Certificate Signing Request (CSR):

keytool -certreq -alias bond.hq.ac.uk -keyalg RSA -file bond.hq.ac.uk.csr -keystore bond.hq.ac.uk.jks

send the file bond.hq.ac.uk.csr to your commercial CA of choice (e.g. Thawte etc) and get the signed certificate back. Add this to the keystore:

keytool -import -alias bond.hq.ac.uk -trustcacerts -file bond.hq.ac.uk.crt -keystore bond.hq.ac.uk.jks
 
where the file bond.hq.ac.uk.crt is the signed certificate you got back from the CA.

Next, record the new identity and credential information in the IdP's config file, idp.xml and link them to the Service Provider:

<identity name="mi5Identity">
  <issuer>urn:bond:hq</issuer>
  <name-qualifier>urn:bond:hq</name-qualifier>
  <format>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</format>
</identity>
 
<creds name="mi5Creds">
  <keystore-type>jks</keystore-type>
  <keystore-file>IDP_HOME/WEB-INF/guanxi_idp/keystore/bond.hq.ac.uk.jks</keystore-file>
  <keystore-password>secretpassword</keystore-password>
  <private-key-alias>bond.hq.ac.uk</private-key-alias>
  <private-key-password>secretpassword</private-key-password>
  <certificate-alias>bond.hq.ac.uk</certificate-alias>
  <key-type>RSA</key-type>
</creds>
 
<service-provider name="urn:scaramanga:den:of:thieves" identity="mi5Identity" creds="mi5Creds"/>

You now have a production grade IdP when communicating with the Service Provider identified as urn:scaramanga:den:of:thieves.

Registering a Service Provider with an existing identity/credential pair

If you have already obtained a commercial grade certificate for use in a federation and you want the IdP to communicate with a new Service Provider, that's just joined the federation for example, all you have to do is associate the new Service Provider's providerId, with the commercial grade identity/creds pair:

<commercialGradeIdentity>
 ...
</commercialGradeIdentity>
 
<commercialGradeCreds>
 ...
</commercialGradeCreds>
 
<service-provider name="urn:new:sp:provider:id" identity="commercialGradeIdentity" creds="commercialGradeCreds"/>

Federation metadata and identity/creds pairs

The manual pairing of identity/creds pairs in idp.xml does not scale to large federations, where there may be thousands of Service Providers. In this case, you should use the default identity/creds pair defined by the DEFAULT Service Provider:

<service-provider name="DEFAULT" identity="commercialGradeIdentity" creds="commercialGradeCreds"/>

If a request comes in from a Service Provider not defined in a service-provider node, the IdP will use the identity/creds pair defined by the DEFAULT service-provider node.