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:
-
Create a Worker application using the PingOne admin console application.
-
Use the PingOne Authorization APIs to get an admin access token (a JSON Web Token) that gives you premissions to run PingOne APIs.
-
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:
-
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.
-
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.
-
An access token is required to authenticate any calls to the PingOne Platform APIs. The access token is valid for one hour.
-
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.
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. | |
Platform | Postman requests for the PingOne platform API. Includes all PingOne documentation and example reponses. No environment variables are included. |
Download a Postman collection
You have two methods for retrieving a Postman collection into your workspace.
-
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.
-
Import the collection into your workspace. This is a one-time transfer and retains no association to the source collection.
To retrieve the collection:
-
Click the collection's Run In Postman button.
-
At the prompt, click Fork Collection at the bottom of the dialog or click import a copy near the bottom of the dialog.
-
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:
-
If not available, creates an environment variable unique to that service.
-
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:
-
Log in to the PingOne admin console. For more information about the PingOne admin console, see Accessing the admin console home page.
-
Select Applications --> Applications.
-
Click the + icon next to Applications to add a new app.
-
In the Application Name field, enter an application name, and select Worker as the Application Type.
-
Click Save.
-
Click the toggle at the upper right to enable the application.
-
The environment ID, Worker app Client ID, and Worker app Client Secret is displayed.
-
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.
-
Click Save.
-
The roles and permissions you've granted are then displayed. They should look like this:
You'll need the Client ID and Client Secret associated with your Worker app when obtaining an admin access token in the next workflow to Create your test environment.
Create your test environment
Although an environment is automatically created for you when you first sign on to PingOne, for the purposes of testing PingOne workflows, you'll create an additional, new environment.
Prerequisites
-
The Organization Admin role is required to create an environment. You're assigned the Organization Admin role when you create a PingOne account.
-
A Postman installation. If you aren't currently using Postman, you can install the free version. See Download Postman to install Postman.
-
Import or fork the Postman collection into your Postman installation. Click the Run in Postman button below. You'll use this collection for the test environment workflow:
For more information about using Postman environments, see The PingOne Postman environment template.
-
When you open the Postman collection, ensure that you select PingOne Postman Environment Template for use with the collection:
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:
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:
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:
-
Open your Postman application, and for each relevant request, select Settings.
-
Ensure that the Automatically follow redirects setting is set to OFF.
For more information about Postman preferences, see Setting up Postman.
Removing session cookies in Postman
When you run use case collections that involve authentication flows, the PingOne API uses session token cookies to establish the user's authentication session and maintain the session throughout the workflow. Postman functions as the calling client to save these cookies, allowing the flow to redirect back to the authorization server to get an access token.
Before you run any use cases, we recommend that you remove all old session token cookies from Postman. To remove these cookies:
-
For the use case you want to run, open the Step 1 request.
-
Click the Cookies link, which is directly under the Send button.
-
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.
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
, orcom.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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute. -
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. -
Make a
GET
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to list all scopes associated with a specified resource (the PingOne platform resource). -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be associated with the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
To initiate the authentication flow, make a
GET
request toGET /{{envID}}/flows/{{flowID}}
. -
To complete the authentication flow, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the token. -
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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be associated with the new population resource. -
Make a
PUT
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
GET
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
To initiate the authentication flow, make a
GET
request toGET /{{envID}}/flows/{{flowID}}
. -
To complete the authentication flow, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the token. -
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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
To initiate the authentication flow, make a
GET
request toGET /{{envID}}/flows/{{flowID}}
. -
To complete the authentication flow, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the token. -
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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
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. -
Make a
GET
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to list all scopes associated with a specified resource (the PingOne platform resource). -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
To initiate the authentication flow, make a
GET
request toGET /{{envID}}/flows/{{flowID}}
. -
To complete the authentication flow, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{applicationID}}/secret
to return the application secret. -
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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{applicationID}}/secret
to get the application's secret, which is needed to authenticate the token request. -
Make a
GET
request to/environments/{{envID}}/applications/{{applicationID}}/roleAssignments
to return a list of roles assigned to the application. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{policyID}}/actions
to add a login action to the sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{applicationID}}/signOnPolicyAssignments
to associate the new sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new admin population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create an admin user who will be assigned to the new population resource. -
Make a
PUT
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
GET
request to/roles
to read all roles. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/roleAssignments
to assign a role to the new admin user. -
Make a
GET
request to/{{envID}}/as/authorize
to initiate an authorization request. This request starts the sign-on flow. -
Make a
GET
request toGET /{{envID}}/flows/{{flowID}}
to initiate the authentication flow. -
To complete the authentication flow, make a
POST
request to/{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the 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.
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:
-
Make a
GET
request to/environments/{{envID}}/templates
to read all notification templates. -
Make a
POST
request to/environments/{{envID}}/templates/general/contents
to create email notification content. -
Make a
PUT
request to/environments/{{envID}}/templates/general/contents/{{emailContentID}}
to update the email notification content. -
Make a
POST
request to/environments/{{envID}}/templates/general/contents
to create SMS notification content. -
Make a
PUT
request to/environments/{{envID}}/templates/general/contents/{{smsContentID}}
to update the SMS notification content. -
Make a
POST
request to/environments/{{envID}}/templates/general/contents
to create voice notification content. -
Make a
PUT
request to/environments/{{envID}}/templates/general/contents/{{voiceContentID}}
to update the voice notification content. -
Make a
POST
request to/environments/{{envID}}/templates/transaction/contents
to create push notification content. -
Make a
PUT
request to/environments/{{envID}}/templates/transaction/contents/{{pushContentID}}
to update the push notification content. -
Make a
GET
request to/environments/{{envID}}/templates/general/contents
to read all general template notification content. -
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.
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:
-
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. -
Make a
GET
request to/environments
to get the environment IDs. -
Make a
POST
request to/environments/{{sourceEnvID}}/applications
to create a SAML application. -
(Optional) Make a
POST
request to/environments/{{sourceEnvID}}/applications/{{appID}}/attributes
to any attribute mappings needed for the source environment application. -
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. -
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. -
Make a
POST
request to/environments/{{destinationEnvID}}/identityProviders
to create the SAML IdP configuration in the destination environment. -
(Optional) Make a
POST
request to/environments/{{destinationEnvID}}/identityProviders/{{providerID}}/attributes
to add any needed attribute mappings for the IdP in the destination environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/signOnPolicies
to create a sign-on policy for the new IdP in the destination environment. -
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. -
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
-
Copy the Self-Service URL for the destination environment. You can find the Self-Service URL on the Settings → Environment → Properties page.
-
Open a private browser window, and enter the Self-Service URL that you copied.
-
Click the button that matches your SAML IdP connection.
-
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.
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:
-
Make
POST
requests to/environments
to create a source environment and a destination environment. -
Make a
POST
request to/environments/{{sourceEnvID}}/applications
to create an OIDC application in the source environment. -
Make a
GET
request to/environments/{{sourceEnvID}}/applications/{{appID}}/secret
to read the OIDC application secret. -
Make a
POST
request to/environments/{{destinationEnvID}}/identityProviders
to create an OIDC IdP in the destination environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/signOnPolicies
to create a sign-on policy for the IdP in the destination environment. -
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. -
Make a
PUT
request to/environments/{{destinationEnvID}}/signOnPolicies/{{policyID}}
to set the policy as default. -
Make a
POST
request to/environments/{{destinationEnvID}}/applications
to create an OIDC application in the destination environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/applications/{{appID}}/signOnPolicyAssignments
to assign the sign-on policy to the destination OIDC application. -
Make a
GET
request to/{{destinationEnvID}}/as/authorize
to retrieve an authorization grant.
Execute the authentication flow
-
Open a private browser window, and enter the
Location
header URL that was returned from the/as/authorize
call. -
Click the button that matches your OIDC IdP connection.
-
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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{webAppSimpleLoginId}}/secret
to return the new application's secret attribute. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the login action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user to assign to the new population resource. -
Make a
PUT
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
GET
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the sign-on flow. -
To complete the login action, make a
POST
request to/{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the 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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user to assign to the new population resource. -
Make a
PUT
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
GET
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the sign-on flow. -
Make a
POST
request to/{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population for the reistered user. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy that enables user registration. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the registration action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to create associate the registration sign-on policy with the application. -
Make a
GET
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to get the flow. -
Make a
POST
request to/{{envID}}/flows/{{flowID}}
to register the new user. -
Make a
POST
request to/{{envID}}/flows/{{flowID}}
to verify the new user account. -
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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/resources
to return a list of all resource entities associated with the specified environment. -
Make a
GET
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to list all scopes associated with a specified resource. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the login action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the MFA action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/mfaEnabled
to enable MFA actions for this user. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/devices
to associate an MFA device with this user. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the sign-on flow. -
To complete the login action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
To complete the MFA action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the one-time passcode. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the auth code. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute, which is needed for the token request. -
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.
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:
-
The client creates and records a
code_verifier
secret, which is a random value between 43 and 128 characters in length. -
The client uses the
code_verifier
value to compute thecode_challenge
value. Thecode_challenge_method
is the transformation method that creates thecode_challenge
value. This parameter value is also recorded. -
The authorization request includes the
code_challenge
and in some cases thecode_challenge_method
parameter values in the request. Thecode_challenge_method
is an optional parameter. It defaults toplain
if not specified (which generates an error when theS256_REQUIRED
PKCE enforcement option is specified by the application). -
The authorization server records the
code_challenge
and thecode_challenge_method
parameter values, and responds by issuing the authorization code. -
The client sends the authorization code to the
/{{envID}}/as/token
endpoint. The token request requires thecode_verifier
secret created in step 1. -
The authorization server uses the
code_challenge_method
to transform thecode_verifier
value and compare it to thecode_challenge
value submitted and recorded in the authorize request. -
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
andcode_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:
-
Make a
POST
request to/environments/{{envID}}/applications
to define an OpenID Connect native app type that uses an authorization code grant. -
Make a
GET
request to/{{envID}}/as/authorize
to initiate authorization and submit thecode_challenge
andcode_challenge_method
values to the authorization server. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to verify the flow initialization. -
Make a
POST
request to/{{envID}}/flows/{{flowID}}
with theapplication/vnd.pingidentity.usernamePassword.check+json
content type to submit the username and password. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the authorize resume endpoint. -
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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute. -
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. -
Make a
GET
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to list all scopes associated with a specified resource (the PingOne platform resource). -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the login action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the progressive profiling action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the flow. -
To complete the login action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
To complete the progressive profiling action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's mobile phone number. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the auth code. -
After the authorization flow completes, make a
POST
request to/{{envID}}/as/token
to exchange the auth code for an access token. -
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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
PUT
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/{{envID}}/as/device_authorization
to return the device code and the user code. -
Make a
GET
request to/{{envID}}/device
to initiate authorization and return a flow ID. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to start the flow. -
To complete the login action, make a
POST
request to/{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
To complete the confirm activation code action, make a
POST
request to/{{envID}}/flows/{{flowID}}
to submit the activation code. -
To complete the consent action, make a
POST
request to/{{envID}}/flows/{{flowID}}
to accept the device authorization grant agreement. -
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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute, which is needed for the token request. -
Make a
GET
request to/environments/{{envID}}/languages
to find the environment's default language. -
Make a
POST
request to/environments/{{envID}}/agreements
to create a new agreement. -
Make a
POST
request to/environments/{{envID}}/agreements/{{agreementID}}/languages
to create the language for the agreement. -
Make a
POST
request to/environments/{{envID}}/agreements/{{agreementID}}/languages/{{agreementLanguageID}}/revisions
to create the revision for the agreement in the specified language. -
Make a
PUT
request to/environments/{{envID}}/agreements/{{agreementID}}/languages/{{agreementLanguageID}}
to enable the agreement language. -
Make a
PUT
request to/environments/{{envID}}/agreements/{{agreementID}}
to enable the agreement. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the login action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the agreement action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the sign-on flow. -
To complete the login action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
To complete the agreement action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide consent to the agreement. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the 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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute, which is needed for the token request. -
Make a
POST
request to/environments/{{envID}}/resources
to define the custom resource. -
Make a
POST
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to define a scope for the custom resource. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the login action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
GET
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the sign-on flow. -
To complete the login action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the auth code. -
Make a
POST
request to/{{envID}}/as/token
to exchange the auth code for an access token. -
To verify that the token grants access to the new custom resource, make a
POST
request toGET /{{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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
POST
request to/environments/{{envID}}/resources
to define a custom resource. -
Make a
POST
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to define a scope for the custom resource. -
Make a
POST
request to/environments/{{envID}}/resources/{{resourceID}}/attribute
to define a resource attribute mapping. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create the access grant for the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
GET
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization and authentication flow. -
To initiate the authentication flow, make a
GET
request to/{{envID}}/flows/{{flowID}}
. -
To complete the authentication flow, make a
POST
request to/{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appJwtAppID}}/secret
to return the new application's secret attribute. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user. -
Make a
PUT
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
GET
request to/{{envID}}/as/authorize
to submit the authorize request. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the sign-on flow. -
To complete the login action, make a
POST
request to/{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the 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.
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:
-
Make a
POST
request to/environments/{{envID}}/groups
to create a new group resource. -
Make a
POST
request to/environments/{{envID}}/applications
to add a new SAML application to the specified environment. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the login action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user to assign to the new population resource. -
Make a
PUT
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/{{envID}}/saml20/idp/sso
to obtain an authorization grant. This request starts the SAML authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the sign-on flow. -
To complete the login action, make a
POST
request to/{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/saml20/resume?flowId={{flowID}}
to call the SAML resume endpoint and return an encodedSAMLResponse
.
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.
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:
-
Make
POST
requests to/environments
to create a source environment and a destination environment. -
Make a
POST
request to/environments/{{sourceEnvID}}/applications
to create an OIDC application in the source environment. -
Make a
GET
request to/environments/{{sourceEnvID}}/applications/{{appID}}/secret
to read the OIDC application secret. -
Make a
POST
request to/environments/{{destinationEnvID}}/identityProviders
to create an OIDC IdP in the destination environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/signOnPolicies
to create a sign-on policy for the IdP in the destination environment. -
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. -
Make a
PUT
request to/environments/{{destinationEnvID}}/signOnPolicies/{{policyID}}
to set the policy as default. -
Make a
POST
request to/environments/{{destinationEnvID}}/applications
to create an OIDC application in the destination environment. -
Make a
GET
request to/environments/{{destinationEnvID}}/applications/{{oidcAppDestinationID}}/secret
to read the application secret in the destination. -
Make a
POST
request to/environments/{{destinationEnvID}}/applications/{{appID}}/signOnPolicyAssignments
to assign the sign-on policy to the destination OIDC application. -
Make a
POST
request to/environments/{{sourceEnvID}}/populations
to create a population in the source environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/populations
to create a population in the destination environment. -
Make a
POST
request to/environments/{{sourceEnvID}}/users
to create a user in the source environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/users
to create a user in the destination environment. -
Make a
PUT
request to/environments/{{sourceEnvID}}/users/{{SourceUserID}}/password
to set the source user's password. -
Make a
PUT
request to/environments/{{destinationEnvID}}/users/{{DestinationUserID}}/password
to set the destination user's password. -
Make a
GET
request to/{{destinationEnvID}}/as/authorize
to retrieve an authorization grant. -
Make a
GET
request to/{{destinationEnvID}}/flows/{{flowID}}
to retrieve the flow. -
Make a
POST
request to/{{destinationEnvID}}/flows/{{flowID}}
to sign on with the destination user. -
Make a
POST
request to/{{destinationEnvID}}/flows/{{flowID}}
to verify the destination user's password. -
Make a
GET
request to/{{destinationEnvID}}/as/resume?flowId={{flowID}}
to call the resume endpoint. -
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.
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:
-
Make
POST
requests to/environments
to create a source environment and a destination environment. -
Make a
POST
request to/environments/{{sourceEnvID}}/applications
to create an OIDC application in the source environment. -
Make a
GET
request to/environments/{{sourceEnvID}}/applications/{{appID}}/secret
to read the OIDC application secret. -
Make a
POST
request to/environments/{{destinationEnvID}}/identityProviders
to create an OIDC IdP in the destination environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/signOnPolicies
to create a sign-on policy for the IdP in the destination environment. -
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. -
Make a
PUT
request to/environments/{{destinationEnvID}}/signOnPolicies/{{policyID}}
to set the policy as default. -
Make a
POST
request to/environments/{{destinationEnvID}}/applications
to create an OIDC application in the destination environment. -
Make a
GET
request to/environments/{{destinationEnvID}}/applications/{{oidcAppDestinationID}}/secret
to read the application secret in the destination. -
Make a
POST
request to/environments/{{destinationEnvID}}/applications/{{appID}}/signOnPolicyAssignments
to assign the sign-on policy to the destination OIDC application. -
Make a
POST
request to/environments/{{sourceEnvID}}/populations
to create a population in the source environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/populations
to create a population in the destination environment. -
Make a
POST
request to/environments/{{sourceEnvID}}/users
to create a user in the source environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/users
to create a user in the destination environment. -
Make a
PUT
request to/environments/{{sourceEnvID}}/users/{{SourceUserID}}/password
to set the source user's password. -
Make a
PUT
request to/environments/{{destinationEnvID}}/users/{{DestinationUserID}}/password
to set the destination user's password. -
Make a
GET
request to/{{destinationEnvID}}/as/authorize
to retrieve an authorization grant. -
Make a
GET
request to/{{destinationEnvID}}/rp/authenticate?providerId={{oidcProviderID}}&flowId={{flowID}}
to read the external authentication initialization. -
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. -
Make a
GET
request to/{{sourceEnvID}}/flows/{{flowID}}
to get the flow for the external IdP. -
Make a
POST
request to/{{sourceEnvID}}/flows/{{flowID}}
to submit the credentials for the external IdP. -
Make a
GET
request to/{{sourceEnvID}}/as/resume?flowId={{flowID}}
to call the resume endpoint for the external IdP. -
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. -
Make a
GET
request to/{{destinationEnvID}}/flows/{{flowID}}
to retrieve the flow needed for account linking. -
Make a
POST
request to/{{destinationEnvID}}/flows/{{flowID}}
to submit the credentials for account linking. -
Make a
GET
request to/{{destinationEnvID}}/as/resume?flowId={{flowID}}
to call the resume endpoint. -
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.
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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/flowPolicies
to return the list of DaVinci flow policies that can be associated with the PingOne application. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/flowPolicyAssignments
to assicn a DaVinci flow policy to the application. -
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.
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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to get the application's secret. -
Make a
GET
request to/environments/{{envID}}/flowPolicies
to return the list of DaVinci flow policies that can be associated with the PingOne application. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/flowPolicyAssignments
to assign a DaVinci flow policy to the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population. -
Make a
POST
request to/environments/{{envID}}/users
to create a new user. -
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.
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:
-
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. -
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. -
Make a
POST
request to{{apiPath}}/environments/{{envID}}/gateways
to create the LDAP gateway to use for your external LDAP directory. -
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.
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:
-
Make a
POST
request to/environments/{{envID}}/groups
to create a new group. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user to assign to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{GroupUseCaseUserID}}/memberOfGroups
to add the new user to the group. -
Make a
GET
request to/environments/{{envID}}/users?filter=memberOfGroups[id eq "{{UseCaseGroupID}}"]
to return a list of all users in the group. -
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.
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:
- Make a
POST
request to/environments/{{envID}}/passwordPolicies
to create a password policy for the population of users to synchronize with Workday. - Make a
POST
request to/environments/{{envID}}/populations
to create a population of users to synchronize with Workday. - Make a
POST
request to/environments/{{envID}}/propagation/plans
to create a Workday propagation plan. - Make a
POST
request to/environments/{{envID}}/propagation/stores
to create a Workday inbound source propagation store with atype
ofWorkday
. - Make a
POST
request to/environments/{{envID}}/propagation/stores
to create a Workday inbound target propagation store with atype
ofPingOne
. - Make a
POST
request to/environments/{{envID}}/propagation/stores
to create a Workday writeback source propagation store oftype
directory (applicable only to Workday). No separate writeback target propagation store is required, the target is the Workday inbound source propagation store. - Make a
POST
request to/environments/{{envID}}/propagation/plans/{{planID}}/rules
to create a Workday propagation rule for mappingWorkday
attributes toPingOne
attributes. - Make a
POST
request to/environments/{{envID}}/propagation/plans/{{planID}}/rules
to create a Workday propagation rule for mappingdirectory
attributes toWorkday
attributes (applicable only to Workday). - 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. - Make a
POST
request to/environments/{{envID}}/propagation/plans/{{ruleID}}/rules
to create a Workday writeback propagation rule mapping that associates a specificdirectory
attribute to a specificWorkday
attribute (applicable only to Workday). - Make a
GET
request to/environments/{{envID}}/propagation/rules/{{ruleID}}/mappings
to verify Workday inbound propagation rule mappings of attributes betweenWorkday
andPingOne
. - Make a
GET
request to/environments/{{envID}}/propagation/rules/{{ruleID}}/mappings
to verify Workday writeback propagation rule mappings of attributes betweendirectory
andWorkday
(applicable only to Workday). - Make a
GET
request to/environments/{{envID}}/propagation/rules
to verify the Workday inbound propagation rule betweenWorkday
andPingOne
and the Workday writeback propagation rule betweendirectory
andWorkday
(applicable only to Workday). - Make a
GET
request to/environments/{{envID}}/propagation/stores
to verify Workday propagation stores of typesWorkday
,PingOne
, anddirectory
. - Make a
GET
request to/environments/{{envID}}/propagation/plans
to verify Workday propagation plans. - 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.
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:
-
Make a
POST
request to/environments/{{envID}}/identityProviders
to create the identity provider configuration for Facebook. -
Make a
POST
request to/environments/{{envID}}/identityProviders/{{providerID}}/attributes
to map the Facebookemail
attributes to PingOneemail
attributes. This step is optional. -
Make a
POST
request to/environments/{{envID}}/populations
to create a population for users who will use their Facebook credentials to sign on. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
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. -
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
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. -
Make a
GET
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to list all scopes associated with a specified resource (the PingOne platform resource). -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
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.
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:
-
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. -
Make a
POST
request to/environments/{{envID}}/identityProviders
to create the SAML identity provider configuration. -
Make a
POST
request to/environments/{{envID}}/populations
to create a population for users who will use their SAML credentials to sign on. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
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.
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:
-
Make a
GET
request to the/environments
endpoint to get the environment resource ID. -
Make a
GET
request to/environments/{{envID}}/integrations
to retrieve a list of available integrations, using thefilter
parameter to provide a targeted result set. -
Make a
GET
request to{{apiPath}}/environments/{{envID}}/integrations/{{integrationID}}/versions
to retrieve a list of available integration versions. -
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.
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:
- Make a
GET
request to/environments/{{envID}}/activities
to return consent agreement history for a specified agreement. - 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.
Step 1. View Consent History for an Agreement
Step 2. View Consent History for a User
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:
-
Make a
POST
request to the/environments/{{envID}}/applications
endpoint to define a new Web application. -
Make a
GET
request to/environments/{{envID}}/resources
to get the list of available resource server IDs. -
Make a get request to
/environments/{{envID}}/resources/{{resourceID}}/scopes
to get the OIDC scopes for the resource grant. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to assign a resource grant to the application. -
Make a
POST
request to the/environments/{{envID}}/signOnPolicies
endpoint to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}
to create an MFA sign-on policy action for the new sign-on policy. -
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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to create a new application connection. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
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. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate this sign-on policy with the specified application. -
Make a
GET
request to the authorization server to retrieve the URL for the sign-on screen, which is returned in the response's HTTPLocation
header.
Click the Run in Postman button below to download the Postman collection for this use case.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute, which is needed for the token request. -
Make a
GET
request to/environments/{{envID}}/resources
to return a list of all resource entities associated with the specified environment. -
Make a
GET
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to list all scopes associated with a specified resource. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the SMS MFA action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/mfaEnabled
to enable MFA actions for this user. -
Make a
POST
request to/environments/{{envID}}/deviceAuthenticationPolicies
to create the device authentication policy. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/devices
to associate an SMS MFA device with this user. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
To complete the SMS MFA action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the one-time passcode. -
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.
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 alogin_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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute, which is needed for the token request. -
Make a
GET
request to/environments/{{envID}}/resources
to return a list of all resource entities associated with the specified environment. -
Make a
GET
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to list all scopes associated with a specified resource. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the SMS MFA action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/templates/transaction/contents
to create a transaction notification template. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/mfaEnabled
to enable MFA actions for this user. -
Make a
POST
request to/environments/{{envID}}/deviceAuthenticationPolicies
to create the device authentication policy. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/devices
to associate an SMS MFA device with this user. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
To complete the SMS MFA action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the one-time passcode. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the 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.
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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/resources
to return a list of all resource entities associated with the specified environment. -
Make a
GET
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to list all scopes associated with a specified resource. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the Email MFA action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/mfaEnabled
to enable MFA actions for this user. -
Make a
POST
request to/environments/{{envID}}/deviceAuthenticationPolicies
to create the device authentication policy. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/devices
to associate an Email MFA device with this user. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the sign-on flow. -
To complete the sign-on action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's username for a user lookup action. -
To complete the Eamil MFA action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the one-time passcode. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the auth code. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute, which is needed for the token request. -
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.