Skip to content

How to Configure your OIDC Application

Examples

Migration Guidelines

Configuration Checklist

The main OIDC configuration for CERN's SSO can be found at the "well-known" endpoint. Key information is included below to get you started:

{
  "issuer":"https://auth.cern.ch/auth/realms/cern",
  "authorization_endpoint":"https://auth.cern.ch/auth/realms/cern/protocol/openid-connect/auth",
  "token_endpoint":"https://auth.cern.ch/auth/realms/cern/protocol/openid-connect/token",
  "token_introspection_endpoint":"https://auth.cern.ch/auth/realms/cern/protocol/openid-connect/token/introspect",
  "userinfo_endpoint":"https://auth.cern.ch/auth/realms/cern/protocol/openid-connect/userinfo",
  "end_session_endpoint":"https://auth.cern.ch/auth/realms/cern/protocol/openid-connect/logout",
  "jwks_uri":"https://auth.cern.ch/auth/realms/cern/protocol/openid-connect/certs",
}

You will also have to configure the Client ID and Client Secret for your application - these are provided by the Application Portal.

Depending on the libraries you use, you may have to specify this configuration under different variable names.

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.

The following claims are included by default in Access and ID tokens. Some claims may not always be in the token: in these cases, the claim is missing or it contains an empty list (e.g. if this resource_access claim is missing there are no roles assigned to the user for the current application).

Claim CERN Account Example Usage Note
cern_upn mcurie User Principal Name, this is unique and can be used to identify a user
sub mcurie Duplicate of cern_upn, unique
preferred_username mcurie Informational/display purposes only (not to be treated as unique)
given_name Marie
family_name Curie
name Marie Curie Display purposes
email marie.curie@cern.ch Communication
cern_person_id 754321 CERN PersonID, only available for known CERN users
cern_mail_upn 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.
cern_preferred_language FR EN or FR, CERN Official Language
eduperson_orcid 0000-0002-1825-0097 Only returned if the user has linked an ORCID to their Identity
scope openid profile email Standard OIDC claim stating which user data is included in the token. CERN SSO returns the openid, profile and email scopes.
aud my-application Application for which the token is issued
resource_access See example below Roles are defined per application and assigned to groups. Use this for access control. The list of roles for your aplication is available in resource_access.{application_name}.roles
cern_roles ["user","editor"] Duplicate of the list in resource_access.{application_name}.roles
cern_roles_missing_loa ["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)
cern_roles_missing_mfa ["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)

Non-CERN Account Examples

The following table contains example values of personal information for Github, Google and eduGAIN accounts. Please note:

  • preferred_username is set by the Identity Provider, is not guaranteed to match the sub (which duplicates cern_upn) and is not guaranteed to be unique.
  • cern_upn and sub for eduGAIN users may have a variety of formats. We choose the best possible unique identifer that is released by the eduGAIN Identity Provider, e.g. 9158807@eduid.ch, /sazwufq+pmpfe16g=@stfc.ac.uk or dave@nikhef.nl7778a0f868c7dab.
Claim Github Google eduGAIN
cern_upn 6168071@github 11185463@google 9158807@eduid.ch
sub 6168071@github 11185463@google 9158807@eduid.ch
preferred_username alovelace a.einstein@gmail.com 9158807@eduid.ch
given_name Ada Albert Margaret
family_name Lovelace Einstein Hamilton
name Ada Lovelace Albert Einstein Margaret Hamilton
email a.lovelace@protonmail.ch a.einstein@gmail.com m.hamilton@hotmail.com

Example for resource_access

  "resource_access": {
    "my-application": {
      "roles": [
        "user",
        "editor"
      ]
    }
  },

UserInfo endpoint

The following additional claims can be retrieved from the UserInfo endpoint.

Field Example Usage Note
cern_uid 55555 Unix ID, for CERN account holders only
cern_gid 5555 Unix group ID, for CERN account holders only
home_institute University of Paris Home institute, when available: for CERN account holders, users and associates

Scopes

We currently support two main sets of scope values in the token request:

  • OIDC: openid profile email or just openid: The response will contain an Access Token and an ID Token with all the user profile information and email address.
  • OAuth2: profile email or no scopes: The response will only contain an Access Token with all the user profile information and email address.

Other standard OpenID Connect scopes, such as phone and address will be accepted for compatibility, but they are unsupported. Their response may contain invalid or missing information.

Logout

When a user logs out from your application, we recommend requesting a Single Sign-On logout as well. Many OIDC libraries will handle this automatically by getting the end_session_endpoint value from the "well-known" endpoint.

If your library doesn't do that automatically, please redirect the logout requests yourself to the end_session_endpoint for auth.cern.ch:

https://auth.cern.ch/auth/realms/cern/protocol/openid-connect/logout?redirect_uri=encodedRedirectUri

Replace encodedRedirectUri above with your homepage URL.