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.
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.
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.
- The SSO transaction invoking the authentication API.
- 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.
- The available actions (if any) for a given state.
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.
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 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. 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.
- User Login
- Trouble Signing in
- Trouble with Username
- Password Reset