PingOne How-to Guides

The PingOne platform How-to guides describe the workflows used for common PingOne use cases, both for the platform and its services. Each use case is configured as a Postman collection, and includes a Run in Postman button, enabling you to load the use case collection in your Postman workspace.

Configuring and managing Postman

Before you begin using the Postman collections linked to PingOne use cases, you must configure your Postman preferences to not follow redirects automatically. Several PingOne use cases, particularly those that involve an authorize request, an authentication flow, and a redirect back to the authorization server, 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 in Postman:

  1. Open your Postman application, and under the Postman menu, click Preferences.

  2. On the Settings screen, click the General tab, if it is not already open.

  3. Under the Headers column, set the Automatically follow redirects setting to OFF.

Postman Settings

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

Removing session cookies in Postman

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

Before you run any use cases, it is recommended that you remove all old session token cookies from Postman. To remove cookies:

  1. Open the Step 1 request for the use case you want to run.

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

  3. On the Manage Cookies screen, 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.

Using a Postman environment

The PingOne use case collections include test scripts that write variables and their current values to your active Postman environment for the newly created PingOne resources. To save and use these resource IDs, you should specify a Postman environment and have the following Postman environment variables set before you begin:

  • {{tld}}

    The top level domain for your region: com, ca, eu, com.au, sg, or asia. 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. Options are: https://api.pingone.com/v1 for environments the North America region, https://api.pingone.ca/v1 for environments in the Canada region, https://api.pingone.eu/v1 for environments in the European Union region, https://api.pingone.com.au/v1 for environments in the Australia region, https://api.pingone.sg/v1 for environments in the Singapore region, and https://api.pingone.asia/v1 for environments in the Asia-Pacific region.

  • {{authPath}}

    The domain for the PingOne authentication server. Options are: https://auth.pingone.com/v1 for environments the North America region, https://auth.pingone.ca/v1 for environments in the Canada region, https://auth.pingone.eu/v1 for environments in the European Union region, https://auth.pingone.com.au/v1 for environments in the Australia region, https://auth.pingone.sg/v1 for environments in the Singapore region, and https://auth.pingone.asia/v1 for environments in the Asia-Pacific region.

  • {{orchestratePath}}

    The regional domain (and part of the path) for the PingOne DaVinci server. Options are: https://orchestrate-api.pingone.com/v1 for environments the North America region, https://orchestrate-api.pingone.ca/v1 for environments in the Canada region, https://orchestrate-api.pingone.eu/v1 for environments in the European Union region, https://orchestrate-api.pingone.com.au/v1 for environments in the Australia region, https://orchestrate-api.pingone.sg/v1 for environments in the Singapore region, and https://orchestrate-api.pingone.asia/v1 for environments in the Asia-Pacific region.

  • {{scimPath}}

    The regional domain (and part of the path) for the PingOne SCIM server. Options are: https://scim-api.pingone.com/v1 for environments the North America region, https://scim-api.pingone.ca/v1 for environments in the Canada region, https://scim-api.pingone.eu/v1 for environments in the European Union region, https://scim-api.pingone.com.au/v1 for environments in the Australia region, https://scim-api.pingone.sg/v1 for environments in the Singapore region, and https://scim-api.pingone.asia/v1 for environments in the Asia-Pacific region.

  • {{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 Getting Started with the PingOne APIs.

Downloading the PingOne Postman environment template

If you download and import any of the PingOne master postman collections into Postman (see Download the PingOne Postman collections), the collection import includes a PingOne Postman environment template automatically. You can use this Postman environment with the use case collections, or any Postman environment you have created previously that includes values for the variables listed above.

For more information about the PingOne Postman environment template, see Use the PingOne Postman environment template.

Authorization and Authentication

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.

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

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/{environmentId}/applications to add a new application to the specified environment.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Run in Postman

Step 1: Create a web application

Step 2: Get all resources

Step 3: Get all OIDC Scopes

Step 4: Assign a resource grant to the web application

Step 5: Create a sign-on policy

Step 6: Create the login sign-on policy action

Step 7: Create the MFA sign-on policy action

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

Step 9: Create a population for MFA users

Step 10: Create a user

Step 11: Set user password

Step 12: Enable user MFA

Step 13: Set user device (SMS)

Step 14: Send an authorization request

Step 15: Get the flow

Step 16: Submit login credentials

Step 17: Check OTP

Step 18: Call the resume endpoint

Step 19: Get the application secret

Step 20: Get the access token

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

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/{environmentId}/applications to add a new application to the specified environment.

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

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

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

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

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

  7. Make a GET request to /{environmentId}/flows/{flowId} to get the flow.

  8. Make a POST request to /{environmentId}/flows/{flowId} to register the new user.

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

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

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

Run in Postman

Step 1: Create an application

Step 2: Create a population for registered users

Step 3: Create the new sign-on policy

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

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

Step 6: Send the authorization request

Step 7: Get the flow

Step 8: Register a new user

Step 9: Verify user

Step 10: Get users

Configure a PKCE authorization workflow

In some cases, as with native 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 /{environmentId}/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.

Workflow order of operations

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

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

  2. Make a GET request to /{environmentId}/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 /{environmentId}/as/token to exchange the authorization code returned by the resume endpoint for an access token.

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

Run in Postman

Step 1: Create the application connection

Step 2: Submit the authorize request

Step 3: Verify flow initialization

Step 4: Submit username and password

Step 5: Call the resume endpoint

Step 6: Get the token

Configure a Progressive Profiling Sign-On Action

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

The following operations are supported by the PingOne APIs:

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

Workflow order of operations

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

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

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

  3. Make a GET request to /environments/{environmentId}/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/{environmentId}/resources/{resourceId}/scopes to list all scopes associated with a specified resource (the PingOne platform resource).

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

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

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

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

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

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

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

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

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

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

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

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

  17. Make a GET request to /{environmentId}/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 /{environmentId}/as/token to exchange the auth code for an access token.

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

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

Run in Postman

Step 1: Create an (OIDC) application

Step 2: Get the application secret

Step 3: Get the list of resources

Step 4: Get all scopes

Step 5: Create the resource access grant

Step 6: Create the new sign-on policy

Step 7: Create the login sign-on policy action

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

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

Step 10: Create a population for profile users

Step 11: Create a user

Step 12: Set user password

Step 13: Send an authorization request

Step 14: Get the flow

Step 15: Submit login credentials

Step 16: Update user profile

Step 17: Call the resume endpoint

Step 18: Get the access token

Step 19: Verify updated user information

Configure a Progressive Profiling Form Sign-On Action

This activity shows you how to use the PROGRESSIVE_PROFILING_FORM sign-on policy action to create a sign-on policy with a form-based 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 form sign-on policy actions
  • Create a user
  • Initiate an authorize request
  • Use flow APIs to login the user and add a nickname
  • Verify the addition of a nickname to the user record

Workflow order of operations

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

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

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

  3. Make a GET request to /environments/{environmentId}/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/{environmentId}/resources/{resourceId}/scopes to list all scopes associated with a specified resource (the PingOne platform resource).

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

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

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

  8. Make a POST request to /environments/{environmentId}/forms to define the progressive profiling form to associate with the progressive profiling form sign-on action.

  9. Make a POST request to /environments/{environmentId}/signOnPolicies/{signOnPolicyId}/actions to define the progressive profiling form action to associated with this sign-on policy.

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

  11. Make a POST request to /environments/{id}/populations to create a new population resource.

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

  13. Make a POST request to /environments/{id}/users/{userId}/password to set the new user's password.

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

  15. Make a GET request to /{environmentId}/flows/{flowID} to initiate the flow.

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

  17. To complete the progressive profiling form action, make a POST request to GET /{environmentId}/flows/{flowID} and provide the user's nickname.

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

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

  20. Make a GET request to /environments/{environmentId}/users/{userId} to view the updated information about the identified user.

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

Run in Postman

Step 1: Create an (OIDC) application

Step 2: Get the application secret

Step 3: Get the list of resources

Step 4: Get all scopes

Step 5: Create the application’s resource access grant

Step 6: Create the new sign-on policy

Step 7: Create the login sign-on policy action

Step 8: Create a progressive profiling form

Step 9: Create the progressive profile form sign-on policy action

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

Step 11: Create a population for profile form users

Step 12: Create the user

Step 13: Set user password

Step 14: Send an authorization request

Step 15: Get the flow

Step 16: Submit login credentials

Step 17: Profile form submit

Step 18: Call the resume endpoint

Step 19: Get the access token

Step 20: Verify updated user information

Add a user through a registration form

This activity shows you how to use the flow manager APIs to create a registration form, a flow definition, and a sign-on policy that references the flow definition to create and verify a new user account.

The following operations are supported by the PingOne APIs:

  • Create an application
  • Create a registration form
  • Create a flow definition for the registration form
  • Create a sign-on policy
  • Initiate an authorize request
  • Use flow execution APIs to create a new user
  • Use flow execution APIs to verify the new user
  • Get an access token

Workflow order of operations

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

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

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

  3. Make a POST request to /environments/{environmentId}/forms to create the registration form.

  4. Make a POST request to /environments/{environmentId}/flowDefinitions to create the flow definitions and flow steps.

  5. Make a POST request to /environments/{environmentId}/signOnPolicies to create a new sign-on policy that references the flow definition resource.

  6. Make a POST request to /environments/{environmentId}/signOnPolicies/{signOnPolicyId}/actions to define the registration form action associated with this sign-on policy.

  7. Make a POST request to /environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments to associate the registration form sign-on policy with the application.

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

  9. Make a GET request to /{environmentId}/flows/{flowId} to get the flow.

  10. Make a POST request to /{environmentId}/experiences/{flowDefinitionID} to trigger flow execution.

  11. Make a POST request to /{environmentId}/flowExecutions/{flowExecutionID} to submit the form.

  12. Make a POST request to /{environmentId}/flowExecutions/{flowExId} to verify the new user account.

  13. Make a GET request to /{environmentId}/flows/{flowId}/flowExecutionCallback?flowExecutionId={flowExID} to return to the flow.

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

  15. Make a GET request to /environments/{environmentId}/applications/{appplicationId}/secret to get the application secret.

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

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

Run in Postman

Step 1: Create an application

Step 2: Create a population for registration form users

Step 3: Create a registration form

Step 4: Create a flow definition for registration

Step 5: Create the new sign-on policy

Step 6: Create the sign-on policy action with registration flow definition

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

Step 8: Send the authorization request

Step 9: Get the flow

Step 10: Trigger the flow execution

Step 11: Submit the form

Step 12: Verify the account

Step 13: Call the flow execution callback endpoint

Step 14: Call the resume endpoint

Step 15: Get the application secret

Step 16: Get the access token

This activity shows you how to use a flow definition with an EXPERIENCE trigger type to register a new user. This registration flow does not require a PingOne sign-on policy. It can be initiated from a link on a web application, and after the new user is created, the flow redirects back to the web application.

The following operations are supported by the PingOne APIs:

  • Create an application
  • Create a registration form
  • Create a flow definition for the registration form
  • Use flow execution APIs to create a new user
  • Use flow execution APIs to verify the new user

Workflow order of operations

To create a new user using a flow definition with an EXPERIENCE trigger, the following tasks must be completed successfully:

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

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

  3. Make a POST request to /environments/{environmentId}/forms to create the registration form.

  4. Make a POST request to /environments/{environmentId}/flowDefinitions to create the flow definition and flow steps.

  5. Make a POST request to /{environmentId}/experiences/{flowDefinitionID} to trigger flow execution.

  6. Make a POST request to /{environmentId}/flowExecutions/{flowExecutionID} to submit the form.

  7. Make a POST request to /{environmentId}/flowExecutions/{flowExecutionID} to verify the new user account.

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

Run in Postman

Step 1: Create an application

Step 2: Create a population for registration form users

Step 3: Create a registration form

Step 4: Create a flow definition for registration

Step 5: Trigger the flow execution

Step 6: Submit the form

Step 7: Verify the account

This activity shows you how to use the login and agreement consent steps in a flow definition with an EXPERIENCE trigger type. This flow does not require a PingOne sign-on policy. It can be initiated from a browser link in a web application, and after the user logs in and accepts the consent agreement, the flow redirects back to the web application.

The following operations are supported by the PingOne APIs:

  • Create an application
  • Create a login form
  • Create a flow definition for the login and consent actions
  • Use flow execution APIs to submit user login credentials
  • Use flow execution APIs to create the consent agreement

Workflow order of operations

To authenticate a user and prompt for consent, the following tasks must be completed successfully:

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

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

  3. Make a POST request to /environments/{environmentId}/agreements to create a new agreement.

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

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

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

  7. Make a PUT request to /environments/{environmentId}/agreements/{agreementID} to enable the agreement.

  8. Make a POST request to /environments/{environmentId}/forms to create the login form.

  9. Make a POST request to /environments/{environmentId}/flowDefinitions to create the flow definition.

  10. Make a POST request to /environments/{environmentId}/experiences/{flowDefinitionID} to trigger the flow.

  11. Make a POST request to /{environmentId}/flowExecutions/{flowExecutionID} to submit the login form with the user's credentials.

  12. Make a POST request to /{environmentId}/flowExecutions/{flowExecutionID} to accept the agreement.

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

Step 1: Create an application

Step 2: Get languages

Step 3: Create an agreement

Step 4: Create an agreement language

Step 5: Create an ageement revision

Step 6: Update the agreement language

Step 7: Enable the agreement

Step 8: Create the login form

Step 9: Create the flow definition (EXPERIENCE trigger)

Step 10: Trigger the flow execution

Step 11: Submit the login form

Step 12: Create consent

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.

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

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/{environmentId}/identityProviders to create the identity provider configuration for Facebook.

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

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

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

  5. Make a POST request to /environments/{environmentId}/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/{environmentId}/applications to add a new application to the specified environment.

  7. Make a GET request to /environments/{environmentId}/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/{environmentId}/resources/{resourceId}/scopes to list all scopes associated with a specified resource (the PingOne platform resource).

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

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

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

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

Run in Postman

Step 1: Create the new identity provider resource

Step 2: Create an optional attribute mapping

Step 3: Create a population for Facebook users

Step 4: Create the new sign-on policy

Step 5: Create the sign-on policy action

Step 6: Create an application

Step 7: Get the list of resources

Step 8: Get all scopes

Step 9: Create the application’s resource access grant

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

Step 11: Send an authorization request

Configure a SAML identity provider

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

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

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

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

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/{environmentId}/certificates to upload the SAML external identity provider's verification certificate and (optionally) to /environments/{environmentId}/keys to upload the signing key.

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

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

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

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

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

Run in Postman

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

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

Step 2: Create the new identity provider resource

Step 3: Create a population for SAML users

Step 4: Create the new sign-on policy

Step 5: Create the sign-on policy action

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.

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

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/{environmentId}/applications to add a new application to the specified environment.

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

  3. Make a GET request to /environments/{environmentId}/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/{environmentId}/resources/{resourceId}/scopes to list all scopes associated with a specified resource (the PingOne platform resource).

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

  6. Make a POST request to /{environmentId}/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 /{environmentId}/flows/{flowID}.

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

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

  10. Use the access token to make a GET request to /environments/{environmentId}/users/{userId} to view return information about the identified user.

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

Run in Postman

Step 1: Create an 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: Obtain an authorization grant

Step 7: Get the flow

Step 8: Submit login credentials

Step 9: Generate the access token

Step 10: Get user information

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

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/{environmentId}/applications to add a new application to the specified environment.

  2. Make a GET request to /environments/{environmentId}/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/{environmentId}/resources/{resourceId}/scopes to list all scopes associated with a specified resource (the PingOne platform resource).

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

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

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

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

  8. Make a POST request to /{environmentId}/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 /{environmentId}/flows/{flowID}.

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

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

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

Run in Postman

Step 1: Create a single-page application

Step 2: Get the list of resources

Step 3: Get all scopes

Step 4: Create the application’s resource access grant

Step 5: Create a population

Step 6: Create user

Step 7: Set user password

Step 8: Send the authorize request

Step 9: Get the Flow

Step 10: Submit Login Credentials

Step 11: Call the resume endpoint

Test a SAML application connection

To test the execution of a SAML identity provider connection for an application configured in your PingOne environment, there needs to be a working SAML identity provider somewhere 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 identity provider.

Prerequisites

  • A destination PingOne environment to act as the service provider for the SAML application. This is the environment you'll use to configure the SAML identity provider connection. Authentication flows in this environment can be configured to allow external authentication.

  • A source PingOne environment that will act as the SAML identity provider. 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:

  • Get the certificate for the source environment.
  • Create a SAML application in the source environment.
  • Create a SAML identity provider 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 identity provider connection.
  • Set the sign-on policy as the default for the destination environment.

Workflow order of operations

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

  1. Make a GET request to /environments/{{sourceEnvID}}/keys to get the signing key for the source environment.

    a. 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 you downloaded in the intial step.

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

  7. Make a POST request to /environments/{{destinationEnvID}}/identityProviders to create the SAML identity provider 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 identity provider in the destination environment.

  9. Make a POST request to /environments/{{destinationEnvID}}/signOnPolicies to create a sign-on policy for the new identity provider 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/{applicationId}/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. The Self-Service URL is found on the Settings → Environment → Properties page.

  2. Open a private browser window, and enter the Self-Service URL 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 may need to perform account linking or user verification.

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

Run in Postman

Step 1: Get the signing key for the source environment

Step 2: Get all environment IDs

Step 3: Create a SAML application in the source environment

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

Step 5: Create a certificate in the destination environment

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

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

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

Step 9: Create a sign-on policy action

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

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.

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/{id}/integrations to retrieve a list of available integrations, using the filter parameter to provide a targeted result set.
  3. Make a GET request to /environments/{id}/integrations/{integrationID}/versions/{integrationVersionID}/asset

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

Run in Postman

Step 1: Get the environment ID

Step 2: Get a list of integrations

Step 3: Download the integration zip file

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

Workflow order of operations

To create the application specify its sign-on policy:

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

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

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

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

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

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

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

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

Run in Postman

Step 1: Create a web application

Step 2: Get all resources

Step 3: Get all OIDC scopes

Step 4: Assign a resource grant to the web application

Step 5: Create an MFA sign-on policy

Step 6: Create a sign-on policy MFA action

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

Configure a passwordless sign-on policy

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

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

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

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/{environmentId}/applications to create a new application connection.

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

  3. Make a POST request to /environments/{environmentId}/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/{environmentId}/applications/{applicationId}/signOnPolicyAssignments to associate this sign-on policy with the specified application.

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

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

Run in Postman

Step 1: Create an application

Step 2: Create the new sign-on policy

Step 3: Create the sign-on policy action

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

Step 5: Test authentication

Configure an MFA Only Flow Using a Login Hint Token

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

The following operations are supported by the PingOne APIs:

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

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/{environmentId}/applications to add a new application to the specified environment.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Run in Postman

Step 1: Create a web application

Step 2: Get the application secret

Step 3: Get all resources

Step 4: Get all OIDC Scopes

Step 5: Assign a resource grant to the web application

Step 6: Create a sign-on policy

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

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

Step 9: Create a population for MFA users

Step 10: Create user

Step 11: Set user password

Step 12: Enable user MFA

Step 13: Set user device (SMS)

Step 14: Send authorize request

Step 15: Check OTP

Step 16: 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 user
  • Initiate an authorize request using a request token and a login_hint_token
  • Use the OTP check API to complete the MFA action

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/{environmentId}/applications to add a new application to the specified environment.

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

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

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

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

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

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

  8. Make a POST request to /environments/{environmentId}/applications/{applicationId}/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/{id}/populations to create a new population resource.

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

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

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

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

  15. Make a POST request to /{environmentId}/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 /{environmentId}/flows/{flowID} and provide the one-time passcode.

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

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

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

Run in Postman

Step 1: Create a web application

Step 2: Get the application secret

Step 3: Get all resources

Step 4: Get all OIDC Scopes

Step 5: Assign a resource grant to the web application

Step 6: Create a sign-on policy

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

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

Step 9: Create a transaction SMS template

Step 10: Create a population for MFA users

Step 11: Create user

Step 12: Set user password

Step 13: Enable user MFA

Step 14: Set user device (SMS)

Step 15: Send authorize request for transaction approval

Step 16: Check OTP

Step 17: Call the resume endpoint

Step 18: Get the access token

Use Two MFA Actions to Authenticate Users

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  14. Make a POST request to /environments/{id}/users/{userId}/devices to associate an Email MFA device with this user.

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

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

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

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

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

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

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

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

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

Run in Postman

Step 1: Create a web application

Step 2: Get all resources

Step 3: Get all OIDC Scopes

Step 4: Assign a resource grant to the web application

Step 5: Create a sign-on policy

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

Step 7: Create an Email 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: Set user device (Email)

Step 15: Send an authorization request

Step 16: Get the flow

Step 17: Sign on with a username

Step 18: Check OTP for SMS

Step 19: Check OTP for Email

Step 20: Call the resume endpoint

Step 21: Get the application secret

Step 22: 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

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.

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

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

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 download the Postman collection for this use case.

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

Workflow order of operations

To create the new user, 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 download the Postman collection for this use case.

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

External Services

This activity shows you how to create an external service resource and how to define specific HTTP requests in the requests property of the external service resource. The following workflow illustrates the steps required to create four HTTP requests, ranging from a basic request that uses static values (which are applicable only to one request) to more complex requests that use variables and secrets, which are properties that can be applied to any request defined in the external services resource. It also shows you how to create a request that uses inputs, which are values that are expected to be given at request invocation time.

In this use case, the following operations are supported by the PingOne APIs:

  • Create an external services resource
  • Update the external services resource to configure HTTP requests to an external resource server
  • Invoke the requests to return a response from the external resource server

Workflow order of operations

This workflow defines HTTP requests to an external service and shows you how to invoke them. The following API call order creates the external service resource first. Next, it steps through four updates to add the HTTP requests. After each PUT operation to add a request, the next step is a POST to invoke the request.

  1. Make a POST request to /environments/{{envID}}/externalServices to add a new external service resource to the specified environment.

  2. Make a PUT request to /environments/{{envID}}/externalServices/{{externalServiceID}} to update the requests property in the external service resource with a an HTTP request that uses static values. The name of this request is Your_First_Request.

  3. Make a POST request to /environments/{{envID}}/externalServices/{{externalServiceID}}/requests/Your_First_Request to invoke the request.

  4. Make a PUT request to /environments/{{envID}}/externalServices/{{externalServiceID}} to update the requests property in the external service resource to add a second HTTP request. This request defines a variable and uses it in the request. The name of this request is Your_Request_Using_A_Variable.

  5. Make a POST request to /environments/{{envID}}/externalServices/{{externalServiceID}}/requests/Your_Request_Using_A_Variable to invoke the request.

  6. Make a PUT request to /environments/{{envID}}/externalServices/{{externalServiceID}}/secrets to create a secret.

  7. Make a PUT request to /environments/{{envID}}/externalServices/{{externalServiceID}} to update the requests property in the external service resource to add a third HTTP request. This request uses the variable and the secret in the request. The name of this request is Your_Request_Using_A_Secret.

  8. Make a POST request to /environments/{{envID}}/externalServices/{{externalServiceID}}/requests/Your_Request_Using_A_Secret to invoke the request.

  9. Make a PUT request to /environments/{{envID}}/externalServices/{{externalServiceID}} to update the requests property in the external service resource to add a fourth HTTP request. This request uses inputs to assign values at invocation. The name of this request is Your_Request_Using_An_Input.

  10. Make a POST request to /environments/{{envID}}/externalServices/{{externalServiceID}}/requests/Your_Request_Using_An_Input to invoke the request.

Click the Run in Postman button below to download a Postman collection that includes the requests described in this section.

Run in Postman

Create your first external service

Add your first request to the external service

Invoke your first request

Add a variable and use it in a request

Invoke your request that uses a variable

Add a secret and use it in a request

Add requests that use a variable and a secret

Invoke your request that uses a secret

Add invocation inputs in a request

Invoke your request that uses an input