Use Cases

Using the PingFederate Authentication API in a DevOps environment

Learn how to configure the PingFederate authentication API and how to get it up and running in Postman.

Components

  • PingFederate 10.3

  • OAuth Playground

Before you begin

You must:

Overview of the PingFederate Authentication API

The PingFederate Authentication API supports two modes of authentication:

  • Redirectless or Application Embedded

    This mode of deployment is useful when you want to manage the sign-on experience without redirecting users to an external identity provider (IdP).

  • Authentication Portal

    In this mode of deployment, applications are still configured as clients on PingFederate. However, rather than authenticating using out of the box templates in PingFederate, users are directed to the authentication portal. The authentication portal presents the desired look, feel, and workflow while authenticating users to PingFederate through the Authentication API.

The deployment modes described above are not mutually exclusive. For example, you can build a central authentication portal that allows single sign-on (SSO) for web clients while also using the redirectless flow for mobile apps. You’ll see this later when you test a redirect flow using ground and a redirectless flow using Postman.

The following table lists URLs you’ll be revisiting throughout this task:

Interface URL

PingFederate administrative console

https://localhost:9999/pingfederate/app?service=page/Home

OAuth Playground

https://localhost:9031/OAuthPlayground/welcome

Authentication API Explorer

https://localhost:9031/pf-ws/authn/explorer

Enabling the Authentication API in PingFederate

About this task

Consult with your PingFederate administrators before configuring a Default Authentication Application in a production or shared environment. It may break non-API login flows unless done properly.

Steps

  1. In the PingFederate administrative console, go to Authentication → Integration → Authentication API Applications.

  2. Click Add Authentication Application and enter the API Explorer application information.

    The URL field is used solely in the Authentication Portal deployment mode. Clients attempting to authenticate to PingFederate will be redirected to the URL specified here with a flow ID set in query parameters.

  3. Click Save.

    Result:

    You’re redirected to the Authentication API Applications page.

    There isn’t a Default Authentication Application selected. This isn’t necessary in our scenario because the PingFederate configuration you’re working with uses an authentication policy that overrides this setting. However, if you’re working in a configuration that doesn’t use an authentication policy, this setting causes clients to be redirected to the specified application instead of using the PingFederate sign-on page.

  4. Click Save again.

Enabling redirect flows for API Explorer

About this task

In this step, you enable redirect flows so you can use the API Explorer to simulate a centralized sign-on page that uses the Authentication API to authenticate users. This might not be appropriate for your desired deployment model. Regardless, the API Explorer is a convenient way for developers to explore the API.

As mentioned in the previous section, the Docker image you’re using in this guide has a pre-configured authentication policy, so even though you’ve enabled the Authentication API, it’s never invoked unless it’s associated with the pre-existing authentication policy.

Steps

  1. Go to Authentication → Policies → Default AuthN Policy.

  2. Select the authentication application that you created.

  3. Click Done and, when you’re redirected to the next page, click Save.

Enabling redirectless flows for Postman

Steps

  1. Go to Applications → OAuth → Clients.

  2. Click the ac_oic_client configuration and enable Allow Authentication API OAuth Initiation.

  3. Select openid, and at the bottom of the page, click Save.

    Result:

    PingFederate is configured for API Authentication and is ready to test.

Testing redirect flows with OAuth Playground

Steps

  1. Open OAuth Playground.

    For instructions on installing and configuring OAuth Playground, see OAuth Playground in the PingFederate documentation.

  2. In the left navigation pane, click Authorization Code and enable OpenID Connect.

  3. Click Submit.

    Result:

    You’re redirected to the API Explorer.

    Usually this would direct you to a sign-on page hosted on PingFederate, but you redirected the flow by adding the API application with the URL of the API Explorer and selecting the application in the active authentication policy.

  4. In the Authentication Adapter/Selector list, select HTML Form IdP Adapter.

  5. Click Get to initiate the Authentication phase of the flow.

    The status is set to USERNAME_PASSWORD_REQUIRED.

  6. Expand the USERNAME_PASSWORD_REQUIRED section.

  7. Click Paste Model Template and edit the template with your credentials.

  8. Click Post.

    The request will look like the following.

    POST https://localhost:9031/pf-ws/authn/flows/VKX4Q?action=checkUsernamePassword

{
"username": "user.1",
"password": "Password1"
}

    The response after you post will look like the following.

    {
"id": "g2H6A",
"pluginTypeId": "7RmQNDWaOnBoudTufx2sEw",
"status": "RESUME",
"resumeUrl": "https://localhost:9031/as/g2H6A/resume/as/authorization.ping",
"_links": {
"self": {
"href": "https://localhost:9031/pf-ws/authn/flows/g2H6A"
}
}
}

  9. Under the Post button, in the Result code box, click Resume URL.

    Result:

    You’re redirected to the OAuth Playground.

  10. Click Submit to exchange your authorization code for a valid token by sending a request to the /as/token.oauth2 endpoint.

    Result:

    You can see the text for the provided access_token and id_token.

  11. Click Validate on either token to have OAuth Playground validate the tokens and display any embedded claims.

    Result:

    You’ve successfully used the Authentication API to simulate an authentication portal experience.

Testing redirectless flows in Postman

About this task

This test flow will be a simple three-call flow that:

  1. Receives a Flow ID

  2. Checks credentials

  3. Retrieves tokens

Steps

  1. To initiate the flow, call the standard authorization endpoint.

    GET https://localhost:9031/as/authorization.oauth2
    Table 1. Query parameters
    Parameter Value Description

    client_id

    ac_oic_client

    The OAuth client ID configured in PingFederate.

    response_type

    code

    Specifies the Authorization code grant type.

    response_mode

    pi.flow

    Specifies a redirectless flow with JSON responses.

    scope

    openid

    Specifies the OAuth2 scope. openid is a reserved scope that enables id_token issuance.

    These are all standard OAuth2 parameters, with the exception of response_mode, which is how PingFederate determines if an authentication flow should be redirected to an authentication portal through a 302 Redirect, or responded to with JSON in a 200 OK.

    Example:

    The following example shows a sample call response.

    {
"id": "Bq5XW",
"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/Bq5XW"
},
"checkUsernamePassword": {
"href": "https://localhost:9031/pf-ws/authn/flows/Bq5XW"
},
"initiateRegistration": {
"href": "https://localhost:9031/pf-ws/authn/flows/Bq5XW"
}
}
}

  2. To see what actions the user should take to authenticate, run the checkUsernamePassword action with the following command.

    POST https://localhost:9031/pf-ws/authn/flows/{{flowId}}
    Table 2. Headers
    Header Value Description

    X-XSRF-HEADER

    test

    This custom header ensures that browsers enforce cross-origin resource sharing (CORS) policies when API requests are sent.

    The value of this header does not matter.

    Content-Type

    application/json

    Standard API header.
    Table 3. Query parameters
    Parameter Value Description

    action

    checkUsernamePassword

    An action associated with the current authentication state.

    Example:

    The payload will look like the following.

    {
"username" : "user.1",
"password" : "Password1"
}

    The call response will look like the following.

    {
"id": "Bq5XW",
"pluginTypeId": "CmqYYkZJLFOAcDW4Ob1wXw",
"status": "COMPLETED",
"authorizeResponse": {
"code": "qXSrGABNgJpn_JBuiSW8IWIVDkxsIVbsQLLrYH_X"
},
"_links": {
"self": {
"href": "https://localhost:9031/pf-ws/authn/flows/Bq5XW"
}
}
}

    Result:

    Your status is COMPLETED, but your code must account for possible error states, such as CREDENTIAL_VALIDATION_FAILED.

    You also receive an href that can be used to initiate the next flow so that you don’t need to store a table of possible statuses and associated endpoints. Using this over hard-coded endpoints helps future-proof your code against possible future changes to the API.

  3. To establish the user’s identity and make API calls on their behalf, retrieve your tokens with the following command.

    POST https://localhost:9031/as/token.oauth2
    Table 4. Payload (x-www-form-urlencoded)
    Payload Value Description

    client_id

    ac_oic_client

    The OAuth client ID configured in PingFederate

    grant_type

    authorization_code

    The grant type associated with the specified client_id

    code

    \{{authCode}}

    The code returned in the previous payload

    client_secret

    abc123DEFghijklmnop4567rstuvwxyzZYXWUT8910SRQPOnmlijhoauthplaygroundapplication

    The client secret associated with the specified client_id

    The following is a sample call response.

    {
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImsxIiwicGkuYXRtIjoieDR6diJ9.eyJzY29wZSI6WyJvcGVuaWQiXSwiY2xpZW50X2lkX25hbWUiOiJhY19vaWNfY2xpZW50IiwiYWdpZCI6ImhoMUt3ckQ1RDRWdmVTRmVlVDc2NEEwdFhOaWZHQ2YyIiwiVXNlcm5hbWUiOiI0ZTliNzg0Ny1lZGNiLTM3OTEtYjExYi03NTA1ZjRhNTVhZjQiLCJPcmdOYW1lIjoiUGluZ0lkZW50aXR5IiwiZXhwIjoxNjE5OTQ4NzQyfQ.WoxPBqRJfA4z71KmQYOnOasVmCZMe9HG06QAi2iVCeG9jzUAudjuNs3HOGvYobtr7_VY8pYu8G3DSK3EPvu1Ox2-c_6D89EZeDmQWJATiL2cpkIs2XU1Fb4HpDuFGPSTZUR4ijSdqyWS7XhYZNAF4MQf3LTu3lih7ud5AH0a1VKlK1tE5kP-VXiebjzo0G6A3oAIhQ9Fopnd9NWTJZ734m8OHldfbueFC1aYLf5u1U-8my2PUMHRkmBzFACVRCdRhp1Dlrkj86kJbZ1WVSZ1qItAe0qSrMmTvIWlD5mlIsSDU0Qh9M1m1ZzzKEnQQET_cXJXxs3QRqTFzFWo6DysHA",
"refresh_token": "ZTZ2psveZ1qe1ngy82zdM2BUqNAPWqxBcDS3FZlgys",
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEzRVRpSGF0Wjg4czFEMlhLSGstdzRyZkdLYyJ9.eyJzdWIiOiI0ZTliNzg0Ny1lZGNiLTM3OTEtYjExYi03NTA1ZjRhNTVhZjQiLCJhdWQiOiJhY19vaWNfY2xpZW50IiwianRpIjoiT2pGaWhQNjNmalJ3OHBiNTBrT1lqNCIsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0OjkwMzEiLCJpYXQiOjE2MTk5NDE1NDAsImV4cCI6MTYxOTk0MTg0MCwiYXV0aF90aW1lIjoxNjE5OTQxNTQwfQ.bJzboJy2oWbdhBbSPBqeKmHwQLqE4hL1M0aIleMdoD9GbQ0PEENjb4PE-rGoxrBhBqUxeoHvqBF-98BQBbUsYVJwwMOAwZ4MU9FnOEf2kpZ-9slAot2dWGHef9S6P-So1doi6bbqp9aPcYJpzyvOKCJRHMzZtiPclRHrIUaU7xRcoFbpfZ-8mr6icJUikqzrtaYqGVxTlILPgenI8c0Aau103yfrezRKbK3LJSdKZ7CJ5NJBhQXOqd7jsyMfEa8AQOT8pWYw7He53Y0FF1jCK6leQIT_ZtXxsl8Gi1-KvXyt2FNm02CPIDMrbpp2cI_054xDc6X7_BchvKlI9mjGiw",
"token_type": "Bearer",
"expires_in": 7199
}

    Result:

    You receive three tokens in the response, marking the end of the authentication process.