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 one of the browser-based 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 steps through 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 action ID is specified via the Content-Type HTTP request header in this format: application/vnd.pingidentity.<actionId>+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 may also be sent if PingFederate encounters an 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.

Note:

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

Recap of 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.

Session management

The authentication API endpoint has the same domain as PingFederate's other application endpoints and shares the PF session cookies with those endpoints. This ensures that session data created by API applications can be retrieved when the user interacts with PingFederate's other endpoints, and vice versa.

Note:

Because the authentication API relies on the PingFederate session cookies, only browser-based web applications can currently make use of the API. Server-side web applications are not supported.

To ensure that the PingFederate session cookies are managed correctly, ensure the Javascript-written authentication application sets the withCredentials flag on the XMLHttpRequest object to true.

To protect against cross-site request forgeries, API clients are also required to include an X-XSRF-Header HTTP request header with each request; for example, X-XSRF-Header: PingFederate. This custom header ensures that browsers enforce cross-origin resource sharing (CORS) policies when API requests are sent. (Note that the value of this header does not matter.)

Default authentication application

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

Authentication API Explorer

PingFederate includes an API Explorer, which allows you to view the states, actions, and models available for the various API-capable adapters and selectors included in your PingFederate environment. The endpoint for the Authentication API Explorer is /pf-ws/authn/explorer.

As of PingFederate 10.0, you can download a Postman collection file from the Authentication API Explorer screen. The file contains information converted from the Explorer into a Postman collection. You can then import the collection file into the Postman application. The collection file provides every possible action of every state in every plugin deployed in the PingFederate instance. It contains:

  • All API-capable pugins (adapters and selectors) with all of their states and actions
  • Pre-populated body containing information about required information types and parameters
  • Headers for API calls (X-XSRF-Header and Content-Type)

For more information, see Exploring authentication API.