Authentication challenge response generator descriptions - PingAccess

Authentication challenge response generator descriptions - PingAccess - 8.0

PingAccess

bundle

pingaccess-80

ft:publication_title

PingAccess

Product_Version_ce

PingAccess 8.0

category

Product

pa-80

pingaccess

ContentType_ce

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 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). Important: 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. Tip: 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 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. 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. Tip: 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`. Important: 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. Note: 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`.