--- title: Configuring authentication challenge policies description: Configure an authentication challenge policy in PingAccess to set the response that PingAccess sends when it receives unauthenticated requests for protected resources. component: pingaccess version: 9.0 page_id: pingaccess:pingaccess_user_interface_reference_guide:pa_configuring_authn_challenge_policies canonical_url: https://docs.pingidentity.com/pingaccess/9.0/pingaccess_user_interface_reference_guide/pa_configuring_authn_challenge_policies.html revdate: February 6, 2023 section_ids: steps: Steps result: Result: result-2: Result: result-3: Result: result-4: Result: --- # Configuring authentication challenge policies Configure an authentication challenge policy in PingAccess to set the response that PingAccess sends when it receives unauthenticated requests for protected resources. ## Steps 1. Click **Access**, then go to **Authentication > Authentication Challenge Policies**. 2. Click **[icon: plus, set=fa]Add Authentication Challenge Policy**. 3. In the **Name** field, enter a unique name for the authentication challenge policy. 4. **Optional:** In the **Description** field, enter a description for the authentication challenge policy. 5. In the **Challenge Response Mapping** list, select a mapping type: The **MS-OFBA** challenge response mapping examines `OPTIONS HTTP` method requests to determine if the user agent is a client that supports Microsoft's MS-OFBA protocol or if the request has a Boolean flag indicating that it supports MS-OFBA. ![Screen capture of the New Authentication Challenge Policy page with MS-OFBA selected as the Challenge Response Mapping.](_images/qvd1666045178214.png) | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | PingAccess provides an MS-OFBA authentication challenge policy that's included with the system by default. As such, the **MS-OFBA** challenge response mapping is best used to address edge cases as they come up. For more information, see [Authentication](pa_authentication.html). | 1. If you selected the **Content Negotiation** mapping type, in the **Media Types** list, select one or more media types. The selection options for media types are **application/json**, **text/html**, **text/plain**, or **text/xml**. ![Screen capture of the New Authentication Challenge Policy page. A list of Media Type options is visible in the Challenge Response Mapping section.](_images/gej1664548558039.png) ### Result: If the `Accept` header field in the request matches any of the specified media types, the mapping is applied. 2. If you selected the **Header Fields** mapping type, click **[icon: plus, set=fa]Add Row** to add one or more rows, and then in the **Name** and **Value Pattern** fields, enter a name and value pattern for each row. ![Screen capture of the Challenge Response Mapping section with Header Fields selected. Add Row and the Name and Value Pattern fields are highlighted.](_images/wjf1664550149420.png) ### Result: If all of the specified header fields in the request match the specified value patterns, the mapping is applied. 6. Configure a challenge response generator for the challenge response mapping: 1. In the **Challenge Response Generator** list, select a challenge response generator. For more information, see [Authentication challenge responses](pa_authentication_challenge_responses.html) and [Authentication challenge response generator descriptions](pa_acr_generator_descriptions.html). 2. **Optional:** If you selected **Browser-handled OIDC Authentication Request**, **HTML OIDC Authentication Request**, **MS-OFBA Authentication Request Redirect**, **OIDC Authentication Request Redirect**, or **PingFederate Authentication API Challenge**, you can select one of the following options from the **Prompt Request Parameter** list to let the authorization server know whether to prompt an end-user to reauthenticate or provide consent. ![Screen capture of HTML OIDC Authentication Request selected as the Challenge Response Generator. The image shows the Prompt Request Parameter options.](_images/dys1672938959914.png) * none Returns an error if the end-user isn't authenticated or if the OAuth client *(tooltip: \
\

The application in an OAuth framework that requests access to resources. If the request is approved by the authorization server, the client is issued an access token for the resources.\

\
)* doesn't have user consent for the requested claims. The authorization server doesn't prompt the end-user with a consent or authentication page if this option is selected. * login The authorization server prompts the end-user to reauthenticate. If the end-user doesn't reauthenticate successfully, it returns an error. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For extra security, PingAccess validates the *\* the login request was sent at against the *\* the OpenID Provider (OP) *(tooltip: \
\

In OAuth terms, an authorization server (AS). The OP/AS issues access tokens to protected resources for approved clients (relying parties). The clients use the access token to access the protected resources hosted by the OAuth resource server.\

\
)* sets in the response. | * consent The authorization server prompts the end-user for consent before giving information to the OAuth client. If the end-user doesn't give their consent, it returns an error. * select\_account The authorization server prompts the end-user to specify which account they are using, in case they have multiple accounts. If the end-user doesn't select an account, it returns an error. If you are using PingFederate as the OP, you should also enable push authorization requests on the web session you want to use with this authentication challenge policy. This advanced setting provides an additional layer of security against frontchannel tampering. For more information, see **Enable Push Authorization** in [Creating web sessions](pa_creating_web_sessions.html). | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can set the **Prompt Request Parameter** in two places: on the web session or on one of the OpenID Connect (OIDC) *(tooltip: \
\

An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management.\

\
)* authentication challenge response generators. A value set on a specific authentication challenge response generator takes precedence over one set on a web session. | 3. **Optional:** If you selected **OIDC Authentication Request Redirect**, **Redirect Challenge**, or **Templated Challenge**, you can configure PingAccess to let the authentication authority know why a user was redirected to it: 1. Go to the **Web Sessions** page and expand the web session that you want to edit. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you selected **Redirect Challenge**, make sure that you select the **Append Redirect Parameters** check box in step 6d.If you selected **Templated Challenge** and are using PingFederate as an authentication source, make sure that you connect to PingFederate's redirectless OIDC flow. | 2. Click the **Pencil** icon, and then select the **Provide Authentication Feedback** check box under **Advanced Settings**. For more information about the feedback PingAccess can provide, see [Creating web sessions](pa_creating_web_sessions.html). An **OIDC Authentication Request Redirect** issues the feedback key `vnd_pi_authn_feedback`. The feedback key issued by an **Redirect Challenge** is `authnFeedback`, and the feedback key issued by an **Templated Challenge** response generator is `oidc.authnFeedback`. 4. If you selected **Redirect Challenge**, enter a **Redirect URL** and select a **Response Code** for the redirect. ![Screen capture of the Redirect URL, Response Code, and Challenge Response Filter fields, which appear when you select Redirect Challenge.](_images/ynf1666725021047.png) Optionally, select the **Append Redirect Parameters** check box to append PingFederate OIDC parameters and the Uniform Resource Locator (URL) *(tooltip: \
\

Identifies a resource according to its internet location.\

\
)* of a requested resource within the query string of a redirect URL that you specify. For more information, see the **Redirect Challenge** table entry in [Authentication challenge response generator descriptions](pa_acr_generator_descriptions.html). ![Screen capture of the Append Redirect Parameters check box, which appears when you select Redirect Challenge.](_images/ayv1666725257637.png) 5. If you selected **Templated Challenge**, select a **Response Code** and **Media Type** for the template, and then enter the template in the **Template** field. ![Screen capture highlighting the Response Code, Media Type, and Template fields, which appear when you select a Templated Challenge response generator.](_images/puw1664551185808.png) 6. In the **Challenge Response Filter** list, select a challenge response filter. ![Screen capture highlighting the Challenge Response Filter field, which appears at the bottom of the section for any challenge response you select.](_images/tqn1664551470127.png) * If you selected **Append Header Fields**, click **[icon: plus, set=fa]Add Row**. Enter a **Name** and **Value** in each row. * If you selected Global PF Redirect Headers Appender, then PingAccess will add the headers defined by the `pf.redirect.headers` in `/conf/run.properties` as described by the [Configuration file reference](../reference_guides/pa_config_file_ref.html). ### Result: The specified HTTP response header fields are appended to the authentication challenge response. 7. **Optional:** To add additional challenge response mappings, click **[icon: plus, set=fa]Add Challenge Response Mapping**, then repeat steps 5 and 6. 8. In the **Default Challenge Response** section, select a default challenge response. PingAccess uses this challenge response if no other challenge responses apply. 1. In the **Challenge Response Generator** list, select a challenge response generator. ![Screen capture of the options in the Challenge Response Generator field. Make sure to use the selector in the Default Challenge Response section.](_images/ndm1666729967835.png) 2. **Optional:** If you selected **Browser-handled OIDC Authentication Request**, **HTML OIDC Authentication Request**, **MS-OFBA Authentication Request Redirect**, **OIDC Authentication Request Redirect**, or **PingFederate Authentication API Challenge**, you can select one of the following options from the **Prompt Request Parameter** list to let the authorization server know whether to prompt an end-user to reauthenticate or provide consent. ![Screen capture of HTML OIDC Authentication Request selected as the Challenge Response Generator. The image shows the Prompt Request Parameter options.](_images/wib1672773289763.png) * none Returns an error if the end-user isn't authenticated or if the OAuth client doesn't have user consent for the requested claims. The authorization server doesn't prompt the end-user with a consent or authentication page if this option is selected. * login The authorization server prompts the end-user to reauthenticate. If the end-user doesn't reauthenticate successfully, it returns an error. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------- | | | For extra security, PingAccess validates the *\* the login request was sent at against the *\* the OP sets in the response. | * consent The authorization server prompts the end-user for consent before giving information to the OAuth client. If the end-user doesn't give their consent, it returns an error. * select\_account The authorization server prompts the end-user to specify which account they are using, in case they have multiple accounts. If the end-user doesn't select an account, it returns an error. If you are using PingFederate as the OP, you should also enable push authorization requests on the web session you want to use with this authentication challenge policy. This advanced setting provides an additional layer of security against frontchannel tampering. For more information, see **Enable Push Authorization** in [Creating web sessions](pa_creating_web_sessions.html). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | You can set the **Prompt Request Parameter** in two places: on the web session or on one of the OIDC authentication challenge response generators. A value set on a specific authentication challenge response generator takes precedence over one set on a web session. | 3. **Optional:** If you selected **OIDC Authentication Request Redirect**, **Redirect Challenge**, or **Templated Challenge**, you can configure PingAccess to let the authentication authority know why a user was redirected to it. 1. Go to the **Web Sessions** page and expand the web session that you want to edit. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you selected **Redirect Challenge**, make sure that you select the **Append Redirect Parameters** check box in step 8d.If you selected **Templated Challenge** and are using PingFederate as an authentication source, make sure that you connect to PingFederate's redirectless OIDC flow. | 2. Click the **Pencil** icon, and then select the **Provide Authentication Feedback** check box under **Advanced Settings**. For more information about the feedback PingAccess can provide, see [Creating web sessions](pa_creating_web_sessions.html). An **OIDC Authentication Request Redirect** issues the feedback key `vnd_pi_authn_feedback`. The feedback key issued by an **Redirect Challenge** is `authnFeedback`, and the feedback key issued by an **Templated Challenge** response generator is `oidc.authnFeedback`. 4. If you selected **Redirect Challenge**, enter a **Redirect URL** and select a **Response Code** for the redirect. ![Screen capture highlighting the Redirect URL, Response Code, and Challenge Response Filter fields, which appear when you select Redirect Challenge.](_images/psd1666728745342.png) Optionally, select the **Append Redirect Parameters** check box to append PingFederate OIDC parameters and the URL of a requested resource within the query string of a redirect URL that you specify. For more information, see the **Redirect Challenge** table entry in [Authentication challenge response generator descriptions](pa_acr_generator_descriptions.html). ![Screen capture of the Append Redirect Parameters check box, which appears when you select Redirect Challenge.](_images/whz1666728887826.png) 5. If you selected **Templated Challenge**, select a **Response Code** and **Media Type** for the template, and then enter the template in the **Template** field. ![Screen capture highlighting the Response Code, Media Type, and Template fields, which appear when you select a Templated Challenge response generator.](_images/mli1664558730908.png) 6. In the **Challenge Response Filter** list, select a challenge response filter. ![Screen capture highlighting the Challenge Response Filter field, which appears at the bottom of the section for any challenge response you select.](_images/mlc1664558912070.png) * If you selected **Append Header Fields**, click **[icon: plus, set=fa]Add Row**, then enter a **Name** and **Value** in each row. ### Result: The specified HTTP response header fields are appended to the authentication challenge response. 9. Click **Save**.