--- title: Using the PingFederate Authentication API in a DevOps environment description: Learn how to configure the PingFederate authentication API and how to get it up and running in Postman. component: solution-guides page_id: solution-guides:single_sign-on_use_cases:htg_pf_authn_api_devops_env canonical_url: https://docs.pingidentity.com/solution-guides/single_sign-on_use_cases/htg_pf_authn_api_devops_env.html revdate: July 25, 2025 page_aliases: ["single_sign-on_use_cases:htg_pf_authn_api_devops_env_oveview.adoc", "single_sign-on_use_cases:htg_pf_authn_api_devops_env_enable_authn_api.adoc", "single_sign-on_use_cases:htg_pf_authn_api_devops_env_enable_redirect_api.adoc", "single_sign-on_use_cases:htg_pf_authn_api_devops_env_enable_redirectless_postman.adoc", "single_sign-on_use_cases:htg_pf_authn_api_devops_env_testing_redirect.adoc", "single_sign-on_use_cases:htg_pf_authn_api_devops_env_testing_redirectless.adoc"] section_ids: components: Components before-you-begin: Before you begin overview-of-the-pingfederate-authentication-api: Overview of the PingFederate Authentication API enabling-the-authentication-api-in-pingfederate: Enabling the Authentication API in PingFederate about-this-task: About this task steps: Steps result: Result: enabling-redirect-flows-for-api-explorer: Enabling redirect flows for API Explorer about-this-task-2: About this task steps-2: Steps enabling-redirectless-flows-for-postman: Enabling redirectless flows for Postman steps-3: Steps result-2: Result: testing-redirect-flows-with-oauth-playground: Testing redirect flows with OAuth Playground steps-4: Steps result-3: Result: result-4: Result: result-5: Result: result-6: Result: testing-redirectless-flows-in-postman: Testing redirectless flows in Postman about-this-task-3: About this task steps-5: Steps example: Example: example-2: Example: result-7: Result: result-8: Result: --- # 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: * Deploy PingFederate to a local instance. To learn more, refer to the Ping Identity [DevOps Introduction](https://developer.pingidentity.com/devops/get-started/introduction.html). * Download and install [OAuth Playground](https://docs.pingidentity.com/pingfederate/latest/developers_reference_guide/pf_oauth_endpoints.html), which demonstrates OAuth and OpenID Connect flows with PingFederate. ## 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, refer to [OAuth Playground](https://docs.pingidentity.com/pingfederate/latest/developers_reference_guide/pf_oauth_endpoints.html) 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. ```json { "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: To view the text of 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. ```json { "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. ```json { "username" : "user.1", "password" : "Password1" } ``` The call response will look like the following. ```json { "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. ```json { "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.