PingFederate Server

Authentication API states, actions, and models

To develop authentication API-capable adapters and selectors, you must understand the states, actions, and models of single sign-on (SSO) transactions through the PingFederate authentication API.

PingFederate assigns a flow ID to each SSO transaction that uses the authentication API. PingFederate uses the flow ID to determine a transaction’s state.

As a user steps through an SSO transaction, the transaction is always in some state. The state includes a status field and other fields specific to that state. The class containing those other fields is the model for the state.

The API endpoint returns the following when the user’s SSO transaction has reached the USERNAME_PASSWORD_REQUIRED state for the form adapter.

{
	"id": "PyH5g",
	"pluginTypeId": "7RmQNDWaOnBoudTufx2sEw",
	"status": "USERNAME_PASSWORD_REQUIRED",
	"showRememberMyUsername": false,
	"showThisIsMyDevice": false,
	"thisIsMyDeviceSelected": false,
	"showCaptcha": false,
	"rememberMyUsernameSelected": false,
	"_links": {
		"self": {
			"href": "https://localhost:9031/pf-ws/authn/flows/PyH5g"
		},
		"checkUsernamePassword": {
			"href": "https://localhost:9031/pf-ws/authn/flows/PyH5g"
		}
	}
}

The model for this state is the class UsernamePasswordRequired. It includes fields such as showThisIsMyDevice, which help the API client know how to render the credential prompt to the user.

The API response also includes a list of available actions. In this case, the only action available is checkUsernamePassword. The API client can select this action by sending a POST request with the Content-Type of application/vnd.pingidentity.checkUsernamePassword+json. Each action has its own model containing the fields that the POST body can provide. For the checkUsernamePassword action, the model is CheckUsernamePassword.

The POST body can be as simple as the following.

{
	"username": "joe",
	"password": "2Federate"
}

After receiving this request, PingFederate calls the lookupAuthN() method of the form adapter. If the form adapter encounters an error while validating the credentials, it writes a JSON API error to the response. If the form adapter successfully validates the credentials, it returns AUTHN_STATUS.SUCCESS from its lookupAuthN()method. PingFederate then goes to the next step in the authentication policy. If the next step is an API-capable adapter, PingFederate calls lookupAuthN()on that adapter and the adapter determines its current state and writes it to the response, along with the available actions.

The PingFederate authentication API follows a different naming convention for actions than PingOne. PingOne names actions as noun.verb, such as otp.check. PingFederate uses verbNoun, such as checkOtp.