Authentication flows are initiated through browser-based single sign-on (SSO)single sign-on (SSO)sso The process of authenticating an identity (signing on) at one website (usually with a user ID and password) and then accessing resources secured by other domains without re-authenticating. application endpoints, such as /idp/startSSO.ping, or a protocol request, such as an OpenID Connect (OIDC)OpenID Connect (OIDC)OIDC An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management. 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)identity provider (IdP)IdP A service that manages identity information and provides authentication services to relying clients or service providers (SPs) within a federated or distributed network. 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, you should give the authentication application the same parent domain as the PingFederate authentication API URL that the application accesses. This could be a common domain of PingFederate's base URL or one of PingFederate's defined virtual hosts.

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 PingFederate 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.

In order for PingFederate to manage session cookies correctly, the Javascript-written authentication application must set 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. This header can have any value.

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.

You can download a Postman collection file from Authentication > Integration > Authentication API Applications. 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 plugins, both 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, both X-XSRF-Header and Content-Type

For more information, see Exploring the authentication API.

JavaScript widget for the PingFederate authentication API

The JavaScript Widget for the PingFederate authentication API is a customizable JavaScript library that provides the capabilities of the HTML Form Adapter and Identifier First Adapter through the authentication API:
  • User Login
  • Trouble Signing in
  • Trouble with Username
  • Password Reset

The widget is a ready-to-use drop-in bundle with CSS and customizable templates. This alternative to the PingFederate templates provides a sign-in experience as a single page application. For more information, go to JavaScript Widget for the PingFederate Authentication API.