Authentication challenge response generator descriptions

This table describes the challenge response generators you could configure on the New Authentication Challenge Policy page:

Browser-handled OIDC Authentication Request

Generates an HTML or 302 redirect response as described by the Authentication challenge responses tables when single-page application (SPA) support is disabled.

Device Authorization Challenge

Generates a response based on a default HTML template that begins the device authorization grant flow. You can select a response code and modify the template in the Device authorization challenge ACR generator configuration steps.

Device authorization grant flow

When an unauthenticated user tries to access a protected application or resource associated with this ACP, PingAccess shows them the Continue on another device page.

This page provides the user with a QR code and continually polls for authentication as described in the /pa/oidc/deviceAuthzGrantPoll endpoint reference.

The user scans the QR code or enters the associated link into a browser on a secondary device.

This link is usually the token provider’s Issuer field followed by the device authorization grant endpoint.

For example, if PingFederate is the token provider, use https://<pf_host>:<pf_traffic_port>/as/user_authz.oauth2 as the URL. The default PingFederate traffic port is 9031. Learn more in Port requirements.

The exact link to the Connect a device page depends on the token provider you’ve configured. You should review your token provider’s documentation on device authorization grant types to confirm what link to use.

The token provider prompts the user to authenticate.
If the user authenticates successfully, the token provider shows the Connect a device page.

This page provides the user with a pre-filled Activation Code field.
The user confirms the Activation Code, then clicks Submit.
The token provider shows an error or confirmation message on the Connect a device page.

If using PingFederate as the token provider, PingFederate presents the user with an expired token error if ten minutes elapse with no response. This is a default value that you can change in the PingFederate configuration. Learn more in Device authorization grant settings.

HTML OIDC Authentication Request

Generates a response with a 401 response code. The response body is an HTML document that automatically issues the OpenID Connect (OIDC) authentication request using JavaScript.

The HTML always attempts to preserve the fragment of the current browser URL and preserves a POST body if the Content-Type is application/x-www-url-formencoded.

MS-OFBA Authentication Request Redirect

Adds two response headers to an HTTP request:

X-FORMS_BASED_AUTH_REQUIRED
X-FORMS_BASED_AUTH_RETURN_URL

This enables you to open Microsoft (MS) Office documents protected by PingAccess in an in-app browser that redirects to the OpenID Provider (OP) for user authentication. After the user authenticates, PingAccess establishes a web session and redirects the user to the corresponding MS Office application (for example, spreadsheets open in MS Excel).

This response generator doesn’t work with MS Office applications running on macOS, as the macOS in-app browser is much more restrictive. It can’t set the nonce cookie that PingAccess requires before redirecting a user.

Additionally, Internet Explorer configurations can dictate the behavior of the in-app browser in some environments. If the document you requested fails to download, ensure that Do not save encrypted pages to disk is disabled in Internet Explorer > Internet Options > Advanced > Settings > Security.

PingAccess provides an MS-OFBA ACP that’s configured automatically on initial setup. The MS-OFBA challenge response mapping is meant to address edge cases as they come up.

Learn more about the system-provided ACP in MS-OFBA.

OIDC Authentication Request Redirect

Generates a response with a 302 response code. The response body directs the browser to send an OIDC authentication request to the OP.

PingFederate Authentication API Challenge

Generates a response with a 401 response code. The body is a JavaScript Object Notation (JSON) object that directs the application to connect to the PingFederate redirectless authorization API. The JSON object contains three strings:

authorizationUrl: Represents the OIDC authentication request.
method: Indicates the HTTP method for the request to the PingAccess OIDC callback endpoint.
oidcAuthnResponseEndpoint: The location of the PingAccess OIDC callback endpoint.

You can find more information about the required PingFederate configuration in PingFederate authentication API in the PingFederate documentation.

You can find more information about configuring the JavaScript widget to enable this challenge response in the Redirectless support page on Github.

Redirect Challenge

Generates a response with the specified response code that redirects the user to a specified URL.

Optionally, select the Append Redirect Parameters checkbox to append PingFederate Authentication API parameters and the URL of the protected resource the user tried to access within the query string of the redirect URL you specified.

This lets you initiate PingFederate’s redirectless OIDC flow from your own sign-on page when an unauthenticated user tries to access a protected resource. The appended parameters are:

authzUrl: The OIDC authentication request, similar to authorizationUrl from the PingFederate Authentication API Challenge response generator. Contains parameters necessary to access the requested resource, such as specific OIDC scopes.
authnResponseMethod: The HTTP method used to interact with the PingAccess callback endpoint. For example, GET.
resourceUrl: The URL of the resource requested by the user. For example, https://localhost:3000.
authnResponseEndpoint: The PingAccess callback endpoint. For example, https://localhost:3000/pa/oidc/cb.

When Append Redirect Parameters is selected, PingAccess provides the information necessary to complete an OIDC flow within the redirect URL’s query string, but it doesn’t automatically redirect the user to the PingFederate authorization endpoint. As such, this setting is best used with the redirectless PingFederate authentication API, which reports the current state of an end user’s PingFederate authentication policy flow so an external web application can manage authentication requests.

Regardless of whether you use the Authentication API, you must send a request to the authzUrl to start a redirectless sign-on flow with the credentials entered into your sign-on form. This endpoint returns an OIDC token, which you must send to the authnResponseEndpoint using the authnResponseMethod so PingAccess can establish a session with the protected resource. After the session is established, you must redirect the user to the resourceUrl.

Templated Challenge

Generates a response with the specified response code based on a specified template. Possible template variables include:

<application.name> (string)

The name of the requested application.

<application.realm> (string)

The OAuth realm associated with the application. If the realm isn’t defined by the application, it’s assumed to be the requested authority and the application’s context root.

<cspNonce> (string)

Use this variable to add a nonce attribute to any inline JavaScript.

<exchangeId> (string)

The ID of the current transaction.

<oidc.authzUrl> (object)

The PingFederate OIDC authentication request. Contains parameters necessary to access the requested resource, such as specific OIDC scopes.

Use this variable alongside the following three variables to initiate PingFederate’s redirectless OIDC flow from your own sign-on page when an unauthenticated user tries to access a protected resource, as described in the Redirect Challenge response table entry.

<oidc.authnResponseEndpoint> (string): The PingAccess callback endpoint, such as https://localhost:3000/pa/oidc/cb.
<oidc.authnResponseMethod> (string): The HTTP method used to interact with the PingAccess callback endpoint, such as GET.
<resource.url> (string): The URL of the resource requested by the user, such as https://localhost: 3000.

<resource.name> (string)

The name of the requested resource.