--- title: Authentication requirements description: 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. component: pingam version: 8.1 page_id: pingam:am-oidc1:oidc-authentication-requirements canonical_url: https://docs.pingidentity.com/pingam/8.1/am-oidc1/oidc-authentication-requirements.html keywords: ["OpenID Connect (OIDC)", "Standards", "Setup & Configuration", "Authentication"] page_aliases: ["oidc1-guide:oidc-authentication-requirements.adoc"] section_ids: acr-claim: The acr claim voluntary_claims: Voluntary claims essential_claims: Essential claims proc-configure-acr: Configure acr claims authn-reqts-request-processing: Request processing amr-claim: The amr claim proc-configure-amr-node: Configure amr claims configure-journey-amr: Configure an authentication journey config-oidc-plugin-amr: Configure the user info claims script allowlist-session-property-amr: Allowlist the session property configure-oidc-plugin-amr: Configure the provider configure-provider-claims-id-token-session: Configure the provider request-acr-example: Demonstrate authentication requirements auth-reqts-create-rp: Create an RP profile auth-reqts-try-voluntary: Request voluntary claims auth-reqts-try-essential: Request essential claims --- # 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. AM lets you associate requirements with authentication journeys. RPs specify the authentication requirements in their requests, and AM uses the associations to authenticate the end user with the requested journey and honor the requirements. AM 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. AM maps `acr` keys to authentication journeys to avoid directly exposing the journey names. AM doesn't add the `acr` claim to ID tokens by default. The RP must request authentication contexts and AM 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 AM admin UI under Realms > *realm name* > Applications > OAuth 2.0 > *client ID* > OpenID Connect. The default `acr` values are the keys of the mapping set when you [Configure `acr` claims](#proc-configure-acr). The JSON response from the [/oauth2/.well-known/openid-configuration](rest-api-oidc-discovery-configuration.html) 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](../am-sessions/session-upgrade.html). ### Configure `acr` claims 1. In the AM admin UI, 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.](_images/oidc-acr-values.png) The *acr-key* mapped to the journey AM uses 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, AM 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 AM has mappings only for `otp` and `username-password`, AM chooses `otp` to authenticate the end user. The following table describes how AM processes the request: | Scenario | Voluntary claims result | Essential claims result | | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | The end user isn't authenticated. | Authenticate with the requested journey. | Authenticate with the requested journey. | | The end user is authenticated with the requested journey. | Don't reauthenticate. | Reauthenticate with the requested journey.On success, delete the original session and create a new session. | | The end user is authenticated with a different journey. | Reauthenticate 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, AM 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 the *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. You can map an `amr` session property to `amr` values using the [Set Session Properties node](https://docs.pingidentity.com/auth-node-ref/8.1/set-session-properties.html). Then update the user info claims script to retrieve the `amr` values mapped to the `amr` session property. When the end user authenticates with a journey using the node, AM includes the `amr` claim in the ID token it issues. ### Configure `amr` claims #### Configure an authentication journey 1. Update an authentication journey to include the [Set Session Properties node](https://docs.pingidentity.com/auth-node-ref/8.1/set-session-properties.html), for example, update the `acr` claims journey. 2. On the Set Session Properties node, configure a key to identify the `amr` values, for example `amr`. As its value, enter a string to identify the authentication method satisfied. For example, `otp`. > **Collapse: Example: Configure the amr session property** > > ![amr-set-session-properties](_images/amr-set-session-properties.png) 3. Save your changes. #### Configure the user info claims script This task describes how to modify the default user info claims script to retrieve the `amr` values mapped to the `amr` session property. This example uses a legacy script. Find a next-generation example [here](../am-oauth2/plugins-user-info-claims.html#example-oidc-claims-nextgen). 1. In the AM admin UI, go to Realms > *realm name* > Scripts, and click OIDC Claims Script. 2. In the Script field: * Groovy * JavaScript Add the `amr` claim details after the existing `computedClaims` line. For example: ```javascript computedClaims = claimsToResolve.collectEntries() { claim -> result = computeClaim(claim) } if (session != null) { def amrValues = [session.getProperty("amr")]; computedClaims.put("amr", amrValues) } ``` Add the `amr` claim details before the `return computedClaims;` line. For example: ```javascript if (session !== null && session !== undefined) { var amrValues = [session.getProperty("amr")]; computedClaims.put("amr", amrValues) } return computedClaims; ``` 3. Save your changes. The default user info claims script is now amended to retrieve `amr` values mapped to the `amr` session property. #### Allowlist the session property Provide access to the `amr` session property to allow it to be output in the ID token. 1. In the AM admin UI, go to Realms > *realm name* > Services > Session Property Whitelist Service. 2. Add `amr` to the Allowlisted Session Property Names field. 3. Save your changes. #### Configure the provider Perform this task to set up an OAuth 2.0 provider to use your custom script. 1. [Configure the provider](../am-oauth2/customizing-oauth2-scopes.html#configure-scripted-oauth2-plugin) and make sure the following properties are set: * OIDC Claims Plugin Type to `SCRIPTED`. * OIDC Claims Script to the name of your custom script. 2. Save your changes. #### Configure the provider Perform this task to set up an OAuth 2.0 provider to use your custom script. 1. [Configure the provider](../am-oauth2/customizing-oauth2-scopes.html#configure-scripted-oauth2-plugin) and make sure the following properties are set: * OIDC Claims Plugin Type to `SCRIPTED`. * OIDC Claims Script to the name of your custom script. 2. Save your changes. 3. Switch to the Advanced OpenID Connect tab to always return scope-derived claims in the ID token. 4. Select Always Return Claims in ID Tokens. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | This option is disabled by default because of the security concerns of returning claims that may contain sensitive user information. Learn more in [Request claims in ID tokens](understanding-openid-connect-scopes-and-claims.html#request-claims-tokens). | 5. Save your changes. ## Demonstrate authentication requirements Demonstrate the process with an RP that uses the [Implicit grant](../am-oauth2/oauth2-implicit-grant.html): 1. Create an end user profile and record the username and password. 2. [Create an RP profile](#auth-reqts-create-rp). 3. Duplicate the default Example journey to create a Login journey. 4. Optionally [configure `amr` claims](#proc-configure-amr-node). 5. [Configure `acr` claims](#proc-configure-acr) to map your duplicate journey to the `username-password` claim. 6. [Request voluntary claims](#auth-reqts-try-voluntary). 7. [Request essential claims](#auth-reqts-try-essential). ### Create an RP profile [Register an OIDC application](../am-oauth2/oauth2-register-client.html) with the following settings: | Setting | Value | | ---------------------- | -------------------------------------- | | Name | `myClient` | | Redirection URIs | `https://www.example.com:443/callback` | | Scopes | `openid` `profile` | | Advanced > Grant Types | Add `Implicit` | ### 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: ```none https://am.example.com:8443/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. AM 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: ```json { "...": "...", "acr": "username-password" } ``` The `amr` claim is also displayed in the decoded token if you configured `amr` claims, for example: ```json "amr": [ "otp" ], ``` ### Request essential claims 1. Define and URL-encode the essential claims parameter value. Essential claims requesting `username-password`: ```json {"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: ```none https://am.example.com:8443/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, AM authenticates the end user again. Learn more in [Request processing](#authn-reqts-request-processing). AM 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: ```json { "...": "...", "acr": "username-password" } ```