SAML2

A full description of SAML2 is out of scope of this document. See the SAML2 core, binding, and metadata specifications and other internet resources for details.

The SAML2 Identity Provider (IDP) must support Service Provider (SP) initiated authentication, HTTP-REDIRECT binding using DEFLATE encoding, and HTTP-POST binding. Such support is indicated by the following XML elements in the Identity Provider's metadata, specifically underneath the IDPSSODescriptor element:

<SingleSignOnService Binding="urn:mace:shibboleth:1.0:profiles:AuthnRequest" Location="https://uat.signin.mycas.org.uk/idp/profile/Shibboleth/SSO"/><SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://uat.signin.mycas.org.uk/idp/profile/SAML2/POST/SSO"/><SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://uat.signin.mycas.org.uk/idp/profile/SAML2/Redirect/SSO"/>

Parameters

As well as the parameters described in Base Provider Parameters, the following must be set in the params object.

Example

{
    "providerName": "examplesaml2provider", 
    "providerDisplayName": "Example SAML2 Provider", 
    "type": "saml2", 
    "userPrefix": "EX_", 
    "params": {
        "identityProviderMetadata": {
            // ID of the IDPSSODescriptor identifying the SAML2 endpoint
            // we're interested in.
            "entityId": "https://idphost.co.uk/idp/shibboleth", 
            // URL from which the IdP metadata will be loaded from.
            // Could also be supplied as a local file via the exclusive
            // idpMetadataFilePath parameter as below for the SP.
            "idpMetadataUrl": "https://idphost.co.uk/idp-metadata.xml", 
            // Alias for the IdP's public certificate, as stored in the 
            // Auth worker's cacerts key store.
            "idpCertificateAlias": "idphost.co.uk_cert"
        }, 
        "serviceProviderMetadata": {
            // ID of the EntityDescriptor within the service provider 
            // metadata.
            "entityId": "http://test.gossinteractive.com", 
            // File path to the SP metadata file. 
            // Could also be supplied as a URL to a file via the exclusive
            // spMetadataFileUrl parameter as above for the IdP.
            "spMetadataFilePath": "E:/sp/service-provider-metadata.xml", 
            // Alias for the SP's key pair as stored in the Auth worker's
            // cacerts key store.
            "spKeyPairAlias": "http://test.gossinteractive.com_keypair"            
        }, 
        "userProfileAttributeMapping": {
            "mapping": {
                "UCRN": {
                    "mappings": ["UNIQUEID", "UCRN"] 
                }, 
                "TITLE": {
                    "mappings": ["TITLE"]
                }, 
                "FNAME": {
                    "mappings": ["PREFERREDNAME", "FORENAMES"]
                }, 
                "MNAME": {
                    "mappings": ["MIDDLENAME"]
                }, 
                "LNAME": {
                    "mappings": ["SURNAME"]
                }, 
                "EMAILADDRESS": {
                    "mappings": ["EMAIL"]
                }
            }
        }
    }
}

Identity Provider Metadata

Details about the identity provider (the third party) are stored in a structured XML format defined in the SAML2 Metadata Specification. The IdP metadata supplies information about what bindings are supported, the URLs associated with those bindings, supported identifier formats, public certificates, and so on.

Service Provider Metadata

Details about the service provider (the Auth worker) are stored in a structured XML format defined in the SAML2 Metadata Specification. Here's an example, although the full X509Certificate values have been trimmed for brevity:

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://demodev1.gossinteractive.com" ID="pfx4fcd1234-2cf3-d4d0-1234-819e7eb21234">
   <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
      <md:KeyDescriptor use="signing">
         <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:X509Data>
               <ds:X509Certificate>MII...PzE=</ds:X509Certificate>
            </ds:X509Data>
         </ds:KeyInfo>
      </md:KeyDescriptor>
      <md:KeyDescriptor use="encryption">
         <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:X509Data>
               <ds:X509Certificate>MII...PzE=</ds:X509Certificate>
            </ds:X509Data>
         </ds:KeyInfo>
      </md:KeyDescriptor>
      <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://demodev1.gossinteractive.com/apiserver/auth/http/reentry" />
      <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
      <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://demodev1.gossinteractive.com/apiserver/auth/http/reentry" index="0" isDefault="true" />
   </md:SPSSODescriptor>
</md:EntityDescriptor>

Setup

Two things must be known before starting:

1. The subsite URL for the client site which is used as the SAML2 entityID and the alias of the corresponding key pair in the cacerts file. Referred to as the 'entityID' from here on.
2. The URL to the auth worker's reentry method for all non-live environments. For example: http://www.{{CLIENT}}-dev/apiserver/auth/http/reentry

Two files are needed before starting:

1. A default java cacerts file from the current version of the API Server. Acquire one from: ${APIServer}/java7/jre/lib/security/cacerts
2. A service provider metadata file. See the template above.

Check the following:

1. The type of user profile on the current iCM installation. This is relevant to creating the user attribute to user profile mappings later on. Is it flat (EMAIL) or nested (USER.CONTACT.ETC.EMAIL)? What are the field names (FORENAME or FIRSTNAME, etc)?
2. If a generic SAML2 provider rather than MyGovScot, check that the identity provider metadata specifies support for AuthnRequest and HTTP-Redirect/HTTP-POST bindings (described right at the top of this page)

Key Pair Generation - Self Signed Certificates

Unlike TLS, where browsers use a list of trusted certificate authorities, SAML federation can use self-signed certificates because the trust can be established explicitly. That is, you can send your public key (part of the certificate) to your partner through a different channel, such as email. The partner then installs it and explicitly trusts that certificate only. There's no need for them to trust a third-party CA. This kind of trust can use self-signed certificates without worry.

The following details how to generate a self-signed certificate using KeyStore Explorer.

1. Rename the cacerts file (previously copied from the API Server's Java JRE install) to {{PREFIX}}_cacerts, where {{PREFIX}} is the environment. This is so we can tell which environment the cacerts file is for use with, e.g. DEV_cacerts, PROD_cacerts, etc. Note that by renaming the files you will need to update the cacertsOverridePath in the Worker Configuration Properties
2. Open the {{PREFIX}}_cacerts file with KeyStore Explorer
3. Generate a self-signed key pair (certificate and private key) with a password of 'changeit' using KeyStore Explorer and store it in the cacerts file
   1. Click the "Generate Key Pair" button
   2. Hit 'OK' to generate the key
   3. Set a two year validity period
   4. Click the address book icon to set the certificate information. Enter the entityID (ie the main subsite URL for the client site as noted in the prerequisites) as the CN. See below for an example for gossdevteamweb1:
      1. CN=http://gossdevteamweb1.storm50.com
      2. OU=Development
      3. O=GOSS Interactive Ltd
      4. L=Plymouth
      5. ST=Devon
      6. C=UK
      7. E=someone@mywebsite.com
   5. Set the key pair alias to the entityId/CN. This alias name will need to be referred to in the provider configuration file later

Setting up Service Provider Metadata, Provider Configuration, Server Files

1. Export the certificate from the key pair as X501
   1. Right click the new key pair entry, then Export, then Export certificate chain
   2. Leave everything as default
   3. Set the export path, and hit export
   4. Keep this file to hand
2. Populate the skeleton service provider metadata file
   1. Replace {{ENTITYID}} with the entityId
   2. Replace {{PUBLIC_KEY}} with the (formatted) public key as exported in the previous step
      1. Open the .cer file exported in the previous step
      2. Remove the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines from the top and bottom of the file
      3. Replace the {{PUBLIC_KEY}} placeholders with the resulting newline delimited base 64 text
   3. Replace {{CLIENT_URL}} within the AssertionCustomerService element appropriately, such that the 'Location' attribute contains the URL to the Auth worker's /http/reentry method
      1. If adding more than one AssertionCustomerService (eg creating a single non-live service that supports multiple non-live environments such as DEV, QA, etc.)a dd in additional AssertionCustomerService elements, setting the additional Location and index to previous+1 each time, ensure that only one AssertionCustomerService entry has isDefault="true" set, and if using a non-default AssertionCustomerService then the provider setting serviceProviderMetadata.assertionConsumerServiceIndex (in the API Server configuration) must be set to the index to use on the server matching that URL
3. To install the Live or UAT service at the SAML2 IDP end, send an email to your contact with a zip file attachment containing the service provider metadata and the previously exported public certificate
4. Populate the API Server configuration file with the provider details described at the start of this article
5. Put the cacerts file containing the key pair under ${APISERVER}/data/auth/cacerts. If the cacerts file has been renamed for each environment (as recommended), eg DEV_cacerts, LIVE_cacerts etc, then the worker level configuration property cacertsOverridePath for that environment will also need to be set to point to the rename file file, eg ${APISERVER}/data/auth/LIVE_cacerts
6. Put the service provider metadata file under ${APISERVER}/data/{{PROVIDERNAME}}/[DEV|LIVE]_serviceProviderMetadata.xml
7. Update the API Server configuration and resend