Terms that you'll use in this section:

• Environment

  Although an environment is automatically created for you when you first sign on to PingOne, for the purposes of testing PingOne workflows, you'll create an additional, new environment.

• Worker app

  A Worker app is an admin-level application connection that interacts with the PingOne APIs on your behalf. The access token associated with a Worker app gives you admin-level access to all of the PingOne APIs. A Worker app's authorized access to the PingOne API resources is determined by the roles and associated permissions that you assign to the Worker app. By default, these roles and permissions are inherited from your user when you create the Worker app.

• Access Token

  An access token is required to authenticate any calls to the PingOne Platform APIs. The access token is valid for one hour.

• Population

  A population is a collection of users within an environment, similar to an organizational unit (OU). This gives you a way to manage and apply operations to a large set of users.

The diagram below shows how these entities interact.

You'll use our Postman collections to complete the stepped instructions for using the PingOne APIs. This makes it easy to see and use the API calls. There is a separate Postman collection for each set of stepped API instructions, with a link to import or fork the associated Postman collection.

If you aren't currently using Postman, you can install the free version. See Download Postman to install Postman, either locally, or in your browser.

Each of our Postman collections contains environment variables that are used by the associated set of APIs. We've already set the values for these environment variables. Additionally, we've included in the collections Postman test scripts that set the necessary environment variable or variables as you move through a workflow. All that's left for you to do is to see, and hopefully understand, what's needed to use the PingOne APIs, and how PingOne workflows operate.

For more information about our Postman environments, see The PingOne Postman environment template.

The Postman master collections includes requests for all create, read, update, and delete (CRUD) operations for the PingOne Platform APIs, the PingOne MFA APIs, and the PingOne Protect APIs. The downloads also include a PingOne Postman environment template to help you assign values to variables in the request URLs.

For more information about the Postman environment template, see The PingOne Postman Environment Template.

The PingOne Postman collections

Collection	Description	Retrieve
Platform	Postman requests for the PingOne platform API. Includes all environment variables. No example responses to make it easy to get started.
Platform	Postman requests for the PingOne platform API. Includes all PingOne documentation and example reponses. No environment variables are included.

Download a Postman collection

You have two methods for retrieving a Postman collection into your workspace.

1. Fork the collection into your workspace. Postman retains an association between the source and your fork. If Ping Identity changes the source collection, you can pull those changes into the fork in your workspace.

2. Import the collection into your workspace. This is a one-time transfer and retains no association to the source collection.

To retrieve the collection:

1. Click the collection's Run In Postman button.

2. At the prompt, click Fork Collection at the bottom of the dialog or click import a copy near the bottom of the dialog.

   Note: You need to be logged in to your Postman account to retrieve the collection.

   

3. Follow the on-screen instructions to fork or import the collection. You might be prompted to open your Postman app and to select a Postman workspace for the retrieved collection.

When you fork a Postman collection, you create a copy of it in a different workspace. Forking a collection creates a linked version that synchronizes with its source collection. This synchronization is apparent when you click the three dots icon on the forked collection - you will see Pull changes on the context menu. Click Pull changes and Postman compares the fork to the source collection. If changes are available, you can pull those changes into your fork. If you also watch the collection, you receive notifications when the source changes.

If you import a collection, a copy is created with no link back to the source. The collection is static. This may be desirable for some use cases. For example, if you intend to keep and consume only portions of the collection, a link back to the source is not needed.

One need not choose one or the other - you can fork a copy to track the source and import a copy for experimentation!

The environment downloaded with the collection of requests contains every variable used in the collection. Each request that creates a new object with an id has a script that:

1. If not available, creates an environment variable unique to that service.

2. Assigns the id of the newly created object to that environment variable.

The Postman collection uses variables in the request URLs to specify UUIDs for PingOne resources within your organization. When you click the Run in Postman button, the environment variable template downloads and installs automatically. With this environment template, you can associate your PingOne resource UUIDs with the common variables used in many of the requests.

For more information about using Postman environments, see the following topic in the Postman documentation: Environments in Postman.

In the PingOne Postman download collections, for POST requests that create a resource and return a resource ID, these requests include a script that automatically adds a resource variable to your active Postman environment template and uses the newly created ID as the value.

For example, the following request from the PingOne Postman collection creates a new user. This request URL contains variables for the API path and environment ID:

POST {{apiPath}}/environments/{{envID}}/users

To run this request, you must ensure the {{apiPath}} in the Postman environment template has the regional top level domain associated with your organization. See Variables you must value for more information.

Almost every request in PingOne requires an environment ID. If you are working primarily in one environment for testing purposes, you should add your environment's UUID to the active Postman template as the value for the {{envID}} variable. In addition, requests to PingOne Management API endpoints require a valid access token to authenticate the request. In the PingOne download collections, the token value is represented in the Postman environment template as the variable {{accessToken}}.

With the {{tld}} and {{envID}} variables defined in your Postman template, and with a valid token value defined in the {{accessToken}} variable, you can run the request. If the request is successful, Postman adds a {{userID}} variable to the Postman template automatically, and it associates the new user's id property value (the UUID of the new user) with this variable.

Notes about environment variables and security

It is important to understand how Postman allows you to Store and reuse values using variables. Postman has two values for each environment variable: an Initial value and a Current value. Pay particular attention to differences between Initial and current values. Initial values are saved to Postman's cloud and available to anyone who has access to the environment. Current values are saved only locally and available only to you. Postman uses only the current value in requests. If an environment variable has an initial value but no current value, Postman does not copy it to the current value or use the initial value in the request, the request simply fails. You must manually copy the initial value to the current value.

In Sharing and persisting data, Postman states: "When you create a new variable in Postman, if you leave the current value empty, it will autofill with the initial value." Note that opening clause: "When you create a new variable in Postman"! When you create a new variable with an initial value and save the environment, Postman autofills the current value. However, that is the only time that Postman autofills the current value. If you subsequently delete the current value, the variable is no longer valued in a request.

Saving initial values to the cloud impacts security, especially if a workspace is public, because initial values are available to anyone who has access to the workspace. If a workspace is public, then literally the entire world can view!

While documented, Postman now emphasizes security of initial values as discussed in Announcing security updates to the Public API Network: new secret-protection policy. The recommended solution to exposing secrets is to Store secrets in your Postman Vault. Use the Postman Vault to Create and manage vault secrets. Remember that Postman uses only current values in requests!

To use a vault variable as the value for another Postman variable, you must add your vault variable to the initial value for your teammates to view and to the current value for a request to use it. For example, a request uses an environment variable called my-secret. One user may choose to use the current value to store their value and leave the initial value blank. Another user may choose to use a Postman Vault variable, such as my-secret-vault, as the value. The former user must ensure that they do not use the initial value if they do not wish to share its value with the team. The latter user can safely use {{vault:my-secret-vault}} as both the initial value and the current value because Postman saves only the text: the name of the vault variable as the text literal, {{vault:my-secret-vault}}. At run time, Postman acquires the value from the user's Vault.

As seen in the previous example, the vault variable need not be named the same as the environment variable. A Postman Vault is exclusively yours and its variables are available for use anywhere Postman variables are used. Thus, if you have multiple environments and each has a different value, then you must differentiate the variable names in your Vault. If you had a PROD environment and a STAGE environment, then you could have my-secret-prod and my-secret-stage in your vault for the two environments.

Variables you must value

When you download the PingOne Postman collections, your workspace receives a Postman environment variable template. Variables in the environment variable template that represent a resource in PingOne automatically receive a value when you create a new PingOne resource using Postman. A script on the Tests tab of each create request inserts the identifier of the resource it creates as the value of the variable associated with that resource. However, some variables essential to using Postman with PingOne are not valued automatically. You must manually add the correct value to the variables in this table before you make any requests in Postman.

Set tld to the top level domain of the region appropriate for your environment:

To make calls to the PingOne Platform API, you must get an admin-level access token from a Worker app and submit this access token whenever you make an API request.

Use the PingOne admin console to create a Worker app connection in your initial PingOne environment created when you first signed on:

1. Log in to the PingOne admin console. For more information about the PingOne admin console, see Accessing the admin console home page.

2. Select Applications --> Applications.

   

3. Click the + icon next to Applications to add a new app.

4. In the Application Name field, enter an application name, and select Worker as the Application Type.

   

5. Click Save.

6. Click the toggle at the upper right to enable the application.

7. The environment ID, Worker app Client ID, and Worker app Client Secret is displayed.

   

   Note: You're also able to get the access token assigned to the Worker app here, but for the purposes of this tutorial, we'll show you how to get the access token using a PingOne API request.

8. Select the Roles tab, and click Grant Roles. The best practice is to reduce the roles assigned to the Worker app to only those necessary. For this tutorial, grant the roles and permissions as shown.

   

9. Click Save.

10. The roles and permissions you've granted are then displayed. They should look like this:

    

You'll need the Client ID and Client Secret associated with your Worker app when obtaining an admin access token in the next workflow to Create your test environment.

Although an environment is automatically created for you when you first sign on to PingOne, for the purposes of testing PingOne workflows, you'll create an additional, new environment.

Prerequisites

• The Organization Admin role is required to create an environment. You're assigned the Organization Admin role when you create a PingOne account.

• A Postman installation. If you aren't currently using Postman, you can install the free version. See Download Postman to install Postman.

• Import or fork the Postman collection into your Postman installation. Click the Run in Postman button below. You'll use this collection for the test environment workflow:

  

  For more information about using Postman environments, see The PingOne Postman environment template.

• When you open the Postman collection, ensure that you select PingOne Postman Environment Template for use with the collection:

  

Now that you have a test environment set up, complete the following PingOne sign-on workflow to test your new environment. You will create an OIDC Web app, get the new web app's secret, and initiate an authorization request.

This workflow uses the environment, access token, and test user that you created in Create your test environment. Rather than using the PingOne admin console to create an OIDC Web app, you'll create the web app using the API request.

Prerequisites

• A Postman installation. If you aren't currently using Postman, you can install the free version. See Download Postman to install Postman.

• Import or fork the Postman collection into your Postman installation. Click the Run in Postman button below. You'll use this collection for the test environment workflow:

  

  For more information about using Postman environments, see The PingOne Postman environment template.

• When you open the Postman collection, ensure that you select PingOne Postman Environment Template for use with the collection:

  

Our workflow library describes the workflows for common PingOne use cases, both for the platform and its services. Each use case is configured as a Postman collection, and includes a Run in Postman button, enabling you to load the collection in your Postman workspace.

Prerequisite

To access the PingOne APIs, you'll need an admin access token. If you haven't completed the configuration steps in Create Your Test Environment, stop and do that now. This workflow shows you how to create a Worker (admin) application and use that application's properties to get an admin access token. In that section, there is a Run In Postman link to download a special Postman collection to help you get the token and create a test user. Do not proceed until you have completed these tasks.

Configuring and managing Postman

When using the Postman collections linked to PingOne use cases, you'll need to configure any of your Postman requests for authorization and authentication to not follow redirects automatically. You'll also need to do this for requests that require a redirect to the authorization server. These requests will not execute the steps in the Postman collection as intended if Postman's Automatically follow redirects setting is turned on.

To disable the Automatically follow redirects setting for requests in Postman:

1. Open your Postman application, and for each relevant request, select Settings.

2. Ensure that the Automatically follow redirects setting is set to OFF.

For more information about Postman preferences, see Setting up Postman.

Removing session cookies in Postman

When you run use case collections that involve authentication flows, the PingOne API uses session token cookies to establish the user's authentication session and maintain the session throughout the workflow. Postman functions as the calling client to save these cookies, allowing the flow to redirect back to the authorization server to get an access token.

Before you run any use cases, we recommend that you remove all old session token cookies from Postman. To remove these cookies:

1. For the use case you want to run, open the Step 1 request.

2. Click the Cookies link, which is directly under the Send button.

3. On the Manage Cookies page, delete all session token cookies listed until you see the No Cookies available message.

For more information about Postman and cookie management, see Using cookies.

Downloading PingOne use case collections

Any of the use case collections you can fork into your Postman workspace, or download and import. Each use case also offers a button to retrieve the collection for that use case. The table lists use cases in the order they appear in the navigation panel.

Use Case	Retrieve
Create your test environment
Simple SSO
Configure an Application with an Authorization Code Grant
Configure an Application with a Refresh Token Grant
Configure a Single-Page Application with PKCE and an AuthCode Grant
Configure a Single-Page Application with an Implicit Grant
Configure a Non-Interactive Worker Application
Configure an Interactive Worker Application
Test a SAML Application Connection
Test an OIDC Application Connection
Configure a Simple Login
Get an ID Token
Add a User through a Registration Flow
Use LOGIN and MFA Actions to Authenticate Users
Configure a PKCE Authorization Workflow
Configure a Progressive Profiling Sign-On Action
Configure Device Authorization Grant Flow
Use LOGIN and AGREEMENT Actions to Authenticate Users
Get a Token for Custom Resource Access
Add a Custom Claim to an Access Token
Configure CLIENT_SECRET_JWT as the token auth method
Use an authentication JWT for token fulfillment
Exchange a Refresh Token
SAML Sign-On
Test an OAuth Connection using Identifier First Authentication
Sign-on using an External Identity Provider
Configure a PingOne App to Use a DaVinci Flow Policy
Configure a DaVinci Non-redirect Flow
Create an LDAP Gateway
Create a Group and Add a User
Create a Workday Propagation Connection
Configure Facebook as an Identity Provider
Configure a SAML Identity Provider
Download an Integration Binary
Audit for Agreement Consents
Assign an MFA Sign-On Policy to a Web Application
Configure a Passwordless Sign-On Policy
Configure an MFA-Only Flow Using a Login Hint Token
Create an MFA Transaction Approval using SMS
Use an Email MFA Action to Authenticate Users
Configure an MFA Sign-On Policy with an Authenticator App
Create and Update Notification Content
Create a Password Policy
Show PingOne Authorize App Permissions in Token
Create and Assign App Roles
Create a Risk Policy Set
Create a Risk Evaluation
Assign a Role to a User
Add User Image
Find and Terminate a User Session
Sign-Off User Session

Using the PingOne Postman environment

The PingOne use case collections include test scripts that write environment variables and their current values to your active Postman environment for the newly created PingOne resources.

To save and use these resource IDs, specify a Postman environment and have the following Postman environment variables set before you begin. See The PingOne Postman Environment Template for the regional domains associated with the API endpoints for these environment variables:

• {{tld}}

  The top level domain for your region: com, ca, eu, asia, or com.au. This variable is incorporated in each of the following {{...Path}} variables to make changing your region simple. When you set {{tld}}, the {{...Path}} variables are also set to the appropriate region.

• {{apiPath}}

  The regional domain for the PingOne server. These IDs identify a specific configured application in PingOne.

• {{authPath}}

  The domain for the PingOne authentication server.

• {{orchestratePath}}

  The regional domain (and part of the path) for the PingOne DaVinci server.

• {{scimPath}}

  The regional domain (and part of the path) for the PingOne SCIM server.

• {{envID}}

  The UUID of an environment resource. This ID identifies your current working domain within your organization.

• {{accessToken}}

  A valid access token returned by the PingOne authorization server from the worker application in your current environment. For information about creating a worker application and getting an access token, see Create an admin Worker app connection.

The PingOne Postman environment template

If you download and import, or fork, any of the PingOne Postman collections into your Postman installation, the collection includes a PingOne Postman environment template automatically. You can use this Postman environment with the use case collections, or any Postman environment you have created previously that includes values for the variables listed above. See The PingOne Postman Environment Template for more information.

These tasks show you how to use the platform APIs to perform common actions for managing applications. Application use cases often call the following platform API resources:

Best practices for application secrets

• Do not store an application secret in applications that are publicly available.

• For security purposes, regenerate application secrets regularly (see Update the application secret).

• If you suspect an application secret has been compromised, generate a new application secret immediately.

This activity shows you how to create an application, configure its connection settings, create a resource access grant, and initiate an authorization request. After an access token is generated, it is used by a user to update a user attribute.

The following operations are supported by the PingOne APIs:

• Create an application
• Create a resource access grant
• Initiate an authorization_code authorization flow
• Update a user attribute

Best practices for application secrets

• Do not store an application secret in applications that are publicly available.

• For security purposes, regenerate application secrets regularly (see Update the application secret).

• If you suspect an application secret has been compromised, generate a new application secret immediately.

Prerequisites

Get an access token from the worker application that you created in Create an admin Worker app connection . To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see Get a PingOne admin access token.

Workflow order of operations

To configure an application and initiate an authorization code flow, the following tasks must be completed successfully:

1. Make a POST request to /environments/{{envID}}/applications to add a new application to the specified environment.

2. Make a GET request to /environments/{{envID}}/applications/{{appID}}/secret to return the new application's secret attribute.

3. Make a GET request to /environments/{{envID}}/resources to return a list of all resource entities associated with the specified environment to get the ID for the PingOne platform resource.

4. Make a GET request to /environments/{{envID}}/resources/{{resourceID}}/scopes to list all scopes associated with a specified resource (the PingOne platform resource).

5. Make a POST request to /environments/{{envID}}/applications/{{appID}}/grants to create a new resource access grant for the application.

6. Make a POST request to /environments/{{envID}}/populations to create a new population resource.

7. Make a POST request to /environments/{{envID}}/users to create a user who will be associated with the new population resource.

8. Make a POST request to /environments/{{envID}}/users/{{userID}}/password to set the new user's password.

9. Make a POST request to /{{envID}}/as/authorize to obtain an authorization grant. This request starts the authorization flow.

10. To initiate the authentication flow, make a GET request to GET /{{envID}}/flows/{{flowID}}.

11. To complete the authentication flow, make a POST request to GET /{{envID}}/flows/{{flowID}} and provide the user's login credentials.

12. Make a GET request to /{{envID}}/as/resume?flowId={{flowID}} to call the resume endpoint and return the token.

13. After the authorization flow completes and returns an auth code, make a POST request to /{{envID}}/as/token to exchange the auth code for an access token.

Click the Run in Postman button below to download the Postman collection for this use case.

This activity shows you how to create an application, configure its connection settings, create a resource access grant, and initiate an authorization request.

The following operations are supported by the PingOne APIs:

• Create an application
• Create a resource access grant
• Initiate an authorization_code authorization flow
• Update a user attribute

Prerequisites

• Get an access token from the worker application you created in Create an admin Worker app connection . If you prefer to get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. See Get a PingOne admin access token.

Workflow order of operations

To configure an application and initiate an authorization code flow, the following tasks must be completed successfully:

1. Make a POST request to /environments/{{envID}}/applications to add a new application to the specified environment.

2. Make a GET request to /environments/{{envID}}/applications/{{appID}}/secret to return the new application's secret attribute.

3. Make a POST request to /environments/{{envID}}/populations to create a new population resource.

4. Make a POST request to /environments/{{envID}}/users to create a user who will be associated with the new population resource.

5. Make a PUT request to /environments/{{envID}}/users/{{userID}}/password to set the new user's password.

6. Make a GET request to /{{envID}}/as/authorize to obtain an authorization grant. This request starts the authorization flow.

7. To initiate the authentication flow, make a GET request to GET /{{envID}}/flows/{{flowID}}.

8. To complete the authentication flow, make a POST request to GET /{{envID}}/flows/{{flowID}} and provide the user's login credentials.

9. Make a GET request to /{{envID}}/as/resume?flowId={{flowID}} to call the resume endpoint and return the token.

10. After the authorization flow completes and returns an auth code, make a POST request to /{{envID}}/as/token to exchange the auth code for an access token and return the refresh token.

Click the Run in Postman button below to download the Postman collection for this use case.

This activity shows you how to create an single-page application, configure its connection settings to use Proof Key for Code Exchange (PKCE) parameters in the authorization request for the authorization code grant, and initiate an authorization request.

The following operations are supported by the PingOne APIs:

• Create an application
• Create a user
• Initiate an authorization code flow and use PKCE to authenticate the token request

Prerequisites

Get an access token from the worker application that you created in Create an admin Worker app connection . To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see Get a PingOne admin access token.

Workflow order of operations

To configure a single-page application and initiate an authentication flow, the following tasks must be completed successfully:

1. Make a POST request to /environments/{{envID}}/applications to add a new application to the specified environment.

2. Make a POST request to /environments/{{envID}}/populations to create a new population resource.

3. Make a POST request to /environments/{{envID}}/users to create a user who will be assigned to the new population resource.

4. Make a POST request to /environments/{{envID}}/users/{{userID}}/password to set the new user's password.

5. Make a POST request to /{{envID}}/as/authorize to obtain an authorization grant. This request starts the authorization flow.

6. To initiate the authentication flow, make a GET request to GET /{{envID}}/flows/{{flowID}}.

7. To complete the authentication flow, make a POST request to GET /{{envID}}/flows/{{flowID}} and provide the user's login credentials.

8. Make a GET request to /{{envID}}/as/resume?flowId={{flowID}} to call the resume endpoint and return the token.

9. Make a POST request to /{{envID}}/as/token to exchange the auth code for an access token.

Click the Run in Postman button below to download the Postman collection for this use case.

This activity shows you how to create an single-page application, configure its connection settings, create a resource access grant, and initiate an authorization request.

The following operations are supported by the PingOne APIs:

• Create an application
• Create a resource access grant
• Initiate an implicit authorization and authentication flow

Prerequisites

Get an access token from the worker application that you created in Create an admin Worker app connection . To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see Get a PingOne admin access token.

Workflow order of operations

To configure a single-page application and initiate an authentication flow, the following tasks must be completed successfully:

1. Make a POST request to /environments/{{envID}}/applications to add a new application to the specified environment.

2. Make a GET request to /environments/{{envID}}/resources to return a list of all resource entities associated with the specified environment to get the ID for the PingOne platform resource.

3. Make a GET request to /environments/{{envID}}/resources/{{resourceID}}/scopes to list all scopes associated with a specified resource (the PingOne platform resource).

4. Make a POST request to /environments/{{envID}}/applications/{{appID}}/grants to create a new resource access grant for the application.

5. Make a POST request to /environments/{{envID}}/populations to create a new population resource.

6. Make a POST request to /environments/{{envID}}/users to create a user who will be assigned to the new population resource.

7. Make a POST request to /environments/{{envID}}/users/{{userID}}/password to set the new user's password.

8. Make a POST request to /{{envID}}/as/authorize to obtain an authorization grant. This request starts the authorization flow.

9. To initiate the authentication flow, make a GET request to GET /{{envID}}/flows/{{flowID}}.

10. To complete the authentication flow, make a POST request to GET /{{envID}}/flows/{{flowID}} and provide the user's login credentials.

11. Make a GET request to /{{envID}}/as/resume?flowId={{flowID}} to call the resume endpoint and return the token.

Click the Run in Postman button below to download the Postman collection for this use case.

This activity shows you how to create non-interactive worker application, configure its connection settings, get the application secret, and configure a token request.

The following operations are supported by the PingOne APIs:

• Create an application
• Get the application secret
• Initiate a token request

Best practices for application secrets

• Do not store an application secret in applications that are publicly available.

• For security purposes, regenerate application secrets regularly (see Update the application secret).

• If you suspect an application secret has been compromised, generate a new application secret immediately.

Prerequisites

Get an access token from the worker application that you created in Create an admin Worker app connection . To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see Get a PingOne admin access token.

Workflow order of operations

To configure a non-interactive worker application and initiate a token request, the following tasks must be completed successfully:

1. Make a POST request to /environments/{{envID}}/applications to add a new application to the specified environment.

2. Make a GET request to /environments/{{envID}}/applications/{{applicationID}}/secret to return the application secret.

3. Make a POST request to /{{envID}}/as/token to get an access token.

Click the Run in Postman button below to download the Postman collection for this use case.

This activity shows you how to create an interactive worker application, configure its connection settings, view the application role assignments, assign roles to an admin user, and initiate an authorization request.

The following operations are supported by the PingOne APIs:

• Create an application
• Read application role assignments
• Create an admin population and an admin user
• Assign roles to the admin user
• Initiate an authorization_code authorization and authentication flow

Best practices for application secrets

• Do not store an application secret in applications that are publicly available.

• For security purposes, regenerate application secrets regularly (see Update the application secret).

• If you suspect an application secret has been compromised, generate a new application secret immediately.

Prerequisites

Get an access token from the worker application that you created in Create an admin Worker app connection . To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see Get a PingOne admin access token.

Workflow order of operations

To configure an interactive worker admin application and initiate an authentication flow, the following tasks must be completed successfully:

1. Make a POST request to /environments/{{envID}}/applications to add a new application to the specified environment.

2. Make a GET request to /environments/{{envID}}/applications/{{applicationID}}/secret to get the application's secret, which is needed to authenticate the token request.

3. Make a GET request to /environments/{{envID}}/applications/{{applicationID}}/roleAssignments to return a list of roles assigned to the application.

4. Make a POST request to /environments/{{envID}}/signOnPolicies to create a new sign-on policy.

5. Make a POST request to /environments/{{envID}}/signOnPolicies/{{policyID}}/actions to add a login action to the sign-on policy.

6. Make a POST request to /environments/{{envID}}/applications/{{applicationID}}/signOnPolicyAssignments to associate the new sign-on policy with the application.

7. Make a POST request to /environments/{{envID}}/populations to create a new admin population resource.

8. Make a POST request to /environments/{{envID}}/users to create an admin user who will be assigned to the new population resource.

9. Make a PUT request to /environments/{{envID}}/users/{{userID}}/password to set the new user's password.

10. Make a GET request to /roles to read all roles.

11. Make a POST request to /environments/{{envID}}/users/{{userID}}/roleAssignments to assign a role to the new admin user.

12. Make a GET request to /{{envID}}/as/authorize to initiate an authorization request. This request starts the sign-on flow.

13. Make a GET request to GET /{{envID}}/flows/{{flowID}} to initiate the authentication flow.

14. To complete the authentication flow, make a POST request to /{{envID}}/flows/{{flowID}} and provide the user's login credentials.

15. Make a GET request to /{{envID}}/as/resume?flowId={{flowID}} to call the resume endpoint and return the auth code.

16. Make a POST request to /{{envID}}/as/token to exchange the auth code for an access token.

Click the Run in Postman button below to download the Postman collection for this use case.

To test the execution of a SAML identity provider (IdP) connection for an application configured in your PingOne environment, you must have a working SAML IdP for your environment to communicate with.

The easiest way to do this is by using two PingOne environments. You can then execute an authentication flow for an application existing in one PingOne environment by using external authentication as a user in a second PingOne environment acting as the SAML IdP.

Prerequisites

• Get an access token from the worker application that you created in Create an admin Worker app connection . To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of the worker app that you selected to authenticate the request. For more information, see Get a PingOne admin access token.

• A destination PingOne environment to act as the service provider (SP) for the SAML application. Use this environment to configure the SAML IdP connection. You can configure authentication flows in this environment to allow external authentication.

• A source PingOne environment to act as the SAML IdP. Users here can complete authentication flows in the destination environment.

• Cross-environment admin permissions for the destination and source environments.

• A PingOne access token for each environment.

This scenario illustrates the following operations supported by the PingOne APIs:

• Get the certificate for the source environment.
• Create a SAML application in the source environment.
• Create a SAML IdP in the destination environment.
• Create a sign-on policy in the destination environment.
• Create a sign-on policy action to enable the sign-on policy for the SAML IdP connection.
• Set the sign-on policy as the default for the destination environment.

Workflow order of operations

To test the SAML application connection:

1. Make a GET request to /environments/{{sourceEnvID}}/keys to get the signing key for the source environment and download the PEM or PKCS7 file for the signing key.

2. Make a GET request to /environments to get the environment IDs.

3. Make a POST request to /environments/{{sourceEnvID}}/applications to create a SAML application.

4. (Optional) Make a POST request to /environments/{{sourceEnvID}}/applications/{{appID}}/attributes to any attribute mappings needed for the source environment application.

5. Make a POST request to /environments/{{destinationEnvID}}/certificates to create a certificate in the destination environment using the PEM or PKCS7 file that you downloaded in the initial step.

6. Make a GET request to /environments/{{destinationEnvID}}/certificates to get a certificate for the destination environment to assign to the IdP that you'll create.

7. Make a POST request to /environments/{{destinationEnvID}}/identityProviders to create the SAML IdP configuration in the destination environment.

8. (Optional) Make a POST request to /environments/{{destinationEnvID}}/identityProviders/{{providerID}}/attributes to add any needed attribute mappings for the IdP in the destination environment.

9. Make a POST request to /environments/{{destinationEnvID}}/signOnPolicies to create a sign-on policy for the new IdP in the destination environment.

10. Make a POST request to /environments/{{destinationEnvID}}/signOnPolicies/{{policyID}}/actions to create a new IDENTIFIER_FIRST sign-on policy action associated with the new sign-on policy.

11. Make a PUT request to /environments/{{destinationEnvID}}/applications/{{appID}}/signOnPolicyAssignments to associate this sign-on policy with the specified SAML application.

Execute the authentication flow

1. Copy the Self-Service URL for the destination environment. You can find the Self-Service URL on the Settings → Environment → Properties page.

2. Open a private browser window, and enter the Self-Service URL that you copied.

3. Click the button that matches your SAML IdP connection.

4. Authenticate as a user in the source environment. Depending on your configuration, you might need to perform account linking or user verification.

Click Run in Postman to download the Postman collection for this use case.

To test the execution of an OpenID Connect (OIDC) connection for an application configured in your PingOne environment, you must have a working OIDC identity provider (IdP) for your environment to communicate with.

The easiest way to do this is by using two PingOne environments. You can then execute an authentication flow for an application existing in one PingOne environment by using external authentication as a user in a second PingOne environment acting as the OIDC IdP.

Prerequisites

• Get an access token from the worker application that you created in Create an admin Worker app connection . To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see Get a PingOne admin access token.

• A destination PingOne environment to act as the service provider (SP) for the OIDC application. You'll use this environment to configure the OIDC IdP connection. Authentication flows in this environment can be configured to allow external authentication.

• A source PingOne environment that will act as the OIDC IdP. Users here will be able to complete authentication flows in the destination environment.

• Cross-environment admin permissions for the destination and source environments.

• A PingOne access token for each environment.

This scenario illustrates the following operations supported by the PingOne APIs:

• Create an OIDC application in the source environment.
• Create an OIDC IdP in the destination environment referencing the source application.
• Create a sign-on policy in the destination environment.
• Create a sign-on policy action to enable the sign-on policy for the OIDC IdP connection.
• Set the sign-on policy as the default for the destination environment.
• Initiate an authorization request.

Workflow order of operations

To test the OIDC application connection, the following tasks must be completed successfully:

1. Make POST requests to /environments to create a source environment and a destination environment.

2. Make a POST request to /environments/{{sourceEnvID}}/applications to create an OIDC application in the source environment.

3. Make a GET request to /environments/{{sourceEnvID}}/applications/{{appID}}/secret to read the OIDC application secret.

4. Make a POST request to /environments/{{destinationEnvID}}/identityProviders to create an OIDC IdP in the destination environment.

5. Make a POST request to /environments/{{destinationEnvID}}/signOnPolicies to create a sign-on policy for the IdP in the destination environment.

6. Make a POST request to /environments/{{destinationEnvID}}/signOnPolicies/{{policyID}}/actions to create a new IDENTIFIER_FIRST sign-on policy action associated with the new sign-on policy.

7. Make a PUT request to /environments/{{destinationEnvID}}/signOnPolicies/{{policyID}} to set the policy as default.

8. Make a POST request to /environments/{{destinationEnvID}}/applications to create an OIDC application in the destination environment.

9. Make a POST request to /environments/{{destinationEnvID}}/applications/{{appID}}/signOnPolicyAssignments to assign the sign-on policy to the destination OIDC application.

10. Make a GET request to /{{destinationEnvID}}/as/authorize to retrieve an authorization grant.

Execute the authentication flow

1. Open a private browser window, and enter the Location header URL that was returned from the /as/authorize call.

2. Click the button that matches your OIDC IdP connection.

3. Authenticate as a user in the source environment. Depending on your configuration, you may need to perform account linking or user verification.

You should be able to sign on as a source environment user, indicating that authentication from the source environment to the OIDC IdP in the destination environment is working. After authenticating, you are taken to the redirect_uri of the application in your destination environment.

Click the Run in Postman button to download the Postman collection for this use case.

These tasks show you how to use the platform APIs to perform common actions for authorization and authentication actions. Authorization and authentication use cases often call the following platform API resources:

This activity shows you how to create a simple login using only a username and password. You'll create a login sign-on policy, initiate an authorization request, and use the flow APIs to complete the authorization.

The following operations are supported by the PingOne APIs:

• Create an application
• Create a sign-on policy
• Create a login sign-on policy action
• Create a user
• Initiate an authorize request
• Use flow APIs to complete the login

Prerequisites

Get an access token from the worker application that you created in Create an admin Worker app connection . To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see Get a PingOne admin access token.

Workflow order of operations

To configure a simple login with a username and password, you must complete the following tasks:

1. Make a POST request to /environments/{{envID}}/applications to add a new application to the specified environment.

2. Make a GET request to /environments/{{envID}}/applications/{{webAppSimpleLoginId}}/secret to return the new application's secret attribute.

3. Make a POST request to /environments/{{envID}}/signOnPolicies to create a new sign-on policy.

4. Make a POST request to /environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions to define the login action associated with this sign-on policy.

5. Make a POST request to /environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments to associate the sign-on policy with the application.

6. Make a POST request to /environments/{{envID}}/populations to create a new population resource.

7. Make a POST request to /environments/{{envID}}/users to create a user to assign to the new population resource.

8. Make a PUT request to /environments/{{envID}}/users/{{userID}}/password to set the new user's password.

9. Make a GET request to /{{envID}}/as/authorize to obtain an authorization grant. This request starts the authorization flow.

10. Make a GET request to /{{envID}}/flows/{{flowID}} to initiate the sign-on flow.

11. To complete the login action, make a POST request to /{{envID}}/flows/{{flowID}} and provide the user's login credentials.

12. Make a GET request to /{{envID}}/as/resume?flowId={{flowID}} to call the resume endpoint and return the auth code.

13. Make a POST request to /{{envID}}/as/token to exchange the auth code for an access token.

Click the Run in Postman button below to download the Postman collection for this use case.

This activity shows you how to get an ID token. See Access tokens and ID tokens for more information.

The following operations are supported by the PingOne APIs:

• Create an application
• Create a population
• Create a user
• Create a user password
• Initiate an authorize request
• Use flow APIs to complete the login

Prerequisites

Get an access token from the worker application that you created in Create an admin Worker app connection . To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see Get a PingOne admin access token.

Workflow order of operations

To get an ID token, you must complete the following tasks:

1. Make a POST request to /environments/{{envID}}/applications to add a new application to the specified environment.

2. Make a POST request to /environments/{{envID}}/populations to create a new population resource.

3. Make a POST request to /environments/{{envID}}/users to create a user to assign to the new population resource.

4. Make a PUT request to /environments/{{envID}}/users/{{userID}}/password to set the new user's password.

5. Make a GET request to /{{envID}}/as/authorize to obtain an authorization grant. This request starts the authorization flow.

6. Make a GET request to /{{envID}}/flows/{{flowID}} to initiate the sign-on flow.

7. Make a POST request to /{{envID}}/flows/{{flowID}} and provide the user's login credentials.

8. Make a GET request to /{{envID}}/as/resume?flowId={{flowID}} to call the resume endpoint and return the auth code.

Click the Run in Postman button below to download the Postman collection for this use case.

This activity shows you how to create a sign-on policy with registration enabled, initiate an authorization request, and use the flow APIs to create and verify a new user account.

The following operations are supported by the PingOne APIs:

• Create an application
• Create a sign-on policy
• Initiate an authorize request
• Use flow APIs to create a new user
• Use flow APIs to verify the new user

Prerequisites

Get an access token from the worker application that you created in Create an admin Worker app connection . To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see Get a PingOne admin access token.

Workflow order of operations

To create a new user through a registration flow, the following tasks must be completed successfully:

1. Make a POST request to /environments/{{envID}}/applications to add a new application to the specified environment.

2. Make a POST request to /environments/{{envID}}/populations to create a new population for the reistered user.

3. Make a POST request to /environments/{{envID}}/signOnPolicies to create a new sign-on policy that enables user registration.

4. Make a POST request to /environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions to define the registration action associated with this sign-on policy.

5. Make a POST request to /environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments to create associate the registration sign-on policy with the application.

6. Make a GET request to /{{envID}}/as/authorize to obtain an authorization grant. This request starts the authorization flow.

7. Make a GET request to /{{envID}}/flows/{{flowID}} to get the flow.

8. Make a POST request to /{{envID}}/flows/{{flowID}} to register the new user.

9. Make a POST request to /{{envID}}/flows/{{flowID}} to verify the new user account.

10. Make a GET request to /environments/{{envID}}/users/{{userID}} to verify that the new user exists in the PingOne directory.

Click the Run in Postman button below to download the Postman collection for this use case.

This activity shows you how to create a sign-on policy with login and mfa actions, initiate an authorization request, and use the flow APIs to complete the authorization.

The following operations are supported by the PingOne APIs:

• Create an application
• Create a sign-on policy
• Create login and MFA sign-on policy actions
• Create a user
• Initiate an authorize request
• Use flow APIs to complete the login and MFA actions

Prerequisites

Get an access token from the worker application that you created in Create an admin Worker app connection . To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see Get a PingOne admin access token.

Workflow order of operations

To complete a login and MFA sign on, the following tasks must be completed successfully:

1. Make a POST request to /environments/{{envID}}/applications to add a new application to the specified environment.

2. Make a GET request to /environments/{{envID}}/resources to return a list of all resource entities associated with the specified environment.

3. Make a GET request to /environments/{{envID}}/resources/{{resourceID}}/scopes to list all scopes associated with a specified resource.

4. Make a POST request to /environments/{{envID}}/applications/{{appID}}/grants to create a new resource access grant for the application.

5. Make a POST request to /environments/{{envID}}/signOnPolicies to create a new sign-on policy.

6. Make a POST request to /environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions to define the login action associated with this sign-on policy.

7. Make a POST request to /environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions to define the MFA action associated with this sign-on policy.

8. Make a POST request to /environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments to associate the sign-on policy with the application.

9. Make a POST request to /environments/{{envID}}/populations to create a new population resource.

10. Make a POST request to /environments/{{envID}}/users to create a user who will be assigned to the new population resource.

11. Make a POST request to /environments/{{envID}}/users/{{userID}}/password to set the new user's password.

12. Make a POST request to /environments/{{envID}}/users/{{userID}}/mfaEnabled to enable MFA actions for this user.

13. Make a POST request to /environments/{{envID}}/users/{{userID}}/devices to associate an MFA device with this user.

14. Make a POST request to /{{envID}}/as/authorize to obtain an authorization grant. This request starts the authorization flow.

15. Make a GET request to /{{envID}}/flows/{{flowID}} to initiate the sign-on flow.

16. To complete the login action, make a POST request to GET /{{envID}}/flows/{{flowID}} and provide the user's login credentials.

17. To complete the MFA action, make a POST request to GET /{{envID}}/flows/{{flowID}} and provide the one-time passcode.

18. Make a GET request to /{{envID}}/as/resume?flowId={{flowID}} to call the resume endpoint and return the auth code.

19. Make a GET request to /environments/{{envID}}/applications/{{appID}}/secret to return the new application's secret attribute, which is needed for the token request.

20. Make a POST request to /{{envID}}/as/token to exchange the auth code for an access token.

Click the Run in Postman button below to download the Postman collection for this use case.

In some cases, as with applications on native devices, the use of an authorization code grant can be compromised by authorization code interception attacks. The attacking application gains access to the client secret, intercepts the authorization code, and is able to exchange the intercepted authorization code for an access token.

Proof Key for Code Exchange (PKCE) authorization requests specify additional parameters in the request to prevent malicious apps from intercepting the authorization code. PKCE uses a random key, a code_verifier, that is used to compute a code_challenge parameter, which functions like a temporary application secret (unique to a single token request). PKCE works as follows:

1. The client creates and records a code_verifier secret, which is a random value between 43 and 128 characters in length.

2. The client uses the code_verifier value to compute the code_challenge value. The code_challenge_method is the transformation method that creates the code_challenge value. This parameter value is also recorded.

3. The authorization request includes the code_challenge and in some cases the code_challenge_method parameter values in the request. The code_challenge_method is an optional parameter. It defaults to plain if not specified (which generates an error when the S256_REQUIRED PKCE enforcement option is specified by the application).

4. The authorization server records the code_challenge and the code_challenge_method parameter values, and responds by issuing the authorization code.

5. The client sends the authorization code to the /{{envID}}/as/token endpoint. The token request requires the code_verifier secret created in step 1.

6. The authorization server uses the code_challenge_method to transform the code_verifier value and compare it to the code_challenge value submitted and recorded in the authorize request.

7. If these values are equal, an access token is granted. If they are not equal, access is denied.

Workflow tasks

This scenario illustrates the following operations supported by the PingOne APIs:

• Create an application and set its pkceEnforcement property.

• Create an authorization request that includes code_challenge and code_challenge_method parameter values.

• Create a token request that includes the code_verifier secret.

Prerequisites

Get an access token from the worker application that you created in Create an admin Worker app connection . To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see Get a PingOne admin access token.

Workflow order of operations

To enable a PKCE authorization workflow, the following tasks must be completed successfully:

1. Make a POST request to /environments/{{envID}}/applications to define an OpenID Connect native app type that uses an authorization code grant.

2. Make a GET request to /{{envID}}/as/authorize to initiate authorization and submit the code_challenge and code_challenge_method values to the authorization server.

3. Make a GET request to /{{envID}}/flows/{{flowID}} to verify the flow initialization.

4. Make a POST request to /{{envID}}/flows/{{flowID}} with the application/vnd.pingidentity.usernamePassword.check+json content type to submit the username and password.

5. Make a GET request to /{{envID}}/as/resume?flowId={{flowID}} to call the authorize resume endpoint.

6. Make a POST request to /{{envID}}/as/token to exchange the authorization code returned by the resume endpoint for an access token.

Click the Run in Postman button below to download the Postman collection for this use case.

This activity shows you how to create a sign-on policy with a progressive profiling action, initiate an authorization request, and use the flow APIs to complete the progressive profiling action.

The following operations are supported by the PingOne APIs:

• Create an application
• Create a sign-on policy
• Create login and a progressive profiling sign-on policy actions
• Create a user
• Initiate an authorize request
• Use flow APIs to login the user and add a mobile phone number
• Verify the addition of a mobile phone number to the user record

Prerequisites

Get an access token from the worker application that you created in Create an admin Worker app connection . To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see Get a PingOne admin access token.

Workflow order of operations

To complete a progressive profiling flow, the following tasks must be completed successfully:

1. Make a POST request to /environments/{{envID}}/applications to add a new application to the specified environment.

2. Make a GET request to /environments/{{envID}}/applications/{{appID}}/secret to return the new application's secret attribute.

3. Make a GET request to /environments/{{envID}}/resources to return a list of all resource entities associated with the specified environment to get the ID for the PingOne platform resource.

4. Make a GET request to /environments/{{envID}}/resources/{{resourceID}}/scopes to list all scopes associated with a specified resource (the PingOne platform resource).

5. Make a POST request to /environments/{{envID}}/applications/{{appID}}/grants to create a new resource access grant for the application.

6. Make a POST request to /environments/{{envID}}/signOnPolicies to create a new sign-on policy.

7. Make a POST request to /environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions to define the login action associated with this sign-on policy.

8. Make a POST request to /environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions to define the progressive profiling action associated with this sign-on policy.

9. Make a POST request to /environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments to associate the sign-on policy with the application.

10. Make a POST request to /environments/{{envID}}/populations to create a new population resource.

11. Make a POST request to /environments/{{envID}}/users to create a user who will be assigned to the new population resource.

12. Make a POST request to /environments/{{envID}}/users/{{userID}}/password to set the new user's password.

13. Make a POST request to /{{envID}}/as/authorize to obtain an authorization grant. This request starts the authorization flow.

14. Make a GET request to /{{envID}}/flows/{{flowID}} to initiate the flow.

15. To complete the login action, make a POST request to GET /{{envID}}/flows/{{flowID}} and provide the user's login credentials.

16. To complete the progressive profiling action, make a POST request to GET /{{envID}}/flows/{{flowID}} and provide the user's mobile phone number.

17. Make a GET request to /{{envID}}/as/resume?flowId={{flowID}} to call the resume endpoint and return the auth code.

18. After the authorization flow completes, make a POST request to /{{envID}}/as/token to exchange the auth code for an access token.

19. Make a GET request to /environments/{{envID}}/users/{{userID}} to view the updated information about the identified user.

Click the Run in Postman button below to download the Postman collection for this use case.

This activity shows you how to initiate a device authorization grant flow to send an activation code to the end user. The authorization and flow orchestration steps apply only to applications that specify device_code as a grant type in the application configuration.

The following operations are supported by the PingOne APIs:

• Create an application
• Create a population and a user
• Initiate an authorize request
• Use flow APIs to complete the flow

Prerequisites

• Get an access token from the worker application you created in Create an admin Worker app connection . If you prefer to get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. See Get a PingOne admin access token.

Workflow order of operations

To configure a device authorization grant flow using the environment's default sign-on policy, the following tasks must be completed successfully:

1. Make a POST request to /environments/{{envID}}/applications to add a new application to the specified environment.

2. Make a POST request to /environments/{{envID}}/populations to create a new population resource.

3. Make a POST request to /environments/{{envID}}/users to create a user who will be assigned to the new population resource.

4. Make a PUT request to /environments/{{envID}}/users/{{userID}}/password to set the new user's password.

5. Make a POST request to /{{envID}}/as/device_authorization to return the device code and the user code.

6. Make a GET request to /{{envID}}/device to initiate authorization and return a flow ID.

7. Make a GET request to /{{envID}}/flows/{{flowID}} to start the flow.

8. To complete the login action, make a POST request to /{{envID}}/flows/{{flowID}} and provide the user's login credentials.

9. To complete the confirm activation code action, make a POST request to /{{envID}}/flows/{{flowID}} to submit the activation code.

10. To complete the consent action, make a POST request to /{{envID}}/flows/{{flowID}} to accept the device authorization grant agreement.

11. Make a POST request to /{{envID}}/as/token to exchange the device code for an access token.

Click the Run in Postman button below to download the Postman collection for this use case.

This activity shows you how to create a sign-on policy with login and agreement actions, initiate an authorization request, and use the flow APIs to complete the authorization.

The following operations are supported by the PingOne APIs:

• Create an application
• Create a sign-on policy
• Create login and agreement sign-on policy actions
• Create a user
• Initiate an authorize request
• Use flow APIs to complete the login and agreement actions

Prerequisites

Get an access token from the worker application that you created in Create an admin Worker app connection . To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see Get a PingOne admin access token.

Workflow order of operations

To complete a login and agreement sign on, the following tasks must be completed successfully:

1. Make a POST request to /environments/{{envID}}/applications to add a new application to the specified environment.

2. Make a GET request to /environments/{{envID}}/applications/{{appID}}/secret to return the new application's secret attribute, which is needed for the token request.

3. Make a GET request to /environments/{{envID}}/languages to find the environment's default language.

4. Make a POST request to /environments/{{envID}}/agreements to create a new agreement.

5. Make a POST request to /environments/{{envID}}/agreements/{{agreementID}}/languages to create the language for the agreement.

6. Make a POST request to /environments/{{envID}}/agreements/{{agreementID}}/languages/{{agreementLanguageID}}/revisions to create the revision for the agreement in the specified language.

7. Make a PUT request to /environments/{{envID}}/agreements/{{agreementID}}/languages/{{agreementLanguageID}} to enable the agreement language.

8. Make a PUT request to /environments/{{envID}}/agreements/{{agreementID}} to enable the agreement.

9. Make a POST request to /environments/{{envID}}/signOnPolicies to create a new sign-on policy.

10. Make a POST request to /environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions to define the login action associated with this sign-on policy.

11. Make a POST request to /environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions to define the agreement action associated with this sign-on policy.

12. Make a POST request to /environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments to associate the sign-on policy with the application.

13. Make a POST request to /environments/{{envID}}/populations to create a new population resource.

14. Make a POST request to /environments/{{envID}}/users to create a user who will be assigned to the new population resource.

15. Make a POST request to /environments/{{envID}}/users/{{userID}}/password to set the new user's password.

16. Make a POST request to /{{envID}}/as/authorize to obtain an authorization grant. This request starts the authorization flow.

17. Make a GET request to /{{envID}}/flows/{{flowID}} to initiate the sign-on flow.

18. To complete the login action, make a POST request to GET /{{envID}}/flows/{{flowID}} and provide the user's login credentials.

19. To complete the agreement action, make a POST request to GET /{{envID}}/flows/{{flowID}} and provide consent to the agreement.

20. Make a GET request to /{{envID}}/as/resume?flowId={{flowID}} to call the resume endpoint and return the auth code.

21. Make a POST request to /{{envID}}/as/token to exchange the auth code for an access token.

Click the Run in Postman button below to download the Postman collection for this use case.

This activity shows you how to create a custom resource and a custom resource scope, initiate an authorization request, and use the flow APIs to get a token that allows access to the custom resource.

The following operations are supported by the PingOne APIs:

• Create an application
• Create a custom resouce and custom scope
• Create a sign-on policy
• Create login sign-on policy action
• Create a user
• Initiate an authorize request
• Use flow APIs to complete the login actions
• Use the token request to get an access token for the custom resource
• use the token introspection endpoint to verify the audience for the token

Prerequisites

Get an access token from the worker application that you created in Create an admin Worker app connection . To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see Get a PingOne admin access token.

Workflow order of operations

To get an access token for the custom resource, the following tasks must be completed successfully:

1. Make a POST request to /environments/{{envID}}/applications to add a new application to the specified environment.

2. Make a GET request to /environments/{{envID}}/applications/{{appID}}/secret to return the new application's secret attribute, which is needed for the token request.

3. Make a POST request to /environments/{{envID}}/resources to define the custom resource.

4. Make a POST request to /environments/{{envID}}/resources/{{resourceID}}/scopes to define a scope for the custom resource.

5. Make a POST request to /environments/{{envID}}/applications/{{appID}}/grants to create a new resource access grant for the application.

6. Make a POST request to /environments/{{envID}}/signOnPolicies to create a new sign-on policy.

7. Make a POST request to /environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions to define the login action associated with this sign-on policy.

8. Make a POST request to /environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments to associate the sign-on policy with the application.

9. Make a POST request to /environments/{{envID}}/populations to create a new population.

10. Make a POST request to /environments/{{envID}}/users to create a user who will be assigned to the new population.

11. Make a POST request to /environments/{{envID}}/users/{{userID}}/password to set the new user's password.

12. Make a GET request to /{{envID}}/as/authorize to obtain an authorization grant. This request starts the authorization flow.

13. Make a GET request to /{{envID}}/flows/{{flowID}} to initiate the sign-on flow.

14. To complete the login action, make a POST request to GET /{{envID}}/flows/{{flowID}} and provide the user's login credentials.

15. Make a GET request to /{{envID}}/as/resume?flowId={{flowID}} to call the resume endpoint and return the auth code.

16. Make a POST request to /{{envID}}/as/token to exchange the auth code for an access token.

17. To verify that the token grants access to the new custom resource, make a POST request to GET /{{envID}}/as/introspect to return the audience and scope information in the token.

Click the Run in Postman button below to download the Postman collection for this use case.