Authentication challenge response generator descriptions

This table describes the challenge response generators available for configuration on the New Authentication Challenge Policy page.

Challenge Response Generator Description

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.

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 Uniform Resource Locator (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 (spreadsheets open in Microsoft Excel, for example).

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 authentication challenge policy that’s included with the system by default. As such, this challenge response generator is best used to address edge cases. For more information, see Authentication.

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 application programming interface (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.

For more information about the required PingFederate configuration, see Authentication API in the PingFederate documentation.

For more information about configuring the JavaScript widget to enable this challenge response, see the Redirectless support page on Github.

Redirect Challenge

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

To opt out of automatic URL encoding, deselect the Encode URL check box. Learn more in Release Notes.

Optionally, select the Append Redirect Parameters check box 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 that 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, such as GET.
resourceUrl: The URL of the resource requested by the user, such as https://localhost:3000.
authnResponseEndpoint: The PingAccess callback endpoint, such as 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 does not automatically redirect the user to the PingFederate authorization endpoint. As such, this setting is best used in conjunction with the redirectless PingFederate Authentication API, which reports the current state of an end-user’s PingFederate authentication policy flow so that 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 that 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:

resource.name represents a string containing the name of the requested resource.
application.name represents a string containing the name of the requested application.
application.realm represents a string containing the OAuth realm associated with the application. If the realm is not defined by the application, it is inferred to be the requested authority and the application’s context root.
exchangeId represents a string containing the ID for the current transaction.
oidc.authzUrl represents the PingFederate OIDC authentication request. Contains parameters necessary to access the requested resource, such as specific OIDC scopes.

Use this variable with 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.authnResponseMethod represents the HTTP method used to interact with the PingAccess callback endpoint, such as GET.
resource.url represents the URL of the resource requested by the user, such as https://localhost: 3000.
oidc.authnResponseEndpoint represents the PingAccess callback endpoint, such as https://localhost:3000/pa/oidc/cb.