Authentication applications and the authentication API

The PingFederate authentication API is a JSON-based API that enables end-user interactions, such as credential prompts, to be handled by an external web application. This API does so by providing access to the current state of the flow as an end user steps through a PingFederate authentication policy.

Authentication flows are initiated through browser-based single sign-on (SSO) application endpoints, such as /idp/startSSO.ping, or a protocol request, such as an OpenID Connect authentication request received at the authorization endpoint: /as/authorization.oauth2. As PingFederate runs the configured authentication policy, if it encounters an API-capable adapter or selector, and an authentication application is configured for the policy, PingFederate redirects to the authentication application’s URL, passing the ID of the flow in the flowId query parameter.

The authentication application can then retrieve the current state of the flow by issuing a GET request to the /pf-ws/authn/flows/{flowId} endpoint. The _links field in the response lists the available authentication actions that can be performed from the current state. To invoke an action, the authentication application sends a POST request to the /pf-ws/authn/flows/{flowId} endpoint.

The API client can choose authentication actions using either an action query parameter or a custom content type. The action query parameter should be used when your networks block custom content types, and is specified using the following format:

For example, to check username and password, pass the checkUsernamePassword action ID through the query parameter as follows:

For the custom content type, the action ID is specified using the Content-Type HTTP request header in the following format:

For example, to indicate a username and password check from the HTML Form Adapter, specify the following:

When the application invokes an action, PingFederate responds either with the next state for the flow or an error.

When the user completes the authentication policy steps successfully, the authentication API returns a RESUME status to the authentication application. This status indicates that the API client should redirect the user’s browser to the resumeUrl specified in the response. PingFederate will then be responsible for the final step in the flow, such as passing a SAML assertion to a partner. A RESUME status will also be sent if PingFederate encounters an identity provider (IdP) connection in the policy tree, or an IdP adapter or selector that is not API-capable. When the API client redirects the user, PingFederate will take the steps needed to invoke the authentication source.

If the user has interacted with an authentication application and the flow terminates with an error, the API client will receive a FAILED status from the API.

Authentication applications must be highly trusted.