In PingFederate, you can configure mobile applications to authenticate through REST APIs as OAuth clients without needing to handle HTTP redirections. When authentication is complete, the applications receive an OAuth authorization code or access token, and possibly an OpenID Connect ID token.
Single-page web applications can also use redirectless mode if administrators configure them in PingFederate as authentication applications. For more information, see Configuring authentication applications. Web-based authentication applications must be highly trusted. See Denying authentication applications access to the authorization endpoint for more information on security considerations for authentication applications.
Administrators can allow an OAuth client to initiate authorization directly through the authentication API:
- Go to the client's configuration in the Client window.
- Select the Allow Authentication API OAuth Initiation check box.
When enabling this feature, consider the following:
- Redirection URLs are optional, but without a redirection URL, browser-based OAuth flows will not work.
- This flow does not support the user-facing scope consent page, Request for Approval. So, enabling this feature automatically enables the Bypass Authorization Approval feature and Restrict Common Scopes feature.
- The application must manage the PF cookie and, if persistent authentication sessions are configured, the PF.PERSISTENT cookie.
To authenticate with this method, an OAuth client makes two or more API requests:
- The OAuth client initiates authentication by calling the OAuth 2.0 authorization
endpoint
/as/authorization.oauth2
to get a flow ID and other information it needs for the next request. The client must specify the pi.flow response mode in this call. See the first request sample below.Note:If a valid authentication session already exists when the OAuth client makes the first request, the client will receive a response with a token. In this case, the client does not need to make the next request.
- The client calls the authentication API flow endpoint
/pf-ws/authn/flows/{flow_id}
to get the token. See the second request sample below.Note:In some cases, depending on the configuration of the authentication policy, the client must make more than two requests to get a token.
First request sample
GET /as/authorization.oauth2?client_id=im_client&response_type=token&response_mode=pi.flow HTTP/1.1
Host: www.example.com:9031
X-XSRF-Header: PingFederate
Sample response 1 to the first request: If a valid authentication session does not
already exist, the OAuth client receives a response that provides the information
the client needs for the next request (see the second request sample). The
self
link in the response shows that the second request must
call the pf-ws/authn/flows
endpoint, rather than the authorization
endpoint. The value of the id
field is the ID of the flow that was
created. The client must append the flow ID to the
pf-ws/authn/flows
endpoint for subsequent API requests.
{
"id": "PyH5g", // Flow ID
"pluginTypeId": "7RmQNDWaOnBoudTufx2sEw",
"status": "USERNAME_PASSWORD_REQUIRED",
"showRememberMyUsername": false,
"showThisIsMyDevice": false,
"thisIsMyDeviceSelected": false,
"showCaptcha": false,
"rememberMyUsernameSelected": false,
"_links": {
"self": {
"href": "https://www.example.com:9031/pf-ws/authn/flows/PyH5g"
},
"checkUsernamePassword": {
"href": "https://www.example.com:9031/pf-ws/authn/flows/PyH5g"
}
}
}
Sample response 2 to the first request: If a valid authentication session already exists, the OAuth client receives a response with a token. So the client does not need to make the second request.
{
"id": "PyH5g", // Flow ID
"pluginTypeId": "7RmQNDWaOnBoudTufx2sEw",
"status": "COMPLETED",
"authorizeResponse": {
"access_token": "000144Qlv9eqpBk03ngAd7M35Gaj41Mgisk",
"token_type": "Bearer"
"_links": {
"self": {
"href": "https://www.example.com:9031/pf-ws/authn/flows/PyH5g"
}
}
}
Second request sample
POST /pf-ws/authn/flows/PyH5g HTTP/1.1
Host: www.example.com:9031
X-XSRF-Header: PingFederate
Content-Type: application/vnd.pingidentity.checkUsernamePassword+json
Cookie: PF=8PgutwFizNS7EoaiB0qVsa
{
"username": "joe",
"password": "Password1"
}
Sample response to the second request
{
"id": "PyH5g",
"pluginTypeId": "7RmQNDWaOnBoudTufx2sEw",
"status": "COMPLETED",
"authorizeResponse": {
"access_token": "000144Qlv9eqpBk03ngAd7M35Gaj41Mgisk",
"token_type": "Bearer"
"_links": {
"self": {
"href": "https://www.example.com:9031/pf-ws/authn/flows/PyH5g"
}
}
}