PingOne for Developers Workflow Library

Our workflow library describes the workflows for common PingOne workflows, both for the platform and its services. Each workflow is configured as a Postman collection, and includes a Run in Postman button that enables you to fork, or download and import, the collection to your Postman workspace. You can see the complete list of workflow collections in Downloading PingOne workflow collections.

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 workflows, you'll need to configure any of your Postman requests for authorization and authentication to not follow redirects automatically. You'll also need to do this for requests that require a redirect to the authorization server. These requests will not execute the steps in the Postman collection as intended if Postman's Automatically follow redirects setting is turned on.

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

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

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

Postman Request Settings

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

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:

    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

    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.

Removing session cookies in Postman

When you run workflow 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 workflows, we recommend that you remove all old session token cookies from Postman. To remove these cookies:

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

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

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

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

Application Management

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

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

Best practices for application secrets

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

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

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

Configure an Application with an Authorization Code Grant

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

The following operations are supported by the PingOne APIs:

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

Best practices for application secrets

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

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

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create an OpenID Connect (OIDC) application

Step 2: Get the application secret

Step 3: Get the list of resources

Step 4: Get all scopes

Step 5: Create the application's resource access grant

Step 6: Create a population

Step 7: Create user

Step 8: Set user password

Step 9: Obtain an authorization grant

Step 10: Get the flow

Step 11: Submit login credentials

Step 12: Call the resume endpoint

Step 13: Generate the access token

Configure an Application with a Refresh Token Grant

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create an application

Step 2: Get the application secret

Step 3: Create a population

Step 4: Create user

Step 5: Set user password

Step 6: Send an authorize request

Step 7: Get the flow

Step 8: Submit login credentials

Step 9: Call the resume endpoint

Step 10: Generate the access token

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

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a single-page application

Step 2: Create a population

Step 3: Create user

Step 4: Set user password

Step 5: Send the authorize request

Step 6: Get the Flow

Step 7: Submit Login Credentials

Step 8: Call the resume endpoint

Step 9: Get the access token

Configure a Single-Page Application with an Implicit Grant

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a single-page application

Step 2: Get the list of resources

Step 3: Get all scopes

Step 4: Create the application's resource access grant

Step 5: Create a population

Step 6: Create user

Step 7: Set user password

Step 8: Send the authorize request

Step 9: Get the Flow

Step 10: Submit Login Credentials

Step 11: Call the resume endpoint

Configure a Non-Interactive Worker Application

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

The following operations are supported by the PingOne APIs:

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

Best practices for application secrets

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

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

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

Prerequisites

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

Workflow order of operations

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a worker application

Step 2: Get the application secret

Step 3: Get a token

Configure an Interactive Worker Application

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

The following operations are supported by the PingOne APIs:

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

Best practices for application secrets

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

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

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a worker application

Step 2: Get the application secret

Step 3: Get the worker application role assignments

Step 4: Create a sign-on policy

Step 5: Create the sign-on policy action

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

Step 7: Create a population

Step 8: Create an admin user

Step 9: Set user password

Step 10: Read all roles

Step 11: Create user role assignment

Step 12: Send the authorize request

Step 13: Get the Flow

Step 14: Submit Login Credentials

Step 15: Call the resume endpoint

Step 16: Get the access token

Test a SAML Application Connection

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

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

Prerequisites

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

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

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

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

  • A PingOne access token for each environment.

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

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

Workflow order of operations

To test the SAML application connection:

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

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

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

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

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

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

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

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

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

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

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

Execute the authentication flow

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Get the signing key for the source environment

Step 2: Get all environment IDs

Step 3: Create a SAML application in the source environment

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

Step 5: Create a certificate in the destination environment

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

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

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

Step 9: Create a sign-on policy action

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

Test an OIDC Application Connection

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

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

Prerequisites

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

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

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

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

  • A PingOne access token for each environment.

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

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

Execute the authentication flow

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1a: Create Source Environment

Step 1b: Create Destination Environment

Step 2: Create an OIDC application in the source environment

Step 3: Read the OIDC application secret

Step 4: Create OIDC provider in destination environment

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

Step 6: Create a sign-on policy action

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

Step 8: Create an OIDC application in the destination environment

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

Step 10: Send an authorization request

Authentication and Authorization

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

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

Configure a Simple Login

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a web application

Step 2: Get the application secret

Step 3: Create a sign-on policy

Step 4: Create the login sign-on policy action

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

Step 6: Create a population for simple login users

Step 7: Create a user

Step 8: Set user password

Step 9: Send an authorization request

Step 10: Get the flow

Step 11: Submit login credentials

Step 12: Call the resume endpoint

Step 13: Get the access token

Get an ID Token

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a single-page application

Step 2: Create a population

Step 3: Create user

Step 4: Set user password

Step 5: Send the authorize request

Step 6: Get the Flow

Step 7: Submit Login Credentials

Step 8: Call the resume endpoint

Add a User through a Registration Flow

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create an application

Step 2: Create a population for registered users

Step 3: Create the new sign-on policy

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

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

Step 6: Send the authorization request

Step 7: Get the flow

Step 8: Register a new user

Step 9: Verify user

Step 10: Get registered user

Use LOGIN and MFA Actions to Authenticate Users

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a web application

Step 2: Get all resources

Step 3: Get all OIDC Scopes

Step 4: Assign a resource grant to the web application

Step 5: Create a sign-on policy

Step 6: Create the login sign-on policy action

Step 7: Create the MFA sign-on policy action

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

Step 9: Create a population for MFA users

Step 10: Create a user

Step 11: Set user password

Step 12: Enable user MFA

Step 13: Set user device (SMS)

Step 14: Send an authorization request

Step 15: Get the flow

Step 16: Submit login credentials

Step 17: Check OTP

Step 18: Call the resume endpoint

Step 19: Get the application secret

Step 20: Get the access token

Configure a PKCE Authorization Workflow

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

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

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

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

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

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

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

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

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

Workflow tasks

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

  • Create an application and set its pkceEnforcement property.

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

  • Create a token request that includes the code_verifier secret.

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create the application connection

Step 2: Submit the authorize request

Step 3: Verify flow initialization

Step 4: Submit username and password

Step 5: Call the resume endpoint

Step 6: Get the token

Configure a Progressive Profiling Sign-On Action

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create an (OIDC) application

Step 2: Get the application secret

Step 3: Get the list of resources

Step 4: Get all scopes

Step 5: Create the resource access grant

Step 6: Create the new sign-on policy

Step 7: Create the login sign-on policy action

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

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

Step 10: Create a population for profile users

Step 11: Create a user

Step 12: Set user password

Step 13: Send an authorization request

Step 14: Get the flow

Step 15: Submit login credentials

Step 16: Update user profile

Step 17: Call the resume endpoint

Step 18: Get the access token

Step 19: Verify updated user information

Configure Device Authorization Grant Flow

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a custom application

Step 2: Create a population

Step 3: Create a user

Step 4: Set user password

Step 5: Authorize (device)

Step 6: Start device flow

Step 7: Get the flow

Step 8: Submit login credentials

Step 9: Confirm device user code

Step 10: Accept device authorization grant consent

Step 11: Get the access token

Use LOGIN and AGREEMENT Actions to Authenticate Users

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a web application

Step 2: Get the application secret

Step 3: Get languages

Step 4: Create an agreement

Step 5: Create an agreement language

Step 6: Create an ageement revision

Step 7: Update the agreement language

Step 8: Enable the agreement

Step 9: Create a sign-on policy

Step 10: Create the login sign-on policy action

Step 11: Create the agreement sign-on policy action

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

Step 13: Create a population for agreement users

Step 14: Create user

Step 15: Set user password

Step 16: Send an authorization request

Step 17: Get the flow

Step 18: Submit login credentials

Step 19: Consent to agreement

Step 20: Call the resume endpoint

Step 21: Get the access token

Get a Token for Custom Resource Access

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a web application

Step 2: Get the application secret

Step 3: Create a custom resource

Step 4: Create a custom resource scope

Step 5: Assign a resource grant to the web application

Step 6: Create a sign-on policy

Step 7: Create the login sign-on policy action

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

Step 9: Create a population

Step 10: Create a user

Step 11: Set user password

Step 12: Send an authorization request

Step 13: Get the flow

Step 14: Submit login credentials

Step 15: Call the resume endpoint

Step 16: Get the access token

Step 17: Token Introspection

Add a Custom Claim to an Access Token

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

The following operations are supported by the PingOne APIs:

  • Create an application
  • Create a custom resouce and scope
  • Create a resource attribute mapping
  • Initiate authorization and complete the authentication flow
  • Verify the custom claim in the access token

Prerequisites

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

Workflow order of operations

To add a custom claim to an access token, the following tasks must be completed successfully:

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

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

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a single-page application

Step 2: Create a custom resource

Step 3: Create a custom scope

Step 4: Create a resource attribute mapping

Step 5: Create the application's resource access grant

Step 6: Create a population

Step 7: Create user

Step 8: Set user password

Step 9: Send the authorize request

Step 10: Get the Flow

Step 11: Submit Login Credentials

Step 12: Call the resume endpoint

Configure CLIENT_SECRET_JWT as the token auth method

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

To configure this workflow, you must complete the following tasks:

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

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

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

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

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

  6. Make a GET request to /{{envID}}/as/authorize to submit the authorize request.

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run In Postman

Step 1: Create a web application

Step 2: Get the application secret

Step 3: Create a population

Step 4: Create user

Step 5: Set user password

Step 6: Send an authorize request

Step 7: Get the flow

Step 8: Submit login credentials

Step 9: Call the resume endpoint

Step 10: Get the access token

Use an authentication JWT for token fulfillment

This activity shows you how to use information from a source authentication JWT to add claims to the PingOne token. For more information about token fulfillment, see Use an authentication JWT for token fulfillment in the PingOne API Reference.

The following operations are supported by the PingOne APIs:

  • Create an application
  • Create a custom resource, a custom scope, and an attribute mapping
  • Create a user
  • Initiate an authorize request
  • Use flow APIs to complete the login
  • Submit a token request
  • Run the token introspection endpoint to view the claim added from the authentication JWT

Prerequisites

Get an access token from the worker application that you created in Getting Started with the PingOne APIs. 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 Worker Application Access Token.

Workflow order of operations

To configure this workflow, you must complete the following tasks:

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

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

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

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

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

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

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

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

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

  10. Make a GET request to /{{envID}}/as/authorize to submit the authorize request.

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

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

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

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

  15. To verify that the token includes the specified property from the authentication JWT, make a POST request to /{{envID}}/as/introspect to return the token claims.

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run In Postman

Step 1: Create a web application

Step 2: Get the application secret

Step 3: Create a custom resource

Step 4: Create a custom scope

Step 5: Create a resource attribute mapping

Step 6: Create the application's resource access grant

Step 7: Create a population

Step 8: Create user

Step 9: Set user password

Step 10: Send an authorize request

Step 11: Get the flow

Step 12: Submit login credentials

Step 13: Call the resume endpoint

Step 14: Get the access token

Step 15: Token Introspection

Exchange a Refresh Token

This activity shows you how to exchange a refresh token for a new access token.

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
  • Get the tokens
  • Use the token request to exchange the refresh token for a new access token

Prerequisites

Get an access token from the worker application that you created in Getting Started with the PingOne APIs. 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 Worker Application Access Token.

Workflow order of operations

To get a refresh token and use it to get a new access token, you must complete the following tasks:

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

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

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

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

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

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

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

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

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

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

  11. Make another POST request to /{{envID}}/as/token to exchange the refresh token generated in Step 10 for a new access token.

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a web application

Step 2: Get the application secret

Step 3: Create a population

Step 4: Create a user

Step 5: Set user password

Step 6: Send an authorization request

Step 7: Get the flow

Step 8: Submit login credentials

Step 9: Call the resume endpoint

Step 10: Get the tokens

Step 11: Exchange the refresh token

SAML Sign-On

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

The following operations are supported by the PingOne APIs:

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

  9. Make a POST request to /{{envID}}/saml20/idp/sso to obtain an authorization grant. This request starts the SAML authorization flow.

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

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

  12. Make a GET request to /{{envID}}/saml20/resume?flowId={{flowID}} to call the SAML resume endpoint and return an encoded SAMLResponse.

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a group

Step 2: Create a SAML application

Step 3: Create the sign-on policy

Step 4: Create the sign-on policy action

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

Step 6: Create a population

Step 7: Create a user

Step 8: Set user password

Step 9: Submit SAML sign-on request

Step 10: Get the flow

Step 11: Submit login credentials

Step 12: Call the SAML resume endpoint

Test an OAuth Connection using Identifier First Authentication

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

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

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

Prerequisites

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

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

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

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

  • A PingOne access token for each environment.

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

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

Workflow order of operations

To test an OAuth connection using the identifier first login flow, the following tasks must be completed successfully:

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

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

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

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

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

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

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

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

  9. Make a GET request to /environments/{{destinationEnvID}}/applications/{{oidcAppDestinationID}}/secret to read the application secret in the destination.

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

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

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

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run In Postman

Step 1: Create Source Environment

Step 2: Create Destination Environment

Step 3: Create an OIDC application in the source environment

Step 4: Read the OIDC application secret

Step 5: Create OIDC IdP in destination environment

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

Step 7: Create a sign-on policy action

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

Step 9: Create an application in the destination environment

Step 10: Read the application secret in destination

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

Step 12: Create a source population

Step 13: Create a destination population

Step 14: Create a source user

Step 15: Create a destination user

Step 16: Set source user password

Step 17: Set destination user password

Step 18: Send an authorization request

Step 19: Get the flow

Step 20: Sign on with a username

Step 21: Check password

Step 22: Call the resume endpoint

Step 23: Get the access token

Sign-on using an External Identity Provider

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

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

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

Prerequisites

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

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

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

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

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

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

Workflow order of operations

To test the external authentication flow to sign-on using an external identity provider, the following tasks must be completed successfully:

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

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

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

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

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

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

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

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

  9. Make a GET request to /environments/{{destinationEnvID}}/applications/{{oidcAppDestinationID}}/secret to read the application secret in the destination.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman.

Step 1a: Create Source Environment

Step 1b: Create Destination Environment

Step 2: Create an OIDC application in the source environment

Step 3: Read the OIDC application secret

Step 4: Create OIDC identity provider in destination environment

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

Step 6: Create a sign-on policy action

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

Step 8: Create an application in the destination environment

Step 9: Read the application secret in destination

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

Step 11: Create a source population

Step 12: Create a destination population

Step 13: Create a source user

Step 14: Create a destination user

Step 15: Set source user password

Step 16: Set destination user password

Step 17: Send an authorization request

Step 18: Read External Authentication Initialization

Step 19: Send external an authorization request to the IdP

Step 20: Get the flow for external identity provider

Step 21: Submit IdP credentials for external identity provider

Step 22: Call the resume endpoint for external identity provider

Step 23: Call the external authentication callback endpoint

Step 24: Get the flow for account linking

Step 25: Submit credentials for account linking

Step 26: Call the resume endpoint

Step 27: Get the access token

DaVinci

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

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

Configure a PingOne App to Use a DaVinci Flow Policy

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

DaVinci flow settings configuration

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

PingOne DaVinci flow

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

PingOne endpoints

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

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

To create the application and flow policy, the following tasks must be completed successfully:

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a PingOne web application

Step 2: Read all flow policies

Step 3: Create the flow policy assignment

Step 4: Send an authorization request

Configure a DaVinci Non-redirect Flow

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

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

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

DaVinci flow settings configuration

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

PingOne DaVinci flow

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

PingOne endpoints

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

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

To create the application and flow policy, the following tasks must be completed successfully:

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a PingOne web application

Step 2: Get the application secret

Step 3: Read all flow policies

Step 4: Create the flow policy assignment

Step 5: Create a population

Step 6: Create a user

Step 7: Send authorize request

Configure a PingOne DaVinci Flow with pi.flow

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

DaVinci flow settings configuration

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

PingOne DaVinci flow

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

PingOne endpoints

This activity shows you how to create a PingOne application, find and associate a DaVinci flow policy with the application, and initiate the flow using a PingOne authorize request. The authorize request sets the response_mode property to pi.flow, which tells the authorization server to return data (HTML and scripts), instead of a redirect URL.

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

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

To create the application and flow policy, the following tasks must be completed successfully:

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a PingOne web application

Step 2: Read all flow policies

Step 3: Create the flow policy assignment

Step 4: Send an authorization request

Configure a PingOne DaVinci Flow with pi.flow and ping-sdk

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

DaVinci flow settings configuration

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

PingOne DaVinci flow

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

PingOne endpoints

This activity shows you how to create a PingOne application, find and associate a DaVinci flow policy with the application, and initiate the flow using a PingOne authorize request. The authorize request sets the response_mode property to pi.flow, which tells the authorization server to return data, instead of a redirect URL. In addition, the authorize request sets the X-Requested-With HTTP header with a value of ping-sdk to return JSON instead of HTML (and scripts).

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

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

To create the application and flow policy, the following tasks must be completed successfully:

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a PingOne web application

Step 2: Read all flow policies

Step 3: Create the flow policy assignment

Step 4: Send an authorization request

Gateway Management

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

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

See the Gateways admin documentation for more information.

Create an LDAP Gateway

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

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

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

Prerequisites

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

Workflow order of operations

To create an LDAP gateway, the following tasks must be completed successfully:

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create the Password Policy

Step 2: Create a Population

Step 3: Create the LDAP Gateway

Step 4: Update the LDAP Gateway

Group Management

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

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

Create a Group and Add a User

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

Prerequisites

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

Workflow order of operations

To create a group and add a user, you must complete the following tasks:

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

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

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

  4. Make a POST request to /environments/{{envID}}/users/{{GroupUseCaseUserID}}/memberOfGroups to add the new user to the group.

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a group

Step 2: Create a population for users

Step 3: Create a user

Step 4: Add user to group

Step 5: Read all users in a group

Step 6: Read all group names for a user

Identity Propagation

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

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

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

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

Create a Workday Propagation Connection

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

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

This scenario illustrates the following common operations:

  • Create a propagation plan.

  • Create a propagation store.

  • Create a writeback propagation store (applicable only to Workday).

  • Create a propagation rule.

  • Create a writeback propagation rule (applicable only to Workday).

  • Create propagation rule mappings.

  • Create writeback propagation rule mappings (applicable only to Workday).

  • Create a new propagation revision.

Prerequisites

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

Workflow order of operations

To create a Workday inbound propagation connection, you will need to complete the following tasks:

  1. Make a POST request to /environments/{{envID}}/passwordPolicies to create a password policy for the population of users to synchronize with Workday.

  2. Make a POST request to /environments/{{envID}}/populations to create a population of users to synchronize with Workday.

  3. Make a POST request to /environments/{{envID}}/propagation/plans to create a Workday propagation plan.

  4. Make a POST request to /environments/{{envID}}/propagation/stores to create a Workday inbound source propagation store with a type of Workday.

  5. Make a POST request to /environments/{{envID}}/propagation/stores to create a Workday inbound target propagation store with a type of PingOne.

  6. Make a POST request to /environments/{{envID}}/propagation/stores to create a Workday writeback source propagation store of type directory (applicable only to Workday). No separate writeback target propagation store is required, the target is the Workday inbound source propagation store.

  7. Make a POST request to /environments/{{envID}}/propagation/plans/{{planID}}/rules to create a Workday propagation rule for mapping Workday attributes to PingOne attributes.

  8. Make a POST request to /environments/{{envID}}/propagation/plans/{{planID}}/rules to create a Workday propagation rule for mapping directory attributes to Workday attributes (applicable only to Workday).

  9. Make a POST request to /environments/{{envID}}/propagation/rules/{{ruleID}}/mappings to create a Workday inbound propagation rule mapping that associates a specific Workday attribute to a specific PingOne attribute.

  10. Make a POST request to /environments/{{envID}}/propagation/plans/{{ruleID}}/rules to create a Workday writeback propagation rule mapping that associates a specific directory attribute to a specific Workday attribute (applicable only to Workday).

  11. Make a GET request to /environments/{{envID}}/propagation/rules/{{ruleID}}/mappings to verify Workday inbound propagation rule mappings of attributes between Workday and PingOne.

  12. Make a GET request to /environments/{{envID}}/propagation/rules/{{ruleID}}/mappings to verify Workday writeback propagation rule mappings of attributes between directory and Workday (applicable only to Workday).

  13. Make a GET request to /environments/{{envID}}/propagation/rules to verify the Workday inbound propagation rule between Workday and PingOne and the Workday writeback propagation rule between directory and Workday (applicable only to Workday).

  14. Make a GET request to /environments/{{envID}}/propagation/stores to verify Workday propagation stores of types Workday, PingOne, and directory.

  15. Make a GET request to /environments/{{envID}}/propagation/plans to verify Workday propagation plans.

  16. Make a POST request to /environments/{{envID}}/propagation/revisions to create a new propagation revision to ensure all operations are reflected in the PingOne Admin Console.

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a password policy for the Workday population

Step 2: Create a population to synchronize with Workday

Step 3: Create a Workday inbound propagation plan

Step 4: Create a Workday inbound source propagation store

Step 5: Create a PingOne inbound target propagation store

Step 6: Create a directory writeback source propagation store

Step 7: Create a Workday inbound propagation rule

Step 8: Create a Workday writeback propagation rule

Step 9: Create a Workday inbound propagation rule mapping

Step 10: Create a Workday writeback propagation rule mapping

Step 11: Read inbound propagation rule mappings to verify

Step 12: Read writeback propagation rule mappings to verify

Step 13: Read all propagation rules to verify

Step 14: Read all propagation stores to verify

Step 15: Read all propagation plans to verify

Step 16: Create a new propagation revision

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

Identity Providers

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

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

Configure Facebook as an Identity Provider

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

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

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

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

Prerequisites

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

Workflow order of operations

To create a sign-on policy that specifies Facebook as a supported external identity provider, the following tasks must be completed successfully:

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

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

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

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

  5. Make a POST request to /environments/{{envID}}/signOnPolicies/{{policyID}}/actions to create a new LOGIN sign-on policy action, which is associated with the new sign-on policy.

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create the new identity provider resource

Step 2: Create an optional attribute mapping

Step 3: Create a population for Facebook users

Step 4: Create the new sign-on policy

Step 5: Create the sign-on policy action

Step 6: Create an application

Step 7: Get the list of resources

Step 8: Get all scopes

Step 9: Create the application's resource access grant

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

Step 11: Send an authorization request

Configure a SAML Identity Provider

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

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

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

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

Prerequisites

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

Workflow order of operations

To create a sign-on policy that supports a SAML external identity provider, the following tasks must be completed successfully:

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

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

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

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

  5. Make a POST request to /environments/{{envID}}/signOnPolicies/{{policyID}}/actions to create a new LOGIN sign-on policy action, which is associated with the new sign-on policy.

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

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

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

Step 2: Create the new identity provider resource

Step 3: Create a population for SAML users

Step 4: Create the new sign-on policy

Step 5: Create the sign-on policy action

Integration Catalog

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

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

Download an Integration Binary

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

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

This scenario illustrates the following common operations:

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

Prerequisites

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

Workflow order of operations

To download a specific integration binary, you will need to complete the following tasks:

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Get the environment ID

Step 2: Get a list of integrations

Step 3: Get a list of integration versions

Step 4: Download the integration zip file

Metrics

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

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

Audit for Agreement Consents

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

The following operations are supported by the PingOne APIs:

  • Use the audit activities endpoint to run a metrics query to return consent agreement history for a specified agreement.
  • Use the audit activities endpoint to run a metrics query to return consent agreement history for a specified user.

Prerequisites

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

Workflow order of operations

To complete a metrics query to return consent agreement history for a specified agreement and user, the following tasks must be completed successfully:

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

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:

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a web application

Step 2: Get all resources

Step 3: Get all OIDC scopes

Step 4: Assign a resource grant to the web application

Step 5: Create an MFA sign-on policy

Step 6: Create a sign-on policy MFA action

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

Configure a Passwordless Sign-On Policy

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

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

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

Prerequisites

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

Workflow order of operations

To create a sign-on policy that does not prompt for a password at login, the following tasks must be completed successfully:

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create an application

Step 2: Create the new sign-on policy

Step 3: Create the sign-on policy action

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

Step 5: Test authentication

Configure an MFA-Only Flow Using a Login Hint Token

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

To complete an MFA only authentication flow, the following tasks must be completed successfully:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a web application

Step 2: Get the application secret

Step 3: Get all resources

Step 4: Get all OIDC Scopes

Step 5: Assign a resource grant to the web application

Step 6: Create a sign-on policy

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

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

Step 9: Create a population for MFA users

Step 10: Create user

Step 11: Set user password

Step 12: Enable user MFA

Step 13: Create the device authentication policy

Step 14: Set user device (SMS)

Step 15: Send authorize request

Step 16: Check OTP

Step 17: Call the resume endpoint

Create an MFA Transaction Approval using SMS

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

To complete a transaction approval MFA authentication flow, the following tasks must be completed successfully:

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

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

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

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

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

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

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

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

  9. Make a POST request to /environments/{{envID}}/templates/transaction/contents to create a transaction notification template.

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a web application

Step 2: Get the application secret

Step 3: Get all resources

Step 4: Get all OIDC Scopes

Step 5: Assign a resource grant to the web application

Step 6: Create a sign-on policy

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

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

Step 9: Create a transaction SMS template

Step 10: Create a population for MFA users

Step 11: Create user

Step 12: Set user password

Step 13: Enable user MFA

Step 14: Create the device authentication policy

Step 15: Set user device (SMS)

Step 16: Send authorize request for transaction approval

Step 17: Check OTP

Step 18: Call the resume endpoint

Step 19: Get the access token

Use an Email MFA Action to Authenticate Users

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  16. To complete the sign-on action, make a POST request to GET /{{envID}}/flows/{{flowID}} and provide the user's username for a user lookup action.

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a web application

Step 2: Get all resources

Step 3: Get all OIDC Scopes

Step 4: Assign a resource grant to the web application

Step 5: Create a sign-on policy

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

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

Step 8: Create a population for MFA users

Step 9: Create a user

Step 10: Set user password

Step 11: Enable user MFA

Step 12: Create the device authentication policy

Step 13: Set user device (Email)

Step 14: Send an authorization request

Step 15: Get the flow

Step 16: Sign on with a username

Step 17: Check OTP for Email

Step 18: Call the resume endpoint

Step 19: Get the application secret

Step 20: Get the access token

Configure an MFA Sign-On Policy with an Authenticator App

This activity shows you how to define a native application, create an MFA sign-on policy that enables MFA using an authenticator application, 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 and specify its sign-on policy:

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace. Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create a native application

Step 2: Get all resources

Step 3: Get all OIDC Scopes

Step 4: Assign a resource grant to the 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 application

Create and Update Notification Content

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

Prerequisites

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

Workflow order of operations

To create and update content for different types of notifications:

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

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

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

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

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

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

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

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

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

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

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

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Read all notification templates

Step 2: Create email notification content

Step 3: Update email notification content

Step 4: Create SMS notification content

Step 5: Update SMS notification content

Step 6: Create voice notification content

Step 7: Update voice notification content

Step 8: Create push notification content

Step 9: Update push notification content

Step 10: Read all general template notification content

Step 11: Read only push notification content

Password Policies

Password policies are associated with an environment, and are implemented on populations in the environment. 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
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).
Users A user has a unique identity within PingOne. Users are associated with an environment and a population.
User Passwords Operations supporting user passwords.

See the Managing Password Policies admin documentation for more information.

Create a Password Policy

You can use password policies to create policies for specific user populations in an environment.

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

  • Create a password policy that will be applied to a population.
  • Create a population to which the password policy is applied.
  • Create a user in the population.
  • Set an initial password for the new user. The password must be changed when the user first signs on.
  • Enable the user to update the password.

Workflow order of operations

To create and apply a password policy, you'll need to:

  1. Make a POST request to {{apiPath}}/environments/{{envID}}/passwordPolicies to create the password policy you'll use.

  2. Make a POST request to {{apiPath}}/environments/{{envID}}/populations to create a population for which you'll apply the password policy. You'll specify the password policy you created as the password policy for this population.

  3. Make a POST request to {{apiPath}}/environments/{{envID}}/users to create a user, assigning the user to the population you created.

  4. Make a PUT request to {{apiPath}}/environments/{{envID}}/users/{{userID}}/password to set an initial password for the new user.

  5. Make another PUT request to {{apiPath}}/environments/{{envID}}/users/{{userID}}/password, this time enabling the new user to specify their password.

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create Password Policy

Step 2: Create Population

Step 3: Create User

Step 4: Update Password (Set)

Step 5: Update Password (Self)

PingOne Authorize

These tasks show you how to use the PingOne Authorize APIs to enable fine-grained, attribute-based, dynamic authorization decisioning capabilities. PingOne Authorize use cases call the following API resources:

Platform API Description
Policy Decision Service Decision endpoints that allow efficient evaluation of policies developed in the PingOneAuthorize Policy Editor Service.
API Access Management The API access management service provides tools to externalize the management and evaluation of access control policies for HTTP-based APIs.
Resources Resources are the protected endpoints that applications request access to using OAuth 2 authorization services.
Application Resources and Roles The application resources and roles service provides endpoints to define custom roles and permissions within PingOne to protect external application resources.

Show PingOne Authorize App Permissions in Token

This activity shows you how to create a custom resource and how to use PingOne Authorize endpoints to create application roles and permissions to associate with the custom resource. The custom resource configuration includes a setting to show application permissions as a claim in the access token.

The following operations are supported by the PingOne APIs:

  • Create an application
  • Create a custom resource
  • Create PingOne Authorize application resources, roles, and permissions
  • 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 show application permissions in the access token

Prerequisites

  • You must have the PING_ONE_AUTHORIZE capability in the Bill of Materials (BOM) for your environment to run the PingOne Authorize requests to create application resources, application roles, and application permissions.

  • 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 get an access token for the custom resource, the following tasks must be completed successfully:

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

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

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

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

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

  6. Make a POST request to /environments/{{envID}}/resources/{{customResourceID}}/applicationResources to create the application resource.

  7. Make a POST request to /environments/{{envID}}/applicationResources/{{appResourceID}}/permissions to create the application resource permission.

  8. Make a POST request to /environments/{{envID}}/applicationRoles to create an application role.

  9. Make a POST request to /environments/{{envID}}/applicationRoles/{{appRoleID}}/permissions to assign an application resource permission to the specified role.

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

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

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

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

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

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

  16. Make a POST request to /environments/{{envID}}/users/{{customResourceUserID}}/applicationRoles to assign the application role to a user.

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

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

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

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

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

  22. To verify that the token includes the application permissions, make a POST request to GET /{{envID}}/as/introspect to view the application permission claim in the token.

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run In Postman

Step 1: Create a web application

Step 2: Get the application secret

Step 3: Create a custom resource

Step 4: Create a custom resource scope

Step 5: Assign a resource grant to the web application

Step 6: Create an application resource

Step 7: Create application permissions

Step 8: Create an application role

Step 9: Create application role permissions

Step 10: Create a sign-on policy

Step 11: Create the login sign-on policy action

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

Step 13: Create a population

Step 14: Create a user

Step 15: Set user password

Step 16: Assign the application role to user

Step 17: Send an authorization request

Step 18: Get the flow

Step 19: Submit login credentials

Step 20: Call the resume endpoint

Step 21: Get the access token

Step 22: Token Introspection

Create and Assign App Roles

This activity shows you how to create and assign application roles to users, which helps to simplify managing application permissions.

Application permissions are used to protect application resources, and can be thought of as the actions that can be taken on a resource. Application roles are associated with application permissions, and can be assigned to users to determine which actions they can perform on an application resource.

In this activity, you'll create a custom resource and use the PingOne Authorize Endpoint to create an application permission and application role. You'll then assign the application role to a user.

The following operations are supported by the PingOne APIs:

  • Create an application
  • Create a custom resource
  • Create PingOne Authorize application resources, roles, and permissions
  • Create user application role assignments

Prerequisites

  • You must have the PING_ONE_AUTHORIZE capability in the Bill of Materials (BOM) for your environment to run the PingOne Authorize requests to create application resources, application roles, and application permissions.

  • Create a user to get a userID. See Create User or Read All Users to find an existing user. A userID is needed to assign an application role to a user in this activity.

  • 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 create application permissions, application roles, and assign application roles to a user, the following tasks must be completed successfully:

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

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

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

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

  5. Make a POST request to /environments/{{envID}}/resources/{{customResourceID}}/applicationResources to create the application resource.

  6. Make a POST request to /environments/{{envID}}/applicationResources/{{appResourceID}}/permissions to create the application resource permission.

  7. Make a POST request to /environments/{{envID}}/applicationRoles to create an application role.

  8. Make a POST request to /environments/{{envID}}/applicationRoles/{{appRoleID}}/permissions to assign an application resource permission to the specified role.

  9. Make a POST request to /environments/{{envID}}/users/{{userID}}/applicationRoles to assign the application role to a user.

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run In Postman

Step 1: Create a web application

Step 2: Create a custom resource

Step 3: Create a custom resource scope

Step 4: Assign a resource grant to the web application

Step 5: Create an application resource

Step 6: Create application permissions

Step 7: Create an application role

Step 8: Create application role permissions

Step 9: Assign the application role to user

Risk Management

These tasks show you how to use the platform APIs to perform common actions for managing risk policies. Risk policy use cases often call the following platform API resources:

Platform API Description
Risk Policies The risk policies service implements directory functions to manage risk policy resources.
Risk Evaluations Risk evaluations provides operations to retrieve risk evaluations from internal and external risk providers based on a specified risk policy.

Create a Risk Policy Set

This activity shows you how to create a new risk policy. This scenario illustrates the following common operations supported by the PingOne APIs:

  • Get the environment ID
  • Create a risk policy set by defining one or more risk policies

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 new risk policy set, the following tasks must be completed successfully:

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

  2. Make a POST request to /environments/{{envID}}/riskPolicies to create a new risk policy set resource.

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Policy set logic

A risk policy set must have at least one defined risk policy, which includes the following components:

  • Condition. The policy logic to define when the policy is evaluated to true and when it is evaluated to false.

  • Result. The policy logic to define what should be returned in case the condition is evaluated to true.

  • Priority. (Optional) A priority ranking to define the execution order of the different risk policies contained in the policy set.

For this use case, you will define a simple risk policy set that includes two risk policies: A whitelist that evaluates risk based on the user's IP address, and an anonymous network detection check.

The following JSON shows the elements defined in the whitelist risk policy. The condition.contains expression uses the ${transaction.ip} condition variable to get the user's IP address and compare it to a range of IP addresses that are considered safe. If the user's IP address is within the range set in condition.ipRange, the condition evaluates to true, and the result.level is set to LOW, indicating low risk for this policy condition.

	"riskPolicies": [
		{
			"name": "WHITELIST",
            "priority": 1,
			"result": {
				"level": "LOW"
			},
			"condition": {
				"contains": "${transaction.ip}",
				"ipRange": [
					"1.1.1.1/16",
					"2.2.2.2/24"
				]
			}
		}
    ]

The following JSON shows the elements defined in the anonymous network detection risk policy. The condition.contains expression uses the ${details.anonymousNetworkDetected} condition variable to to determine whether the user is attempting to authenticate from an anonymous network. If the condition.value evaluates to true, then the result.level is set to HIGH, indicating that this is a high-risk transaction.

     ...
            "name": "ANONYMOUS_NETWORK_DETECTION",
            "priority": 2,
            "result": {
                "level": "HIGH",
                "type": "VALUE"
            },
            "condition": {
                "equals": true,
                "value": "${details.anonymousNetworkDetected}"
            },

For more information about risk policies, see Risk Policies.

Step 1: Get the environment ID

Step 2: Create a risk policy set

Create a Risk Evaluation

This activity shows you how to create a new risk evaluation. This scenario illustrates the following common operations supported by the PingOne APIs:

  • Get a list of risk policy set resources
  • Create a risk evaluation resource that uses a specific risk policy set

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 new risk evaluation, the following tasks must be completed successfully:

  1. Make a GET request to /environments/{{envID}}/riskPolicies to return the list of risk policy set resources associated with the environment.

  2. Make a POST request to /environments/{{envID}}/riskEvaluations to create a new risk evaluation resource that references a risk policy set resource.

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Defining the risk evaluation resource

For the POST request to /environments/{{envID}}/riskEvaluations, the risk evaluation resource definition lets you specify the risk policy set to apply to the evaluation. If a particular risk policy set is not specified, the risk evaluation uses the environment's default risk policy set to determine the risk levels for the event. In this use case, the risk evaluation sets theriskPolicySet.id property to the {{riskPolicySetID}} Postman variable, which should contain the ID of the risk policy set that you created in the USE CASE: Create a risk policy set activity.

The risk evaluation definition must include an event object that specifies details about the authentication action to evaluate against the risk policies defined in the risk policy set. In its most basic form, the event object defines a user (user.id and user.type) and an IP address (ip). From this information, the risk evaluation can provide a meaningful risk response for all supported risk predictors (anonymousNetwork, ipRisk, geoVelocity, userRiskBehavior) except the user risk behavior predictor, which requires the targetResource and UserAgent properties. For more information about the risk evaluation event data model, see Risk Evaluations in the PingOne API Reference.

The risk evaluation process follows these steps:

  1. The risk service receives an event that it is configured to monitor and evaluate.

  2. A risk calculation is made for the event based on the configured risk policies.

  3. The risk service returns the risk result to the client.

Step 1: Get risk policy set IDs

Step 2: Create a risk evaluation

User Management

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

Platform API Description
Roles Roles determine which actions a user is allowed to perform.
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.

Assign a Role to a User

Roles determine what actions a user can perform. For example, to generate a client secret, a user must be assigned the Environment Admin role.

The PingOne roles are:

Role Icon Abbr.
Organization Admin Organization Admin role ORG
Environment Admin Environment Admin role ENV
Identity Data Admin Identity Data Admin role IDA
DaVinci Admin DaVinci Admin role DVA
Custom Role Admin Custom Role Admin role ROLE
Application Owner Application Owner role APP-O
Identity Data Read-Only Admin Identity Data Read Only role IDA-R
Configuration Read-Only Admin Configuration Read Only role CFA-R
DaVinci Read-Only Admin DaVinci Admin Read Only role DVA-R
Client Application Developer Client Application Developer role APP

For permissions associated with each role, see PingOne Role Permissions.

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.

  • An existing user to assign the role to.

Workflow order of operations

To assign a role to a user, complete the following tasks:

  1. Make a GET request to {{apiPath}}/environments/{{envID}}/users to get the ID of the user.

  2. Make a GET request to {{apiPath}}/roles to get the ID of the role to assign.

  3. Make a POST request to {{apiPath}}/environments/{{envID}}/users/{{userID}}/roleAssignments to create the user role assignment.

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Get the user ID

Step 2: Get the role ID

Step 3: Create the user role assignment

Add User Image

This activity shows you how to update the user image for an existing user.

The following operations are supported by the PingOne APIs:

  • Create a user
  • Create an image
  • Update the user profile

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.
  • Run Read all populations to find a population ID value. You will use this value to create a user in step 1.
  • Download an image file (maximum size 2 MB) to your machine. You will attach this image to the request in step 2.

Workflow order of operations

To upload and assign a user image, complete the following tasks:

  1. Make a POST request to /environments/{{envID}}/users to create a user.
  2. Make a POST request to /environments/{{envID}}/images to upload an image to your PingOne environment.
  3. Make a PATCH request to /environments/{{envID}}/users/{{userID}} to assign the image to a user profile.

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Create User

Step 2: Create Image

Step 3: Update User

Find and Terminate a User Session

This activity shows you how to find and terminate a user session.

The following operations are supported by the PingOne APIs:

  • Read a user session
  • Delete a user session

Prerequisites

Workflow order of operations

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

  1. Make a GET request to /environments/{{envID}}/users/{{SimpleLoginUserID}}/sessions to locate the current user session.

  2. Make a DELETE request to /environments/{{envID}}/users/{{SimpleLoginUserID}}/sessions/{{UserSessionID}} to terminate the current user session.

  3. Make a GET request to /environments/{{envID}}/users/{{SimpleLoginUserID}}/sessions to verify no sessions are found.

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Read the current user session

Step 2: Delete the user session

Step 3: Verify there are no active sessions

Sign-Off User Session

This activity shows you how to create the PingOne signoff flow. This flow ends the user's SSO session, which signs them out of all applications using that session.

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

  • Get a user session.

  • Terminate the user's current session.

Prerequisites

  • Create a test user and activate a user session. Complete the Configure a Simple Login use case to open an active user session.

Workflow order of operations

To end a user's active session, complete the following tasks:

  1. Make a GET request to /environments/{{envID}}/users/{{userID}}/sessions to verify the active user session.

  2. Make a GET request to /{{envID}}/as/signoff to terminate the user session.

We highly recommend that you use our Postman collection for this workflow. For information about using Postman environments, see The PingOne Postman Environment Template.

Click the Run in Postman button below to fork, or download and import, the Postman collection for this workflow to your workspace.

Run in Postman

Step 1: Get user sessions

Step 2: Sign-off user session

Downloading PingOne workflow collections

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

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

Using the PingOne Postman environment

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

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

  • {{tld}}

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

  • {{apiPath}}

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

  • {{authPath}}

    The domain for the PingOne authentication server.

  • {{orchestratePath}}

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

  • {{scimPath}}

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

  • {{envID}}

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

  • {{accessToken}}

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