The PingFederate authentication
Authentication flows are initiated through browser-based
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
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.
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.
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 PingFederate instance. It contains:
. 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- 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
- 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.