Configure an authentication challenge policy in PingAccess to set the response that PingAccess sends when it receives unauthenticated requests for protected resources.
- Click Access and then go to Authentication > Authentication Challenge Policies.
- Click + Add Authentication Challenge Policy.
- In the Name field, enter a unique name for the authentication challenge policy.
- Optional: In the Description field, enter a description for the authentication challenge policy.
-
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.Tip: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.
-
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.
If the
Accept
header field in the request matches any of the specified media types, the mapping is applied. -
If you selected the Header Fields mapping type,
click + 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.
If all of the specified header fields in the request match the specified value patterns, the mapping is applied.
-
If you selected the Content Negotiation mapping
type, in the Media Types list, select one or more
media types.
-
Configure a challenge response generator for the challenge response
mapping:
-
In the Challenge Response Generator list, select
a challenge response generator.
For more information, see Authentication challenge responses and Authentication challenge response generator descriptions.
- 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.
- 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.Note:
For extra security, PingAccess validates the <auth_time> the login request was sent at against the <auth_time> the OpenID Provider (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.
Note:You can set the Prompt Request Parameter in two places: on the web session or on one of the OpenID Connect (OIDC) authentication challenge response generators. A value set on a specific authentication challenge response generator takes precedence over one set on a web session.
- 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:
- Go to the Web Sessions page and expand the
web session that you want to edit.Important:
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.
- 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.
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.
- Go to the Web Sessions page and expand the
web session that you want to edit.
-
If you selected Redirect Challenge, enter a
Redirect URL and select a Response
Code for the redirect.
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.
-
If you selected Templated Challenge, select a
Response Code and Media
Type for the template, and then enter the template in
the Template field.
-
In the Challenge Response Filter list, select a
challenge response filter.
- If you selected Append Header Fields,
click + 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 <PA_HOME>/conf/run.properties as described by the Configuration file reference.
The specified HTTP response header fields are appended to the authentication challenge response.
- If you selected Append Header Fields,
click + Add Row.
-
In the Challenge Response Generator list, select
a challenge response generator.
- Optional: To add additional challenge response mappings, click + Add Challenge Response Mapping, then repeat steps 5 and 6.
-
In the Default Challenge Response section, select a
default challenge response.
PingAccess uses this challenge response if no other challenge responses apply.
-
In the Challenge Response Generator list, select
a challenge response generator.
- 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.
- 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.Note:
For extra security, PingAccess validates the <auth_time> the login request was sent at against the <auth_time> 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.
Note: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.
- 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.
- Go to the Web Sessions page and expand the
web session that you want to edit.Important:
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.
- 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.
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.
- Go to the Web Sessions page and expand the
web session that you want to edit.
-
If you selected Redirect Challenge, enter a
Redirect URL and select a Response
Code for the redirect.
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.
-
If you selected Templated Challenge, select a
Response Code and Media
Type for the template, and then enter the template in
the Template field.
-
In the Challenge Response Filter list, select a
challenge response filter.
- If you selected Append Header Fields, click + Add Row, then enter a Name and Value in each row.
The specified HTTP response header fields are appended to the authentication challenge response.
-
In the Challenge Response Generator list, select
a challenge response generator.
- Click Save.