MyGovScot myaccount

The MyGovScot provider is a specialised version of the SAML2 provider. The main difference between it and SAML2 is that it allows the user to be redirected to a MyGovScot specific log out page.

Everything in the SAML2 article also applies to this provider. There are two additional configuration parameters.

Parameters

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

User Profile Data

See the SAML2 User Profile Data section.

Identity Provider Metadata

The Improvement Service (who run mygov.scot myaccount) update their identity provider metadata annually. Once we have received the metadata, usually via a GOSS client who uses the service, we'll include it in the next iCM update, so it is rolled out to all clients who use the MyGovScot provider.

Renewed SSL Certificates

When you renew an SSL certificate we will update the relevant files and contact the Improvement Service. We will deploy the new files to your API Server, which will have an accompanying change control as a restart will also be needed.

Setup

Follow the instructions in SAML2 for setup instructions, with the following exception.

Using a Certificate from a CA in the Production Environment

Unlike MyGovScot's UAT environment, live requires a key pair signed by a trusted CA. This must be acquired by the client or by ourselves on their behalf if we host them. It must be provided to us as a PKCS12 file (.pfx or .p12) - this is a binary format for storing the server certificate, any intermediate certificates, and the private key in a single file.

Several important points:

• We must be given the private key as well as the certificate, not just the certificate. This is a public certificate/private key pair required for signing requests between the Auth worker and the SAML2 identity provider. The private key is required to sign our own requests
• This is NOT an SSL certificate. It does not require any particular SubjectAlternativeName, or any of the usual attributes associated with SSL
• MyGovScot at least will not accept a wild card certificate (eg *.sitename.com)

Once the PKCS12 file containing the certificate and the private key is acquired, perform the following steps:

1. Rename the cacerts file (previously copied from the API Server's Java JRE install) to LIVE_cacerts. This is so we can tell which environment the cacerts file is for use with. Note that by renaming the files you will need to update the cacertsOverridePath in the Worker Configuration Properties
2. Open the LIVE_cacerts file with KeyStore Explorer
3. Import the PKCS #12 file using the entityId as the alias
   1. Click the "Import Key Pair" button
   2. Choose a type of 'PKCS #12'
   3. Input the password, if protected by one (PKCS #12 files can be password encrypted)
   4. Browse to the PKCS #12 file itself and hit 'Import'
   5. Set the key pair alias to be the entityId (i.e. the main subsite URL for the client site as noted in the prerequisites) and import

Example

Also see the SAML2 configuration example. Note that the only differences are that the type is set to "mygovscot" and the additional mygovscot specific parameters above are available.

{
    "providerName": "mygovscot",
    "providerDisplayName": "MyGovScot",
    "type": "mygovscot",
    "userPrefix": "MGS_",
    "profileFieldsToUpdate": ["FIRSTNAME", "LASTNAME"],
    "params": {
        "identityProviderMetadata": {
            // ID of the IDPSSODescriptor identifying the SAML2 endpoint.
            "entityId": "https://idphost.co.uk/idp/shibboleth",
            // URL from which the IdP metadata will be loaded from.
            // Use the "latest" version of the auth worker installed, or use a custom file and point at that instead.
            "idpMetadataFilePath": "${APISERVER}\\workers\\auth\\1.7.10\\conf\\mygovscot\\UAT_idp-metadata.xml"
        },
        "serviceProviderMetadata": {
            // Entity Id value within the SP Metadata File.
            "entityId": "http://example.gossinteractive.com",
            // File path to the SP metadata file.
            "spMetadataFilePath": "${APISERVER}\\data\\auth\\mygovscot\\DEV_serviceProviderMetadata.xml",
            // Certificate Alias - Helpful if it matches entityId. If it doesn't this isn't a problem but might be confusing.
            "spKeyPairAlias": "http://example.gossinteractive.com"
        },
        "userProfileAttributeMapping": { //This depends on your User profile structure etc.
            "mapping": {
                "UCRN": {
                    "mappings": ["UNIQUEID", "UCRN"]
                },
                "TITLE": {
                    "mappings": ["TITLE"]
                },
                "FNAME": {
                    "mappings": ["PREFERREDNAME", "FORENAMES"]
                },
                "MNAME": {
                    "mappings": ["MIDDLENAME"]
                },
                "LNAME": {
                    "mappings": ["SURNAME"]
                },
                "EMAILADDRESS": {
                    "mappings": ["EMAIL"]
                }
            }
        }
    }
}