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

1. Create an application connection using the PingOne admin console application.

2. Get the application's access token (a JSON Web Token) for the application you created.

3. Test the access token by running a simple PingOne Platform API request.

You'll then be able to make any PingOne Platform API requests allowed by the permissions encoded in your access token. For general information about PingOne Platform APIs, see Management APIs Overview and Authorization and Authentication APIs Overview.

4. (Optional) If you're using Postman to develop or test your project, you can also download the Postman collection for our entire PingOne Platform API, with the Postman environment template used in our example requests.

To get the access token you created in Create an application connection:

1. Click the application's details icon (located to the right of the enable/disable button).
2. Click the Configuration tab.
3. Click Get Access Token.
4. From the Access Token window, click Copy Access Token to copy the access token.

To get your environment ID from the Admin Console:

1. Click Settings.
2. Click Environment.
3. Click Properties.

The Properties page shows the environment ID.

Test your access token

Your PingOne account has at least one defined environment resource. You can use the PingOne APIs to return information about the environment resource associated with your application connection.

In the North America (NA) region:

curl -X GET "https://api.pingone.com/v1/environments/{{envID}}" \
-H "Authorization: Bearer accessToken"

In the Canada region:

curl -X GET "https://api.pingone.ca/v1/environments/{{envID}}" \
-H "Authorization: Bearer accessToken"

In the European Union (EU) region:

curl -X GET "https://api.pingone.eu/v1/environments/{{envID}}" \
-H "Authorization: Bearer accessToken"

In the Asia Pacific (AP) region:

curl -X GET "https://api.pingone.asia/v1/environments/{{envID}}" \
-H "Authorization: Bearer accessToken"

The accessToken value in your request is your full base64url-encoded access token generated by the PingOne authentication service. If your token is valid, the API request returns a 200: Successful operation message. It also displays the property data for the environment and links to show the related resources associated with the environment.

Application connections determine how PingOne integrates with client applications. When you define the application connection, you also define the application's access to PingOne resources, which are encoded in the application's access token. To make calls to the PingOne Platform API, you must submit your access token with the API request.

Use the PingOne admin console to create your first application connection. To create the application connection:

1. Click Connections.

2. Click + Add Application.

3. Select the Worker application type.

4. Click Configure.

5. Create the application profile by entering the following information:

   • Application name. A unique identifier for the application.

   • Description (optional). A brief characterization of the application.

   • Icon (optional). A pictorial representation of the application. Use a file up to 1MB in JPG, JPEG, GIF, or PNG format.

6. Click Save and Close.

7. The Applications page shows the new application. To view the application's access token, you must enable the new application:

   • Click the Enable toggle switch at the right. The toggle switch shows green to indicate that the new application is enabled.

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

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

The PingOne Postman collections

Collection	Description	Retrieve
Platform	Postman requests for the PingOne platform API, which includes all endpoints.

Download a Postman collection

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

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

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

To retrieve the collection:

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

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

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

   

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

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

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

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

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

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

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

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

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

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

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

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

Variables you must value

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

Most APIs require authorization to ensure that client requests access data securely. Postman can pass along whatever authorization details necessary for the method demanded by the endpoint. You can manually include authorization data in the header, body, or as parameters to a request. However, the easiest way is to use the Authorization tab in Postman. Select an authorization Type on that tab and Postman offers a dialog to gather the information required by that Type. When you run a request, Postman uses the information from the Authorization tab to automatically add the necessary authorization header, body, or parameters to the request.

Postman offers the Authorization tab on requests, folders, and collections. When you select an authorization method on a request, that method is used. But Postman does not require that you set a method on every request. Postman offers an additional choice: Inherit auth from parent. When this is selected on a request, Postman ascends the hierarchy of folders until it finds a folder, or the collection, where an authorization method is selected and uses that method for the request.

In PingOne collections, the authorization method is defined at the collection level. Only those requests that require a specific authorization method have authorization defined on the request (roughly 10% of PingOne requests). This allows you to easily change the authorization used for most requests.

Unexpected authorization failure

The default Authorization tab Type for a collection in Postman is No Auth. If you copy a request from a PingOne collection into your own collection and the request fails with an authorization error, check the Authorization tab of your collection. If Type is No Auth, you have two choices:

1. Change the Authorization tab in Postman for your collection to your choice of Type, such as Bearer Token or OAuth 2.0.

2. Change the Authorization tab in Postman for the request you copied to your choice of Type.

Obtain a Bearer Token before running requests

Before you can run requests in this documentation that use Bearer Token using a selected coding framework (available in the drop-down list), you must retrieve an access token. To retrieve an access token:

1. Run Token Admin App (client_credentials).

2. Copy access_token from the response.

3. Use the access token in subsequent requests until it expires.

4. Repeat these steps.

Bearer tokens enable requests to authenticate using an access key, such as a JSON Web Token (JWT) used by PingOne. The token is three base64url strings separated by periods, and specified in the variable used by the Authorization header.

To configure a PingOne collection to use Bearer Token for authorization:

1. Click on the collection.

2. Click the Authorization tab.

3. Select Bearer Token from Type.

4. In Token, type {{accessToken}}, the variable from the environment variable template.

You should always place your API key value in the variable. Authorization requests in PingOne collections that return an access token automatically set the {{accessToken}} variable to the returned access token.

Postman appends the Token value to the text Bearer in the required format to the request Authorization header: Authorization: Bearer <access token>.

Before you can run Postman requests that use Bearer Token, you must retrieve an access token. To retrieve an access token manually in Postman:

1. Run Token Admin App (client_credentials).

   The script on the Tests tab sets the {{accessToken}} environment variable to access_token from the response.

2. Postman applies {{accessToken}} to requests with Authorization Inherit auth from parent until it expires.

3. Repeat these steps.

OAuth (short for "Open Authorization") is an open standard that grants websites or applications access to users' information on other websites without giving them their passwords.

When authorization is set to OAuth 2.0, instead of the default Bearer Token, you use Postman’s automatic OAuth features to retrieve and refresh tokens. You also use your browser to authenticate your session, which improves platform operational security and developer experience.

To configure a PingOne collection to use OAuth 2.0 for authorization:

1. Click on the collection.

2. Click the Authorization tab.

3. Select OAuth 2.0 from Type.

4. Select Request Headers from Add auth data to.

5. In Token, select any unexpired token previously generated.

6. In Header Prefix, type Bearer.

   You must Configure New Token, if none are available in Token.

7. In Token Name, type any name. If you generate more than one token, this appears in Token to select a valid token.

8. Select Client Credentials from Grant Type.

9. In Access Token URL, type {{authPath}}/{{adminEnvID}}/as/token.

10. In Client ID, type {{adminAppID}}.

11. In Client Secret, type {{adminAppSecret}}.

12. Scope is not required in this use case, leave blank.

13. Select Send as Basic Auth Header from Client Authentication.

14. In Refresh Token URL, type {{authPath}}/{{adminEnvID}}/as/token.

To generate a new access token:

1. Click Get New Access Token.

   The Get new access token dialog appears.

2. Click Proceed. If you do nothing, the dialog proceeds after 5 seconds.

   The Manage Access Tokens dialog appears.

3. Click Use Token. Postman applies the access token to requests with Authorization Inherit auth from parent until it expires.

4. If Postman does not automatically refresh the access token, repeat these steps.

The following section provides additional information about PingOne platform authorization and authentication workflows. It also includes detailed information about access tokens and ID tokens and how user scopes and platform roles enable access to PingOne resources. Topics include:

• Access tokens and ID tokens

• Authorization and authentication by application type

• Authorization flow by grant type

• Access services through scopes and roles

• Control access to applications through roles and groups

• PingOne basic login authentication flow

• Login and MFA authentication workflow walkthrough

• PingOne authentication flow states

Access tokens are credential strings that represent authorization to access a protected resource. Client applications obtain access tokens by making OAuth 2 or OpenID Connect requests to an authorization server; resource servers require clients to authenticate using access tokens.

Access tokens are obtained from the token endpoint (when using the client credentials grant type) or from the authorization endpoint (when using the implicit grant type). Access tokens are typically granted on behalf of a specific authenticated user. (Tokens granted directly to applications are called application tokens.)

Clients present access tokens when making requests to a resource server (for example, the PingOne API endpoints) using bearer token authentication as described by RFC 6750. Here is a sample request using an access token:

curl -X GET "https://api.pingone.com/v1/environments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6InRlc3QifQ.eyJzY29wZSI6IiIsImNsaWVudF9pZCI6ImlkZW50aXR5LWRpcmVjdG9yeS1zeW50aGV0aWMtdGVzdGluZyIsImlzcyI6ImF1dGgtc3RhZ2luZy5waW5nb25lLmNvbSIsImF1ZCI6ImFwaS1zdGFnaW5nLnBpbmdvbmUuY29tIiwiYWNjIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwiZW52aXJvbm1lbnRfaWQiOiIiLCJvcmciOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJvcmdhbml6YXRpb25faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJlbnYiOiIiLCJleHAiOjE1MzAxMTc1Nzl9.OTGQethw-flgnf0oslpQOmW9YdExf6ZpsqpmRtBTeD5gpKGFmaSeHguFMVpR94GSjb27OEPzCY8qpU_OkoaQGH9FiysdgvFFVNVzHOb80e0MgP47ean1Rtk3lHmIWHg1ihp3Kt7vq9fO0OwekmfshejyaLYLX2g4seWFZKbs7ICIaSufYuGTsLLQFixiK7b0tM-lcjZUmLglPlzdGEYQgg13ZWho02rFVjwRrfOVkQRCLuhkk2Pz2eeblQgWBlzMi_zbHnRhqRnrHyX2PwoPZ9qHh3aqz6yNgGinUwSrE3J1slnx8uPeP88obYcX4QXTXOCf7su2rinbexOsNu4Puw"

OAuth 2 and OpenID Connect define the authorization grant types by which a client application obtains an authorization grant in the form of an access token. PingOne supports the following grant types:

Authorization code

This grant type is used by web applications. The authorization request generates an authorization code that is exchanged for an access token. For more information, see Authorization request with a code grant.

Implicit

This grant type is intended for use by native applications or client-side web applications with no server-side component. The implicit grant type is for applications that cannot guarantee the confidentiality of the client secret.

In this flow, the client makes a request to the server’s authorization endpoint. If the request contains the id_token response type and the openid scope, then it is considered an authentication (OpenID Connect) request, and an ID token is issued. For more information, see Native and single-page applications.

Client credentials

This grant type is made directly to the token endpoint and is used to request an access token for either:

• Resources owned by the client rather than any specific end user.
• Resources belonging to multiple end users.

The client uses HTTP basic authentication with its client ID and client secret to authenticate itself to the token endpoint and must specify a Content-Type of application/x-www-form-urlencoded. For more information, see Obtain an access token.

Refresh token

This grant type is used by applications to exchange the refresh token for a new access token. It gives applications the ability to acquire a valid access token without additional interaction. For more information, see Obtain an access token.

Device code

This grant type is used by applications to return an activation code in the response to the POST /{{envID}}/as/device_authorization request. It gives OAuth enabled devices such as smart TVs the ability to complete user authorization and access protected resources. For more information, see Device Authorization Grant.

The authorization request must specify a response_type attribute, which determines whether an access token, an authorization code, or an ID token is returned by the authorization server. The following is the list of the OAuth 2.0 response types supported by the PingOne authorization server:

• code

  Returns an authorization code. If the grant type is authorization_code, the response_type attribute must have the code value. The authorization code returned by the request is exchanged for an access token to complete the authorization flow.

• token

  Returns an access token. If the grant type is implicit or client_credentials, the response_type attribute can specify the token value to return an access token.

• id_token

  Returns an ID token. If the grant type is implicit, the response_type attribute can specify the id_token value to return a JWT containing a set of claims that represent the authentication state of an end user.

• id_token (OpenID Connect ID token)

  If the request contains the id_token response type and the openid scope, then it is considered an authentication (OpenID Connect) request, and an ID token is issued. The ID token includes the ID of the user; this request can also include the profile scope to add additional user claims to the ID token.

All tokens in PingOne are JSON Web Tokens (JWTs) signed using the RS256 signing algorithm. The following section lists the supported claims for each token type.

Access token claims

For access tokens, the JWT header must contain the ID of the signing key as the kid claim.

ID Token claims

ID tokens are signed with the same key as the access token. The JWT header must contain the ID of the signing key as the kid claim.

Refresh tokens

Refresh tokens are JWTs signed with the same key as the access token. They are not intended to be read by the client. For more information about refresh token usage, see Obtain an access token.

PingOne lets you customize the content of access tokens by adding custom resource attributes and their values to the token. You can use the access token customization APIs to convey additional information about the user to applications. For more information, see Resource attributes.

ID token customization

You can also customize the content of OIDC ID tokens by adding custom user claims to the token. For more information, see Attribute mappings.

Token analysis

The PingOne platform supports endpoints to returns the active state of an OAuth 2.0 token and all of the claims in the token. The request takes a token parameter, which is the token string. For more information, see Token introspection.

PingOne provides an out-of-box workflow to authenticate users. In addition, requests from OIDC/OAuth 2 and SAML applications initiate the flow and can redirect the browser to a custom authentication UI. The following diagram shows the authentication flow.

PingOne authentication flow endpoints

The following walk-through shows the actions required to authenticate a user. This scenario illustrates the following authentication operations:

• Initiate an authorization request

• Redirect to the authentication UI

• Retrieve the flow and present appropriate forms to end users (and submit data) for all required steps.

• Redirect to the resume URL when the flow is complete.

The steps that follow illustrate general flow actions. This exploration is not written as a step-by-step process that can be completed successfully.

Step 1: Initiate an authorization request

The following sample shows the GET /{{envID}}/as/authorize operation for an authorization_code request. The following sample shows as authorize request for an OIDC/OAuth 2 application.

curl -X GET \
  'https://auth.pingone.com/{{envID}}/as/authorize?response_type=code&client_id={{appID}}&redirect_uri={{redirect_uri}}&scope=p1:read:self:user&acr_values=Multi_Factor'

The response returns a 302 message with a flowID embedded in the Location header, which specifies that a call should be made to another resource to continue the authentication flow. The Location header looks like this:

Location: http://example.com?environmentId=5caa81af-ec05-41ff-a709-c7378007a99c&flowId=acfa3223-aa05-49d5-bab2-b03dc019bb5f

Step 2: Retrieve the flow resource

The flowId returned in Step 1 specifies the flow to run to continue the authentication request. The following sample shows the GET /{{envID}}/flows/{{flowID}} operation that calls the flow identified by the flowId.

curl -X GET \
  'https://auth.pingone.com/{{envID}}/flows/{{flowID}}'

The response data looks like this. The status property in the response specifies the next action in the authentication flow. In this flow, the USERNAME_PASSWORD_REQUIRED action is the next required step:

{
    "_links": {
        "self": {
            "href": "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/flows/5318a876-a8de-4d68-be79-b64043ff6490"
        },
        "usernamePassword.check": {
            "href": "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/flows/5318a876-a8de-4d68-be79-b64043ff6490"
        },
        "password.forgot": {
            "href": "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/flows/5318a876-a8de-4d68-be79-b64043ff6490"
        }
    },
    "id": "5318a876-a8de-4d68-be79-b64043ff6490",
    "resumeUrl": "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/as/resume?flowId=5318a876-a8de-4d68-be79-b64043ff6490",
    "status": "USERNAME_PASSWORD_REQUIRED",
    "createdAt": "2019-06-18T18:47:44.750Z",
    "expiresAt": "2019-06-18T19:09:07.629Z",
    "_embedded": {
        "application": {
          "name" : "PingOne Admin Console",
          "icon" : {
             "id" : "<uuid>", 
             "href" : "[https://assets.pingone.com/ux/ui-library/4.18.0/images/logo-pingidentity.png] " 
          }
        }
    }
}

For more information about flow status values, see Flows.

Step 3: Submit data for the required action

The required action specified in Step 2 calls the action service to present the appropriate input form to end users, and after input is provided, to submit the data. This operation is performed repeatedly for each action required in the authentication flow, depending on the actions configured in the sign-on policy configuration. It continues until the flow status is COMPLETED or FAILED.

For example, the following sample shows the POST /{{envID}}/flows/{{flowID}} operation that calls the login with username and password action. This operation uses the application/vnd.pingidentity.usernamePassword.check+json custom media type as the content type in the request header when there is no user associated with the current flow.

curl -X POST "https://auth.pingone.com/{{envID}}/flows/{{flowID}}" \
-H 'Content-type: application/vnd.pingidentity.usernamePassword.check+json' \
-d '{
  "username": "jameslymanstone",
  "password": "ChangeM3!"
}'

Step 4: Redirect to the resume endpoint

After completing the actions specified by the sign-on policy, the authentication UI redirects the browser to the URL specified in the resumeUrl property in the flow resource.

The following sample shows the resumeUrl value constructed by the flow to return the flow back to the authorization service, specifying the flowID in the request URL.

"resumeUrl": "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/as/resume?flowId=663067c8-3973-4578-adf2-f42514fe3dc1"

An application's sign-on policy determines the flow states and the corresponding actions required to complete an authentication workflow. When the authentication workflow begins, the flow gets the list of sign-on policies assigned to the application and evaluates the policy conditions that must be met to complete sign on. The sign-on policy evaluation logic is shown in the diagram below:

For more information about sign-on policies, see Sign-on policies, Sign-on policy actions, and Sign-on policy assignments.

Common authentication actions

The PingOne flow API supports single-factor and multi-factor actions to complete an authentication workflow. For a single-factor login flow, there are four branches that allow the user to submit a username and password (or create a new account). PingOne also supports an identity first discovery action that identifies the user and determines the user's applicable identity provider and authentication methods. For a multi-factor authentication action, there are two branches in which either a one-time password (OTP) or a push confirmation is used as the second factor in the authentication workflow.

PingOne supports a progressive profiling action that prompts users to provide additional data at sign on. This action type does not authenticate users. It is used only to obtain additional profile data.

• Login action

  • Sign on with username and password

  • Forgot password

  • Register user

  • Sign on with identity provider

• Identifier first action

• Multi-factor (MFA) action

  • Push authentication

• Progressive profiling action

Login action authentication flows start with a call to the /{{envID}}/as/authorize endpoint. The response to an authorize request returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID for the authentication workflow. For a new session, the user’s browser is redirected to the sign-on screen that prompts for a PingOne username and password (or, based on the sign-on policy configuration, provides access to an external identity provider's sign-on URL).

For an existing session, the user's browser is redirected to a sign-on screen that prompts for a password only. The following diagram shows the flow options for the USERNAME_PASSWORD_REQUIRED and PASSWORD_REQUIRED flow states:

The login flow consists of the following four branches, which can be chosen to submit the username and password, recover a forgotten password, or create account credentials to complete the sign-on flow:

• Sign on with username/password

  This flow verifies the username and password submitted by the user through the sign-on screen.

• Forgot password

  If enabled, the recover password flow initiates actions to recover the account and set a new password.

• Register user

  If enabled, the register user flow initiates actions to create an account for a user. The flow calls the user.register action to create the new user.

• Sign on with identity provider

  If enabled, the social sign-on flow initiates actions to authenticate the user through an external identity provider.

Sign on with username and password

The username/password branch of the login flow uses the usernamePassword.check action to verify the user's password. If the user's password status is OK, the flow transitions to the next action required by the sign-on policy. If the user's password has expired, the flow transitions to the PASSWORD_EXPIRED flow state. The response from the usernamePassword.check action includes a link to initiate the password.reset action to update the password. If the user is using a temporary password, the flow transitions to the MUST_CHANGE_PASSWORD flow state. The user can initiate the password.reset action to change the temporary password.

Forgot password

The recover password branch of the login flow uses the user.lookup action to verify the user. After user look-up, the flow transitions to the RECOVERY_CODE_REQUIRED flow state. The flow uses the password.recover action to issue a recovery code to the user. After the recovery code is issued and the user submits the correct code, the flow transitions to the MUST_CHANGE_PASSWORD flow state and uses the password.reset action to update the user's password.

Register user

The register user branch of the login flow initiates the user.register action to create a new user account and set a password. The sign-on screen prompts the user to submit a username, an email address, and a password. If this action executes successfully, the flow transitions to the next action required by the sign-on policy.

Sign on with identity provider

The external identity provider (social sign-on) branch of the login flow initiates actions to authenticate the user through an external identity provider. It also links the external identity provider to the PingOne user account.

The flow diagram shows a flow path to update a user who already has an existing link to an external identity provider account, bypassing the ACCOUNT_LINKING_REQUIRED flow state. It also shows a flow path if the external identity provider account is not linked to an existing PingOne user. In this case, the flow transitions to the ACCOUNT_LINKING_REQUIRED flow state and calls the user.register action to find a matching user and initiate account linking to the external provider.

From the ACCOUNT_LINKING_REQUIRED flow state, a user can either register as a new user or link to an existing PingOne user. In cases where the user does not exist in PingOne, the external identity provider login flow calls the user.register action to register the external identity account user as a new PingOne user. Consequently, when the social sign-on branch is implemented as a sign-on option, the sign-on policy should also include the register user sign-on branch with the registration.enabled policy action attribute set to true.

If registration is enabled and the user exists in PingOne but no external account link is defined, PingOne tries to find a matching user (usually by email address). If PingOne does not find a matching user, then registration is required. If PingOne finds one or more matching users (more than one user in the system with a matching email address), then the flow prompts for a username and password to verify the user's identity and complete the account link.

If the registration login flow branch is disabled in the sign-on policy, then the user who tries to log in with external identity provider credentials can only link to an already existing user in PingOne.

The identity provider discovery login flow initiates actions to identify the user and determine the applicable authentication methods for this user. It is designed to be used as an alternative to the standard login flow. It differs from the username/password login flow in that it first prompts the user for a username, and then it uses the identity provider discovery rules defined in the sign-on policy to route the user to the correct external identity provider for authentication.

A condition in the sign-on policy specifies the external identity providers that are evaluated to verify whether one of them is the authoritative source of identity. If one is found, the user is directed to authenticate using the external identity provider’s authentication flow. The flow transitions to the EXTERNAL_AUTHENTICATION_REQUIRED flow state and redirects the browser to the external identity provider's login URL.

If the authorize request uses the login_hint property to identify the user, then the identity provider discovery login flow no longer prompts the user for a username in the sign-on flow. It uses the identity provider discovery rules defined in the sign-on policy to route the user directly to the correct external identity provider for authentication. The flow transitions to the EXTERNAL_AUTHENTICATION_REQUIRED flow state and redirects the browser to the external identity provider's login URL.

Identity provider account confirmation occurs when the confirmIdentityProviderAttributes property in the login sign-on action is set to true. If the flow does not find a linked user with PingOne authorization authority linked to the external account, the flow transitions to the ACCOUNT_CONFIRMATION_REQUIRED flow state and redirects the browser to a form to confirm or update values for attributes mapped from the identity provider. After confirmation or update, the flow calls the user.confirm action to search for users with PingOne authentication authority based on mapped unique attributes. If matches are found, the flow transitions to the ACCOUNT_LINKING_REQUIRED flow state and redirects the browser to a form to select the matching user account. The flow updates the user account and completes.

The MFA (multi-factor authentication) flow adds an MFA action to the authentication flow. When an MFA flow is initiated, the flow evaluates information about the requesting device and initiates appropriate MFA actions:

1. If the MFA flow begins on a paired MOBILE device, it transitions directly to the device authorization flow (with or without extra verification specified in the sign-on policy).

2. If the device authorization flow was not initiated, the flow checks the device to determine if it is a paired FIDO2 biometric device (by looking for an existing session token ST cookie). If the user has a session token cookie for this user on the browser (or if a FIDO2 biometrics device is selected during the device selection flow), the flow transitions to the FIDO2 biometrics flow. If no session token cookie exists, the flow will complete with the default device or with device selection, but not through bypass.

3. If the FIDO2 biometrics flow is not started, the flow transitions to the device selection flow or to another flow using the default device.

4. If the selected (or default) device is a MOBILE device with PUSH enabled, the flow transitions to the native PUSH flow.

5. If the selected (or default) device is of type MOBILE, SMS, VOICE, EMAIL, TOTP, or SECURITY_KEY, the flow transitions to the offline flow (for MOBILE, SMS, VOICE, EMAIL, TOTP types) or the security key flow.

These MFA flow paths are described in the following sections.

If the user is authenticating from a paired MOBILE device and device authorization with extra verification is enabled (in the sign-on policy), the MFA flow transitions to PUSH_CONFIRMATION_REQUIRED. If extra verification is not enabled, the flow completes immediately. If the user does not have a default device, the flow transitions to the DEVICE_SELECTION_REQUIRED flow state and calls the device.select action to specify the device used for the MFA action. For more information about extra verification, see the "MULTI_FACTOR_AUTHENTICATION action data model" table in the Sign-On Policy Actions topic.

If the user is authenticating from a registered platform device and has a session token (ST) cookie on a compatible browser, the FIDO2 biometric flow uses this device, bypassing the default device. The flow transitions to the ASSERTION_REQUIRED flow state and calls the assertion.check action to complete the flow. If there is no session token cookie on the browser, or the FIDO2 device type is SECURITY_KEY, the default device is selected automatically. The flow transitions to the ASSERTION_REQUIRED flow state and calls the assertion.check action to complete the flow. For more information about FIDO2 platform devices, see MFA Devices.

If the default device is a MOBILE application with PUSH enabled, a PUSH notification is sent to the application, and the flow transitions to the PUSH_CONFIRMATION_REQUIRED flow state. The flow transitions to one of the following states:

• COMPLETED if the user approves the authentication action on the native device.

• FAILED if the user denies the authentication action on the native device.

• PUSH_CONFIRMATION_TIMED_OUT if the user does not respond to the authentication action on the native device.

If pushless is enabled, the flow transitions to the OTP_REQUIRED flow state and calls the otp.check action to send a one-time passcode (OTP) to the user's specified device. After the OTP is issued and the user submits the correct OTP, the flow completes.

If the default device is an email, SMS, voice, authenticator device (TOTP) or a MOBILE device in PUSHLESS mode, the flow transitions to the OTP_REQUIRED flow state and calls the otp.check action to send a one-time passcode (OTP) to the user's specified device. After the OTP is issued and the user submits the correct OTP, the flow completes.

If the default device (or selcted device) is SECURITY_KEY, the flow transitions to the ASSERTION_REQUIRED flow state and calls the assertion.check action to send a FIDO2 assertion retrieved by the WebAuthn browser API for the specified device. After the client submits the correct assertion, the flow completes. For more information about FIDO2 security key devices, see MFA Devices.

If the user does not have a default device, and the conditions to trigger the device authorization or FIDO2 platform flows are not met, the flow transitions to the DEVICE_SELECTION_REQUIRED flow state. The client calls the device.select action to specify an MFA device to use for performing the MFA action. After device selection, the flow transitions to either the offline flow, the FIDO2 biometrics flow, or the native flow with PUSH enabled, depending on the selected device. For more information, see MFA Devices.

If pushless is enabled, and the flow is in the PUSH_CONFIRMATION_TIMED_OUT state, the flow can also transition to the OTP_REQUIRED flow state and calls the otp.check action to send a one-time passcode (OTP) to the user's specified device. After the OTP is issued and the user submits the correct OTP, the flow completes.

The progressive profiling login flow prompts users to provide additional data at sign on. The attribute data provided is added to the user's profile. For example, this flow can be configured to follow the user.register action to add more user data to the newly created account. The sign-on screen prompts the user to submit data for the specified user attributes. If this action executes successfully, the flow transitions to the next action required by the sign-on policy.

An authentication workflow starts with an application's sign-on policy. The sign-on policy determines the steps and corresponding actions required to authenticate a user's account. When the authentication workflow begins, the flow gets the sign-on policy (or policies) assigned to the application.

Application sign-on policies

The PingOne platform includes the following two pre-configured sign-on policies:

• Single_Factor

  A single-factor sign-on policy that prompts users to enter a username and password to authenticate the account.

• Multi_Factor

  A two-step authentication process that prompts users to take the following actions to authenticate the account:

  • Enter a username and password.
  • Enter a one-time password (OTP) on a registered phone number or email, or approve the authentication on a registered native device.

If an application does not have an assigned sign-on policy, it uses the default sign-on policy for the environment. If the application has one or more assigned sign-on policies, the flow service evaluates the sign-on policies and their conditions based on designated priority (or the order in which the assigned policies are listed in the acr_values attribute of the authorization request). If all actions for an assigned policy complete successfully, the authorization workflow completes successfully.

For more information about sign-on policies, see Sign-on policies and Sign-on policy actions.

For information about assigning a sign-on policy to an application, see Sign-on policy assignments.

Sign-on request

PingOne authentication workflows are initiated with a call to the /{{envID}}/as/authorize endpoint. The application's type property determines the parameters required in the authorize request. For more information about application types and the supported parameters for an authorize request, see Authorization requests for application types.

The response to an /{{envID}}/as/authorize request returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID for this specific authentication workflow. The user's browser is redirected to the sign-on screen, which looks like this for a new session.

For an existing session, the user's browser is redirected to a sign-on screen that prompts for a password:

Get the flow

As the user's browser is redirected to the sign-on screen, the authorize service calls the GET /{{envID}}/flows/{{flowID}} operation and uses the {{flowID}} value from the /{{envID}}/as/authorize response to get the flow and the current flow state. The status property in the GET /{{envID}}/flows/{{flowID}} response specifies the initial flow state, which determines the possible next actions in the authentication workflow.

Both the Single_Factor and Multi_Factor pre-defined sign-on policies require a username and password. The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/flows/663067c8-3973-4578-adf2-f42514fe3dc1"
        },
        "usernamePassword.check": {
            "href": "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/flows/663067c8-3973-4578-adf2-f42514fe3dc1"
        },
        "password.forgot": {
            "href": "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/flows/663067c8-3973-4578-adf2-f42514fe3dc1"
        }
    },
    "id": "663067c8-3973-4578-adf2-f42514fe3dc1",
    "resumeUrl" : "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/as/resume?flowId=ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6",
    "status" : "USERNAME_PASSWORD_REQUIRED",
    "createdAt" : "2019-06-04T21:52:34.866Z",
    "expiresAt" : "2019-06-04T22:07:35.724Z"
  }
}

In this example, the status attribute shows a flow state of USERNAME_PASSWORD_REQUIRED, specifying that username and password values are required to complete this sign-on action. The response also includes the following links to present options for the next operation in the flow:

• usernamePassword.check

  An action to sign on with a username and password.

• password.forgot

  A sign-on action to recover a user’s forgotten password.

Complete the sign-on action

To respond to the USERNAME_PASSWORD_REQUIRED flow state, the user initiates the usernamePassword.check action, which includes these steps:

1. The user enters a username and password in the fields provided on the sign-on screen.

2. The user clicks Sign on to initiate the usernamePassword.check authentication action.

3. The flow service calls the POST /{{envID}}/flows/{{flowID}} endpoint operation and uses the application/vnd.pingidentity.usernamePassword.check+json custom media type in the Content-type HTTP request header to identify the action. For more information about this request, see Login with username and password.

Complete the Single_Factor sign-on flow

For a Single_Factor sign-on policy, if the user's account and password are valid, the flow returns a status of COMPLETED, indicating that the conditions of the Single_Factor sign on policy have been met.

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/flows/663067c8-3973-4578-adf2-f42514fe3dc1"
        }
    },
    "id": "663067c8-3973-4578-adf2-f42514fe3dc1",
    "session": {
        "id": "ec249037-9f42-40d5-bdda-eb9b7ddeac18"
    },
    "resumeUrl": "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/as/resume?flowId=663067c8-3973-4578-adf2-f42514fe3dc1",
    "status": "COMPLETED",
    "createdAt": "2019-07-09T19:56:59.817Z",
    "expiresAt": "2019-07-09T20:22:08.229Z",
    "_embedded": {
        "user": {
            "id": "710d6278-ccce-4a91-bdb9-ac7a4a0e60d5",
            "username": "lindajones@example.com",
            "name": {
                "given": "Linda",
                "family": "Jones"
            }
        }
    }
}

Continue the flow for Multi_Factor authentication

For a Multi_Factor sign-on policy, after the username/password action finishes, the flow continues by returning one of the following MFA status values:

• DEVICE_SELECTION_REQUIRED

  This flow state prompts the user to select a device to receive the OTP. This status occurs when the user has more than one registered device.

  

• OTP_REQUIRED

  This flow state prompts the user to complete a multi-factor authentication action that involves receiving a one-time password (OTP) on a specified device and submitting the OTP. This status occurs when the user has only one EMAIL, SMS or VOICE registered device used to receive the OTP (or after selecting a device).

  

• PUSH_CONFIRMATION_REQUIRED

  This flow state prompts the user to approve or deny a push confirmation sent to the user’s registered native device. This status occurs when the user has only one registered MOBILE device type registered to receive push notifications (or after selecting a native device).

  

• PUSH_CONFIRMATION_TIMED_OUT

  This flow state occurs when the user does not respond to the push authentication confirmation request. It prompts the user to retry push authentication (with the same device) or choose a different registered device.

  

Complete the MFA action

The MFA authentication flow requires specific actions depending on the flow state.

DEVICE_SELECTION_REQUIRED

To respond to the DEVICE_SELECTION_REQUIRED flow state, the user initiates the device.select action, which includes these steps:

1. The sign-on screen presents the list of registered devices.

2. The user clicks a registered device to specify the device to use for the MFA action.

3. The flow service calls the POST /{{envID}}/flows/{{flowID}} endpoint operation and uses the application/vnd.pingidentity.device.select+json custom media type in the Content-type HTTP request header to identify the action. For more information about this request, see Select an MFA device.

After a device is selected, the flow transitions to the OTP_REQUIRED flow state and initiates the otp.check action, or it transitions to the PUSH_CONFIRMATION_REQUIRED flow state to prompt the user to accept or deny the confirmation request.

OTP_REQUIRED

To respond to the OTP_REQUIRED flow state, the user initiates the otp.check action, which includes these steps:

1. The user receives the OTP on the specified device.

2. The user enters the OTP in the field provided on the sign-on screen.

3. The user clicks Submit to initiate the otp.check authentication action.

4. The flow service calls the POST /{{envID}}/flows/{{flowID}} endpoint operation and uses the application/vnd.pingidentity.otp.check+json custom media type in the Content-type HTTP request header to identify the action. For more information about this request, see Validate the OTP.

After the OTP is issued and the user submits the correct OTP, the flow completes.

PUSH_CONFIRMATION_REQUIRED

To respond to the PUSH_CONFIRMATION_REQUIRED flow state, the user completes these actions:

1. The user receives the push authentication request on the specified native device.

2. The user chooses ACCEPT or DENY in response to the confirmation prompt.

3. Validation for a push authentication request is managed by the PingOne Native SDK on the native device. For more information, see Native SDK APIs.

PUSH_CONFIRMATION_TIMED_OUT

To respond to the PUSH_CONFIRMATION_TIMED_OUT flow state, the user completes these actions:

1. The user is prompted to either retry push authentication on the currently selected device, or select a different registered native device.

2. For a retry action, the user receives the push authentication request on the currently selected native device and chooses APPROVE or DENY in response to the confirmation prompt.

3. Validation for a push authentication request is managed by the PingOne Native SDK on the native device.

For a Multi_Factor sign-on policy, if the user submits the correct OTP or selects APPROVE in the push confirmation prompt, the flow returns a status of COMPLETED, indicating that the conditions of the Single_Factor sign on policy have been met.

For more information about MFA flow states, see Multi-factor authentication flow states.

The authorization request flow depends on the grant type you have selected for the application. The grant type can be an authorization code, implicit, or a hybrid (both code and implicit).

If the grant type is authorization_code, PingOne returns an authorization code in the response to the application's authorization request. The Location HTTP header returned by the /as/resume endpoint contains the authorization code. The authorization code returned in the resume endpoint response is used by the /as/token endpoint to get an ID token, an access token, or both.

PingOne supports GET and POST HTTP methods for initiating the authorize request.

Authorization code authorize request using GET

Step 1: Send an authorize request to the PingOne authorization server using GET.

curl --location --request GET '{{authPath}}/{{envID}}/as/authorize?response_type=code&client_id={{appID}}&redirect_uri={{redirect_uri}}&scope=openid'

The request requires the following properties in the request URL:

• response_type: For an authorization_code grant the response type is code.

• client_id: The application's ID.

• redirect_uri: The URL to redirect the browser after sign on.

• scope: The permissions that specify accessible resources.

The response returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID for the sign-on workflow. For information about additional optional query parameters that can be set on the request, see Authorize (authorization_code).

Step 2: After the sign-on flow completes, call the resume endpoint.

curl --location --request GET '{{authPath}}/{{envID}}/as/resume?flowId={{flowID}}' \
--header 'Cookie: {{sessionToken}}'

The request requires the following properties in the request URL:

• flowID: The ID for the authentication flow.

The Location HTTP header returned by the resume endpoint contains the code. Note that the PingOne API uses session token cookies to establish the user's authentication session and maintain the session throughout the workflow, allowing the flow to redirect back to the authorization server to get the token.

Step 3: Call the token endpoint to exchange the authorization code for a token.

curl --location --request POST '{{authPath}}/{{envID}}/as/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code={{authCode}}' \
--data-urlencode 'redirect_uri={{redirect_uri}}'

The request requires the following properties in the request URL:

• grant_type: The grant type of the token request. In this example, the value is authorization_code.

• code: The authorization code value returned by the resume endpoint.

• redirect_uri: The URL that specifies the return entry point of the application.

The token endpoint response returns the access token, ID token, or both. For information about the authorization code token request based on the application's tokenEndpointAuthMethod, see Token.

Authorization code authorize request using POST

The authorize request using POST is essentially the same as GET. The POST request accepts all the same parameters as the GET request. For the POST request, parameters and their values are Form Serialized by adding the parameter names and values to the entity body of the HTTP request and specifying the Content-Type: application/x-www-form-urlencoded request header.

Step 1: Send an authorize request to the PingOne authorization server using POST.

curl --location --request POST '{{authPath}}/{{envID}}/as/authorize' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'response_type=code' \
--data-urlencode 'client_id={{appID}}' \
--data-urlencode 'redirect_uri={{redirect_uri}}' \
--data-urlencode 'scope=openid'

The request requires the following properties in the request URL:

• response_type: For an authorization_code grant the response type is code.

• client_id: The application's ID.

• redirect_uri: The URL to redirect the browser after sign on.

• scope: The permissions that specify accessible resources.

The response returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID for the sign-on workflow. For information about additional optional query parameters that can be set on the request, see Authorize (authorization_code).

Step 2: After the sign-on flow completes, call the resume endpoint.

curl --location --request GET '{{authPath}}/{{envID}}/as/resume?flowId={{flowID}}' \
--header 'Cookie: {{sessionToken}}'

Step 3: Call the token endpoint to exchange the authorization code for a token.

curl --location --request POST '{{authPath}}/{{envID}}/as/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code={{authCode}}' \
--data-urlencode 'redirect_uri={{redirect_uri}}'

For an implicit grant type, the response to the authorization request is an id_token, a token (access token), or both, depending on the value of the response_type parameter in the authorization request. The implicit workflow does not need to call the token endpoint. The response from the resume endpoint includes the token (or tokens) in the Location header.

PingOne supports GET and POST HTTP methods for initiating the implicit authorize request.

Implicit authorize request using GET

Step 1: Send an authorize request to the PingOne authorization server using GET.

curl --location --request GET '{{authPath}}/{{envID}}/as/authorize?response_type=token id_token&client_id={{appID}}&redirect_uri={{redirect_uri}}&scope=openid'

The request requires the following properties in the request URL:

• response_type: For an implicit grant the response type is token, id_token, or both.

• client_id: The application's ID.

• redirect_uri: The URL to redirect the browser after sign on.

• scope: The permissions that specify accessible resources.

The response returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID for the sign-on workflow. For information about additional optional query parameters that can be set on the request, see Authorize (implicit).

Step 2: After the sign-on flow completes, call the resume endpoint.

curl --location --request GET '{{authPath}}/{{envID}}/as/resume?flowId={{flowID}}' \
--header 'Cookie: {{sessionToken}}'

The request requires the following properties in the request URL:

• flowID: The ID for the authentication flow.

The Location HTTP header returned by the resume endpoint contains the token, ID token, or both. Note that the PingOne API uses session token cookies to establish the user's authentication session and maintain the session throughout the workflow, allowing the flow to redirect back to the authorization server to get the token.

Implicit authorize request using POST

The POST request accepts all the same parameters as the GET request. For the POST request, parameters and their values are Form Serialized by adding the parameter names and values to the entity body of the HTTP request and specifying theContent-Type: application/x-www-form-urlencoded` request header.

Step 1: Send an authorize request to the PingOne authorization server using POST.

curl --location --request POST '{{authPath}}/{{envID}}/as/authorize' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'response_type=token id_token' \
--data-urlencode 'client_id={{appID}}' \
--data-urlencode 'redirect_uri={{redirect_uri}}' \
--data-urlencode 'scope=openid' 

The request requires the following properties in the request URL:

• response_type: For an implicit grant the response type is token, id_token, or both.

• client_id: The application's ID.

• redirect_uri: The URL to redirect the browser after sign on.

• scope: The permissions that specify accessible resources.

The response returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID for the sign-on workflow. For information about additional optional query parameters that can be set on the request, see Authorize (implicit).

Step 2: After the sign-on flow completes, call the resume endpoint.

curl --location --request GET '{{authPath}}/{{envID}}/as/resume?flowId={{flowID}}' \
--header 'Cookie: {{sessionToken}}'

In a hybrid authorize flow, an authorization code is returned from the authorization endpoint, some tokens are returned from the authorization endpoint, and others are returned from the token endpoint. The authorization endpoint's response_type property specifies the code type and it also specifies id_token, or token, or both. An authorization code (specified by the code response type) is always returned in a hybrid flow.

PingOne supports GET and POST HTTP methods for initiating the authorize request.

Hybrid authorize request using GET

Step 1: Send an authorize request to the PingOne authorization server using GET.

curl --location --request GET '{{authPath}}/{{envID}}/as/authorize?response_type=code token&client_id={{appID}}&redirect_uri={{redirect_uri}}&scope=openid'

The request requires the following properties in the request URL:

• response_type: For a hybrid grant the response type always includes code, and it also specifies id_token, or token, or both.

• client_id: The application's ID.

• redirect_uri: The URL to redirect the browser after sign on.

• scope: The permissions that specify accessible resources.

The response returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID for the sign-on workflow. For information about additional optional query parameters that can be set on the request, see Authorize (hybrid).

Step 2: After the sign-on flow completes, call the resume endpoint.

curl --location --request GET '{{authPath}}/{{envID}}/as/resume?flowId={{flowID}}' \
--header 'Cookie: {{sessionToken}}'

The request requires the following properties in the request URL:

• flowID: The ID for the authentication flow.

The Location HTTP header returned by the resume endpoint contains the code. In addition, the Location header for a hybrid authorization flow also returns the token or ID token (or both) if specified in the response_type property.

Step 3: Call the token endpoint to exchange the authorization code for a token.

curl --location --request POST '{{authPath}}/{{envID}}/as/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code={{authCode}}' \
--data-urlencode 'redirect_uri={{redirect_uri}}'

The request requires the following properties in the request URL:

• grant_type: The grant type of the token request. In this example, the value is authorization_code.

• code: The authorization code value returned by the resume endpoint.

• redirect_uri: The URL that specifies the return entry point of the application.

The token endpoint exchanges the code for an access token, ID token, or both. For information about the authorization code token request based on the application's tokenEndpointAuthMethod, see Token.

Hybrid authorize request using POST

The authorize request using POST is essentially the same as GET. The POST request accepts all the same parameters as the GET request. For the POST request, parameters and their values are Form Serialized by adding the parameter names and values to the entity body of the HTTP request and specifying the Content-Type: application/x-www-form-urlencoded request header.

Step 1: Send an authorize request to the PingOne authorization server using POST.

curl --location --request POST '{{authPath}}/{{envID}}/as/authorize' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'response_type=code id_token' \
--data-urlencode 'client_id={{appID}}' \
--data-urlencode 'redirect_uri={{redirect_uri}}' \
--data-urlencode 'scope=openid'

The request requires the following properties in the request URL:

• response_type: For a hybrid grant the response type always includes code, and it also specifies id_token, or token, or both.

• client_id: The application's ID.

• redirect_uri: The URL to redirect the browser after sign on.

• scope: The permissions that specify accessible resources.

The response returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID for the sign-on workflow. For information about additional optional query parameters that can be set on the request, see Authorize (hybrid).

Step 2: After the sign-on flow completes, call the resume endpoint. The Location HTTP header returned by the resume endpoint contains the code. In addition, the Location header for a hybrid authorization flow also returns the token or ID token (or both) if specified in the response_type property.

curl --location --request GET '{{authPath}}/{{envID}}/as/resume?flowId={{flowID}}' \
--header 'Cookie: {{sessionToken}}'

Step 3: Call the token endpoint to exchange the authorization code for a token.

curl --location --request POST '{{authPath}}/{{envID}}/as/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code={{authCode}}' \
--data-urlencode 'redirect_uri={{redirect_uri}}'

For added security, you can also include Proof Key for Code Exchange (PKCE) parameters in the authorization request for the code and hybrid grant types. PKCE for OAuth uses either plain text or a cryptographic hash of a random string that is included in the authorization request (code_challenge) along with the encoding method used (code_challenge_method). When the authorization code is issued in the response, the original plain text or random string (code_verifier) is included in the token request.

Step 1: Send an authorize request to the PingOne authorization server.

curl --location --request GET '{{authPath}}/{{envID}}/as/authorize?response_type=code&client_id={{appID}}&redirect_uri={{redirect_uri}}&scope=openid&code_challenge={{codeChallenge}}&code_challenge_method=S256'

The request requires the following properties in the request URL:

• response_type: For an authorization_code grant the response type is code.

• client_id: The application's ID.

• redirect_uri: The URL to redirect the browser after sign on.

• scope: The permissions that specify accessible resources.

• code_challenge: A string that is computed from the code_verifier that is used in a Proof Key for Code Exchange (PKCE) authorization request.

• code_challenge_method: A string that specifies the computation logic used to generate the code_challenge string.

For more information about the PKCE query parameters that can be set on the request, see Authorize (authorization_code).

Step 2: After the sign-on flow completes, call the resume endpoint.

curl --location --request GET '{{authPath}}/{{envID}}/as/resume?flowId={{flowID}}' \
--header 'Cookie: {{sessionToken}}'

The request requires the following properties in the request URL:

• flowID: The ID for the authentication flow.

The Location HTTP header returned by the resume endpoint contains the code. Note that the PingOne API uses session token cookies to establish the user's authentication session and maintain the session throughout the workflow, allowing the flow to redirect back to the authorization server to get the token.

Step 3: Call the token endpoint to exchange the authorization code for a token.

curl --location --request POST '{{authPath}}/{{envID}}/as/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code={{authCode}}' \
--data-urlencode 'redirect_uri={{redirect_uri}}' \
--data-urlencode 'client_id={{appID}}' \
--data-urlencode 'code_verifier={{codeVerifier}}'

The request requires the following properties in the request URL:

• grant_type: The grant type of the token request. In this example, the value is authorization_code.

• code: The authorization code value returned by the resume endpoint.

• redirect_uri: The URL that specifies the return entry point of the application.

• client_id: The application's ID.

• code_verifier: A string used to verify the code_challenge value submitted in the authorization request.

The token request transforms the code_verifier property value using the code_challenge_method specified in the authorize request. If the transformed code_verifier value is equal to the code_challenge value submitted in the authorize request, then the authorization server issues the token.

For information about additional parameters supported by the authorization code token request, see Token.

If the grant type is device_code, PingOne returns an activation code in the response to the POST /{{envID}}/as/device_authorization request. This authorize endpoint is used only with device authorization grant flows. It starts a flow that gives OAuth enabled devices such as smart TVs the ability to complete user authorization and access protected resources.

Unlike the PingOne as/authorize request, which returns a 302 Location header in the response, the /as/device_authorization endpoint returns a 200 OK successful operation message. The response body returns the user_code property value (the activation code) as well as the verification URI (a short web address) that end users visit on another device to enter (or confirm) the activation code.

The steps below outline the device authorization grant flow.

Authorization for a device authorize grant request

The POST /{{envID}}/as/device_authorization request takes all configuration paramaters in the endpoint's request body. Parameters and their values are Form Serialized by adding the parameter names and values to the entity body of the HTTP request and specifying the Content-Type: application/x-www-form-urlencoded request header.

Step 1: Send an authorize request to the PingOne authorization server using POST.

curl --location --request POST '{{authPath}}/{{envID}}/as/device_authorization' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={{deviceAppID}}' \
--data-urlencode 'scope=openid'

The request requires the following properties:

• client_id: The application ID for an application that specifies the device_code grant type.

• scope: The permissions that specify accessible resources.

The response returns a 200 OK message with the following properties:

{
    "device_code": "96624b82-1469-46a9-a4f8-544970b62c37",
    "user_code": "GKHF-JQBC",
    "verification_uri": "https://auth.pingone.com/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/device",
    "verification_uri_complete": "https://auth.pingone.com/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/device?user_code=GKHF-JQBC",
    "expires_in": 600,
    "interval": 5
}

Step 2: Start the flow using GET {{authPath}}/{{envID}}/device/{{appIdentifier}} or GET {{authPath}}/{{envID}}/device.

The response returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID.

Step 3: The sign-on flow calls the POST /{{envID}}/flows/{{flowID}} flow orchestration endpoints to prompt the end user to complete the actions required by the sign-on policy, and perform the following two device code actions: (1) confirm the device activation code, and (2) accept device authorization grant consent.

This flow action confirms the activation code:

curl --location --request POST '{{authPath}}/{{envID}}/flows/{{flowID}}' \
--header 'Content-Type: application/vnd.pingidentity.deviceAuthGrant.userCode.verify+json' \
--data-raw '{
    "userCode": "{{userCode}}"
}'

This flow action accepts consent:

curl --location --request POST '{{authPath}}/{{envID}}/flows/{{flowID}}' \
--header 'Content-Type: application/vnd.pingidentity.deviceAuthGrant.consent+json' \
--data-raw '{
	"accept": true
}'

Step 4: Call the token endpoint to exchange the device code for a token. Note that the grant_type parameter in the request body uses the IETF-specified syntax to identify the device code grant type (urn:ietf:params:oauth:grant-type:device_code).

curl --location --request POST '{{authPath}}/{{envID}}/as/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
--data-urlencode 'device_code={{deviceCode}}' \
--data-urlencode 'client_id={{deviceAppID}}'

For more information about the endpoints used in a device authorization grant flow, see Device Authorization Grant and Device Authorization Grant Flows.

PingOne supports several application types. When you make a POST /environments/{{envID}}/applications request to define a new application, you must specify the type property that best describes the application. PingOne supports the following application types:

• Web application

  A browser-based application with a server-side component, such as ASP, CGI, JSP/Java, Node.js, or Ruby on Rails applications.

• Native application

  An application that is installed and run directly on the local operating system, like Java, Objective-C, Swift, or React applications. Native applications are typically intended for native devices.

• Single page application

  A browser-based application that runs on the front-end with no server-side component, such as Sencha Touch, AngularJS, and React applications. A single page application runs on the client side after it loads, so it cannot keep a client secret.

• Non-interactive

  A web application that does not require user interaction through the web browser, like a command line interface, a service, or a daemon.

• Worker

  An administrator application that can interact with platform APIs. Access to platform APIs is determined by the user's or application's role assignments.

Authorization flow steps

An authorization grant gives applications the capability to authenticate users and access secure resources. The following steps describe the application authorization flow:

1. The application initiates the authorization flow through a GET or POST request to the authorize endpoint.

2. The authorization service generates the access token for the implicit grant.

3. For authorization_code and client_credentials grants, the application calls the /{{envID}}/as/token endpoint to acquire the access token.

For more information about authorization, see OpenID Connect/OAuth 2.

Authorization requests for application types

The following topics describe common authorization requests for the designated application type.

For web applications, the typical grant type to request access to protected resources is authorization_code. The /{{envID}}/as/authorize endpoint supports GET and POST methods and returns the authorization code needed to acquire an access token. After an authorization code is returned successfully, the code is used to get the access token.

The following sample shows the GET /{{envID}}/as/authorize operation.

https://auth.pingone.com/{{envID}}/as/authorize?response_type=code&client_id={{appID}}&redirect_uri={{redirect_uri}}&scope=openid%20profile%20email&acr_values=Single_Factor&prompt=login

The request URL contains the following parameter values:

• response type

  Specifies the response type for the authorization request. If the grant type is authorization_code, the response_type parameter must have a value of code. This parameter is required.

• client_id

  Specifies the application's UUID, returned from a GET /environments/{{envID}}/applications/{{appID}} request. This parameter is required.

• redirect_uri

  Provides a URL that specifies the return entry point of the application. This parameter is required.

  Note: To ensure proper redirect on some iOS and OSX browsers, the redirect_uri value must include a trailing slash. For example, a registered URI of https://www.pingidentity.com/ redirects properly to https://www.pingidentity.com/#access_token=eyJsdf, but a registered URI of https://www.pingidentity.com redirects incorrectly to https://www.pingidentity.com/en.html, and the client application would not receive the access token.

• scope

  Specifies permissions that determine the resources that the application can access. This parameter is not required, but it is needed to specify accessible resources.

• acr_values

  An optional parameter that designates whether the authentication request includes specified sign-on policies. Sign-on policy names should be listed in order of preference, and they must be assigned to the application. For more information, see Sign-on policies.

• prompt

  An optional parameter that specifies whether the user is prompted to login for re-authentication. The prompt parameter can be used as a way to check for existing authentication, verifying that the user is still present for the current session.

The authorization request returns a URL to initiate login flow. This authentication flow presents appropriate login forms to an end user and submits data provided by the user for all required sign-on steps. After all login actions in the flow are completed, the GET /{{envID}}/as/resume endpoint continues processing the authorization request.

https://auth.pingone.com/{{envID}}/as/resume?flowId={{flowID}}

After restarting the authorization flow, the authorization code is submitted through a request to the POST /{{envID}}/as/token endpoint to create the access token.

curl --request POST \
  --url 'https://auth.pingone.com/{{envID}}/as/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code&code={{authCode}}&redirect_uri={{redirect_uri}}'

The grant_type, code, and redirect_uri parameter values are required in the request body.

For native applications and single-page applications, the default grant type to request access to protected resources is implicit.

For the implicit flow, the application is issued an access token without requiring an authorization code exchange. When the request is made to the /{{envID}}/as/authorize endpoint for an implicit grant type, the value of the response_type parameter is set to token or id_token.

If the request contains the id_token response type and the openid scope, then it is considered an authentication (OpenID Connect) request, and an ID token is issued. The ID token includes the ID of the user; this request can also include the profile, email, address, and phone OIDC scopes to add additional user claims to the ID token.

The following sample shows the GET /{{envID}}/as/authorize operation to return an id_token.

https://auth.pingone.com/{{envID}}/as/authorize?client_id={{appID}}&redirect_uri={{redirect_uri}}&response_type=id_token&scope=openid%20profile%20email&acr_values=Single_Factor&max_age=86400

The request can specify the token or id_token response types individually, or both. The following sample shows the GET /{{envID}}/as/authorize operation to return a token and an id_token:

curl --request GET \
  --url 'https://auth.pingone.com/{{envID}}/as/authorize?client_id={{appID}}&redirect_uri={{redirect_uri}}&response_type=token id_token&nonce=12345&scope=openid profile p1:read:user&acr_values=Single_Factor&max_age=86400'

In this request, the p1:read:user scope is included in the access token but not in the ID token.

The request URL contains the following parameter values:

• response type

  Specifies the response type for the authorization request. The implicit grant type requires a response_type parameter value of token or id_token (or both). This parameter is required.

• client_id

  Specifies the application's UUID, returned from a GET /environments/{{envID}}/applications/{{appID}} request. This parameter is required.

• redirect_uri

  Provides a URL that specifies the return entry point of the application. This parameter is required.

  Note: To ensure proper redirect on some iOS and OSX browsers, the redirect_uri value must include a trailing slash. For example, a registered URI of https://www.pingidentity.com/ redirects properly to https://www.pingidentity.com/#access_token=eyJsdf, but a registered URI of https://www.pingidentity.com redirects incorrectly to https://www.pingidentity.com/en.html, and the client application would not receive the access token.

• nonce

  A string that is used to associate a client session with a token to mitigate replay attacks. The value is passed through unmodified from the authentication request to the token. This is a required property for authorization requests that return a token. It is not required for requests that return only an id_token.

• scope

  Specifies permissions that determine the resources that the application can access. This parameter is not required, but it is needed to specify accessible resources.

• acr_values

  An optional parameter that designates whether the authentication request includes specified sign-on policies. Sign-on policy names should be listed in order of preference, and they must be assigned to the application. For more information, see Sign-on policies.

• max_age

  An optional parameter that specifies the maximum amount of time allowed since the user last authenticated. If the max_age value is exceeded, the user must re-authenticate.

After all login action steps in the flow are completed successfully, the GET /{{envID}}/as/resume endpoint is called to continue processing the authorization request.

https://auth.pingone.com/{{envID}}/as/resume?flowId={{flowID}}

The authorization service generates the token or id_token for the application after restarting the authorization flow; it does not require a step to call the /{{envID}}/as/token endpoint.

Non-interactive applications support the client_credentials, authorization_code, implicit, and refresh_token grant types to obtain an access token. For information about authentication flows for applications using the authorization_code and implicit grant types.

The following sample shows the POST request to the /{{envID}}/as/token endpoint to acquire the access token. Note that the application must have its tokenEndpointAuthMethod attribute value set to client_secret_post.

curl --request POST \
  --url 'https://auth.pingone.com/{{envID}}/as/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials&client_id={{appID}}&client_secret={{secret}}'

The request URL contains the following parameter values:

• grant_type

  Specifies the grant type for the authorization request, which for non-interactive applications must be a client_credentials grant. This parameter is required.

• client_id

  Specifies the application's UUID, returned from a GET /environments/{{envID}}/applications/{{appID}} request. This parameter is required.

• client_secret

  Specifies the application's client secret, returned from a GET /environments/{{envID}}/applications/{{appID}}/secret request. This parameter is required.

For client_credentials requests in which the application's tokenEndpointAuthMethod attribute value is set to client_secret_basic, the client_id and client_secret attributes cannot be part of the request body. In these cases, the client_id and client_secret are passed in as a Base64 encoded authorization header in the request:

curl --request POST \
 --url 'https://auth.pingone.com/{{envID}}/as/token' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --user 'client_id:client_secret' \
 --data 'grant_type=client_credentials'

The --user 'client_id:client_secret' option tells curl to use a BASIC authentication header with the specified credentials in the request, which is similar to this:

Authorization: Basic <base64 encoded "client_id:client_secret">

Worker applications are administrator applications that interact with platform APIs. This application type supports only the OPENID_CONNECT protocol. When creating a new worker application, the application inherits the same role assignments as the user or application that created the application. When getting a token using the client_credentials grant type, the application's role assignments are used.

Worker applications that use a user-based grant type such as implicit or authorization_code let you assign only OIDC scopes to the application. When getting a token using a user-based grant type, the user's role assignments are used.

The following sample shows the /{{envID}}/as/token request with a client_credentials grant to return an access token with no platform scopes.

curl --request POST \
 --url 'https://auth.pingone.com/{{envID}}/as/token' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data 'grant_type=client_credentials&client_id={{appID}}&client_secret={{secret}}'

The response returns the access_token, the token_type, and the expires_in property values. It does not list any scopes.

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InRlc3QifQ.eyJzY29wZSI6IiIsImNsaWVudF9pZCI6ImlkZW50aXR5LW...",
  "token_type": "Bearer",
  "expires_in" : 3600
}

User applications rely on self-management scopes to grant users access to a subset of PingOne resources. For more information about scopes, see Resource scopes. Conversely, administrator applications use role assignments to determine the actions a user or client can perform. For more information about roles, see Roles.

For detailed information about scopes, see the following topics:

• PingOne self-management scopes

• OpenID Connect (OIDC) scopes

• Custom scopes

Self-management scopes are applicable to users only. They are granted on authorization_code and implicit authorization flows. PingOne self-management scopes cannot be granted on a client_credentials flow.

The self-management scopes specified in an authorization request identify the resources that end users can access to perform self-management actions. These scopes use the following naming format to represent a self-management permission:

p1:<permission-action>:<permission-classifier>

For example, the self-management scope to read user information is p1:read:user.

The PingOne platform includes the following self-management scopes:

User scopes enable self-service actions

User scopes provide privileges to specific actions, giving end users the ability to interact with their own profile data. An example of a commonly used user scope is p1:reset:userPassword. This scope, when included in an authorization request, generates access tokens that give users permission to run the self-service password reset action.

The following sample shows an authorization_code request that includes the reset password scope.

curl --request GET \
  --url 'https://auth.pingone.com/{{envID}}/as/authorize?response_type=code&client_id={{appID}}&redirect_uri={{redirect_uri}}&scope=p1:reset:userPassword'

For more information about authorization requests, see OpenID Connect/OAuth 2.

Access control self scopes

Some PingOne platform self-management scopes allow organizations to specify which user profile attributes are accessible to end users. An administrator might want to prevent end users with access to their profiles from seeing or modifying particular attributes that should remain private, such as custom attributes for entitlements, internal foreign keys, account status information, or any profile data that should not be exposed to an individual user. With access control scopes, organizations can store additional private data in the user profile without risk that the end user can see the data.

The following scopes allow access control:

For example, an access control scope based off of p1:update:user (such as p1:update:user:name that specifies only the ['name.family', 'name.given'] user attribute in the scope's schemaAttributes property) allows self updates of the first and last name attributes only. For more information about self-scope properties, see Resource scopes.

When the actor is self, the following behaviors apply to the p1:read:user and p1:read:user:{{suffix}} access control scopes for a GET /environments/{{envID}}/users/{{userID}} request:

• Attributes that are not included in any provided read scope are excluded from output, except for the id attribute, which is always included in the response if any other user schema attributes are returned.

• An attribute that is included in a read scope and present in the user record is included in the response body.

• An attribute that is not included in a read scope and present in the user record is excluded from the response body.

If no attributes are included in the provided read scopes (if self has no access), then an HTTP Status 403 error is returned.

Likewise, the following behaviors apply to the p1:update:user and p1:update:user:{{suffix}} access control scopes for a PUT /environments/{{envID}}/users/{{userID}} request:

• Attributes that are not included in any provided updates scope are not accessible to end users for update.

• Immutable attributes such as id even if included, are not updated. Attempts to update immutable user attributes are ignored.

• An attribute that is included in an update scope and present in the user record is accessible to update, unless it is immutable.

• An attribute that is not included in an update scope and present in the user record is not accessible to update.

• Multi-value attribute updates replace the entire attribute. It is not possible to merge data into an existing set of values.

• The multiValued property of an attribute can only be changed from false or null to true, never from true to false.

These scopes are not granted if the user authenticates with an authoritative identityProvider (user.identityProvider.id is not null).

If the user does not have update access to an attribute, a 403 Forbidden error is returned if an update is attempted for that attribute.

Restricted access scopes

License capabilities control access to some PingOne self-service scopes. Your PingOne license can disable access to specific scopes (and their associated permissions) based on the capabilities enabled by the license package. For example, if your PingOne license supports only MFA capabilities, then other self-service capabilities such as canUsePasswordManagement, canUseIdentityProviders, and canUsersUpdateSelf are set to false in the license. With these capabilities set to false, access to the scopes controlled by these capabilities are restricted.

The following capabilities control access to these associated scopes:

If the controlling capability is set to false, authorization requests that specify restricted scopes will not grant a token that includes the restricted scopes. However, if the authorization request also specifies a non-restricted platform scope, such as p1:read:user, the request returns a token that includes only the p1:read:user scope.

The following self-service scopes are not granted if the user authenticates with an authoritative identityProvider (user.identityProvider.id is not null).

• p1:update:user
• p1:update:user:{{suffix}}
• p1:read:userPassword
• p1:reset:userPassword
• p1:validate:userPassword
• p1:read:userLinkedAccounts
• p1:delete:userLinkedAccounts

Standard OpenID Connect scopes control which user claims are included in an id_token or in a userinfo response. Unlike other resources, scopes from this resource can be included in an access token along with scopes from another resource.

PingOne supports the following OIDC scopes:

The following sample shows an implicit authorization request with an id_token response type. The scope parameter specifies the required openid scope. It also specifies the optional profile scope to provide access to the end-user's default profile claims.

curl -X GET \
  'https://auth.pingone.com/{{envID}}/as/authorize?client_id={{appID}}&redirect_uri={{redirect_uri}}&response_type=id_token&scope=openid%20profile'

For more information about retrieving scopes for a specified resource, see Get scopes for a resource.

Resources are the protected endpoints that applications request access to using OAuth 2 authorization services. The PingOne platform includes two predefined resources, PingOne API, which is a defined resource that represents the PingOne APIs, and openid, which represents OpenID Connect scopes. These resources have self scopes that grant an actor permission to perform CRUD operations on the actor's data (such as p1:create:device, p1:read:device, p1:update:device, and p1:delete:device).

In addition, the platform lets you configure additional resources and their associated self scopes. For example, a custom resource such as https://api.acme-photo.com might have upload:photos, read:photos, edit:photos, and delete:photos scopes that give users permission to manage their photo libraries.

PingOne supports the following two types of resource scopes.

Custom resource scopes

Custom resource scopes are associated with protected endpoints on a non-PingOne resource server. Custom resources can be associated with an application either exclusively, or in addition to the platform's predefined resources. When an application is associated with both the PingOne platform resource and a custom resource, an authorization request cannot include scopes from both PingOne and the custom resource.

If you do specify scopes from two different resources in the authorize request, the request returns the following error:

The request could not be completed. One or more validation errors were in the request.: May not request scopes for multiple resources (Correlation ID: 8E7B23B8-6761-4532-8AFC-4B723D52FF5D).

If more than one resource is associated with the application, actors need to make separate authorization requests to get a token for the desired resource scopes.

For more information about defining scopes for custom resources, see Create scope.

Custom PingOne API scopes

Custom PingOne API scopes control access to specific user schema attributes. As described above, a PingOne platform custom scope is based on an existing platform scope and uses the schemaAttributes property in the scope's definition to list the specific user attributes that the end user has permission to read or update. For example, a scope that grants permission to update only the user's email address would list only the email attribute in the schemaAttributes property. This PingOne custom scope is named by adding a descriptive suffix to the base PingOne scope name: p1:update:user:email-only.

For more information about defining custom PingOne API scopes, see Create PingOne access control scope.

Unlike user self-service applications, administrator applications use role assignments to determine the actions a user or client can perform. For external API client applications, the access tokens do not use scopes to control access to resources. Instead, the actor's role assignments determine resource access.

Worker application permissions

Administrator applications that interact with non-self Platform APIs are classified as a WORKER application type. This application type supports only the OPENID_CONNECT protocol. A worker application that uses the client_credentials grant type inherits the same role assignments as the user or application that created the application. These role assignments can be cross-environment, which allows access to APIs for other environments.

Role assignments determine access to APIs (see Application role assignments and User role assignments. Users and clients cannot create or use clients that have more privileges than the worker application itself. For example, an actor with only the Identity Data Admin role cannot create a worker application that has Environment Admin privileges. Likewise, access to an application's client secret is restricted based on the accessing user's or application's role assignments. If an actor has only the Identity Data Admin role, it is not able to see the client secret. Similar roles can have different privileges, or restrictions, based on the role's scope. For example, an actor with an Environment Admin role over a single environment cannot access the client secret of an application with Environment Admin privileges over the entire organization.

PingOne roles include a set of permissions that allow access to PingOne resources. For example, the Identity Data Admin role grants access to PingOne resources for these user management actions:

• Read, create, update, and delete user resources
• Read, create, update, and delete device management resources
• Assign identity resources
• Bulk user import
• Read, create, update and delete population resources
• Update user password resources
• Read user password state resources
• Read password policy resources
• Read audit reporting activities resources
• Read schema resources

The actor (user or client) assigning roles to the application must have the permissions that they are trying to assign. In other words, the requesting user or client must have the same (or broader) role assignments as the target application's role assignments. This prevents a lesser privileged user (such as a Client Application Developer) from creating a more privileged client_credentials application (such as an Environment Admin).

When retrieving access tokens for WORKER applications, the authorization service checks to make sure the user or client has at least one role assignment. If not, the token request is rejected. If at least one role assignment exists, the authorization service creates a token with no scopes except for the requested OIDC scopes. When accessing platform APIs with this token, it retrieves the actor's entitlements, which ensures that clients and users can access only the resources that their role assignments allow.

Worker applications and environments

When a worker application with Environment Admin privileges creates a new environment, that application is given Identity Data Admin and Client Application developer role assignments for the new environment. Only the worker application can perform Identity Data Admin operations in that environment (see the list of Identity Data Admin actions above). However, the worker application can give the same role assignment to another user or worker application.

The applications data model includes optional accessControl properties that, when set, specify the conditions that must be met by an authenticating actor to access the application. The application properties that control application access are:

• accessControl.role.type

  This property specifies that an administrator role is required to access the application. When set, the only option for this property is ADMIN_USERS_ONLY, which means that the actor must be assigned at least one or more of the following administrator roles: Organization Admin, Environment Admin, Identity Data Admin, or Client Application Developer. For more information about roles, see Roles. If this property is not set, access to the application is not restricted by administrator roles.

• accessControl.group.type

  This property specifies that the actor must be associated with a particular group (or groups) to access the application. When set, this property can be set to ANY_GROUP, which means that the actor must be a member of at least one group specified in the accessControl.group.groups property. This property can also be set to ALL_GROUPS, which means that the actor must belong to all groups specified in the accessControl.group.groups property. If this property is not set, access to the application is not restricted by groups.

• accessControl.group.groups

  This property specifies a list of one or more groups that control access to the application. If there is more than one group, then the actor must belong to at least one group (if ANY_GROUP is the value of accessControl.group.type) or all groups (if ALL_GROUPS is the value of accessControl.group.type). If this property is not set, access to the application is not restricted by groups.

Application access control for OpenID Connect applications

When accessControl properties are set for an application, the authenticating actor must meet the requirements specified in the application's accessControl properties to get a token.

To implement role-based application access control:

1. Set the accessControl.role.type property value to ADMIN_USERS_ONLY.

2. Ensure that the authenticating actor has at least one assigned administrator role.

If the actor has an assigned administrator role, a token is issued that allows access to the application.

To implement group-based application access control:

1. Set the accessControl.group.type and accessControl.group.groups properties. (If you set one of the application's access control group properties, you must set the other.)

2. Set the property value for the accessControl.group.type. The options are ANY_GROUP and ALL_GROUPS.

3. Set the accessControl.group.groups property value to list the group IDs to which an actor must belong. For information about obtaining group IDs, see Groups.

If the actor belongs to at least one group (for the ANY_GROUP type), or all groups (for the ALL_GROUPS type), a token is issued that allows access to the application.

Application access control for SAML applications

When accessControl properties are set for a SAML application, the authenticating actor must meet the requirements specified in the application's accessControl properties to get an assertion. The steps to define the accessControl properties for role-based and group-based conditions are the same as for OIDC applications. If the authenticating actor meets the the application's access control conditions, an assertion is created. If the conditions are not met, a sign-on attempt returns an authorization failed error.

The PingOne API Toolkit groups PingOne endpoints into common authorization, authentication, and configuration actions for use as building blocks in your flows. For example, if you're building a login flow that returns an authorization code to exchange for an access token, the Auth collection contains the requests you need to configure this flow. Likewise, the Management collection provides grouped endpoints to manage users, create and manage devices, update password policies, and many others.

To download the collections, click the Run in Postman buttons associated with each collection.

Toolkit group	Server domain	Collection link
Authorization and authentication APIs	https://auth.pingone.com
Management APIs	https://api.pingone.com/v1

The Authorization and Authentication APIs collection includes the following endpoint operations.

The Management APIs collection includes endpoints for the following admin configuration actions:

• Applications

• Users

• MFA

• Sign-on policies

• Password policies

• Metrics

Application management configuration

User management configuration

MFA configuration

Password configuration

Sign-on policy configuration

Metrics configuration

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

Prerequisite

To access the PingOne APIs, you'll first need to create an application connection, and get the assigned access token. See Getting started in our Developer Guide for instructions.

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.

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, 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 (and part of the path) for the PingOne server. These IDs identify a specific configured application in PingOne. Options are: https://api.pingone.com/v1 for environments the North America region (excluding Canada), https://api.pingone.ca/v1 for environments in the Canada region, https://api.pingone.eu/v1 for environments in the European Union region, and https://api.pingone.asia/v1 for environments in the Asia-Pacific region. Note that the trailing /v1 is required in the {{apiPath}} variable.

• {{authPath}}

  The regional domain for the PingOne authentication server. Options are: https://auth.pingone.com for the North America region (excluding Canada), https://auth.pingone.ca for the Canada region, https://auth.pingone.eu for the European Union region, and https://auth.pingone.asia for the Asia-Pacific region. Note that nothing trails the domain in the {{authPath}} variable.

• {{orchestratePath}}

  The regional domain (and part of the path) for the PingOne DaVinci server. Options are: https://orchestrate-api.pingone.com/v1 for the North America region (excluding Canada), https://orchestrate-api.pingone.ca/v1 for the Canada region, https://orchestrate-api.pingone.eu/v1 for the European Union region, and https://orchestrate-api.pingone.asia/v1 for the Asia-Pacific region. Note that the trailing /v1 is required in the {{orchestratePath}} variable.

• {{scimPath}}

  The regional domain (and part of the path) for the PingOne SCIM server. Options are: https://scim-api.pingone.com/v1 for the North America region (excluding Canada), https://scim-api.pingone.ca/v1 for the Canada region, https://scim-api.pingone.eu/v1 for the European Union region, and https://scim-api.pingone.asia/v1 for the Asia-Pacific region. Note that the trailing /v1 is required in the {{scimPath}} variable.

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

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.

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:

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

Prerequisites

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

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

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

To test the execution of a SAML identity provider 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

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

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

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

This activity shows you how to create a 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 you created in Getting Started with the PingOne APIs. 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 Worker Application Access Token.

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 you created in Getting Started with the PingOne APIs. 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 Worker Application 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/ 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.

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 /{{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 you created in Getting Started with the PingOne APIs. 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 Worker Application Access Token.

Workflow order of operations

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

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

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

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

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

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

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

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

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

The following operations are supported by the PingOne APIs:

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

Prerequisites

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

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

This activity shows you how to 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 you created in Getting Started with the PingOne APIs. 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 Worker Application Access Token.

Workflow order of operations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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