...

A typical process for setting up SAML login requires coordination with the administrator of the SAML identity provider (IdP).

1. Request the metadata URL of the IdP from its administrator. Also communicate the attributes that need to be released (made available) in the SAML response from the IdP. CollectionSpace requires the following attributes:

   • Email address. When a user first logs in using SSO, this is used to associate the user on the IdP to an existing CollectionSpace user account. If no account exists with a username that is equal to the email address, the log in fails. (There is currently no auto-registration feature for users on the IdP that do not have an existing CSpace account.) This can be released as either an attribute or the NameID of the SAML assertion. Ask the administrator of the IdP for the attribute name that will be used (or if it will be the NameID of the assertion).

   • User ID. This should be a persistent identifier used by the IdP to uniquely and permanently identify a user. This can be the same

...

1. • as the user’s email, but only if the user’s email on the IdP is never expected to change. When a user first logs in using SSO, and their CSpace account is successfully located using the email address, this ID is stored, and subsequent logins will be able to associate a user on the IdP to a CSpace user using this ID, even if the user’s email changes on the IdP. This can be released as either an attribute or the NameID of the SAML assertion. Ask the administrator of the IdP for the attribute name that will be used (or if it will be the NameID of the assertion).

   • Full name. The user’s full name. This is not currently used, but will be used in the future to auto-register new CSpace users

...

1. • . Ask the administrator of the IdP for the attribute name that will be used.

2. Configure SSO for CSpace using the instructions below. Add a relying party registration, setting the metadata URL of the provider to the URL received in Step 1. Configure the locations to probe for the email address and user id, using the information received in Step 1.

3. Start CollectionSpace.

4. Provide the metadata URL of the SAML relying party added in step 2 to administrator of the IdP.

5. The administrator of the IdP communicates that the connection is ready. Test a login. When a SAML assertion is received from the IdP, the NameID and attributes are logged to cspace-services.log. Confirm that the expected NameID and attributes are received.

Creating a file to store local configuration

...

<?xml version="1.0" encoding="UTF-8"?>

<svc:service-config
    xmlns:svc='http://collectionspace.org/services/config'
    xmlns:merge='http://xmlmerge.el4j.elca.ch'
>
    <security>
        <sso>
            <saml>
                <single-logout />

                <relying-party-registrations>
                    <relying-party id="auth0">
                        <name>Auth0</name>
                        <icon location="https://cdn.auth0.com/manhattan/versions/1.4478.0/assets/badge.png" />
                        <metadata location="https://dev-vynkcnqhac3c0s10.us.auth0.com/samlp/metadata/aiXoltFSsQymeHorBxWM5pGLxnslocpe" />

                        <assertion-username-probes>
                            <attribute name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" />
                        </assertion-username-probes>

                        <assertion-sso-id-probes>
                            <name-id />
                            <attribute name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" />
                        </assertion-sso-id-probes>

                        <signing-x509-credentials>
                            <x509-credential>
                                <private-key location="file:///home/collectionspace/tomcat/cspace/services/credentials/private.key" />
                                <x509-certificate location="file:///home/collectionspace/tomcat/cspace/services/credentials/certificate.crt" />
                            </x509-credential>
                        </signing-x509-credentials>

                        <decryption-x509-credentials>
                            <x509-credential>
                                <private-key location="file:///home/collectionspace/tomcat/cspace/services/credentials/private.key" />
                                <x509-certificate location="file:///home/collectionspace/tomcat/cspace/services/credentials/certificate.crt" />
                            </x509-credential>
                        </decryption-x509-credentials>
                    </relying-party>
                </relying-party-registrations>
            </saml>
        </sso>
    </security>
</svc:service-config>

...

The required location attribute contains the URL of the metadata. This may be a file:// URL, if the metadata can be found in a local file.

assertion-username-probes

A list of locations in a SAML assertion returned by the identity provider to look for the username of a CollectionSpace user. A location is either an attribute in the assertion or the NameID of the assertion. Each location is probed in the order given. If it contains something that looks like an email address, an attempt is made to locate a CSpace user whose username is equal to that email. Once a user is found, probing of locations stops.

name-id

Specifies that the NameID of the assertion is a possible location of the email/username.

attribute

Specifies that an attribute in the assertion is a possible location of the email/username. The required name attribute specifies the name of the attribute in the assertion.

Defaults to:

<name-id />

<attribute name="urn:oid:0.9.2342.19200300.100.1.3" />

<attribute name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" />

<attribute name="email" />

<attribute name="mail" />

assertion-sso-id-probes

A list of locations in a SAML assertion returned by the identity provider to look for the SSO ID of a CollectionSpace user (the persistent ID of the user in the identity provider). A location is either an attribute in the assertion or the NameID of the assertion. Each location is probed in the order given. Once a non-null value is found, probing stops.

name-id

Specifies that the NameID of the assertion is a possible location of the SSO ID.

attribute

Specifies that an attribute in the assertion is a possible location of the SSO ID. The required name attribute specifies the name of the attribute in the assertion.

Defaults to:

<name-id />

signing-x509-credentials

A list of credentials to use for signing SAML requests issued by CollectionSpace. Typically, you will only specify a single credential (private key and certificate pair). A credential is required if the identity provider requires login requests to be signed (as reported in its metadata), or if single logout is enabled. Otherwise, signing credentials are optional.

...