PingOne for Developers Tutorial

PingOne for Developers Tutorials 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 use case collection in your Postman workspace.

This guide serves as a quick start for configuring PingOne to get an admin access token. It also provides information about configuring the Postman application to take advantage of the workflow collections.

Prerequisites

To begin using the PingOne Platform APIs, you'll need to first:

  1. Create a Worker application using the PingOne admin console application.

  2. Use the PingOne Authorization APIs to get an admin access token (a JSON Web Token) that gives you premissions to run PingOne APIs.

  3. Create a test environment.

The Create an admin Worker app connection and Create your test environment topics walk you through these configuration steps.

Using the PingOne APIs

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.

TutorialFlow

Overview

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.

PingOne Postman collections

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. Run In Postman
Platform Postman requests for the PingOne platform API. Includes all PingOne documentation and example reponses. No environment variables are included. Run In Postman

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.

    RunInPostman

  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 PingOne Postman Environment Template

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.

Postman variable PingOne resource
adminAppID The Client ID of the worker app when you Create an Admin Worker App Connection.
adminAppSecret The Client Secret of the worker app when you Create an Admin Worker App Connection.
adminEnvID The identifier for your administrative environment. This should be the environment in which your worker app resides. This prevents accidentally overwriting your administrative environment identifier should you use the API in Postman to create a new environment, which will overwrite the existing envID.
envID The identifier for the environment in which you are running your Postman API requests.
orgID The identifier for your organization. In PingOne Console, click Environment and click Properties to view your organization identifier.
tld The top-level domain for this environment. Used in apiPath, authPath, orchestratePath, and scimPath.
apiPath The regional domain for the PingOne management server. Should be https://api.pingone.{{tld}}/v1.
authPath The regional domain for the PingOne authorization and authentication server. Should be https://auth.pingone.{{tld}}.
orchestratePath The regional domain for the PingOne DaVinci management server. Should be https://orchestrate-api.pingone.{{tld}}/v1.
scimPath The regional domain for the PingOne DaVinci management server. Should be https://scim-api.pingone.{{tld}}.

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

Region Top level domain
North America region (excluding Canada) com (default)
Canada region ca
European Union region eu
Asia-Pacific region asia
Australia region com.au

Create an admin Worker app connection

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.

    AdminConsoleAppMain

  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.

    AdminConsoleAddApp

  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.

    AdminConsoleClientIdAndSecret

  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.

    AdminConsoleWorkerAppAssignRoles

  9. Click Save.

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

    AdminConsoleWorkerAppRolesAssigned

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.

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:

    Run in Postman

    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:

    PingOnePostmanEnvironmentTemplate


Step 1: Get a PingOne admin access token


Step 2: Create an environment


Step 3: Create a population


Step 4: Create a user


Step 5: Set the user password

Create an SSO workflow

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.

Simple SSO

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:

    Run in Postman

    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:

    PingOnePostmanEnvironmentTemplate


Step 1: Create a web application


Step 2: Get the application secret


Step 3: Send an authorization request

Workflow library

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.

Postman Request Settings

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

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.

Application Management

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:

Platform API Description
Applications Application resources define the connection between PingOne and the actual application, commonly referred to as a client connection.

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.

Configure an Application with an Authorization Code Grant

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.

Run in Postman


Step 1: Create an OpenID Connect (OIDC) application


Step 2: Get the application secret


Step 3: Get the list of resources


Step 4: Get all scopes


Step 5: Create the application's resource access grant


Step 6: Create a population


Step 7: Create user


Step 8: Set user password


Step 9: Obtain an authorization grant


Step 10: Get the flow


Step 11: Submit login credentials


Step 12: Call the resume endpoint


Step 13: Generate the access token

Configure an Application with a Refresh Token Grant

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.

Run in Postman


Step 1: Create an application


Step 2: Get the application secret


Step 3: Create a population


Step 4: Create user


Step 5: Set user password


Step 6: Send an authorize request


Step 7: Get the flow


Step 8: Submit login credentials


Step 9: Call the resume endpoint


Step 10: Generate the access token

Configure a Single-Page Application with PKCE and an AuthCode Grant

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.

Run in Postman


Step 1: Create a single-page application


Step 2: Create a population


Step 3: Create user


Step 4: Set user password


Step 5: Send the authorize request


Step 6: Get the Flow


Step 7: Submit Login Credentials


Step 8: Call the resume endpoint


Step 9: Get the access token

Configure a Single-Page Application with an Implicit Grant

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.

Run in Postman


Step 1: Create a single-page application


Step 2: Get the list of resources


Step 3: Get all scopes


Step 4: Create the application's resource access grant


Step 5: Create a population


Step 6: Create user


Step 7: Set user password


Step 8: Send the authorize request


Step 9: Get the Flow


Step 10: Submit Login Credentials


Step 11: Call the resume endpoint

Configure a Non-Interactive Worker Application

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.

Run in Postman


Step 1: Create a worker application


Step 2: Get the application secret


Step 3: Get a token

Configure an Interactive Worker Application

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.

Run in Postman


Step 1: Create a worker application


Step 2: Get the application secret


Step 3: Get the worker application role assignments


Step 4: Create a sign-on policy


Step 5: Create the sign-on policy action


Step 6: Assign the sign-on policy to an application


Step 7: Create a population


Step 8: Create an admin user


Step 9: Set user password


Step 10: Read all roles


Step 11: Create user role assignment


Step 12: Send the authorize request


Step 13: Get the Flow


Step 14: Submit Login Credentials


Step 15: Call the resume endpoint


Step 16: Get the access token

Create and Update Notification Content

This activity shows you how to create and update content for different types of notifications.

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 and update content for different types of notifications:

  1. Make a GET request to /environments/{{envID}}/templates to read all notification templates.

  2. Make a POST request to /environments/{{envID}}/templates/general/contents to create email notification content.

  3. Make a PUT request to /environments/{{envID}}/templates/general/contents/{{emailContentID}} to update the email notification content.

  4. Make a POST request to /environments/{{envID}}/templates/general/contents to create SMS notification content.

  5. Make a PUT request to /environments/{{envID}}/templates/general/contents/{{smsContentID}} to update the SMS notification content.

  6. Make a POST request to /environments/{{envID}}/templates/general/contents to create voice notification content.

  7. Make a PUT request to /environments/{{envID}}/templates/general/contents/{{voiceContentID}} to update the voice notification content.

  8. Make a POST request to /environments/{{envID}}/templates/transaction/contents to create push notification content.

  9. Make a PUT request to /environments/{{envID}}/templates/transaction/contents/{{pushContentID}} to update the push notification content.

  10. Make a GET request to /environments/{{envID}}/templates/general/contents to read all general template notification content.

  11. Make a GET request to /environments/{{envID}}/templates/transaction/contents/{{pushContentID}} to read only push notification content.

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

Run in Postman


Step 1: Read all notification templates


Step 2: Create email notification content


Step 3: Update email notification content


Step 4: Create SMS notification content


Step 5: Update SMS notification content


Step 6: Create voice notification content


Step 7: Update voice notification content


Step 8: Create push notification content


Step 9: Update push notification content


Step 10: Read all general template notification content


Step 11: Read only push notification content

Test a SAML Application Connection

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

Run in Postman


Step 1: Get the signing key for the source environment


Step 2: Get all environment IDs


Step 3: Create a SAML application in the source environment


Step 4: (Optional) Create attribute mappings for the application


Step 5: Create a certificate in the destination environment


Step 6: Create the new identity provider in the destination environment


Step 7: (Optional) Create attribute mappings for the identity provider


Step 8: Create a sign-on policy for the new identity provider


Step 9: Create a sign-on policy action


Step 10: Set the sign-on policy as the default

Test an OIDC Application Connection

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.

Run in Postman


Step 1a: Create Source Environment


Step 1b: Create Destination Environment


Step 2: Create an OIDC application in the source environment


Step 3: Read the OIDC application secret


Step 4: Create OIDC provider in destination environment


Step 5: Create a sign-on policy for the OIDC IdP


Step 6: Create a sign-on policy action


Step 7: Set the sign-on policy as the default


Step 8: Create an OIDC application in the destination environment


Step 9: Assign the sign-on policy to the destination OIDC application


Step 10: Send an authorization request

Authentication and Authorization

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:

Platform API Description
OpenID Connect/OAuth 2 The PingOne authorization endpoint is used to interact with the resource owner and obtain an authorization grant.
Flows The flow endpoint is used to interact with the user in a sign-on workflow.
SAML 2.0 The SAML endpoints are used by SAML applications to initiate sign-on and signoff operations.
Sign-On Policies Sign-on policies determine the account authentication flow users must complete to access applications secured by PingOne services.
Resources Resources are the protected endpoints that applications request access to using OAuth 2 authorization services.

Configure a Simple Login

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.

Run in Postman


Step 1: Create a web application


Step 2: Get the application secret


Step 3: Create a sign-on policy


Step 4: Create the login sign-on policy action


Step 5: Assign the sign-on policy to the web application


Step 6: Create a population for simple login users


Step 7: Create a user


Step 8: Set user password


Step 9: Send an authorization request


Step 10: Get the flow


Step 11: Submit login credentials


Step 12: Call the resume endpoint


Step 13: Get the access token

Get an ID Token

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.

Run in Postman


Step 1: Create a single-page application


Step 2: Create a population


Step 3: Create user


Step 4: Set user password


Step 5: Send the authorize request


Step 6: Get the Flow


Step 7: Submit Login Credentials


Step 8: Call the resume endpoint

Add a User through a Registration Flow

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.

Run in Postman


Step 1: Create an application


Step 2: Create a population for registered users


Step 3: Create the new sign-on policy


Step 4: Create the sign-on policy action with registration enabled


Step 5: Assign the sign-on policy to an application


Step 6: Send the authorization request


Step 7: Get the flow


Step 8: Register a new user


Step 9: Verify user


Step 10: Get registered user

Use LOGIN and MFA Actions to Authenticate Users

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.

Run in Postman


Step 1: Create a web application


Step 2: Get all resources


Step 3: Get all OIDC Scopes


Step 4: Assign a resource grant to the web application


Step 5: Create a sign-on policy


Step 6: Create the login sign-on policy action


Step 7: Create the MFA sign-on policy action


Step 8: Assign the sign-on policy to the web application


Step 9: Create a population for MFA users


Step 10: Create a user


Step 11: Set user password


Step 12: Enable user MFA


Step 13: Set user device (SMS)


Step 14: Send an authorization request


Step 15: Get the flow


Step 16: Submit login credentials


Step 17: Check OTP


Step 18: Call the resume endpoint


Step 19: Get the application secret


Step 20: Get the access token

Configure a PKCE Authorization Workflow

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.

Run in Postman


Step 1: Create the application connection


Step 2: Submit the authorize request


Step 3: Verify flow initialization


Step 4: Submit username and password


Step 5: Call the resume endpoint


Step 6: Get the token

Configure a Progressive Profiling Sign-On Action

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.

Run in Postman


Step 1: Create an (OIDC) application


Step 2: Get the application secret


Step 3: Get the list of resources


Step 4: Get all scopes


Step 5: Create the resource access grant


Step 6: Create the new sign-on policy


Step 7: Create the login sign-on policy action


Step 8: Create the progressive profiling sign-on policy action


Step 9: Assign the sign-on policy to an application


Step 10: Create a population for profile users


Step 11: Create a user


Step 12: Set user password


Step 13: Send an authorization request


Step 14: Get the flow


Step 15: Submit login credentials


Step 16: Update user profile


Step 17: Call the resume endpoint


Step 18: Get the access token


Step 19: Verify updated user information

Configure Device Authorization Grant Flow

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.

Run in Postman


Step 1: Create a custom application


Step 2: Create a population


Step 3: Create a user


Step 4: Set user password


Step 5: Authorize (device)


Step 6: Start device flow


Step 7: Get the flow


Step 8: Submit login credentials


Step 9: Confirm device user code


Step 10: Accept device authorization grant consent


Step 11: Get the access token

Use LOGIN and AGREEMENT Actions to Authenticate Users

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.

Run in Postman


Step 1: Create a web application


Step 2: Get the application secret


Step 3: Get languages


Step 4: Create an agreement


Step 5: Create an agreement language


Step 6: Create an ageement revision


Step 7: Update the agreement language


Step 8: Enable the agreement


Step 9: Create a sign-on policy


Step 10: Create the login sign-on policy action


Step 11: Create the agreement sign-on policy action


Step 12: Assign the sign-on policy to the web application


Step 13: Create a population for agreement users


Step 14: Create user


Step 15: Set user password


Step 16: Send an authorization request


Step 17: Get the flow


Step 18: Submit login credentials


Step 19: Consent to agreement


Step 20: Call the resume endpoint


Step 21: Get the access token

Get a Token for Custom Resource Access

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.

Run in Postman


Step 1: Create a web application


Step 2: Get the application secret


Step 3: Create a custom resource


Step 4: Create a custom resource scope


Step 5: Assign a resource grant to the web application


Step 6: Create a sign-on policy


Step 7: Create the login sign-on policy action


Step 8: Assign the sign-on policy to the web application


Step 9: Create a population


Step 10: Create a user


Step 11: Set user password


Step 12: Send an authorization request


Step 13: Get the flow


Step 14: Submit login credentials


Step 15: Call the resume endpoint


Step 16: Get the access token


Step 17: Token Introspection

Add a Custom Claim to an Access Token

This activity shows you how to define a custom resource and custom scope and add the custom scope as a claim in an access token.

The following operations are supported by the PingOne APIs:

  • Create an application
  • Create a custom resouce and scope
  • Create a resource attribute mapping
  • Initiate authorization and complete the authentication flow
  • Verify the custom claim in the access 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 add a custom claim to an access token, 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}}/resources to define a custom resource.

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

  4. Make a POST request to /environments/{{envID}}/resources/{{resourceID}}/attribute to define a resource attribute mapping.

  5. Make a POST request to /environments/{{envID}}/applications/{{appID}}/grants to create the 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 assigned to 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 GET request to /{{envID}}/as/authorize to obtain an authorization grant. This request starts the authorization and authentication flow.

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

  11. To complete the authentication flow, 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 token.

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

Run in Postman


Step 1: Create a single-page application


Step 2: Create a custom resource


Step 3: Create a custom scope


Step 4: Create a resource attribute mapping


Step 5: Create the application's resource access grant


Step 6: Create a population


Step 7: Create user


Step 8: Set user password


Step 9: Send the authorize request


Step 10: Get the Flow


Step 11: Submit Login Credentials


Step 12: Call the resume endpoint

Configure CLIENT_SECRET_JWT as the token auth method

This activity shows you how to use a client secret JWT to authenticate a token request.

The following operations are supported by the PingOne APIs:

  • Create an application
  • Create a user
  • Initiate an authorize request
  • Use flow APIs to complete the login
  • Submit a 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 this workflow, 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/{{appJwtAppID}}/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.

  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 submit the authorize request.

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

  8. To complete the login action, make a POST request to /{{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 auth code.

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

Run In Postman


Step 1: Create a web application


Step 2: Get the application secret


Step 3: Create a population


Step 4: Create user


Step 5: Set user password


Step 6: Send an authorize request


Step 7: Get the flow


Step 8: Submit login credentials


Step 9: Call the resume endpoint


Step 10: Get the access token

SAML Sign-On

This activity shows you how to create a basic PingOne sign-on flow for a SAML application.

The following operations are supported by the PingOne APIs:

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

Workflow order of operations

To configure a basic PingOne sign-on flow for a SAML application, you must complete the following tasks:

  1. Make a POST request to /environments/{{envID}}/groups to create a new group resource.

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

  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 POST request to /{{envID}}/saml20/idp/sso to obtain an authorization grant. This request starts the SAML 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}}/saml20/resume?flowId={{flowID}} to call the SAML resume endpoint and return an encoded SAMLResponse.

We highly recommend that you use our Postman collection for this workflow. The collection also contains the accompanying Postman environment template, making it easy for you to use and save variable values. For more information about using Postman environments, see The PingOne Postman Environment Template.

Click the Run in Postman button below to download or fork the Postman collection for this solution.

Run in Postman


Step 1: Create a group


Step 2: Create a SAML application


Step 3: Create the sign-on policy


Step 4: Create the sign-on policy action


Step 5: Assign the sign-on policy to an application


Step 6: Create a population


Step 7: Create a user


Step 8: Set user password


Step 9: Submit SAML sign-on request


Step 10: Get the flow


Step 11: Submit login credentials


Step 12: Call the SAML resume endpoint

Test an OAuth Connection using Identifier First Authentication

This activity shows you how to test an OAuth connection using the identifier first login flow.

The easiest way to do this is by using two PingOne environments. This allows you to create a sign-on policy in one environment, and initiate the identifier first login flow as a user in the other environment, acting as the OIDC identity provider (IdP).

The identifier first login flow will first prompt a user for a username, and then use the identity provider discovery rules defined in the sign-on policy to route the user to the correct external identity provider for authentication. In this case, there will be one discoverable path, which is to sign on with a password. You will then call the resume endpoint to complete authorization and obtain an access token.

Prerequisites

  • Get an access token from the worker application that you created in Create an admin Worker app connection .

  • 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.
  • Create an OIDC application in the destination environment.
  • Set the sign-on policy as the default for the destination environment.
  • Create a population in the source and destination environments.
  • Create users in the source and destination environments.
  • Initiate an authorization request.
  • Get the flow to read the sign-on policy associated with the OIDC application.
  • Pass in the user credentials for verification.
  • Retrieve the authorization code from the authorization server by calling the resume endpoint.
  • Exchange the authorization code for the access token.

Workflow order of operations

To test an OAuth connection using the identifier first login flow, 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 GET request to /environments/{{destinationEnvID}}/applications/{{oidcAppDestinationID}}/secret to read the application secret in the destination.

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

  11. Make a POST request to /environments/{{sourceEnvID}}/populations to create a population in the source environment.

  12. Make a POST request to /environments/{{destinationEnvID}}/populations to create a population in the destination environment.

  13. Make a POST request to /environments/{{sourceEnvID}}/users to create a user in the source environment.

  14. Make a POST request to /environments/{{destinationEnvID}}/users to create a user in the destination environment.

  15. Make a PUT request to /environments/{{sourceEnvID}}/users/{{SourceUserID}}/password to set the source user's password.

  16. Make a PUT request to /environments/{{destinationEnvID}}/users/{{DestinationUserID}}/password to set the destination user's password.

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

  18. Make a GET request to /{{destinationEnvID}}/flows/{{flowID}} to retrieve the flow.

  19. Make a POST request to /{{destinationEnvID}}/flows/{{flowID}} to sign on with the destination user.

  20. Make a POST request to /{{destinationEnvID}}/flows/{{flowID}} to verify the destination user's password.

  21. Make a GET request to /{{destinationEnvID}}/as/resume?flowId={{flowID}} to call the resume endpoint.

  22. Make a POST request to /{{destinationEnvID}}/as/token to retrieve the access token.

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

Run In Postman


Step 1: Create Source Environment


Step 2: Create Destination Environment


Step 3: Create an OIDC application in the source environment


Step 4: Read the OIDC application secret


Step 5: Create OIDC IdP in destination environment


Step 6: Create a sign-on policy for the OIDC IdP


Step 7: Create a sign-on policy action


Step 8: Set the sign-on policy as the default


Step 9: Create an application in the destination environment


Step 10: Read the application secret in destination


Step 11: Assign the sign-on policy to the destination OIDC application


Step 12: Create a source population


Step 13: Create a destination population


Step 14: Create a source user


Step 15: Create a destination user


Step 16: Set source user password


Step 17: Set destination user password


Step 18: Send an authorization request


Step 19: Get the flow


Step 20: Sign on with a username


Step 21: Check password


Step 22: Call the resume endpoint


Step 23: Get the access token

Sign-on using an External Identity Provider

This activity shows you how to test the external authentication flow to sign-on using an external identity provider (IdP).

The easiest way to do this is by using two PingOne environments. One environment will act as the service provider (SP) for an OIDC application, while the other environment is used to configure an OIDC identity provider (IdP) connection.

This activity requires completing an internal authentication flow within the external authentication flow, so it's important to take note of which environment should be used to complete each step. On the first use of external authentication, you will need to link accounts. This takes place in step 25 of this activity. After the accounts are linked once, you will not need to link them again and can omit step 25 in the future.

Prerequisites

  • Get an access token from the worker application that you created in Create an admin Worker app connection .

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

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.
  • Create an OIDC application in the destination environment.
  • Set the sign-on policy as the default for the destination environment.
  • Create a population in the source and destination environments.
  • Create users in the source and destination environments.
  • Initiate an authorization request.
  • Read an external authentication initialization.
  • Send an external authentication request.
  • Get the flow for an external identity provider.
  • Pass in external identity provider credentials for verification.
  • Retrieve an authorization code from the authorization server by calling the resume endpoint.
  • Call the external authentication callback to get the response from an external identity provider.
  • Get the flow and submit credentials for account linking.
  • Retrieve an authorization code from the authorization server by calling the resume endpoint.
  • Exchange an authorization code for an access token.

Workflow order of operations

To test the external authentication flow to sign-on using an external identity provider, 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 GET request to /environments/{{destinationEnvID}}/applications/{{oidcAppDestinationID}}/secret to read the application secret in the destination.

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

  11. Make a POST request to /environments/{{sourceEnvID}}/populations to create a population in the source environment.

  12. Make a POST request to /environments/{{destinationEnvID}}/populations to create a population in the destination environment.

  13. Make a POST request to /environments/{{sourceEnvID}}/users to create a user in the source environment.

  14. Make a POST request to /environments/{{destinationEnvID}}/users to create a user in the destination environment.

  15. Make a PUT request to /environments/{{sourceEnvID}}/users/{{SourceUserID}}/password to set the source user's password.

  16. Make a PUT request to /environments/{{destinationEnvID}}/users/{{DestinationUserID}}/password to set the destination user's password.

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

  18. Make a GET request to /{{destinationEnvID}}/rp/authenticate?providerId={{oidcProviderID}}&flowId={{flowID}} to read the external authentication initialization.

  19. Make a GET request to /{{sourceEnvID}}/as/authorize?response_type=code&redirect_uri=https://auth.pingone.com/{{destinationEnvID}}/rp/callback/openid_connect&scope=openid&client_id={{oidcAppSourceID}}&nonce={{nonce}}&state={{externalProviderState}} to send the external authorization request to the IdP.

  20. Make a GET request to /{{sourceEnvID}}/flows/{{flowID}} to get the flow for the external IdP.

  21. Make a POST request to /{{sourceEnvID}}/flows/{{flowID}} to submit the credentials for the external IdP.

  22. Make a GET request to /{{sourceEnvID}}/as/resume?flowId={{flowID}} to call the resume endpoint for the external IdP.

  23. Make a GET request to /{{destinationEnvID}}/rp/callback/{{providerType}}?code={{authCode}}&state={{externalProviderState}}&nonce={{nonce}} to call the external authentication callback endpoint and get the response from the external identity provider.

  24. Make a GET request to /{{destinationEnvID}}/flows/{{flowID}} to retrieve the flow needed for account linking.

  25. Make a POST request to /{{destinationEnvID}}/flows/{{flowID}} to submit the credentials for account linking.

  26. Make a GET request to /{{destinationEnvID}}/as/resume?flowId={{flowID}} to call the resume endpoint.

  27. Make a POST request to /{{destinationEnvID}}/as/token to retrieve the access token.

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

Run in Postman.


Step 1a: Create Source Environment


Step 1b: Create Destination Environment


Step 2: Create an OIDC application in the source environment


Step 3: Read the OIDC application secret


Step 4: Create OIDC identity provider in destination environment


Step 5: Create a sign-on policy for the OIDC IdP


Step 6: Create a sign-on policy action


Step 7: Set the sign-on policy as the default


Step 8: Create an application in the destination environment


Step 9: Read the application secret in destination


Step 10: Assign the sign-on policy to the destination OIDC application


Step 11: Create a source population


Step 12: Create a destination population


Step 13: Create a source user


Step 14: Create a destination user


Step 15: Set source user password


Step 16: Set destination user password


Step 17: Send an authorization request


Step 18: Read External Authentication Initialization


Step 19: Send external an authorization request to the IdP


Step 20: Get the flow for external identity provider


Step 21: Submit IdP credentials for external identity provider


Step 22: Call the resume endpoint for external identity provider


Step 23: Call the external authentication callback endpoint


Step 24: Get the flow for account linking


Step 25: Submit credentials for account linking


Step 26: Call the resume endpoint


Step 27: Get the access token

DaVinci

These tasks show you how to use a DaVinci flow policy with PingOne APIs to perform common actions for creating a sign-on flow policy, associating the flow policy with an application, and starting the flow. DaVinci use cases in PingOne often call the following API resources:

DaVinci API Description
Flow Policies The flow policies endpoint identifies the DaVinci flow policy resources defined in the specified environment.
Application Flow Policy Assignments Flow policy assignment endpoints manage the DaVinci flow policies associated with the specified application.

Configure a PingOne App to Use a DaVinci Flow Policy

You need to begin in DaVinci, and create the DaVinci application, the DaVinci flow, and the flow policy on the application. See How to create a flow for instructions. You'll need the DaVinci flow policy ID to define the PingOne application's flow policy assignment property.

DaVinci flow settings configuration

DaVinci flows invoked using a PingOne authorize request require special configuration. In DaVinci, when you create your flow, on the flow's Settings screen, you must toggle on the PingOne Flow property located on the General tab.

PingOne DaVinci flow

Setting this property indicates that the flow is a PingOne flow, enabling it to be included in PingOne flow policies and launched directly from PingOne.

PingOne endpoints

This activity shows you how to create a PingOne application, find and associate a DaVinci flow policy with the application, and initiate the flow using a PingOne authorize request. This scenario illustrates the following common operations supported by the PingOne APIs:

  • Create the application.
  • Assign a DaVinci flow policy to the application.
  • Create the PingOne authorize request.

To create the application and flow 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 GET request to /environments/{{envID}}/flowPolicies to return the list of DaVinci flow policies that can be associated with the PingOne application.

  3. Make a POST request to /environments/{{envID}}/applications/{{appID}}/flowPolicyAssignments to assicn a DaVinci flow policy to the application.

  4. Make a GET request to /{{envID}}/as/authorize to obtain an authorization grant. This request starts the authorization flow using the DaVinci flow policy you assigned to the PingOne application.

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

Run in Postman


Step 1: Create a PingOne web application


Step 2: Read all flow policies


Step 3: Create the flow policy assignment


Step 4: Send an authorization request

Configure a DaVinci Non-redirect Flow

This use case triggers a DaVinci flow policy through a PingOne authorize request. In addition, it configures the authorize request to initiate a redirectless flow.

If you set the response_mode parameter on the authorize request to pi.flow, the authorize request does not return a 302 Location header and redirect to the PingOne authorization server. Instead, it returns a 200 message and JSON data from DaVinci. The returned data can be used to create a custom interface on a mobile application, or custom controls on a web application that engage PingOne endpoints. In general, this response mode allows a seamless integration experience, one in which no PingOne UI elements are rendered.

To complete this workflow, you need to begin in DaVinci, and create the DaVinci application, the DaVinci flow, and the flow policy on the application. See How to create a flow for instructions. You'll need the DaVinci flow policy ID to define the PingOne application's flow policy assignment property.

DaVinci flow settings configuration

DaVinci flows invoked using a PingOne authorize request require special configuration. In DaVinci, when you create your flow, on the flow's Settings screen, you must toggle on the PingOne Flow property located on the General tab.

PingOne DaVinci flow

Setting this property indicates that the flow is a PingOne flow, enabling it to be included in PingOne flow policies and launched directly from PingOne.

PingOne endpoints

This activity shows you how to create a PingOne application, find and associate a DaVinci flow policy with the application, and initiate the flow using a PingOne authorize request. This scenario illustrates the following common operations supported by the PingOne APIs:

  • Create the application.
  • Assign a DaVinci flow policy to the application.
  • Create a PingOne population and user.
  • Create the PingOne authorize request that uses the pi.flow setting to turn off redirects.

To create the application and flow 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 GET request to /environments/{{envID}}/applications/{{appID}}/secret to get the application's secret.

  3. Make a GET request to /environments/{{envID}}/flowPolicies to return the list of DaVinci flow policies that can be associated with the PingOne application.

  4. Make a POST request to /environments/{{envID}}/applications/{{appID}}/flowPolicyAssignments to assign a DaVinci flow policy to the application.

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

  6. Make a POST request to /environments/{{envID}}/users to create a new user.

  7. Make a GET request to /{{envID}}/as/authorize to obtain an authorization grant. This request starts the authorization flow using the DaVinci flow policy you assigned to the PingOne application.

Run in Postman


Step 1: Create a PingOne web application


Step 2: Get the application secret


Step 3: Read all flow policies


Step 4: Create the flow policy assignment


Step 5: Create a population


Step 6: Create a user


Step 7: Send authorize request

Gateway Management

You can use the PingOne Gateways APIs to connect your on-premises resources to PingOne by creating gateway resources in PingOne, and managing the gateways from PingOne. These use cases show you how to use the PingOne Platform APIs to perform common actions for setting up and managing the gateways. The use cases often call the following APIs:

Platform API Description
Gateway Management The gateways endpoints connect resources in one security domain (for example, an on-premises datacenter or a hosted private cloud) with an environment in the PingOne platform.
Password Policies Password policies are implemented on populations in a PingOne environment.
Populations A PingOne population defines a set of users, similar to an organizational unit (OU).

See the Gateways admin documentation for more information.

Create an LDAP Gateway

You can use an LDAP gateway to authenticate users at PingOne when their credentials are stored in an external LDAP directory. Kerberos authentication is supported.

This use case illustrates the following operations supported by the PingOne APIs:

  • Create a password policy that will be applied to the population assigned to the LDAP gateway.
  • Create a population for the users whose credentials are stored in the external LDAP directory.
  • Create the LDAP gateway to be used for the external LDAP directory.
  • Update the LDAP gateway.

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 an LDAP gateway, the following tasks must be completed successfully:

  1. Make a POST request to {{apiPath}}/environments/{{envID}}/passwordPolicies to create the password policy you'll (subsequently) assign to the population for the users whose credentials are stored in the external LDAP directory.

  2. Make a POST request to {{apiPath}}/environments/{{envID}}/populations to create the population for the users whose credentials are stored in the external LDAP directory. You'll specify the password policy you created as the password policy to apply to the LDAP directory.

  3. Make a POST request to {{apiPath}}/environments/{{envID}}/gateways to create the LDAP gateway to use for your external LDAP directory.

  4. Make a PUT request to {{apiPath}}/environments/{{envID}}/gateways/{{gatewayID}} to modify the LDAP gateway as needed.

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

Run in Postman


Step 1: Create the Password Policy


Step 2: Create a Population


Step 3: Create the LDAP Gateway


Step 4: Update the LDAP Gateway

Group Management

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

Platform API Description
Groups The groups service enables you to create collections of users with the same access to applications.
Users User resources are unique identities within PingOne that interact with the applications and services in the environment to which the user is assigned. The users service implements directory functions to create, read, update, delete, and search for user resources.
Populations A PingOne population defines a set of users, similar to an organizational unit (OU).

Create a Group and Add a User

This activity shows you how to create a group and assign a user to that group.

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 group and add a user, you must complete the following tasks:

  1. Make a POST request to /environments/{{envID}}/groups to create a new group.

  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 POST request to /environments/{{envID}}/users/{{GroupUseCaseUserID}}/memberOfGroups to add the new user to the group.

  5. Make a GET request to /environments/{{envID}}/users?filter=memberOfGroups[id eq "{{UseCaseGroupID}}"] to return a list of all users in the group.

  6. Make a GET request to /environments/{{envID}}/users/{{GroupUseCaseUserID}}?include=memberOfGroupNames to return a list of all groups associated with the specified user.

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

Run in Postman


Step 1: Create a group


Step 2: Create a population for users


Step 3: Create a user


Step 4: Add user to group


Step 5: Read all users in a group


Step 6: Read all group names for a user

Identity Propagation

PingOne can propagate user identity information from the PingOne directory to a target identity store, or from a source identity store to the PingOne directory. The service continually synchronizes changes to and from the source and target identity stores. Propagation events are triggered by any addition, change, or deletion of users or user information in the source identity store.

These tasks show you how to use the platform APIs to perform common actions for managing identity propagations. Identity propagation use cases often call the following platform API resources:

Platform API Description
Propagation Plans The propagation plans service implements unidirectional provisioning relationships between pairs of identity stores.
Propagation Stores The propagation stores service implements connections to an identity store owned by a customer.
Propagation Rules The propagation rules service implements unidirectional provisioning relationships between a subset of identities on a source identity store and a target identity store.
Propagation Mappings The propagation mappings service implements attribute mappings associated with identity propagation rules.

See Provisioning for more information regarding propagation of identities and Inbound and outbound provisioning for more information regarding inbound versus outbound identity stores.

Create a Workday Propagation Connection

This use case shows you how to create a propagation connection between a Workday source identity store and your PingOne directory target identity store.

A Workday propagation connection is unique in requiring a writeback of information from the target, PingOne directory, to the source, Workday. Workday is demonstrated because of its unique writeback requirement. This use case guides you in successfully creating a Workday propagation connection.

This scenario illustrates the following common operations:

  • Create a propagation plan.
  • Create a propagation store.
  • Create a writeback propagation store (applicable only to Workday).
  • Create a propagation rule.
  • Create a writeback propagation rule (applicable only to Workday).
  • Create propagation rule mappings.
  • Create writeback propagation rule mappings (applicable only to Workday).
  • Create a new propagation revision.

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 Workday inbound propagation connection, you will need to complete the following tasks:

  1. Make a POST request to /environments/{{envID}}/passwordPolicies to create a password policy for the population of users to synchronize with Workday.
  2. Make a POST request to /environments/{{envID}}/populations to create a population of users to synchronize with Workday.
  3. Make a POST request to /environments/{{envID}}/propagation/plans to create a Workday propagation plan.
  4. Make a POST request to /environments/{{envID}}/propagation/stores to create a Workday inbound source propagation store with a type of Workday.
  5. Make a POST request to /environments/{{envID}}/propagation/stores to create a Workday inbound target propagation store with a type of PingOne.
  6. Make a POST request to /environments/{{envID}}/propagation/stores to create a Workday writeback source propagation store of type directory (applicable only to Workday). No separate writeback target propagation store is required, the target is the Workday inbound source propagation store.
  7. Make a POST request to /environments/{{envID}}/propagation/plans/{{planID}}/rules to create a Workday propagation rule for mapping Workday attributes to PingOne attributes.
  8. Make a POST request to /environments/{{envID}}/propagation/plans/{{planID}}/rules to create a Workday propagation rule for mapping directory attributes to Workday attributes (applicable only to Workday).
  9. Make a POST request to /environments/{{envID}}/propagation/rules/{{ruleID}}/mappings to create a Workday inbound propagation rule mapping that associates a specific Workday attribute to a specific PingOne attribute.
  10. Make a POST request to /environments/{{envID}}/propagation/plans/{{ruleID}}/rules to create a Workday writeback propagation rule mapping that associates a specific directory attribute to a specific Workday attribute (applicable only to Workday).
  11. Make a GET request to /environments/{{envID}}/propagation/rules/{{ruleID}}/mappings to verify Workday inbound propagation rule mappings of attributes between Workday and PingOne.
  12. Make a GET request to /environments/{{envID}}/propagation/rules/{{ruleID}}/mappings to verify Workday writeback propagation rule mappings of attributes between directory and Workday (applicable only to Workday).
  13. Make a GET request to /environments/{{envID}}/propagation/rules to verify the Workday inbound propagation rule between Workday and PingOne and the Workday writeback propagation rule between directory and Workday (applicable only to Workday).
  14. Make a GET request to /environments/{{envID}}/propagation/stores to verify Workday propagation stores of types Workday, PingOne, and directory.
  15. Make a GET request to /environments/{{envID}}/propagation/plans to verify Workday propagation plans.
  16. Make a POST request to /environments/{{envID}}/propagation/revisions to create a new propagation revision to ensure all operations are reflected in the PingOne Admin Console.

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

Run in Postman


Step 1: Create a password policy for the Workday population


Step 2: Create a population to synchronize with Workday


Step 3: Create a Workday inbound propagation plan


Step 4: Create a Workday inbound source propagation store


Step 5: Create a PingOne inbound target propagation store


Step 6: Create a directory writeback source propagation store


Step 7: Create a Workday inbound propagation rule


Step 8: Create a Workday writeback propagation rule


Step 9: Create a Workday inbound propagation rule mapping


Step 10: Create a Workday writeback propagation rule mapping


Step 11: Read inbound propagation rule mappings to verify


Step 12: Read writeback propagation rule mappings to verify


Step 13: Read all propagation rules to verify


Step 14: Read all propagation stores to verify


Step 15: Read all propagation plans to verify


Step 16: Create a new propagation revision


Step 17: Restore your Postman and PingOne environments (Optional)

Identity Providers

These tasks show you how to use the platform APIs to perform common actions for managing external identity providers. External identity provider use cases often call the following platform API resources:

Platform API Description
Identity Provider Management The identity provider endpoints manage external identity provider configurations.
Gateway Management The gateways endpoints connect resources in one security domain (for example, an on-premises datacenter or a hosted private cloud) with an environment in the PingOne platform.
Identity Propagation The identity propagation endpoints provide for configurable and audit-capable propagation of identities and their attributes between identity stores owned or managed by a customer.

Configure Facebook as an Identity Provider

PingOne supports several external identity providers, including Facebook. A sign-on policy configuration in PingOne for Facebook as an identity provider allows users to authenticate and gain access to a configured application using the Facebook sign-on flow and their Facebook credentials.

If the client secret has been updated, you must also update the client secret in both the PingOne configuration for the OIDC external identity provider, and the external OpenID provider.

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

  • Create an identity provider configuration
  • Create an optional identity provider attribute mapping
  • Create a population for Facebook users
  • Create a sign-on policy
  • Create a sign-on policy action
  • Create an application
  • Associate the sign-on policy with the application

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 sign-on policy that specifies Facebook as a supported external identity provider, the following tasks must be completed successfully:

  1. Make a POST request to /environments/{{envID}}/identityProviders to create the identity provider configuration for Facebook.

  2. Make a POST request to /environments/{{envID}}/identityProviders/{{providerID}}/attributes to map the Facebook email attributes to PingOne email attributes. This step is optional.

  3. Make a POST request to /environments/{{envID}}/populations to create a population for users who will use their Facebook credentials to sign on.

  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 create a new LOGIN sign-on policy action, which is associated with the new sign-on policy.

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

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

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

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

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

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

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

Run in Postman


Step 1: Create the new identity provider resource


Step 2: Create an optional attribute mapping


Step 3: Create a population for Facebook users


Step 4: Create the new sign-on policy


Step 5: Create the sign-on policy action


Step 6: Create an application


Step 7: Get the list of resources


Step 8: Get all scopes


Step 9: Create the application's resource access grant


Step 10: Assign the sign-on policy to an application


Step 11: Send an authorization request

Configure a SAML Identity Provider

An external identity provider configuration in PingOne to support a SAML identity provider allows users to authenticate and gain access to application resources using a SAML sign-on flow and credentials.

The SAML identity provider's verification certificate and the signing key can be imported using the PingOne certificate management service. For information about importing certificates, see Certificate management.

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

  • Create an identity provider configuration
  • Create a sign-on policy
  • Create a sign-on policy action
  • Assign the sign-on policy to an application

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 sign-on policy that supports a SAML external identity provider, the following tasks must be completed successfully:

  1. Make a POST request to /environments/{{envID}}/certificates to upload the SAML external identity provider's verification certificate and (optionally) to /environments/{{envID}}/keys to upload the signing key.

  2. Make a POST request to /environments/{{envID}}/identityProviders to create the SAML identity provider configuration.

  3. Make a POST request to /environments/{{envID}}/populations to create a population for users who will use their SAML credentials to sign on.

  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 create a new LOGIN sign-on policy action, which is associated with the new sign-on policy.

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

Run in Postman


Step 1a: Upload the SAML application's verification certificate


Step 1b: Upload the SAML application's signing key (Optional)


Step 2: Create the new identity provider resource


Step 3: Create a population for SAML users


Step 4: Create the new sign-on policy


Step 5: Create the sign-on policy action

Integration Catalog

Providing a seamless integration with cloud, mobile, and on-premise applications, the rich ecosystem of available PingOne integrations provides a highly customizable platform. These integrations extend authentication, access, and directory processes of Ping solutions to support single sign-on, multi-factor authentication, native device management, risk intelligence, external identity providers, provisioning, and more.

Of course, with so many integration options available, the need for management of these assets becomes apparent. The Integration Catalog service of the PingOne API acts as a central hub for these features, providing programmatic access to the software binaries and related metadata for each integration, as well as its relevant versions. Access to this data will help administrators map and maintain their Ping integration landscape, regardless of scale.

Download an Integration Binary

Integration kits include .jar files, configuration files, templates, documentation, and other content packaged with an integration. In this use case, you will search your environment for a specific integration. Once found, you will download the integration kit as a zip file.

The purpose of this use case is to provide a simplified view of the interaction with the PingOne Integration Catalog service. In a real world environment, an administrator would expand upon this example to ensure specific integrations were available. For instance, a PingCloud administrator could establish a connection to the PingOne Integration Catalog to retrieve integration kits and include them in the automated startup of containers.

This scenario illustrates the following common operations:

  • Get the environment ID.
  • Get a list of integrations and their versions.
  • Download the integration binary.

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 download a specific integration binary, you will need to complete the following tasks:

  1. Make a GET request to the /environments endpoint to get the environment resource ID.

  2. Make a GET request to /environments/{{envID}}/integrations to retrieve a list of available integrations, using the filter parameter to provide a targeted result set.

  3. Make a GET request to {{apiPath}}/environments/{{envID}}/integrations/{{integrationID}}/versions to retrieve a list of available integration versions.

  4. Make a GET request to /environments/{{envID}}/integrations/{{integrationID}}/versions/{{integrationVersionID}}/asset

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

Run in Postman


Step 1: Get the environment ID


Step 2: Get a list of integrations


Step 3: Get a list of integration versions


Step 4: Download the integration zip file

Metrics

These tasks show you how to use the platform APIs to perform common activities for querying metrics data. Metrics use cases often call the following platform API resources:

Platform API Description
Audit Activities Audit reporting caches incoming audit messages and provides endpoints to request audit events for a specified date range.

Audit for Agreement Consents

This activity shows you how to use the activities endpoint to find agreements associated with users, and users associated with agreements.

The following operations are supported by the PingOne APIs:

  • Use the audit activities endpoint to run a metrics query to return consent agreement history for a specified agreement.
  • Use the audit activities endpoint to run a metrics query to return consent agreement history for a specified 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 complete a metrics query to return consent agreement history for a specified agreement and user, the following tasks must be completed successfully:

  1. Make a GET request to /environments/{{envID}}/activities to return consent agreement history for a specified agreement.
  2. Make a GET request to /environments/{{envID}}/activities to return consent agreement history for a specified user.

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

Run in Postman

Multi-factor Authentication

These tasks show you how to use the platform APIs to perform common MFA actions for non-native applications. MFA use cases often call the following platform API resources:

Platform API Description
Sign-On Policies Sign-on policies determine the account authentication flow users must complete to access applications secured by PingOne services.
Resources Resources are the protected endpoints that applications request access to using OAuth 2 authorization services.
Applications Application resources define the connection between PingOne and the actual application.

Assign an MFA Sign-On Policy to a Web Application

This activity shows you how to define a Web application, create an MFA sign-on policy, and assign the sign-on policy to the application.

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

  • Create an application
  • Assign a resource grant to the application
  • Create a sign-on policy
  • Create a sign-on policy MFA action
  • Assign a sign-on policy to an application

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 the application specify its sign-on policy:

  1. Make a POST request to the /environments/{{envID}}/applications endpoint to define a new Web application.

  2. Make a GET request to /environments/{{envID}}/resources to get the list of available resource server IDs.

  3. Make a get request to /environments/{{envID}}/resources/{{resourceID}}/scopes to get the OIDC scopes for the resource grant.

  4. Make a POST request to /environments/{{envID}}/applications/{{appID}}/grants to assign a resource grant to the application.

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

  6. Make a POST request to /environments/{{envID}}/signOnPolicies/{{signOnPolicyID}} to create an MFA sign-on policy action for the new sign-on policy.

  7. Make a POST request to /environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments to assign the MFA sign-on policy with the new Web application.

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

Run in Postman


Step 1: Create a web application


Step 2: Get all resources


Step 3: Get all OIDC scopes


Step 4: Assign a resource grant to the web application


Step 5: Create an MFA sign-on policy


Step 6: Create a sign-on policy MFA action


Step 7: Assign the MFA sign-on policy to the web application

Configure a Passwordless Sign-On Policy

PingOne supports a sign-on flow that uses only a username and a multi-factor authentication (MFA) sign-on action to authenticate the user. This activity shows you how to create a sign-on policy that does not require a password at sign on.

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

  • Create an application connection
  • Create a sign-on policy
  • Create a sign-on policy action
  • Assign the sign-on policy to an application

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 sign-on policy that does not prompt for a password at login, the following tasks must be completed successfully:

  1. Make a POST request to /environments/{{envID}}/applications to create a new application connection.

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

  3. Make a POST request to /environments/{{envID}}/signOnPolicies/{{policyID}}/actions to create a new MFA sign-on policy action, which is associated with the new (no password) sign-on policy.

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

  5. Make a GET request to the authorization server to retrieve the URL for the sign-on screen, which is returned in the response's HTTP Location header.

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

Run in Postman


Step 1: Create an application


Step 2: Create the new sign-on policy


Step 3: Create the sign-on policy action


Step 4: Assign the sign-on policy to an application


Step 5: Test authentication

Configure an MFA-Only Flow Using a Login Hint Token

This activity shows you how to create an MFA only authentication flow using a login_hint_token to identify and authenticate the end-user without needing to encode the entire authentication request in a signed JWT.

The following operations are supported by the PingOne APIs:

  • Create an application
  • Create a sign-on policy
  • Create an SMS sign-on policy action
  • Create a user
  • Create a device authentication policy
  • Initiate an authorize request using a login_hint_token
  • Use the OTP check API to complete the MFA action

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 an MFA only 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/{{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}}/resources to return a list of all resource entities associated with the specified environment.

  4. Make a GET request to /environments/{{envID}}/resources/{{resourceID}}/scopes to list all scopes associated with a specified 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 SMS 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}}/deviceAuthenticationPolicies to create the device authentication policy.

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

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

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

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

Run in Postman


Step 1: Create a web application


Step 2: Get the application secret


Step 3: Get all resources


Step 4: Get all OIDC Scopes


Step 5: Assign a resource grant to the web application


Step 6: Create a sign-on policy


Step 7: Create an SMS MFA sign-on policy action


Step 8: Assign the sign-on policy to the web application


Step 9: Create a population for MFA users


Step 10: Create user


Step 11: Set user password


Step 12: Enable user MFA


Step 13: Create the device authentication policy


Step 14: Set user device (SMS)


Step 15: Send authorize request


Step 16: Check OTP


Step 17: Call the resume endpoint

Create an MFA Transaction Approval using SMS

This activity shows you how to create a transaction approval MFA authentication flow using a request token to encode the request parameters in a signed JWT.

The following operations are supported by the PingOne APIs:

  • Create an application
  • Create a sign-on policy
  • Create an SMS sign-on policy action
  • Create a device authentication policy
  • Create a user
  • Initiate an authorize request using a request token and a login_hint_token
  • Use the OTP check API to complete the MFA action

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 transaction approval MFA 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/{{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}}/resources to return a list of all resource entities associated with the specified environment.

  4. Make a GET request to /environments/{{envID}}/resources/{{resourceID}}/scopes to list all scopes associated with a specified 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 SMS 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}}/templates/transaction/contents to create a transaction notification template.

  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 /environments/{{envID}}/users/{{userID}}/mfaEnabled to enable MFA actions for this user.

  14. Make a POST request to /environments/{{envID}}/deviceAuthenticationPolicies to create the device authentication policy.

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

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

  17. To complete the SMS 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 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.

Run in Postman


Step 1: Create a web application


Step 2: Get the application secret


Step 3: Get all resources


Step 4: Get all OIDC Scopes


Step 5: Assign a resource grant to the web application


Step 6: Create a sign-on policy


Step 7: Create an SMS MFA sign-on policy action


Step 8: Assign the sign-on policy to the web application


Step 9: Create a transaction SMS template


Step 10: Create a population for MFA users


Step 11: Create user


Step 12: Set user password


Step 13: Enable user MFA


Step 14: Create the device authentication policy


Step 15: Set user device (SMS)


Step 16: Send authorize request for transaction approval


Step 17: Check OTP


Step 18: Call the resume endpoint


Step 19: Get the access token

Use an Email MFA Action to Authenticate Users

This activity shows you how to create a sign-on policy with an Email MFA action, 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 an Email MFA sign-on policy action
  • Create a device authentication policy
  • Create a user
  • Initiate an authorize request
  • Use flow APIs to complete the MFA action

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 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 Email MFA action associated with this sign-on policy.

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

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

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

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

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

  12. Make a POST request to /environments/{{envID}}/deviceAuthenticationPolicies to create the device authentication policy.

  13. Make a POST request to /environments/{{envID}}/users/{{userID}}/devices to associate an Email 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 sign-on action, make a POST request to GET /{{envID}}/flows/{{flowID}} and provide the user's username for a user lookup action.

  17. To complete the Eamil 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.

Run in Postman


Step 1: Create a web application


Step 2: Get all resources


Step 3: Get all OIDC Scopes


Step 4: Assign a resource grant to the web application


Step 5: Create a sign-on policy


Step 6: Create an Email MFA sign-on policy action


Step 7: Assign the sign-on policy to the web application


Step 8: Create a population for MFA users


Step 9: Create a user


Step 10: Set user password


Step 11: Enable user MFA


Step 12: Create the device authentication policy