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:

/pf-ws/authn/flows/<flowId>?action=<actionID>

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

/pf-ws/authn/flows/<flowId>?action=checkUsernamePassword

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

application/vnd.pingidentity.<actionId>+json

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

application/vnd.pingidentity.checkUsernamePassword+json

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.

Note:

To avoid issues with third-party cookies in some browsers, give the authentication application the same parent domain as the PingFederate base URL.

Key concepts

Flow
The SSO transaction invoking the authentication API.
States
The available states (if any) for a given API-enabled adapter or selector.
Current state
Indicates what the adapter or selector is ready to do next.
Actions
The available actions (if any) for a given state.

Default authentication application

In addition to specifying an authentication application for each policy, you can also configure a default application. PingFederate uses the default application if it encounters an API-capable adapter outside of a policy tree. For example, the default application activates if the user navigates to the Change Password endpoint, /ext/pwdchange/Identify, or the Account Recovery endpoint, /ext/pwdreset/Identify. PingFederate also uses the default application if authentication policies are disabled, or if the flow falls through to a default authentication source.