PingOne Advanced Identity Cloud

Authentication requirements

A relying party (RP) can have different authentication requirements for different protected resources. For example, a financial services provider accepts username and password authentication to create an account, but requires multi-factor authentication to download bank account statements.

PingOne Advanced Identity Cloud lets you associate requirements with authentication journeys. RPs specify the authentication requirements in their requests, and PingOne Advanced Identity Cloud uses the associations to authenticate the end user with the requested journey and honor the requirements.

PingOne Advanced Identity Cloud communicates the honored requirements by optionally returning claims in ID tokens. It uses the following standard claims:

  • An authentication context class reference (acr) claim holds a case-sensitive string identifying the class of authentication methods or procedures the authentication process satisfied; for example, an identifier for the authentication journey the end user completed successfully.

  • An authentication method references (amr) claim holds a JSON array of strings identifying the authentication methods satisfied; for example, an indication the end user has authenticated with a username-password combination and a one-time password.

The acr claim

The acr claim holds a case-sensitive string you configure in the OAuth 2.0 provider service. PingOne Advanced Identity Cloud maps acr keys to authentication journeys to avoid directly exposing the journey names.

PingOne Advanced Identity Cloud does not add the acr claim to ID tokens by default. The RP must request authentication contexts and PingOne Advanced Identity Cloud must authenticate the end user.

The acr claims can be voluntary or essential.

Voluntary claims

RPs request voluntary acr claims for optional authentication mechanisms to improve the user experience. They do this in one of the following ways:

  • Specify the authentication mechanism in the acr_values parameter for a request to the /oauth2/authorize endpoint.

  • Specify the authentication mechanisms in the JSON format claims parameter for a request to the /oauth2/authorize endpoint.

  • Rather than specifying the mechanisms in the request, rely on Default ACR values in the RP client profile.

    Find the field in the Advanced Identity Cloud admin UI under Applications > Client ID > Sign On > General Settings > Show advanced settings > Authentication.

    The default acr values are the keys of the mapping set when you Configure acr claims. The JSON response from the /oauth2/.well-known/openid-configuration endpoint lists the keys as acr_values_supported strings; for example:

    "acr_values_supported": ["username-password"]

    Any mechanisms the RP specifies in the request override the default acr values.

Essential claims

RPs request essential acr claims for required authentication mechanisms.

RPs request essential acr claims by specifying the authentication mechanisms in the JSON format claims parameter for a request to the /oauth2/authorize endpoint.

Essential claims resemble, but are unrelated to, step-up authentication.

Configure acr claims

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect.

  2. Enable Enable "claims_parameter_supported" to let RPs request acr claims using the claims parameter.

  3. In the OpenID Connect acr_values to Auth Chain Mapping box, map keys to authentication journey identifiers.

    The following example maps username-password to the Login journey:

    Map `acr` claim strings to journeys.

    The key for the journey PingOne Advanced Identity Cloud use to authenticate the end user becomes the value of the acr claim in the resulting ID token.

  4. Save your changes.

Request processing

When an RP requests authentication contexts, PingOne Advanced Identity Cloud initially determines the requested journey. It uses the first context for which it has a valid mapping. For example, if the RP requests push otp username-password and PingOne Advanced Identity Cloud has mappings only for otp and username-password, PingOne Advanced Identity Cloud chooses otp to authenticate the end user.

The following table describes how PingOne Advanced Identity Cloud processes the request:

Scenario Voluntary claims result Essential claims result

The end user is not authenticated.

Authenticate with the requested journey.

Authenticate with the requested journey.

The end user is authenticated with the requested journey.

Do not re-authenticate.

Re-authenticate with the requested journey.

On success, delete the original session and create a new session.

The end user is authenticated with a different journey.

Re-authenticate with the requested journey.

On success, delete the original session and create a new session.

The request specifies an unmapped acr_values or claims string.

Continue the grant flow without returning an error.

Return an error and redirect to the redirect_uri, if available.

After authenticating the end user, PingOne Advanced Identity Cloud returns an ID token whose acr claim has one of the following values:

0 (zero)

The RP requested an unmapped voluntary claim.

acr-key

The end user authenticated with the journey mapped to acr-key.

If authentication involves more than one journey, the acr-key reflects the last mapped journey.

The amr claim

The amr claim holds an array of strings identifying families of authentication methods.

PingOne Advanced Identity Cloud lets you map AuthType session properties to amr values with the Set Session Properties node. When the end user authenticates with a journey using the node, PingOne Advanced Identity Cloud includes the amr claim in the ID token it issues.

Configure amr claims

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect.

  2. Save your changes.

  3. Go to Realms > Realm Name > Services and add a Session Property Whitelist service.

  4. Add AuthType to the Allowlisted Session Property Names field.

  5. Save your changes.

  6. Create or update an authentication journey to include a Set Session Properties node with an AuthType property whose value is the amr claim.

    The following example node configuration sets the value to username-password:

    Set `AuthType` to the `amr` claim.

Demonstrate authentication requirements

Demonstrate the process with an RP that uses the Implicit grant:

  1. Create an end user profile and record the username and password.

  2. Create an RP profile.

  3. Duplicate the default Login journey.

  4. Optionally Configure amr claims.

  5. Configure acr claims to map your duplicate journey to the username-password claim.

  6. Request voluntary claims.

  7. Request essential claims.

Create an RP profile

Register a custom OIDC application with the following settings:

Setting

Value

Application Type

Web

Name

myClient

Sign On > General Settings > Sign-in URLs

Add https://www.example.com:443/callback

Sign On > General Settings > Grant Types

Add Implicit

Sign On > General Settings > Scopes

Include openid
profile

Request voluntary claims

  1. Open a new tab in your browser.

  2. Paste a URL with the acr_values parameter to request voluntary claims into the new browser tab:

    The following URL requests an ID token with the implicit grant:

    https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/authorize?acr_values=username-password&client_id=myClient&response_type=id_token&scope=openid%20profile&redirect_uri=https://www.example.com:443/callback&nonce=abc123&state=123abc

  3. Authenticate as the end user.

    PingOne Advanced Identity Cloud redirects to the application sign-in URL (redirect_uri) with the id_token in the fragment.

  4. Extract the ID token from the sign-in URL.

  5. Decode the ID token to display the acr claim:

    {
  "...": "...",
  "acr": "username-password"
}

Request essential claims

  1. Define and URL-encode the essential claims parameter value.

    Essential claims requesting username-password:

      {"id_token":{"acr":{"essential":true,"values":["username-password"]}}}

    URL-encoded value:

    %7B%22id_token%22%3A%7B%22acr%22%3A%7B%22essential%22%3Atrue%2C%22values%22%3A%5B%22username-password%22%5D%7D%7D%7D

  2. Paste a URL with the encoded claims parameter to request essential claims into the new browser tab:

    The following URL requests an ID token with the implicit grant:

    https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/authorize?claims=%7B%22id_token%22%3A%7B%22acr%22%3A%7B%22essential%22%3Atrue%2C%22values%22%3A%5B%22username-password%22%5D%7D%7D%7D&client_id=myClient&response_type=id_token&scope=openid%20profile&redirect_uri=https://www.example.com:443/callback&nonce=abc123&state=123abc&prompt=login

    The prompt setting forces the end user to authenticate explicitly regardless of any implied consent.

    When you request essential claims, PingOne Advanced Identity Cloud authenticates the end user again. For details, refer to Request processing.

    PingOne Advanced Identity Cloud redirects to the application sign-in URL (redirect_uri) with the id_token in the fragment.

  3. Extract the ID token from the sign-in URL.

  4. Decode the ID token to display the acr claim:

    {
  "...": "...",
  "acr": "username-password"
}