How to Configure your OIDC Application
Examples
- Some examples can be found at CERN's Gitlab or in the Keycloak Documentation.
Migration Guidelines
- Here are some guidelines for Apache migration to OIDC
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 |
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 thesub
(which duplicatescern_upn
) and is not guaranteed to be unique.cern_upn
andsub
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
ordave@nikhef.nl7778a0f868c7dab
.
Claim | Github | 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 |
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 justopenid
: 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.