OpenID Connect scopes and claims
To issue an ID token, the authorization request must contain at least the openid scope. To control which user claims are included in the ID token, specify additional scopes.
The table below summarizes the scopes that are relevant for OpenID Connect.
| scope | Description |
|---|---|
| openid | Activates the OpenID functionality and allows you to issue an ID token as a part of an OAuth 2.0 authorization request. |
| profile | Requests access to the following claims: name, family_name, given_name, nickname, preferred_username, gender, birthdate, locale. |
Requests access to the following claims: email and email_verified. |
|
| address | Requests access to the address claim that is composed of the following fields: street_address, locality, region, postal_code, country |
| phone | Requests access to the following claims: phone_number and phone_number_verified. |
The claims are obtained from the identity provider (IDP) using the person API and mapped as listed below:
| claim | Person API source |
|---|---|
| name | profile > name > first + last |
| given_name | profile > name > first |
| family_name | profile > name > last |
| nickname | profile > name > display_name |
| preferred_username | profile > name > display_name |
| gender | profile > gender |
| birthdate | profile > date_of_birth |
| locale | profile > preferred_locale |
| profile > email_addresses > value | |
| email_verified | profile > email_addresses > verified |
| phone | profile > phone_numbers > value |
| phone_number_verified | profile > phone_numbers > verified |
| address > street_address | profile > address > street_name + house_number + house_number_addition |
| address > locality | profile > address > city |
| address > region | profile > address > region |
| address > postal_code | profile > address > postal_code |
| address > country | profile > address > country_name |
Custom claims
Custom claims that are defined and returned by the OneWelcome Identity Platform share a constant prefix urn:onegini.com:oidc value. This prefix uniquely identifies their source and prevents potential clashes or collisions.
Optional claims
ACR
Note
This feature requires the use of the the CIM component (formerly Onegini CIM) as the IDP.
Use Authentication Context Class Reference (ACR) to request that a specific authentication context must be met upon successful authentication.
The table below summarizes the supported values. The available values are also exposed with the Discovery API.
| ACR value | Description |
|---|---|
| urn:onegini.com:oidc:authentication_level:1 | Requires an authentication level of at least 1 from the CIM. |
| urn:onegini.com:oidc:authentication_level:2 | Requires an authentication level of at least 2 from the CIM. |
| urn:onegini.com:oidc:authentication_level:3 | Requires an authentication level of at least 3 from the CIM. |
| urn:onegini.com:oidc:authentication_level:4 | Requires an authentication level of at least 4 from the CIM. |
To request a specific ACR value, include the acr_values parameter when requesting an ID token.
Example request:
http://tokenserver.example.com/oauth/authorize?response_type=code&client_id=openid&redirect_uri=http%3A%2F%2F.example.com&scope=openid&state=d5dbda85-ecdb-4172-9ada-7ba15c6982d0&acr_values=urn:onegini.com:oidc:authentication_level:2
Only a single ACR value can be specified at a time. Sending multiple values results in a Bad Request error.
The OneWelcome Identity Platform might return an ACR with a value that is higher than the authentication level that was requested.
Authentication level
You can specify the required user authentication level. Depending on the required authentication level, the user might be requested to perform step-up authentication. For example, to access a resource, the user might be requested to authenticate with a password and SMS code. The service provider can be configured in the OneWelcome Identity Platform IdP to require a specific authentication level. The service provider can override it using the authentication_level request parameter. The following is an authentication request example: http://idp.com/saml/single-sign-on?authentication_level=3.
For more information, see the OpenID Specification.
Custom attributes
Note
This feature requires the CIM component.
The CIM supports custom attributes for a user. These attributes are included as claims within an ID token.
