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, 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.

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.

Sequence diagram of mobile application authentication through REST APIs

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"
        }
    }
}

PingFederate Server

Mobile application authentication through REST APIs

First request sample

Second request sample