Skip to content

How to Configure your SAML Applications

Examples

Some examples can be found at CERN's Gitlab or in the Keycloak Documentation.

Migration Guidelines

Configuration/Troubleshooting checklist

Usually, SAML Service Providers (i.e. your SAML application) require minimal configuration beyond trusting CERN's Identity Provider metadata. If you're experiencing issues, please follow the list below.

  • For SAML Service Providers on a non-CERN domains
    • I need to have the domain added to the listed of trusted domains (Please send a request to the SSO Service)
  • For all SAML Service Providers
    • If I am using signing certificates, my metadata identifies the key that will be used for signing by adding a tag <md:KeyDescriptor use="signing">
    • The entityID in my metadata matches the Issuer of the SAML requests sent by my service
    • I have created an application in the Application Portal and added a SAML SSO Registration where I have pasted my metadata. If you're using Shibboleth, see the dedicated guidelines for Shibboleth migration for how to generate your metadata.
    • I am trusting CERN's Identity Provider metadata (either by downloading it or specifying the url: https://auth.cern.ch/auth/realms/cern/protocol/saml/descriptor)

What will be in your tokens?

Please note: although the attributes are considered fixed, the values may change slightly as the infrastructure evolves. Additional attributes may be added.

Field Example Usage Note
upn mcurie User Principal Name, this is unique and can be used to identify a user.
PersonID 754321 CERN PersonID, for known CERN users
Firstname Marie
Lastname Curie
displayName Marie Curie Display purposes
EmailAddress marie.curie@cern.ch Communication
PreferredLanguage FR EN or FR, CERN Official Language
eduPersonOrcid 0000-0002-1825-0097 Only returned if the user has linked an ORCID to their Identity
uidNumber 55555 Unix ID, for CERN account holders only
gidNumber 5555 Unix group ID, for CERN account holders only
CernRoles "user", "editor" Roles are defined per application and assigned to groups. Use this for access control.
CernRolesMissingLoa "app-user" Roles that the current user has, but are not assigned because the user must log in using an account with a higher Level of Assurance (e.g. a CERN account instead of a social account)
CernRolesMissingMfa "manager" Roles that the current user has, but are not assigned because the user must log in using a Two-factor Authentication method (i.e. Authenticator App or Yubikey)
CernMailUpn mcurie@cern.ch A claim in the format "[login]@cern.ch" exclusively for CERN accounts. It can be used as an alternative identifier. The name of this claim might change in the future.
HomeInstitute University of Paris Home institute, when available: for CERN account holders, users and associates

Metadata

Metadata is normally generated by your Service Provider software, but you may wish to generate it yourself. You can use a tool such as onelogin SAML Developer Tools to construct metadata manually.

SAML NameID

You can modify the value returned in the SAML token subject by requesting a particular NameID Format in your SAML Metadata. If you specify multiple, the first will apply. The following are supported:

<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
<md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
<md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>
<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>

Logout

If you want to include a Logout button from your application, be sure to include metadata for the endpoint where the logout response will be returned e.g.

<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://cern.ch/testapp"/>
We do not recommend forcibly logging people out of SSO as this causes significant confusion for users; if you need to restrict access to your application after a specific period that is shorter than the SSO session lifetime, please handle it within your application logic.

Signing and Encryption

We strongly recommend that your SAML Service Provider signs its Authentication Requests, this mitigates the risk of impersonation. Similarly, requesting encrypted tokens adds a layer of security. CERN's Identity Provider will require signature, and encrypt tokens, based on the certificates included in your metadata.

How to signal that you are signing Authentication Requests

If your metadata includes a signing certificate (see example below, note the signing element), CERN's Identity Provider will require all Authentication Requests from your SAML Service Provider to be signed. If you do not include this signing certificate, CERN's Identity Provider will accept unsigned Authentication Requests.

<md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIID2zCCAs...MONRk1/jw4w==</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>

How to request encrypted tokens

If your metadata includes an encryption certificate (see example below, note the encryption element), CERN's Identity Provider will encrypt tokens issued to your SAML Service Provider. If one is not included, tokens will be sent unencrypted.

<md:KeyDescriptor use="encryption">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIID2zCCA...JMONRk1/jw4w==</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>