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.
Enable Authentication API
- On the Enable Authentication API check box. screen, select the
Enable API Explorer
- On the Enable API Explorer check box. screen, select the
Configure an authentication application for the Authentication API Explorer
- On the Add Authentication Application. screen, click
On the Authentication Application screen, configure each
field as described in the following table.
Field Description Name A name of the authentication application; for example:
Authentication API Explorer
Description An optional description of the authentication application; for example:
Explore the authentication API!
URL A combination of the PingFederate base URL and the application path of /pf-ws/authn/explorer
For example, if the base URL is https://localhost:9031, enter:
Additional Allowed Origins Any additional allowed origins (see Configuring an authentication application).
If you are using a PingFederate base URL of https://localhost:9031 for testing purpose, you can skip this field.
- On the Authentication Application screen, click Save.
- On the Manage Authentication Applications screen, click Save as well.
Explore the available states, actions, and models for any API-capable adapter or selector in your PingFederate environment
Browse to the URL of the Authentication API Explorer; for example:
Select an authentication adapter or selector from the Authentication
Based on your selection, the Authentication API Explorer displays a list of states. You can then inspect the following items for any given state.
- The state purpose
- The state data model (if any)
- The available action of actions (if any)
- The action data model (if any) for a given action
- The errors (if any) for a given action
This information is vital for the developers of your web applications to create the desired authentication experience.
Explore the authentication API through a request without an authentication policy
Configure a use case to use an instance of the HTML Form Adapter for
For example, you may create an SP connection that uses an instance of the HTML Form Adapter for authentication.
- On the Authentication API Explorer from the Default Authentication Application list. screen, choose the authentication application that represents the
Initiate a request supported by the use case you configured in step 9.
When PingFederate receives your request, it gathers from your use case that it should invoke the HTML Form Adapter. Because the HTML Form Adapter is API-enabled and you have configured the Authentication API Explorer to be the default authentication application, instead of returning the Sign On screen (from the HTML Form Adapter), PingFederate redirects the browser to the Authentication API Explorer with a flowid query parameter; for example: https://localhost:9031/pf-ws/authn/explorer?flowId=Tt9n7
The Authentication API Explorer opens and pre-populates the Flow ID field with the flow ID value generated by PingFederate,
Tt9n7in our example.
In the Authentication API Explorer, click Get next to the pre-populated flow ID
The Authentication API Explorer displays a JSON response as the result of the GET request. This response contains information that the web application requires to proceed further. For instance, the status parameter value indicates the current state of the request. Because the sample request invokes the HTML Form Adapter, the current state should be USERNAME_PASSWORD_REQUIRED.
At the end of the result is a hyperlink to the current state. In this example, when you select the current state link, the Authentication API Explorer jumps to the USERNAME_PASSWORD_REQUIRED state and expands its contents for further review.
From this point, you can review the state data model and move the request further by selecting the appropriate action (and action data if it is required).
Explore the authentication API through a request with an authentication policy
On the Select from the
Default Authentication Application list.
As a result, there is no default authentication application now.
Define an authentication policy to use the Authentication API Explorer.
- On the Add Policy. screen, click
- Enter a policy name and optionally a description.
- Select the authentication application that represents the Authentication API Explorer from the Authentication Application list.
Select the HTML Form Adapter instance that has been mapped to your use
case in step 9.
For both the Fail and Success policy paths, select Done.
- Click Done.
- Select the IdP Authentication Policies check box.
- Click Save.
- Initiate a request supported by the use case you configured in step 9.
- Use the Authentication API Explorer to learn more about the authentication API.
Generate a Postman collection file
Browse to the URL of the Authentication API Explorer; for
- Click the orange Postman Collection button.
- Navigate to the location where you want to save the postman_collection.json file, and click Save.
- Open Postman, and import the file.
In Postman, manually configure the following:
flowidcollection variable. When PingFederate receives a request, it generates the
flowidand displays it in the Flow ID field on the Authentication API Explorer screen; for example,
baseUrlcollection variable. This is the base URL of your Authentication API Explorer; for example: https://localhost:9031.
- The PingFederate cookie.
You must also modify the body (if one exists) to ensure that API calls work correctly.