Mobile application authentication through REST APIs
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 an access token and possibly an OpenID Connect (OIDC) 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.
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 Redirectless Mode check box.
When enabling this feature, consider the following:
-
Redirection URLs are optional, but without a redirection URL, browser-based OAuth flows do not work.
-
This flow does not support the user-facing scope consent page, Request for Approval.
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, thePF.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.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.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
- 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).
{
"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"
}
}
}
The self
link in the response shows that the second request must call the pf-ws/authn/flows
endpoint instead of 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.
- 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"
}
}
}