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)
cern_identity_id 08d7563a-d25b-a2f0-f637-15e7f2895265 Identity UUID from the authorization service database

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 Guest/Lightweight accounts
cern_upn 6168071@github 11185463@google 9158807@eduid.ch guest:pablo.picasso@example.com
sub 6168071@github 11185463@google 9158807@eduid.ch guest:pablo.picasso@example.com
preferred_username alovelace a.einstein@gmail.com 9158807@eduid.ch (Not provided)
given_name Ada Albert Margaret Pablo
family_name Lovelace Einstein Hamilton Picasso
name Ada Lovelace Albert Einstein Margaret Hamilton Pablo Picasso
email a.lovelace@protonmail.ch a.einstein@gmail.com m.hamilton@hotmail.com pablo.picasso@example.com.

Note: The origin of the identity is not released through SSO. You can restrict access to certain identity providers by using the Levels of Assurance option for your SSO roles. If you need to know the origin you can query the Authorization Service API; the source attribute will identify the origin of the identity, i.e. google|facebook|linkedin|github|edugain. For CERN accounts the source is cern.

Example for the resource_access claim

  "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
account_type Primary Account type, when available: for CERN account holders when they are logged in with their CERN account

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. 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.

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

You can include the following URL parameters (all of them are optional):

  • post_logout_redirect_uri: URL that the user will be redirected to (usually your homepage URL).
  • client_id: Your Client ID.
  • id_token_hint: User's ID Token.

You need to include either the client_id or id_token_hint parameter in case that post_logout_redirect_uri is included. Logout will need to be explictly confirmed by the user unless you include the id_token_hint parameter. You can also include all paramters, as in the following example:

https://auth.cern.ch/auth/realms/cern/protocol/openid-connect/logout?client_id=my-client-id&post_logout_redirect_uri=http://info.cern.ch&id_token_hint=eyJhbGciOiJSUzI1NiIsInR5cC...

Legacy logout with redirect_uri

The following logout URL format was supported by previous versions of the CERN SSO but has been deprecated.

Warning

This logout method is deprecated and it will be removed in the future!

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

If you notice performance issues during logout, please check if you are still using redirect_uri and replace it with:

  • client_id and post_logout_redirect_uri: logout will be faster but it will still need user confirmation.
  • id_token_hint and post_logout_redirect_uri: logout will be faster and users will be automatically redirected.

Troubleshooting

Invalid parameter: redirect_uri

The application owner most likely forgot to declare all used redirect URLs on the Application Portal.

  • Check the URL on the SSO webpage where you get the error; it will be something like https://auth.cern.ch/auth/realms/cern/protocol/openid-connect/auth?client_id=users-portal&redirect_uri=https%3A%2F%2Fusers-portal.web.cern.ch%2F&some_other_stuff=xyz
  • Decode the redirect_uri parameter from the URL
  • Make sure that the decoded value matches one of the valid redirect URLs in the SSO registration on the Application Portal (the match is case-sensitive)

(When specifying redirect URLs in the Application Portal, it's a good practice to list exact URLs rather than using wildcards excessively. This enhances security by ensuring that only trusted endpoints are allowed, thereby minimizing the risk of redirect-based attacks.)