PingOne for Developers
PingOne for Developers is intended to get you up and running quickly, taking you through the steps to create your first worker application and obtain an access token, which is needed to interact with PingOne APIs. In addition, this guide also provides topics to help you answer the "big picture" questions you might have about the PingOne platform.
PingOne API domains
The PingOne API includes the following regional domains.
-
api.pingone.com
,api.pingone.ca
,api.pingone.eu
,api.pingone.asia
, andapi.pingone.com.au
These are the primary domains for calling PingOne Management API resource server, with
api.pingone.com
used for environments in the North America region (excluding Canada),api.pingone.ca
for environments in the Canada region,api.pingone.eu
for environments in the European Union region,api.pingone.asia
for environments in the Asia-Pacific region, andapi.pingone.com.au
for environments in the Australia region.The
{{apiPath}}
variable in the sample requests represents the regional domain for the PingOne server. This variable stands forhttps://api.pingone.com/v1
for environments in 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,https://api.pingone.asia/v1
for environments in the Asia-Pacific region, andhttps://api.pingone.com.au/v1
for environments in the Australia region. Note that the trailing/v1
is required. -
auth.pingone.com
,auth.pingone.ca
,auth.pingone.eu
,auth.pingone.asia
, andauth.pingone.com.au
This is the authorization and authentication server domain called to request the access token required to authenticate PingOne API requests, with
auth.pingone.com
used for environments in the North America region (excluding Canada),auth.pingone.ca
for the Canada region,auth.pingone.eu
for the European Union region,auth.pingone.asia
for the Asia-Pacific region, andauth.pingone.com.au
for the Australia region.The
{{authPath}}
variable in the sample requests represents the regional domain for the PingOne authentication server. This variable stands forhttps://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,https://auth.pingone.asia
for the Asia-Pacific region, andhttps://auth.pingone.com.au
for the Australia region. Note that nothing trails the domain in the{{authPath}}
variable. -
orchestrate-api.pingone.com
,orchestrate-api.pingone.ca
,orchestrate-api.pingone.eu
,orchestrate-api.pingone.asia
, andorchestrate-api.pingone.com.au
These are the primary domains for calling the PingOne DaVinci Management API resource server, with
orchestrate-api.pingone.com
used for environments in the North America region (excluding Canada),orchestrate-api.pingone.ca
for environments in the Canada region,orchestrate-api.pingone.eu
for environments in the European Union region,orchestrate-api.pingone.asia
for environments in the Asia-Pacific region, andorchestrate-api.pingone.com.au
for environments in the Australia region.The
{{orchestratePath}}
variable in the DaVinci requests documentation represents the regional domain for the PingOne server. This variable stands forhttps://orchestrate-api.pingone.com/v1
for environments in the North America region (excluding Canada),https://orchestrate-api.pingone.eu/v1
for environments in the European Union region,https://orchestrate-api.pingone.ca/v1
for environments in the Canada region,https://orchestrate-api.pingone.asia/v1
for environments in the Asia-Pacific region, andhttps://orchestrate-api.pingone.com.au/v1
for environments in the Australia region. Note that the trailing/v1
is required. -
scim-api.pingone.com
,scim-api.pingone.ca
,scim-api.pingone.eu
,scim-api.pingone.asia
, andscim-api.pingone.com.au
These are the primary domains for calling the PingOne System for Cross-domain Identity Management (SCIM) API resource server, with
scim-api.pingone.com
used for environments in the North America region (excluding Canada),scim-api.pingone.ca
for environments in the Canada region,scim-api.pingone.eu
for environments in the European Union region,scim-api.pingone.asia
for environments in the Asia-Pacific region, andscim-api.pingone.com.au
for environments in the Australia region.The
{{scimPath}}
variable in the SCIM requests documentation represents the regional domain for the PingOne SCIM server. This variable stands forhttps://scim-api.pingone.com
for environments in the North America region (excluding Canada),https://scim-api.pingone.eu
for environments in the European Union region,https://scim-api.pingone.ca
for environments in the Canada region,https://scim-api.pingone.asia
for environments in the Asia-Pacific region, andhttps://scim-api.pingone.com.au
for environments in the Australia region.
Getting Started with the PingOne APIs
To begin using the PingOne Platform APIs, you'll need to first:
-
Create an application connection using the PingOne admin console application.
-
Get the application's access token (a JSON Web Token) for the application you created.
-
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.
-
(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.
Create an application connection
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:
-
Click Applications > Applications.
-
Click the + icon next to Applications in the heading.
-
In the Application Name field, enter an application name.
-
Click Save.
-
On the application's Roles tab, click Grant Roles.
-
Select the check box for the role(s) you want to assign to the application.
-
Click Save.
-
Click the toggle at the upper right of the application page to enable the application.
-
Click Save.
-
On the application's Overview page, click the toggle at the upper right to enable the application.
Get an access token
To get the access token you created in Create an application connection:
-
Click the application's Configuration tab.
-
Scroll down and click to expand the General section.
-
Scroll down to the Advanced section and click Get Access Token.
-
From the Access Token window, click the copy icon and then click Done.
To get your environment ID from the Admin Console:
-
Click Settings.
-
Click Environment.
-
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 Authorization request header field, the accessToken
value is your full base64url-encoded JSON web token generated by the PingOne authentication service.
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"
In the Australia region:
curl -X GET "https://api.pingone.com.au/v1/environments/{{envID}}" \
-H "Authorization: Bearer accessToken"
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.
Read Environment API
Get a Worker Application Access Token
Download the PingOne Postman collections
The Postman master collections includes requests for all create, read, update, and delete (CRUD) operations for the PingOne Platform APIs, the PingOne MFA APIs, and the PingOne Protect APIs. The downloads also include a PingOne Postman environment template to help you assign values to variables in the request URLs.
For more information about the Postman environment template, see 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.
-
Fork the collection into your workspace. Postman retains an association between the source and your fork. If Ping Identity changes the source collection, you can pull those changes into the fork in your workspace.
-
Import the collection into your workspace. This is a one-time transfer and retains no association to the source collection.
To retrieve the collection:
-
Click the collection's Run In Postman button.
-
At the prompt, click Fork Collection at the bottom of the dialog or click import a copy near the bottom of the dialog.
-
Follow the on-screen instructions to fork or import the collection. You might be prompted to open your Postman app and to select a Postman workspace for the retrieved collection.
The environment downloaded with the collection of requests contains every variable used in the collection. Each request that creates a new object with an id
has a script that:
-
If not available, creates an environment variable unique to that service.
-
Assigns the
id
of the newly created object to that environment variable.
Use the PingOne Postman environment template
The Postman collection uses variables in the request URLs to specify UUIDs for PingOne resources within your organization. When you click the Run in Postman button 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.
Notes about environment variables and security
It is important to understand how Postman allows you to Store and reuse values using variables. Postman has two values for each environment variable: an Initial value and a Current value. Pay particular attention to differences between Initial and current values. Initial values are saved to Postman's cloud and available to anyone who has access to the environment. Current values are saved only locally and available only to you. Postman uses only the current value in requests. If an environment variable has an initial value but no current value, Postman does not copy it to the current value or use the initial value in the request, the request simply fails. You must manually copy the initial value to the current value.
In Sharing and persisting data, Postman states: "When you create a new variable in Postman, if you leave the current value empty, it will autofill with the initial value." Note that opening clause: "When you create a new variable in Postman"! When you create a new variable with an initial value and save the environment, Postman autofills the current value. However, that is the only time that Postman autofills the current value. If you subsequently delete the current value, the variable is no longer valued in a request.
Saving initial values to the cloud impacts security, especially if a workspace is public, because initial values are available to anyone who has access to the workspace. If a workspace is public, then literally the entire world can view!
While documented, Postman now emphasizes security of initial values as discussed in Announcing security updates to the Public API Network: new secret-protection policy. The recommended solution to exposing secrets is to Store secrets in your Postman Vault. Use the Postman Vault to Create and manage vault secrets. Remember that Postman uses only current values in requests!
To use a vault variable as the value for another Postman variable, you must add your vault variable to the initial value for your teammates to view and to the current value for a request to use it. For example, a request uses an environment variable called my-secret
. One user may choose to use the current value to store their value and leave the initial value blank. Another user may choose to use a Postman Vault variable, such as my-secret-vault
, as the value. The former user must ensure that they do not use the initial value if they do not wish to share its value with the team. The latter user can safely use {{vault:my-secret-vault}}
as both the initial value and the current value because Postman saves only the text: the name of the vault variable as the text literal, {{vault:my-secret-vault}}
. At run time, Postman acquires the value from the user's Vault.
As seen in the previous example, the vault variable need not be named the same as the environment variable. A Postman Vault is exclusively yours and its variables are available for use anywhere Postman variables are used. Thus, if you have multiple environments and each has a different value, then you must differentiate the variable names in your Vault. If you had a PROD environment and a STAGE environment, then you could have my-secret-prod
and my-secret-stage
in your vault for the two environments.
Variables you must value
When you Download the PingOne Postman collections, your workspace receives a Postman environment variable template. Variables in the environment variable template that represent a resource in PingOne automatically receive a value when you create a new PingOne resource using Postman. A script on the Tests tab of each create request inserts the identifier of the resource it creates as the value of the variable associated with that resource. However, some variables essential to using Postman with PingOne are not valued automatically. You must manually add the correct value to the variables in this table before you make any requests in Postman.
Postman variable | PingOne resource |
---|---|
adminAppID |
The Client ID of the worker app when you Create an application connection. Used with authorization type of Bearer Token . |
adminAppSecret |
The Client Secret of the worker app when you Create an application connection. Used with authorization type of Bearer Token . |
adminEnvID |
The identifier for your administrative environment. This should be the environment in which your worker app resides. This prevents accidentally overwriting your administrative environment identifier should you use the API in Postman to create a new environment, which will overwrite the existing envID . |
envID |
The identifier for the environment in which you are running your Postman API requests. |
orgID |
The identifier for your organization. In PingOne Console, click Environment and click Properties to view your organization identifier. |
apiPath |
The regional domain for the PingOne management server. Options are: https://api.pingone.com/v1 for environments in 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, https://api.pingone.asia/v1 for environments in the Asia-Pacific region, and https://api.pingone.com.au/v1 for environments in the Australia region. |
authPath |
The regional domain for the PingOne authorization and 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, https://auth.pingone.asia for the Asia-Pacific region, and https://auth.pingone.com.au for the Australia region. |
orchestratePath |
The regional domain for the PingOne DaVinci management server. Options are: https://orchestrate-api.pingone.com/v1 for environments in the North America region (excluding Canada), https://orchestrate-api.pingone.eu/v1 for environments in the European Union region, https://orchestrate-api.pingone.ca/v1 for environments in the Canada region, https://orchestrate-api.pingone.asia/v1 for environments in the Asia-Pacific region, and https://orchestrate-api.pingone.com.au/v1 for environments in the Australia region. |
scimPath |
The regional domain for the PingOne DaVinci management server. Options are: https://scim-api.pingone.com for environments in the North America region (excluding Canada), https://scim-api.pingone.eu for environments in the European Union region, https://scim-api.pingone.ca for environments in the Canada region, https://scim-api.pingone.asia for environments in the Asia-Pacific region, and https://scim-api.pingone.com.au for environments in the Australia region. |
Postman Collection-Level Authorization
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:
-
Change the Authorization tab in Postman for your collection to your choice of Type, such as Bearer Token or OAuth 2.0.
-
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:
-
Copy
access_token
from the response. -
Use the access token in subsequent requests until it expires.
-
Repeat these steps.
Bearer Token
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:
-
Click on the collection.
-
Click the Authorization tab.
-
Select
Bearer Token
from Type. -
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:
-
Run Token Admin App (client_credentials).
The script on the Tests tab sets the
{{accessToken}}
environment variable toaccess_token
from the response. -
Postman applies
{{accessToken}}
to requests with AuthorizationInherit auth from parent
until it expires. -
Repeat these steps.
OAuth 2.0
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:
-
Click on the collection.
-
Click the Authorization tab.
-
Select
OAuth 2.0
from Type. -
Select
Request Headers
from Add auth data to. -
In Token, select any unexpired token previously generated.
-
In Header Prefix, type
Bearer
.You must Configure New Token, if none are available in Token.
-
In Token Name, type any name. If you generate more than one token, this appears in Token to select a valid token.
-
Select
Client Credentials
from Grant Type. -
In Access Token URL, type
{{authPath}}/{{adminEnvID}}/as/token
. -
In Client ID, type
{{adminAppID}}
. -
In Client Secret, type
{{adminAppSecret}}
. -
Scope is not required in this use case, leave blank.
-
Select
Send as Basic Auth Header
from Client Authentication. -
In Refresh Token URL, type
{{authPath}}/{{adminEnvID}}/as/token
.
To generate a new access token:
-
Click Get New Access Token.
The Get new access token dialog appears.
-
Click Proceed. If you do nothing, the dialog proceeds after 5 seconds.
The Manage Access Tokens dialog appears.
-
Click Use Token. Postman applies the access token to requests with Authorization
Inherit auth from parent
until it expires. -
If Postman does not automatically refresh the access token, repeat these steps.
PingOne Authentication and Authorization
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
All tokens in PingOne are JSON Web Tokens (JWTs) signed using the RS256 signing algorithm. 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 or authorization code grant types) 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"
Grant types
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.
Response types
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
, theresponse_type
attribute must have thecode
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
orclient_credentials
, theresponse_type
attribute can specify thetoken
value to return an access token. -
id_token
Returns an ID token. If the grant type is
implicit
, theresponse_type
attribute can specify theid_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 theopenid
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 theprofile
scope to add additional user claims to the ID token.
Token claims
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.
Claim | Description |
---|---|
sub |
A string that specifies the identifier for the authenticated user. This claim is not present for client_credentials tokens. |
client_id |
A string that specifies the application that requested this token. |
aud |
A string that lists the names of resources that this token is intended for. The resource of an application’s resource access grant is included if one or more scopes from the grant is requested and granted. |
scope |
A string that specifies the space-separated list of scope names associated with this token in the format described in Section 3.3 of OAuth 2.0 RFC6749. |
iss |
A string that specifies the per-environment issue URI: For example, https://auth.pingone.com/<environmentId>/as . |
iat |
An integer that specifies the timestamp, measured in the number of seconds since January 1, 1970, UTC, indicating when this token was originally issued, as defined in JWT RFC7519. |
exp |
An integer that specifies the timestamp, measured in the number of seconds since January 1, 1970, UTC, indicating when this token will expire, as defined in JWT RFC7519. |
sid |
A string that specifies the identifier for the user session. This claim is not present for client_credentials tokens. |
env |
A string that specifies the environment ID of the authenticated user or application. This claim is not present when the resource's audience property does not include the PingOne platform API resource. |
org |
A string that specifies the organization ID of the authenticated user or application. This claim is not present when resource's audience property does not include the PingOne platform API resource. |
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.
Claim | Description |
---|---|
sub |
A string that specifies the identifier for the authenticated user. |
aud |
A string that lists the names of resources that this token is intended for. The resource of an application’s resource access grant is included if one or more scopes from the grant is requested and granted. |
iss |
A string that specifies the per-environment issuer URI: https://auth.pingone.com/<environmentId>/as or https://<customDomain>/as . |
iat |
An integer that specifies the timestamp, measured in the number of seconds since January 1, 1970, UTC, indicating when this token was originally issued, as defined in JWT RFC7519. |
exp |
An integer that specifies the timestamp, measured in the number of seconds since January 1, 1970, UTC, indicating when this token will expire, as defined in JWT RFC7519. |
sid |
A string that specifies the identifier for the user session. |
auth_time |
A string that specifies the time when the user authentication occurred. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the current date and time. |
nonce |
A string that specifies the value used to associate a client session with an id_token , and to mitigate replay attacks. The value is passed through unmodified from the authentication request to the ID token. |
at_hash |
A case-sensitive string that specifies the access token hash value, which is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access token value. For more information, see OpenID Connect Core 1.0. |
c_hash |
A case-sensitive string that specifies the code hash value, which is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the code value. For more information, see OpenID Connect Core 1.0. |
acr |
A string that specifies the name of the sign-on policy that was completed when the original authentication was performed. This claim is present only if an ID token was minted. |
amr |
A string array that specifies the methods associated with the authenticators used when the original authentication was performed. This claim is present only if an ID token was minted. |
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 POST Token (refresh_token) (CLIENT_SECRET_BASIC), POST Token (refresh_token) (CLIENT_SECRET_POST), or POST Token (refresh_token) (NONE).
Token customization and introspection
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.
Token storage
To ensure the security of your application and its resilience to malicious attacks, it is important to understand the best practices for storing JSON Web Tokens (JWTs). This will vary by client and application type, and the specific threat model and risks pertinent to your organization.
General recommendations
For more detailed information on token storage best practices, see the following:
Single-page application
For a single-page application, the most secure way to store tokens is to use web workers. This method stores tokens in a separate thread from the main runtime, which isolates tokens from any malicious code.
Where the client uses implicit flows to acquire access tokens, tokens should be kept within the client's runtime (e.g. JavaScript) memory. However, using implicit flows is not recommended as of OAuth 2.1.
In rare cases where the client needs to store the JWT, using sessionStorage is generally preferable to localStorage, which persists across browser restarts. When transmitting tokens, only do so in the Authorization header or in POST request bodies over HTTPS. Never include tokens in query parameters.
Web application
For a web application, where a backend server acquires access tokens on behalf of the client, tokens should be kept in the backend and only associated indirectly with the client through its authentication session. Tokens can also be associated with the client's authentication session with a session cookie.
The tokens themselves should not be included in the session cookie unless the client requires the ability to make direct API requests to the resource server protected by the tokens, or the server is unable to maintain a session on the backend. In the former situation, the the tokens would be returned to the client in the response body instead of by cookies.
In many cases, storing JWTs in a session cookie is the recommended approach. Depending on the security requirements of your application, you may want to consider other approaches.
You can customize the behavior of cookies using the following flags:
-
The
Domain
flag defines the domain where the cookie is sent. If left unspecified, the cookie is only sent to the origin server by default, which is the most secure option. -
The
Path
flag defines the directory and subdirectories where the cookie is sent. Set this flag as specific as possible to the path that uses the session ID. -
The
HttpOnly
flag ensures that it's only sent in HTTP requests to the server, thus it's never revealed to JavaScript running in the browser. -
The
Secure
flag ensures the cookie can only be used with secure, encrypted connections. -
The
SameSite
flag ensures that cookies cannot be sent cross-site, which prevents cross-site request forgery (CSRF) attacks. -
The
MaxAge
andExpires
flags set the expiration time of the cookie. If left unspecified, the cookie will expire when the browser is closed, which is the most secure option.
The following is an example of setting a cookie in the HTTP response header:
Set-Cookie: <cookie-name>=<cookie-value
Set-Cookie: <cookie-name>=<cookie-value>; Path=<path-value>
Set-Cookie: <cookie-name>=<cookie-value>; HttpOnly
Set-Cookie: <cookie-name>=<cookie-value>; Secure
Set-Cookie: <cookie-name>=<cookie-value>; SameSite=Strict
PingOne basic login authentication flow
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"
PingOne authentication flow states
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.
-
-
Sign on with username and password
-
Forgot password
-
Register user
-
Sign on with identity provider
-
-
- Push authentication
Login 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.
Identifier first action
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.
Identifier first with login_hint
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
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.
Multi-factor (MFA) action
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:
-
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).
-
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.
-
If the FIDO2 biometrics flow is not started, the flow transitions to the device selection flow or to another flow using the default device.
-
If the selected (or default) device is a MOBILE device with PUSH enabled, the flow transitions to the native PUSH flow.
-
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.
Device authorization flow
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.
FIDO2 device flow
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.
Native PUSH device flow
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.
Offline device and security key flows
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.
Device selection flow
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.
Progressive profiling action
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.
Authentication workflow walkthrough
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 PingOne 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:
-
The user enters a username and password in the fields provided on the sign-on screen.
-
The user clicks Sign on to initiate the
usernamePassword.check
authentication action. -
The flow service calls the
POST /{{envID}}/flows/{{flowID}}
endpoint operation and uses theapplication/vnd.pingidentity.usernamePassword.check+json
custom media type in theContent-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
orVOICE
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:
-
The sign-on screen presents the list of registered devices.
-
The user clicks a registered device to specify the device to use for the MFA action.
-
The flow service calls the
POST /{{envID}}/flows/{{flowID}}
endpoint operation and uses theapplication/vnd.pingidentity.device.select+json
custom media type in theContent-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:
-
The user receives the OTP on the specified device.
-
The user enters the OTP in the field provided on the sign-on screen.
-
The user clicks Submit to initiate the
otp.check
authentication action. -
The flow service calls the
POST /{{envID}}/flows/{{flowID}}
endpoint operation and uses theapplication/vnd.pingidentity.otp.check+json
custom media type in theContent-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:
-
The user receives the push authentication request on the specified native device.
-
The user chooses ACCEPT or DENY in response to the confirmation prompt.
-
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:
-
The user is prompted to either retry push authentication on the currently selected device, or select a different registered native device.
-
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.
-
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.
Authorization flow by grant type
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).
Authorization code grant type
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 iscode
. -
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 isauthorization_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 iscode
. -
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}}'
Implicit grant type
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 istoken
,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 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=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 istoken
,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}}'
Hybrid grant type
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 includescode
, and it also specifiesid_token
, ortoken
, 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 isauthorization_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 includescode
, and it also specifiesid_token
, ortoken
, 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}}'
PKCE parameters
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 iscode
. -
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 isauthorization_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 thecode_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.
Device code grant type
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 thedevice_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.
Authorization and authentication by application type
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:
-
The application initiates the authorization flow through a
GET
orPOST
request to theauthorize
endpoint. -
The authorization service generates the access token for the
implicit
grant. -
For
authorization_code
andclient_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.
Web applications
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
, theresponse_type
parameter must have a value ofcode
. 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 ofhttps://www.pingidentity.com/
redirects properly tohttps://www.pingidentity.com/#access_token=eyJsdf
, but a registered URI ofhttps://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.
Native and single-page applications
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 aresponse_type
parameter value oftoken
orid_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 ofhttps://www.pingidentity.com/
redirects properly tohttps://www.pingidentity.com/#access_token=eyJsdf
, but a registered URI ofhttps://www.pingidentity.com
redirects incorrectly tohttps://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 anid_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
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
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, by default the application inherits the same role assignments as the actor that created the application.
Best Practice: Disable this inheritance using the assignActorRoles
parameter when creating the Worker app using the API. This is for security purposes, to ensure you assign only the minimal set of permissions necessary for the Worker app. See Applications OIDC settings data model for more information.
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
}
Access services through scopes and roles
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
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:
Scope | Description |
---|---|
p1:read:user |
Users can retrieve their own user identity and all attributes. If the user authenticates with an authoritative identity provider (user.identityProvider.id is not null ), their password state will not be returned with a self-service GET READ One User request. |
p1:update:user |
Users can modify the attributes of their own user identity. This scope is not granted if the user authenticates with an authoritative identityProvider (user.identityProvider.id is not null ). |
p1:update:userMfaEnabled |
Users can enable and disable multi-factor authentication for their own user identity. |
p1:create:device |
Users can create multi-factor authentication devices for their own user identity. |
p1:read:device |
Users can retrieve multi-factor authentication devices for their own user identity. |
p1:update:device |
Users can update multi-factor authentication devices for their own user identity. |
p1:delete:device |
Users can delete multi-factor authentication devices for their own user identity. |
p1:read:userPassword |
Users can read the password state for their own user identity. This scope is not granted if the user authenticates with an authoritative identityProvider (user.identityProvider.id is not null ). |
p1:reset:userPassword |
Users can reset the password for their own user identity. This scope is not granted if the user authenticates with an authoritative identityProvider (user.identityProvider.id is not null ). |
p1:validate:userPassword |
Users can validate the password for their own user identity. This scope is not granted if the user authenticates with an authoritative identityProvider (user.identityProvider.id is not null ). |
p1:read:userLinkedAccounts |
Users can read linked accounts for their own user identity. This scope is not granted if the user authenticates with an authoritative identityProvider (user.identityProvider.id is not null ). |
p1:delete:userLinkedAccounts |
Users can delete linked accounts for their own user identity. This scope is not granted if the user authenticates with an authoritative identityProvider (user.identityProvider.id is not null ). |
p1:create:pairingKey |
Users can create a pairing key for their own user identity. |
p1:delete:pairingKey |
Users can delete a pairing key for their own user identity. |
p1:read:pairingKey |
Users can read a pairing key for their own user identity. |
p1:read:sessions |
Users can read sessions for their own user identity. |
p1:delete:sessions |
Users can delete sessions for their own user identity. |
p1:read:userConsent |
Users can read consents for their own user identity. |
p1:verify:user |
Users can verify their own user identity. |
p1:read:oauthConsent |
Users can read oauth scope consents for their own user identity. |
p1:update:oauthConsent |
Users can update oauth scope consents for their own user identity. |
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:
Scope | Description |
---|---|
p1:read:user and p1:read:user:{{suffix}} |
Users can read any of the user schema attributes defined in the scope's schemaAttributes property for their own user identity. The p1:read:user scope can be modified using PUT to change the list of user schema attributes. The p1:read:user:{{suffix}} scope is created using POST and must specify at least one user schema attribute in the schemaAttributes property. |
p1:update:user and p1:update:user:{{suffix}} |
Users can modify any of the user schema attributes defined in the scope's schemaAttributes property for their own user identity. The p1:update:user scope can be modified using PUT to change the list of user schema attributes. The p1:update:user:{{suffix}} scope is created using POST and must specify at least one user schema attribute in the schemaAttributes property. These scopes are not granted if the user authenticates with an authoritative identityProvider (user.identityProvider.id is not null ). |
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 and 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:
Capability | Associated scopes |
---|---|
canUsePasswordManagement |
p1:reset:userPassword , p1:read:userPassword |
canUseIdentityProviders |
p1:read:userLinkedAccounts , p1:delete:userLinkedAccounts |
canUsersUpdateSelf |
p1:update:user |
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.
Authoritative identity providers and access scopes
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
Reduced scopes based on AMR values
The platform has settings that can reduce the granted self-service scopes based on AMR (Authentication Methods References) claim values in the access token. For example, if the token's amr
claim does not have a value of mfa
, which specifies MFA-based authentication, the collection of granted self-service scopes to manage MFA devices can be reduced to just a few essential scopes.
The following table shows the reduced self-service scopes when the amr
claim values do not include common authentication methods such as mfa
. Note that the reduced scopes for MFA depend on whether the user has paired MFA devices.
AMR claim not included | Reduced scopes |
---|---|
mfa (user has paired MFA devices) |
p1:create:device , p1:create:pairingKey , p1:delete:device , p1:delete:pairingKey , p1:update:device , p1:update:device , p1:update:userMfaEnabled |
mfa (user does not have paired MFA devices) |
p1:update:userMfaEnabled |
OpenID Connect (OIDC) scopes
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:
Scope | Description |
---|---|
profile |
This scope value requests access to the end-user's profile claims, which are: name , family_name , given_name , middle_name , preferred_username , nickname , picture , zoneinfo , locale , profile , website , gender , birthdate , and updated_at . |
email |
This scope value requests access to the email and email_verified claims. |
address |
This scope value requests access to the following claims: address.street_address , address.locality , address.region , address.postal_code , address.country , address.formatted . |
phone |
This scope value requests access to the phone_number and phone_number_verified claims. |
OIDC scopes for user information
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.
Custom scopes
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.
Administrator permissions and role assignments
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.
Best Practice: Disable this inheritance using the assignActorRoles
parameter when creating the Worker app using the API. This is for security purposes, to ensure you assign only the minimal set of permissions necessary for the Worker app. See Applications OIDC settings data model for more information.
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.
Control access to applications through roles and groups
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 theaccessControl.group.groups
property. This property can also be set toALL_GROUPS
, which means that the actor must belong to all groups specified in theaccessControl.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 ofaccessControl.group.type
) or all groups (ifALL_GROUPS
is the value ofaccessControl.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:
-
Set the
accessControl.role.type
property value toADMIN_USERS_ONLY
. -
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:
-
Set the
accessControl.group.type
andaccessControl.group.groups
properties. (If you set one of the application's access control group properties, you must set the other.) -
Set the property value for the
accessControl.group.type
. The options areANY_GROUP
andALL_GROUPS
. -
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.
Use Cases
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:
-
Open your Postman application, and under the Postman menu, click Preferences.
-
On the Settings screen, click the General tab, if it is not already open.
-
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:
-
Open the Step 1 request for the use case you want to run.
-
Click the Cookies link, which is directly under the Send button.
-
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.
Downloading PingOne use case collections
Any of the use case collections you can fork into your Postman workspace, or download and import. Each use case also offers a button to retrieve the collection for that use case. The table lists use cases in the order they appear in the navigation panel.
Using 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
,asia
, orcom.au
. This variable is incorporated in each of the following{{...Path}}
variables to make changing your region simple. When you set{{tld}}
, the{{...Path}}
variables are also set to the appropriate region. -
{{apiPath}}
The regional domain (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,https://api.pingone.asia/v1
for environments in the Asia-Pacific region, andhttps://api.pingone.com.au/v1
for environments in the Australia 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,https://auth.pingone.asia
for the Asia-Pacific region, andhttps://auth.pingone.com.au
for the Australia 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,https://orchestrate-api.pingone.asia/v1
for the Asia-Pacific region, andhttps://orchestrate-api.pingone.com.au/v1
for the Australia 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
for the North America region (excluding Canada),https://scim-api.pingone.ca
for the Canada region,https://scim-api.pingone.eu
for the European Union region,https://scim-api.pingone.asia
for the Asia-Pacific region, andhttps://scim-api.pingone.com.au
for the Australia region. -
{{envID}}
The UUID of an environment resource. This ID identifies your current working domain within your organization.
-
{{accessToken}}
A valid access token returned by the PingOne authorization server from the worker application in your current environment. For information about creating a worker application and getting an access token, see Getting started.
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.
Application Management
These tasks show you how to use the platform APIs to perform common actions for managing applications. Application use cases often call the following platform API resources:
Platform API | Description |
---|---|
Applications | Application resources define the connection between PingOne and the actual application, commonly referred to as a client connection. |
Best practices for application secrets
-
Do not store an application secret in applications that are publicly available.
-
For security purposes, regenerate application secrets regularly (see Update the application secret).
-
If you suspect an application secret has been compromised, generate a new application secret immediately.
Configure an Application with an Authorization Code Grant
This activity shows you how to create an application, configure its connection settings, create a resource access grant, and initiate an authorization request. After an access token is generated, it is used by a user to update a user attribute.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a resource access grant
- Initiate an
authorization_code
authorization flow - Update a user attribute
Best practices for application secrets
-
Do not store an application secret in applications that are publicly available.
-
For security purposes, regenerate application secrets regularly (see Update the application secret).
-
If you suspect an application secret has been compromised, generate a new application secret immediately.
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To configure an application and initiate an authorization code flow, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute. -
Make a
GET
request to/environments/{{envID}}/resources
to return a list of all resource entities associated with the specified environment to get the ID for the PingOne platform resource. -
Make a
GET
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to list all scopes associated with a specified resource (the PingOne platform resource). -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be associated with the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
To initiate the authentication flow, make a
GET
request toGET /{{envID}}/flows/{{flowID}}
. -
To complete the authentication flow, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the token. -
After the authorization flow completes and returns an auth code, make a
POST
request to/{{envID}}/as/token
to exchange the auth code for an access token.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create an OpenID Connect (OIDC) application
Step 2: Get the application secret
Step 3: Get the list of resources
Step 4: Get all scopes
Step 5: Create the application's resource access grant
Step 6: Create a population
Step 7: Create user
Step 8: Set user password
Step 9: Obtain an authorization grant
Step 10: Get the flow
Step 11: Submit login credentials
Step 12: Call the resume endpoint
Step 13: Generate the access token
Configure an Application with a Refresh Token Grant
This activity shows you how to create an application, configure its connection settings, create a resource access grant, and initiate an authorization request.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a resource access grant
- Initiate an
authorization_code
authorization flow - Update a user attribute
Prerequisites
- Get an access token from the worker application you created in 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:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be associated with the new population resource. -
Make a
PUT
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
GET
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
To initiate the authentication flow, make a
GET
request toGET /{{envID}}/flows/{{flowID}}
. -
To complete the authentication flow, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the token. -
After the authorization flow completes and returns an auth code, make a
POST
request to/{{envID}}/as/token
to exchange the auth code for an access token and return the refresh token.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create an application
Step 2: Get the application secret
Step 3: Create a population
Step 4: Create user
Step 5: Set user password
Step 6: Send an authorize request
Step 7: Get the flow
Step 8: Submit login credentials
Step 9: Call the resume endpoint
Step 10: Generate the access token
Configure a Single-Page Application with PKCE and an AuthCode Grant
This activity shows you how to create an single-page application, configure its connection settings to use Proof Key for Code Exchange (PKCE) parameters in the authorization request for the authorization code grant, and initiate an authorization request.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a user
- Initiate an authorization code flow and use PKCE to authenticate the token request
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To configure a single-page application and initiate an authentication flow, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
To initiate the authentication flow, make a
GET
request toGET /{{envID}}/flows/{{flowID}}
. -
To complete the authentication flow, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the token. -
Make a
POST
request to/{{envID}}/as/token
to exchange the auth code for an access token.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a single-page application
Step 2: Create a population
Step 3: Create user
Step 4: Set user password
Step 5: Send the authorize request
Step 6: Get the Flow
Step 7: Submit Login Credentials
Step 8: Call the resume endpoint
Step 9: Get the access token
Configure a Single-Page Application with an Implicit Grant
This activity shows you how to create an single-page application, configure its connection settings, create a resource access grant, and initiate an authorization request.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a resource access grant
- Initiate an
implicit
authorization and authentication flow
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To configure a single-page application and initiate an authentication flow, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/resources
to return a list of all resource entities associated with the specified environment to get the ID for the PingOne platform resource. -
Make a
GET
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to list all scopes associated with a specified resource (the PingOne platform resource). -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
To initiate the authentication flow, make a
GET
request toGET /{{envID}}/flows/{{flowID}}
. -
To complete the authentication flow, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the token.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a single-page application
Step 2: Get the list of resources
Step 3: Get all scopes
Step 4: Create the application's resource access grant
Step 5: Create a population
Step 6: Create user
Step 7: Set user password
Step 8: Send the authorize request
Step 9: Get the Flow
Step 10: Submit Login Credentials
Step 11: Call the resume endpoint
Configure a Non-Interactive Worker Application
This activity shows you how to create non-interactive worker application, configure its connection settings, get the application secret, and configure a token request.
The following operations are supported by the PingOne APIs:
- Create an application
- Get the application secret
- Initiate a token request
Best practices for application secrets
-
Do not store an application secret in applications that are publicly available.
-
For security purposes, regenerate application secrets regularly (see Update the application secret).
-
If you suspect an application secret has been compromised, generate a new application secret immediately.
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To configure a non-interactive worker application and initiate a token request, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{applicationID}}/secret
to return the application secret. -
Make a
POST
request to/{{envID}}/as/token
to get an access token.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a worker application
Step 2: Get the application secret
Step 3: Get a token
Configure an Interactive Worker Application
This activity shows you how to create an interactive worker application, configure its connection settings, view the application role assignments, assign roles to an admin user, and initiate an authorization request.
The following operations are supported by the PingOne APIs:
- Create an application
- Read application role assignments
- Create an admin population and an admin user
- Assign roles to the admin user
- Initiate an
authorization_code
authorization and authentication flow
Best practices for application secrets
-
Do not store an application secret in applications that are publicly available.
-
For security purposes, regenerate application secrets regularly (see Update the application secret).
-
If you suspect an application secret has been compromised, generate a new application secret immediately.
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To configure an interactive worker admin application and initiate an authentication flow, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{applicationID}}/secret
to get the application's secret, which is needed to authenticate the token request. -
Make a
GET
request to/environments/{{envID}}/applications/{{applicationID}}/roleAssignments
to return a list of roles assigned to the application. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{policyID}}/actions
to add a login action to the sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{applicationID}}/signOnPolicyAssignments
to associate the new sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new admin population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create an admin user who will be assigned to the new population resource. -
Make a
PUT
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
GET
request to/roles
to read all roles. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/roleAssignments
to assign a role to the new admin user. -
Make a
GET
request to/{{envID}}/as/authorize
to initiate an authorization request. This request starts the sign-on flow. -
Make a
GET
request toGET /{{envID}}/flows/{{flowID}}
to initiate the authentication flow. -
To complete the authentication flow, make a
POST
request to/{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the auth code. -
Make a
POST
request to/{{envID}}/as/token
to exchange the auth code for an access token.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a worker application
Step 2: Get the application secret
Step 3: Get the worker application role assignments
Step 4: Create a sign-on policy
Step 5: Create the sign-on policy action
Step 6: Assign the sign-on policy to an application
Step 7: Create a population
Step 8: Create an admin user
Step 9: Set user password
Step 10: Read all roles
Step 11: Create user role assignment
Step 12: Send the authorize request
Step 13: Get the Flow
Step 14: Submit Login Credentials
Step 15: Call the resume endpoint
Step 16: Get the access token
Create and Update Notification Content
This activity shows you how to create and update content for different types of notifications.
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To create and update content for different types of notifications:
-
Make a
GET
request to/environments/{{envID}}/templates
to read all notification templates. -
Make a
POST
request to/environments/{{envID}}/templates/general/contents
to create email notification content. -
Make a
PUT
request to/environments/{{envID}}/templates/general/contents/{{emailContentID}}
to update the email notification content. -
Make a
POST
request to/environments/{{envID}}/templates/general/contents
to create SMS notification content. -
Make a
PUT
request to/environments/{{envID}}/templates/general/contents/{{smsContentID}}
to update the SMS notification content. -
Make a
POST
request to/environments/{{envID}}/templates/general/contents
to create voice notification content. -
Make a
PUT
request to/environments/{{envID}}/templates/general/contents/{{voiceContentID}}
to update the voice notification content. -
Make a
POST
request to/environments/{{envID}}/templates/transaction/contents
to create push notification content. -
Make a
PUT
request to/environments/{{envID}}/templates/transaction/contents/{{pushContentID}}
to update the push notification content. -
Make a
GET
request to/environments/{{envID}}/templates/general/contents
to read all general template notification content. -
Make a
GET
request to/environments/{{envID}}/templates/transaction/contents/{{pushContentID}}
to read only push notification content.
Click Run in Postman to download the Postman collection for this use case.
Step 1: Read all notification templates
Step 2: Create email notification content
Step 3: Update email notification content
Step 4: Create SMS notification content
Step 5: Update SMS notification content
Step 6: Create voice notification content
Step 7: Update voice notification content
Step 8: Create push notification content
Step 9: Update push notification content
Step 10: Read all general template notification content
Step 11: Read only push notification content
Test a SAML Application Connection
To test the execution of a SAML identity provider (IdP) connection for an application configured in your PingOne environment, you must have a working SAML IdP for your environment to communicate with.
The easiest way to do this is by using two PingOne environments. You can then execute an authentication flow for an application existing in one PingOne environment by using external authentication as a user in a second PingOne environment acting as the SAML IdP.
Prerequisites
-
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of the worker app that you selected to authenticate the request. For more information, see GET a Worker Application Access Token.
-
A destination PingOne environment to act as the service provider (SP) for the SAML application. Use this environment to configure the SAML IdP connection. You can configure authentication flows in this environment to allow external authentication.
-
A source PingOne environment to act as the SAML IdP. Users here can complete authentication flows in the destination environment.
-
Cross-environment admin permissions for the destination and source environments.
-
A PingOne access token for each environment.
This scenario illustrates the following operations supported by the PingOne APIs:
- Get the certificate for the source environment.
- Create a SAML application in the source environment.
- Create a SAML IdP in the destination environment.
- Create a sign-on policy in the destination environment.
- Create a sign-on policy action to enable the sign-on policy for the SAML IdP connection.
- Set the sign-on policy as the default for the destination environment.
Workflow order of operations
To test the SAML application connection:
-
Make a
GET
request to/environments/{{sourceEnvID}}/keys
to get the signing key for the source environment and download the PEM or PKCS7 file for the signing key. -
Make a
GET
request to/environments
to get the environment IDs. -
Make a
POST
request to/environments/{{sourceEnvID}}/applications
to create a SAML application. -
(Optional) Make a
POST
request to/environments/{{sourceEnvID}}/applications/{{appID}}/attributes
to any attribute mappings needed for the source environment application. -
Make a
POST
request to/environments/{{destinationEnvID}}/certificates
to create a certificate in the destination environment using the PEM or PKCS7 file that you downloaded in the initial step. -
Make a
GET
request to/environments/{{destinationEnvID}}/certificates
to get a certificate for the destination environment to assign to the IdP that you'll create. -
Make a
POST
request to/environments/{{destinationEnvID}}/identityProviders
to create the SAML IdP configuration in the destination environment. -
(Optional) Make a
POST
request to/environments/{{destinationEnvID}}/identityProviders/{{providerID}}/attributes
to add any needed attribute mappings for the IdP in the destination environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/signOnPolicies
to create a sign-on policy for the new IdP in the destination environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/signOnPolicies/{{policyID}}/actions
to create a new IDENTIFIER_FIRST sign-on policy action associated with the new sign-on policy. -
Make a
PUT
request to/environments/{{destinationEnvID}}/applications/{{appID}}/signOnPolicyAssignments
to associate this sign-on policy with the specified SAML application.
Execute the authentication flow
-
Copy the Self-Service URL for the destination environment. You can find the Self-Service URL on the Settings → Environment → Properties page.
-
Open a private browser window, and enter the Self-Service URL that you copied.
-
Click the button that matches your SAML IdP connection.
-
Authenticate as a user in the source environment. Depending on your configuration, you might need to perform account linking or user verification.
Click Run in Postman to download the Postman collection for this use case.
Step 1: Get the signing key for the source environment
Step 2: Get all environment IDs
Step 3: Create a SAML application in the source environment
Step 4: (Optional) Create attribute mappings for the application
Step 5: Create a certificate in the destination environment
Step 6: Create the new identity provider in the destination environment
Step 7: (Optional) Create attribute mappings for the identity provider
Step 8: Create a sign-on policy for the new identity provider
Step 9: Create a sign-on policy action
Step 10: Set the sign-on policy as the default
Test an OIDC Application Connection
To test the execution of an OpenID Connect (OIDC) connection for an application configured in your PingOne environment, you must have a working OIDC identity provider (IdP) for your environment to communicate with.
The easiest way to do this is by using two PingOne environments. You can then execute an authentication flow for an application existing in one PingOne environment by using external authentication as a user in a second PingOne environment acting as the OIDC IdP.
Prerequisites
-
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
-
A destination PingOne environment to act as the service provider (SP) for the OIDC application. You'll use this environment to configure the OIDC IdP connection. Authentication flows in this environment can be configured to allow external authentication.
-
A source PingOne environment that will act as the OIDC IdP. Users here will be able to complete authentication flows in the destination environment.
-
Cross-environment admin permissions for the destination and source environments.
-
A PingOne access token for each environment.
This scenario illustrates the following operations supported by the PingOne APIs:
- Create an OIDC application in the source environment.
- Create an OIDC IdP in the destination environment referencing the source application.
- Create a sign-on policy in the destination environment.
- Create a sign-on policy action to enable the sign-on policy for the OIDC IdP connection.
- Set the sign-on policy as the default for the destination environment.
- Initiate an authorization request.
Workflow order of operations
To test the OIDC application connection, the following tasks must be completed successfully:
-
Make
POST
requests to/environments
to create a source environment and a destination environment. -
Make a
POST
request to/environments/{{sourceEnvID}}/applications
to create an OIDC application in the source environment. -
Make a
GET
request to/environments/{{sourceEnvID}}/applications/{{appID}}/secret
to read the OIDC application secret. -
Make a
POST
request to/environments/{{destinationEnvID}}/identityProviders
to create an OIDC IdP in the destination environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/signOnPolicies
to create a sign-on policy for the IdP in the destination environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/signOnPolicies/{{policyID}}/actions
to create a new IDENTIFIER_FIRST sign-on policy action associated with the new sign-on policy. -
Make a
PUT
request to/environments/{{destinationEnvID}}/signOnPolicies/{{policyID}}
to set the policy as default. -
Make a
POST
request to/environments/{{destinationEnvID}}/applications
to create an OIDC application in the destination environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/applications/{{appID}}/signOnPolicyAssignments
to assign the sign-on policy to the destination OIDC application. -
Make a
GET
request to/{{destinationEnvID}}/as/authorize
to retrieve an authorization grant.
Execute the authentication flow
-
Open a private browser window, and enter the
Location
header URL that was returned from the/as/authorize
call. -
Click the button that matches your OIDC IdP connection.
-
Authenticate as a user in the source environment. Depending on your configuration, you may need to perform account linking or user verification.
You should be able to sign on as a source environment user, indicating that authentication from the source environment to the OIDC IdP in the destination environment is working. After authenticating, you are taken to the redirect_uri
of the application in your destination environment.
Click the Run in Postman button to download the Postman collection for this use case.
Step 1a: Create Source Environment
Step 1b: Create Destination Environment
Step 2: Create an OIDC application in the source environment
Step 3: Read the OIDC application secret
Step 4: Create OIDC provider in destination environment
Step 5: Create a sign-on policy for the OIDC IdP
Step 6: Create a sign-on policy action
Step 7: Set the sign-on policy as the default
Step 8: Create an OIDC application in the destination environment
Step 9: Assign the sign-on policy to the destination OIDC application
Step 10: Send an authorization request
Authentication and Authorization
These tasks show you how to use the platform APIs to perform common actions for authorization and authentication actions. Authorization and authentication use cases often call the following platform API resources:
Platform API | Description |
---|---|
OpenID Connect/OAuth 2 | The PingOne authorization endpoint is used to interact with the resource owner and obtain an authorization grant. |
Flows | The flow endpoint is used to interact with the user in a sign-on workflow. |
SAML 2.0 | The SAML endpoints are used by SAML applications to initiate sign-on and signoff operations. |
Sign-On Policies | Sign-on policies determine the account authentication flow users must complete to access applications secured by PingOne services. |
Resources | Resources are the protected endpoints that applications request access to using OAuth 2 authorization services. |
Configure a Simple Login
This activity shows you how to create a simple login using only a username and password. You'll create a login sign-on policy, initiate an authorization request, and use the flow APIs to complete the authorization.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a sign-on policy
- Create a login sign-on policy action
- Create a user
- Initiate an authorize request
- Use flow APIs to complete the login
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To configure a simple login with a username and password, you must complete the following tasks:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{webAppSimpleLoginId}}/secret
to return the new application's secret attribute. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the login action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user to assign to the new population resource. -
Make a
PUT
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
GET
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the sign-on flow. -
To complete the login action, make a
POST
request to/{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the auth code. -
Make a
POST
request to/{{envID}}/as/token
to exchange the auth code for an access token.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a web application
Step 2: Get the application secret
Step 3: Create a sign-on policy
Step 4: Create the login sign-on policy action
Step 5: Assign the sign-on policy to the web application
Step 6: Create a population for simple login users
Step 7: Create a user
Step 8: Set user password
Step 9: Send an authorization request
Step 10: Get the flow
Step 11: Submit login credentials
Step 12: Call the resume endpoint
Step 13: Get the access token
Use LOGIN and MFA Actions to Authenticate Users
This activity shows you how to create a sign-on policy with login and mfa actions, initiate an authorization request, and use the flow APIs to complete the authorization.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a sign-on policy
- Create login and MFA sign-on policy actions
- Create a user
- Initiate an authorize request
- Use flow APIs to complete the login and MFA actions
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To complete a login and MFA sign on, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/resources
to return a list of all resource entities associated with the specified environment. -
Make a
GET
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to list all scopes associated with a specified resource. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the login action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the MFA action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/mfaEnabled
to enable MFA actions for this user. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/devices
to associate an MFA device with this user. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the sign-on flow. -
To complete the login action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
To complete the MFA action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the one-time passcode. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the auth code. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute, which is needed for the token request. -
Make a
POST
request to/{{envID}}/as/token
to exchange the auth code for an access token.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a web application
Step 2: Get all resources
Step 3: Get all OIDC Scopes
Step 4: Assign a resource grant to the web application
Step 5: Create a sign-on policy
Step 6: Create the login sign-on policy action
Step 7: Create the MFA sign-on policy action
Step 8: Assign the sign-on policy to the web application
Step 9: Create a population for MFA users
Step 10: Create a user
Step 11: Set user password
Step 12: Enable user MFA
Step 13: Set user device (SMS)
Step 14: Send an authorization request
Step 15: Get the flow
Step 16: Submit login credentials
Step 17: Check OTP
Step 18: Call the resume endpoint
Step 19: Get the application secret
Step 20: Get the access token
Add a User through a Registration Flow
This activity shows you how to create a sign-on policy with registration enabled, initiate an authorization request, and use the flow APIs to create and verify a new user account.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a sign-on policy
- Initiate an authorize request
- Use flow APIs to create a new user
- Use flow APIs to verify the new user
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To create a new user through a registration flow, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population for the reistered user. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy that enables user registration. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the registration action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to create associate the registration sign-on policy with the application. -
Make a
GET
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to get the flow. -
Make a
POST
request to/{{envID}}/flows/{{flowID}}
to register the new user. -
Make a
POST
request to/{{envID}}/flows/{{flowID}}
to verify the new user account. -
Make a
GET
request to/environments/{{envID}}/users/
to verify that the new user exists in the PingOne directory.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create an application
Step 2: Create a population for registered users
Step 3: Create the new sign-on policy
Step 4: Create the sign-on policy action with registration enabled
Step 5: Assign the sign-on policy to an application
Step 6: Send the authorization request
Step 7: Get the flow
Step 8: Register a new user
Step 9: Verify user
Step 10: Get users
Configure a PKCE Authorization Workflow
In some cases, as with applications on native devices, the use of an authorization code grant can be compromised by authorization code interception attacks. The attacking application gains access to the client secret, intercepts the authorization code, and is able to exchange the intercepted authorization code for an access token.
Proof Key for Code Exchange (PKCE) authorization requests specify additional parameters in the request to prevent malicious apps from intercepting the authorization code. PKCE uses a random key, a code_verifier
, that is used to compute a code_challenge
parameter, which functions like a temporary application secret (unique to a single token request). PKCE works as follows:
-
The client creates and records a
code_verifier
secret, which is a random value between 43 and 128 characters in length. -
The client uses the
code_verifier
value to compute thecode_challenge
value. Thecode_challenge_method
is the transformation method that creates thecode_challenge
value. This parameter value is also recorded. -
The authorization request includes the
code_challenge
and in some cases thecode_challenge_method
parameter values in the request. Thecode_challenge_method
is an optional parameter. It defaults toplain
if not specified (which generates an error when theS256_REQUIRED
PKCE enforcement option is specified by the application). -
The authorization server records the
code_challenge
and thecode_challenge_method
parameter values, and responds by issuing the authorization code. -
The client sends the authorization code to the
/{{envID}}/as/token
endpoint. The token request requires thecode_verifier
secret created in step 1. -
The authorization server uses the
code_challenge_method
to transform thecode_verifier
value and compare it to thecode_challenge
value submitted and recorded in the authorize request. -
If these values are equal, an access token is granted. If they are not equal, access is denied.
Workflow tasks
This scenario illustrates the following operations supported by the PingOne APIs:
-
Create an application and set its
pkceEnforcement
property. -
Create an authorization request that includes
code_challenge
andcode_challenge_method
parameter values. -
Create a token request that includes the
code_verifier
secret.
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To enable a PKCE authorization workflow, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to define an OpenID Connect native app type that uses an authorization code grant. -
Make a
GET
request to/{{envID}}/as/authorize
to initiate authorization and submit thecode_challenge
andcode_challenge_method
values to the authorization server. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to verify the flow initialization. -
Make a
POST
request to/{{envID}}/flows/{{flowID}}
with theapplication/vnd.pingidentity.usernamePassword.check+json
content type to submit the username and password. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the authorize resume endpoint. -
Make a
POST
request to/{{envID}}/as/token
to exchange the authorization code returned by the resume endpoint for an access token.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create the application connection
Step 2: Submit the authorize request
Step 3: Verify flow initialization
Step 4: Submit username and password
Step 5: Call the resume endpoint
Step 6: Get the token
Configure a Progressive Profiling Sign-On Action
This activity shows you how to create a sign-on policy with a progressive profiling action, initiate an authorization request, and use the flow APIs to complete the progressive profiling action.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a sign-on policy
- Create login and a progressive profiling sign-on policy actions
- Create a user
- Initiate an authorize request
- Use flow APIs to login the user and add a mobile phone number
- Verify the addition of a mobile phone number to the user record
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To complete a progressive profiling flow, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute. -
Make a
GET
request to/environments/{{envID}}/resources
to return a list of all resource entities associated with the specified environment to get the ID for the PingOne platform resource. -
Make a
GET
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to list all scopes associated with a specified resource (the PingOne platform resource). -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the login action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the progressive profiling action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the flow. -
To complete the login action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
To complete the progressive profiling action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's mobile phone number. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the auth code. -
After the authorization flow completes, make a
POST
request to/{{envID}}/as/token
to exchange the auth code for an access token. -
Make a
GET
request to/environments/{{envID}}/users/{{userID}}
to view the updated information about the identified user.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create an (OIDC) application
Step 2: Get the application secret
Step 3: Get the list of resources
Step 4: Get all scopes
Step 5: Create the resource access grant
Step 6: Create the new sign-on policy
Step 7: Create the login sign-on policy action
Step 8: Create the progressive profiling sign-on policy action
Step 9: Assign the sign-on policy to an application
Step 10: Create a population for profile users
Step 11: Create a user
Step 12: Set user password
Step 13: Send an authorization request
Step 14: Get the flow
Step 15: Submit login credentials
Step 16: Update user profile
Step 17: Call the resume endpoint
Step 18: Get the access token
Step 19: Verify updated user information
Configure Device Authorization Grant Flow
This activity shows you how to initiate a device authorization grant flow to send an activation code to the end user. The authorization and flow orchestration steps apply only to applications that specify device_code
as a grant type in the application configuration.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a population and a user
- Initiate an authorize request
- Use flow APIs to complete the flow
Prerequisites
- Get an access token from the worker application you created in 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 device authorization grant flow using the environment's default sign-on policy, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
PUT
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/{{envID}}/as/device_authorization
to return the device code and the user code. -
Make a
GET
request to/{{envID}}/device
to initiate authorization and return a flow ID. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to start the flow. -
To complete the login action, make a
POST
request to/{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
To complete the confirm activation code action, make a
POST
request to/{{envID}}/flows/{{flowID}}
to submit the activation code. -
To complete the consent action, make a
POST
request to/{{envID}}/flows/{{flowID}}
to accept the device authorization grant agreement. -
Make a
POST
request to/{{envID}}/as/token
to exchange the device code for an access token.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a custom application
Step 2: Create a population
Step 3: Create a user
Step 4: Set user password
Step 5: Authorize (device)
Step 6: Start device flow
Step 7: Get the flow
Step 8: Submit login credentials
Step 9: Confirm device user code
Step 10: Accept device authorization grant consent
Step 11: Get the access token
Use LOGIN and AGREEMENT Actions to Authenticate Users
This activity shows you how to create a sign-on policy with login and agreement actions, initiate an authorization request, and use the flow APIs to complete the authorization.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a sign-on policy
- Create login and agreement sign-on policy actions
- Create a user
- Initiate an authorize request
- Use flow APIs to complete the login and agreement actions
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To complete a login and agreement sign on, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute, which is needed for the token request. -
Make a
GET
request to/environments/{{envID}}/languages
to find the environment's default language. -
Make a
POST
request to/environments/{{envID}}/agreements
to create a new agreement. -
Make a
POST
request to/environments/{{envID}}/agreements/{{agreementID}}/languages
to create the language for the agreement. -
Make a
POST
request to/environments/{{envID}}/agreements/{{agreementID}}/languages/{{agreementLanguageID}}/revisions
to create the revision for the agreement in the specified language. -
Make a
PUT
request to/environments/{{envID}}/agreements/{{agreementID}}/languages/{{agreementLanguageID}}
to enable the agreement language. -
Make a
PUT
request to/environments/{{envID}}/agreements/{{agreementID}}
to enable the agreement. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the login action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the agreement action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the sign-on flow. -
To complete the login action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
To complete the agreement action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide consent to the agreement. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the auth code. -
Make a
POST
request to/{{envID}}/as/token
to exchange the auth code for an access token.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a web application
Step 2: Get the application secret
Step 3: Get languages
Step 4: Create an agreement
Step 5: Create an agreement language
Step 6: Create an ageement revision
Step 7: Update the agreement language
Step 8: Enable the agreement
Step 9: Create a sign-on policy
Step 10: Create the login sign-on policy action
Step 11: Create the agreement sign-on policy action
Step 12: Assign the sign-on policy to the web application
Step 13: Create a population for agreement users
Step 14: Create user
Step 15: Set user password
Step 16: Send an authorization request
Step 17: Get the flow
Step 18: Submit login credentials
Step 19: Consent to agreement
Step 20: Call the resume endpoint
Step 21: Get the access token
Get a Token for Custom Resource Access
This activity shows you how to create a custom resource and a custom resource scope, initiate an authorization request, and use the flow APIs to get a token that allows access to the custom resource.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a custom resouce and custom scope
- Create a sign-on policy
- Create login sign-on policy action
- Create a user
- Initiate an authorize request
- Use flow APIs to complete the login actions
- Use the token request to get an access token for the custom resource
- use the token introspection endpoint to verify the audience for the token
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To get an access token for the custom resource, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute, which is needed for the token request. -
Make a
POST
request to/environments/{{envID}}/resources
to define the custom resource. -
Make a
POST
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to define a scope for the custom resource. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the login action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
GET
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the sign-on flow. -
To complete the login action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the auth code. -
Make a
POST
request to/{{envID}}/as/token
to exchange the auth code for an access token. -
To verify that the token grants access to the new custom resource, make a
POST
request toGET /{{envID}}/as/introspect
to return the audience and scope information in the token.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a web application
Step 2: Get the application secret
Step 3: Create a custom resource
Step 4: Create a custom resource scope
Step 5: Assign a resource grant to the web application
Step 6: Create a sign-on policy
Step 7: Create the login sign-on policy action
Step 8: Assign the sign-on policy to the web application
Step 9: Create a population
Step 10: Create a user
Step 11: Set user password
Step 12: Send an authorization request
Step 13: Get the flow
Step 14: Submit login credentials
Step 15: Call the resume endpoint
Step 16: Get the access token
Step 17: Token Introspection
Add a Custom Claim to an Access Token
This activity shows you how to define a custom resource and custom scope and add the custom scope as a claim in an access token.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a custom resouce and scope
- Create a resource attribute mapping
- Initiate authorization and complete the authentication flow
- Verify the custom claim in the access token
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To add a custom claim to an access token, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
POST
request to/environments/{{envID}}/resources
to define a custom resource. -
Make a
POST
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to define a scope for the custom resource. -
Make a
POST
request to/environments/{{envID}}/resources/{{resourceID}}/attribute
to define a resource attribute mapping. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create the access grant for the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
GET
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization and authentication flow. -
To initiate the authentication flow, make a
GET
request to/{{envID}}/flows/{{flowID}}
. -
To complete the authentication flow, make a
POST
request to/{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the token.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a single-page application
Step 2: Create a custom resource
Step 3: Create a custom scope
Step 4: Create a resource attribute mapping
Step 5: Create the application's resource access grant
Step 6: Create a population
Step 7: Create user
Step 8: Set user password
Step 9: Send the authorize request
Step 10: Get the Flow
Step 11: Submit Login Credentials
Step 12: Call the resume endpoint
Configure CLIENT_SECRET_JWT as the token auth method
This activity shows you how to use a client secret JWT to authenticate a token request.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a user
- Initiate an authorize request
- Use flow APIs to complete the login
- Submit a token request
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To configure this workflow, you must complete the following tasks:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appJwtAppID}}/secret
to return the new application's secret attribute. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user. -
Make a
PUT
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
GET
request to/{{envID}}/as/authorize
to submit the authorize request. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the sign-on flow. -
To complete the login action, make a
POST
request to/{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the auth code. -
Make a
POST
request to/{{envID}}/as/token
to exchange the auth code for an access token.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a web application
Step 2: Get the application secret
Step 3: Create a population
Step 4: Create user
Step 5: Set user password
Step 6: Send an authorize request
Step 7: Get the flow
Step 8: Submit login credentials
Step 9: Call the resume endpoint
Step 10: Get the access token
SAML Sign-On
This activity shows you how to create a basic PingOne sign-on flow for a SAML application.
The following operations are supported by the PingOne APIs:
- Create a group
- Create a SAML application
- Create a sign-on policy
- Create a login sign-on policy action
- Create a user
- Initiate a SAML authorize request
- Use flow APIs to complete the login
Workflow order of operations
To configure a basic PingOne sign-on flow for a SAML application, you must complete the following tasks:
-
Make a
POST
request to/environments/{{envID}}/groups
to create a new group resource. -
Make a
POST
request to/environments/{{envID}}/applications
to add a new SAML application to the specified environment. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the login action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user to assign to the new population resource. -
Make a
PUT
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/{{envID}}/saml20/idp/sso
to obtain an authorization grant. This request starts the SAML authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the sign-on flow. -
To complete the login action, make a
POST
request to/{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/saml20/resume?flowId={{flowID}}
to call the SAML resume endpoint and return an encodedSAMLResponse
.
We highly recommend that you use our Postman collection for this workflow. The collection also contains the accompanying Postman environment template, making it easy for you to use and save variable values. For more information about using Postman environments, see The PingOne Postman environment template.
Click the Run in Postman button below to download or fork the Postman collection for this solution.
Step 1: Create a group
Step 2: Create a SAML application
Step 3: Create the sign-on policy
Step 4: Create the sign-on policy action
Step 5: Assign the sign-on policy to an application
Step 6: Create a population
Step 7: Create a user
Step 8: Set user password
Step 9: Submit SAML sign-on request
Step 10: Get the flow
Step 11: Submit login credentials
Step 12: Call the SAML resume endpoint
Test an OAuth Connection using Identifier First Authentication
This activity shows you how to test an OAuth connection using the identifier first login flow.
The easiest way to do this is by using two PingOne environments. This allows you to create a sign-on policy in one environment, and initiate the identifier first login flow as a user in the other environment, acting as the OIDC identity provider (IdP).
The identifier first login flow will first prompt a user for a username, and then use the identity provider discovery rules defined in the sign-on policy to route the user to the correct external identity provider for authentication. In this case, there will be one discoverable path, which is to sign on with a password. You will then call the resume endpoint to complete authorization and obtain an access token.
Prerequisites
-
Get an access token from the worker application that you created in Getting Started with the PingOne APIs.
-
A destination PingOne environment to act as the service provider (SP) for the OIDC application. You'll use this environment to configure the OIDC IdP connection. Authentication flows in this environment can be configured to allow external authentication.
-
A source PingOne environment that will act as the OIDC IdP. Users here will be able to complete authentication flows in the destination environment.
-
Cross-environment admin permissions for the destination and source environments.
-
A PingOne access token for each environment.
This scenario illustrates the following operations supported by the PingOne APIs:
- Create an OIDC application in the source environment.
- Create an OIDC IdP in the destination environment referencing the source application.
- Create a sign-on policy in the destination environment.
- Create a sign-on policy action to enable the sign-on policy for the OIDC IdP connection.
- Set the sign-on policy as the default for the destination environment.
- Create an OIDC application in the destination environment.
- Set the sign-on policy as the default for the destination environment.
- Create a population in the source and destination environments.
- Create users in the source and destination environments.
- Initiate an authorization request.
- Get the flow to read the sign-on policy associated with the OIDC application.
- Pass in the user credentials for verification.
- Retrieve the authorization code from the authorization server by calling the resume endpoint.
- Exchange the authorization code for the access token.
Workflow order of operations
To test an OAuth connection using the identifier first login flow, the following tasks must be completed successfully:
-
Make
POST
requests to/environments
to create a source environment and a destination environment. -
Make a
POST
request to/environments/{{sourceEnvID}}/applications
to create an OIDC application in the source environment. -
Make a
GET
request to/environments/{{sourceEnvID}}/applications/{{appID}}/secret
to read the OIDC application secret. -
Make a
POST
request to/environments/{{destinationEnvID}}/identityProviders
to create an OIDC IdP in the destination environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/signOnPolicies
to create a sign-on policy for the IdP in the destination environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/signOnPolicies/{{policyID}}/actions
to create a new IDENTIFIER_FIRST sign-on policy action associated with the new sign-on policy. -
Make a
PUT
request to/environments/{{destinationEnvID}}/signOnPolicies/{{policyID}}
to set the policy as default. -
Make a
POST
request to/environments/{{destinationEnvID}}/applications
to create an OIDC application in the destination environment. -
Make a
GET
request to/environments/{{destinationEnvID}}/applications/{{oidcAppDestinationID}}/secret
to read the application secret in the destination. -
Make a
POST
request to/environments/{{destinationEnvID}}/applications/{{appID}}/signOnPolicyAssignments
to assign the sign-on policy to the destination OIDC application. -
Make a
POST
request to/environments/{{sourceEnvID}}/populations
to create a population in the source environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/populations
to create a population in the destination environment. -
Make a
POST
request to/environments/{{sourceEnvID}}/users
to create a user in the source environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/users
to create a user in the destination environment. -
Make a
PUT
request to/environments/{{sourceEnvID}}/users/{{SourceUserID}}/password
to set the source user's password. -
Make a
PUT
request to/environments/{{destinationEnvID}}/users/{{DestinationUserID}}/password
to set the destination user's password. -
Make a
GET
request to/{{destinationEnvID}}/as/authorize
to retrieve an authorization grant. -
Make a
GET
request to/{{destinationEnvID}}/flows/{{flowID}}
to retrieve the flow. -
Make a
POST
request to/{{destinationEnvID}}/flows/{{flowID}}
to sign on with the destination user. -
Make a
POST
request to/{{destinationEnvID}}/flows/{{flowID}}
to verify the destination user's password. -
Make a
GET
request to/{{destinationEnvID}}/as/resume?flowId={{flowID}}
to call the resume endpoint. -
Make a
POST
request to/{{destinationEnvID}}/as/token
to retrieve the access token.
Click the Run in Postman button to download the Postman collection for this use case.
Step 1: Create Source Environment
Step 2: Create Destination Environment
Step 3: Create an OIDC application in the source environment
Step 4: Read the OIDC application secret
Step 5: Create OIDC IdP in destination environment
Step 6: Create a sign-on policy for the OIDC IdP
Step 7: Create a sign-on policy action
Step 8: Set the sign-on policy as the default
Step 9: Create an application in the destination environment
Step 10: Read the application secret in destination
Step 11: Assign the sign-on policy to the destination OIDC application
Step 12: Create a source population
Step 13: Create a destination population
Step 14: Create a source user
Step 15: Create a destination user
Step 16: Set source user password
Step 17: Set destination user password
Step 18: Send an authorization request
Step 19: Get the flow
Step 20: Sign on with a username
Step 21: Check password
Step 22: Call the resume endpoint
Step 23: Get the access token
Sign-on using an External Identity Provider
This activity shows you how to test the external authentication flow to sign-on using an external identity provider (IdP).
The easiest way to do this is by using two PingOne environments. One environment will act as the service provider (SP) for an OIDC application, while the other environment is used to configure an OIDC identity provider (IdP) connection.
This activity requires completing an internal authentication flow within the external authentication flow, so it's important to take note of which environment should be used to complete each step. On the first use of external authentication, you will need to link accounts. This takes place in step 25 of this activity. After the accounts are linked once, you will not need to link them again and can omit step 25 in the future.
Prerequisites
-
Get an access token from the worker application that you created in Getting Started with the PingOne APIs.
-
A destination PingOne environment to act as the service provider (SP) for the OIDC application. You'll use this environment to configure the OIDC IdP connection. Authentication flows in this environment can be configured to allow external authentication.
-
A source PingOne environment that will act as the OIDC IdP. Users here will be able to complete authentication flows in the destination environment.
-
Cross-environment admin permissions for the destination and source environments.
This scenario illustrates the following operations supported by the PingOne APIs:
- Create an OIDC application in the source environment.
- Create an OIDC IdP in the destination environment referencing the source application.
- Create a sign-on policy in the destination environment.
- Create a sign-on policy action to enable the sign-on policy for the OIDC IdP connection.
- Set the sign-on policy as the default for the destination environment.
- Create an OIDC application in the destination environment.
- Set the sign-on policy as the default for the destination environment.
- Create a population in the source and destination environments.
- Create users in the source and destination environments.
- Initiate an authorization request.
- Read an external authentication initialization.
- Send an external authentication request.
- Get the flow for an external identity provider.
- Pass in external identity provider credentials for verification.
- Retrieve an authorization code from the authorization server by calling the resume endpoint.
- Call the external authentication callback to get the response from an external identity provider.
- Get the flow and submit credentials for account linking.
- Retrieve an authorization code from the authorization server by calling the resume endpoint.
- Exchange an authorization code for an access token.
Workflow order of operations
To test the external authentication flow to sign-on using an external identity provider, the following tasks must be completed successfully:
-
Make
POST
requests to/environments
to create a source environment and a destination environment. -
Make a
POST
request to/environments/{{sourceEnvID}}/applications
to create an OIDC application in the source environment. -
Make a
GET
request to/environments/{{sourceEnvID}}/applications/{{appID}}/secret
to read the OIDC application secret. -
Make a
POST
request to/environments/{{destinationEnvID}}/identityProviders
to create an OIDC IdP in the destination environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/signOnPolicies
to create a sign-on policy for the IdP in the destination environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/signOnPolicies/{{policyID}}/actions
to create a new IDENTIFIER_FIRST sign-on policy action associated with the new sign-on policy. -
Make a
PUT
request to/environments/{{destinationEnvID}}/signOnPolicies/{{policyID}}
to set the policy as default. -
Make a
POST
request to/environments/{{destinationEnvID}}/applications
to create an OIDC application in the destination environment. -
Make a
GET
request to/environments/{{destinationEnvID}}/applications/{{oidcAppDestinationID}}/secret
to read the application secret in the destination. -
Make a
POST
request to/environments/{{destinationEnvID}}/applications/{{appID}}/signOnPolicyAssignments
to assign the sign-on policy to the destination OIDC application. -
Make a
POST
request to/environments/{{sourceEnvID}}/populations
to create a population in the source environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/populations
to create a population in the destination environment. -
Make a
POST
request to/environments/{{sourceEnvID}}/users
to create a user in the source environment. -
Make a
POST
request to/environments/{{destinationEnvID}}/users
to create a user in the destination environment. -
Make a
PUT
request to/environments/{{sourceEnvID}}/users/{{SourceUserID}}/password
to set the source user's password. -
Make a
PUT
request to/environments/{{destinationEnvID}}/users/{{DestinationUserID}}/password
to set the destination user's password. -
Make a
GET
request to/{{destinationEnvID}}/as/authorize
to retrieve an authorization grant. -
Make a
GET
request to/{{destinationEnvID}}/rp/authenticate?providerId={{oidcProviderID}}&flowId={{flowID}}
to read the external authentication initialization. -
Make a
GET
request to/{{sourceEnvID}}/as/authorize?response_type=code&redirect_uri=https://auth.pingone.com/{{destinationEnvID}}/rp/callback/openid_connect&scope=openid&client_id={{oidcAppSourceID}}&nonce={{nonce}}&state={{externalProviderState}}
to send the external authorization request to the IdP. -
Make a
GET
request to/{{sourceEnvID}}/flows/{{flowID}}
to get the flow for the external IdP. -
Make a
POST
request to/{{sourceEnvID}}/flows/{{flowID}}
to submit the credentials for the external IdP. -
Make a
GET
request to/{{sourceEnvID}}/as/resume?flowId={{flowID}}
to call the resume endpoint for the external IdP. -
Make a
GET
request to/{{destinationEnvID}}/rp/callback/{{providerType}}?code={{authCode}}&state={{externalProviderState}}&nonce={{nonce}}
to call the external authentication callback endpoint and get the response from the external identity provider. -
Make a
GET
request to/{{destinationEnvID}}/flows/{{flowID}}
to retrieve the flow needed for account linking. -
Make a
POST
request to/{{destinationEnvID}}/flows/{{flowID}}
to submit the credentials for account linking. -
Make a
GET
request to/{{destinationEnvID}}/as/resume?flowId={{flowID}}
to call the resume endpoint. -
Make a
POST
request to/{{destinationEnvID}}/as/token
to retrieve the access token.
Click the Run in Postman button to download the Postman collection for this use case.
Step 1a: Create Source Environment
Step 1b: Create Destination Environment
Step 2: Create an OIDC application in the source environment
Step 3: Read the OIDC application secret
Step 4: Create OIDC identity provider in destination environment
Step 5: Create a sign-on policy for the OIDC IdP
Step 6: Create a sign-on policy action
Step 7: Set the sign-on policy as the default
Step 8: Create an application in the destination environment
Step 9: Read the application secret in destination
Step 10: Assign the sign-on policy to the destination OIDC application
Step 11: Create a source population
Step 12: Create a destination population
Step 13: Create a source user
Step 14: Create a destination user
Step 15: Set source user password
Step 16: Set destination user password
Step 17: Send an authorization request
Step 18: Read External Authentication Initialization
Step 19: Send external an authorization request to the IdP
Step 20: Get the flow for external identity provider
Step 21: Submit IdP credentials for external identity provider
Step 22: Call the resume endpoint for external identity provider
Step 23: Call the external authentication callback endpoint
Step 24: Get the flow for account linking
Step 25: Submit credentials for account linking
Step 26: Call the resume endpoint
Step 27: Get the access token
DaVinci
These tasks show you how to use a DaVinci flow policy with PingOne APIs to perform common actions for creating a sign-on flow policy, associating the flow policy with an application, and starting the flow. DaVinci use cases in PingOne often call the following API resources:
DaVinci API | Description |
---|---|
Flow Policies | The flow policies endpoint identifies the DaVinci flow policy resources defined in the specified environment. |
Application Flow Policy Assignments | Flow policy assignment endpoints manage the DaVinci flow policies associated with the specified application. |
Configure a PingOne App to Use a DaVinci Flow Policy
You need to begin in DaVinci, and create the DaVinci application, the DaVinci flow, and the flow policy on the application. See How to create a flow for instructions. You'll need the DaVinci flow policy ID to define the PingOne application's flow policy assignment property.
DaVinci flow settings configuration
DaVinci flows invoked using a PingOne authorize request require special configuration. In DaVinci, when you create your flow, on the flow's Settings screen, you must toggle on the PingOne Flow property located on the General tab.
Setting this property indicates that the flow is a PingOne flow, enabling it to be included in PingOne flow policies and launched directly from PingOne.
PingOne endpoints
This activity shows you how to create a PingOne application, find and associate a DaVinci flow policy with the application, and initiate the flow using a PingOne authorize request. This scenario illustrates the following common operations supported by the PingOne APIs:
- Create the application.
- Assign a DaVinci flow policy to the application.
- Create the PingOne authorize request.
To create the application and flow policy, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/flowPolicies
to return the list of DaVinci flow policies that can be associated with the PingOne application. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/flowPolicyAssignments
to assicn a DaVinci flow policy to the application. -
Make a
GET
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow using the DaVinci flow policy you assigned to the PingOne application.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a PingOne web application
Step 2: Read all flow policies
Step 3: Create the flow policy assignment
Step 4: Send an authorization request
Configure a DaVinci Non-redirect Flow
This use case triggers a DaVinci flow policy through a PingOne authorize request. In addition, it configures the authorize request to initiate a redirectless flow.
If you set the response_mode
parameter on the authorize request to pi.flow
, the authorize request does not return a 302 Location header and redirect to the PingOne authorization server. Instead, it returns a 200 message and JSON data from DaVinci. The returned data can be used to create a custom interface on a mobile application, or custom controls on a web application that engage PingOne endpoints. In general, this response mode allows a seamless integration experience, one in which no PingOne UI elements are rendered.
To complete this workflow, you need to begin in DaVinci, and create the DaVinci application, the DaVinci flow, and the flow policy on the application. See How to create a flow for instructions. You'll need the DaVinci flow policy ID to define the PingOne application's flow policy assignment property.
DaVinci flow settings configuration
DaVinci flows invoked using a PingOne authorize request require special configuration. In DaVinci, when you create your flow, on the flow's Settings screen, you must toggle on the PingOne Flow property located on the General tab.
Setting this property indicates that the flow is a PingOne flow, enabling it to be included in PingOne flow policies and launched directly from PingOne.
PingOne endpoints
This activity shows you how to create a PingOne application, find and associate a DaVinci flow policy with the application, and initiate the flow using a PingOne authorize request. This scenario illustrates the following common operations supported by the PingOne APIs:
- Create the application.
- Assign a DaVinci flow policy to the application.
- Create a PingOne population and user.
- Create the PingOne authorize request that uses the
pi.flow
setting to turn off redirects.
To create the application and flow policy, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to get the application's secret. -
Make a
GET
request to/environments/{{envID}}/flowPolicies
to return the list of DaVinci flow policies that can be associated with the PingOne application. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/flowPolicyAssignments
to assign a DaVinci flow policy to the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population. -
Make a
POST
request to/environments/{{envID}}/users
to create a new user. -
Make a
GET
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow using the DaVinci flow policy you assigned to the PingOne application.
Step 1: Create a PingOne web application
Step 2: Get the application secret
Step 3: Read all flow policies
Step 4: Create the flow policy assignment
Step 5: Create a population
Step 6: Create a user
Step 7: Send authorize request
Gateway Management
You can use the PingOne Gateways APIs to connect your on-premises resources to PingOne by creating gateway resources in PingOne, and managing the gateways from PingOne. These use cases show you how to use the PingOne Platform APIs to perform common actions for setting up and managing the gateways. The use cases often call the following APIs:
Platform API | Description |
---|---|
Gateway Management | The gateways endpoints connect resources in one security domain (for example, an on-premises datacenter or a hosted private cloud) with an environment in the PingOne platform. |
Password Policies | Password policies are implemented on populations in a PingOne environment. |
Populations | A PingOne population defines a set of users, similar to an organizational unit (OU). |
See the Gateways admin documentation for more information.
Create an LDAP Gateway
You can use an LDAP gateway to authenticate users at PingOne when their credentials are stored in an external LDAP directory. Kerberos authentication is supported.
This use case illustrates the following operations supported by the PingOne APIs:
- Create a password policy that will be applied to the population assigned to the LDAP gateway.
- Create a population for the users whose credentials are stored in the external LDAP directory.
- Create the LDAP gateway to be used for the external LDAP directory.
- Update the LDAP gateway.
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To create an LDAP gateway, the following tasks must be completed successfully:
-
Make a
POST
request to{{apiPath}}/environments/{{envID}}/passwordPolicies
to create the password policy you'll (subsequently) assign to the population for the users whose credentials are stored in the external LDAP directory. -
Make a
POST
request to{{apiPath}}/environments/{{envID}}/populations
to create the population for the users whose credentials are stored in the external LDAP directory. You'll specify the password policy you created as the password policy to apply to the LDAP directory. -
Make a
POST
request to{{apiPath}}/environments/{{envID}}/gateways
to create the LDAP gateway to use for your external LDAP directory. -
Make a
PUT
request to{{apiPath}}/environments/{{envID}}/gateways/{{gatewayID}}
to modify the LDAP gateway as needed.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create the Password Policy
Step 2: Create a Population
Step 3: Create the LDAP Gateway
Step 4: Update the LDAP Gateway
Group Management
These tasks show you how to use the platform APIs to perform common actions for managing groups. Group management use cases often call the following platform API resources:
Platform API | Description |
---|---|
Groups | The groups service enables you to create collections of users with the same access to applications. |
Users | User resources are unique identities within PingOne that interact with the applications and services in the environment to which the user is assigned. The users service implements directory functions to create, read, update, delete, and search for user resources. |
Populations | A PingOne population defines a set of users, similar to an organizational unit (OU). |
Create a Group and Add a User
This activity shows you how to create a group and assign a user to that group.
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To create a group and add a user, you must complete the following tasks:
-
Make a
POST
request to/environments/{{envID}}/groups
to create a new group. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user to assign to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{GroupUseCaseUserID}}/memberOfGroups
to add the new user to the group. -
Make a
GET
request to/environments/{{envID}}/users?filter=memberOfGroups[id eq "{{UseCaseGroupID}}"]
to return a list of all users in the group. -
Make a
GET
request to/environments/{{envID}}/users/{{GroupUseCaseUserID}}?include=memberOfGroupNames
to return a list of all groups associated with the specified user.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a group
Step 2: Create a population for users
Step 3: Create a user
Step 4: Add user to group
Step 5: Read all users in a group
Step 6: Read all group names for a user
Identity Providers
These tasks show you how to use the platform APIs to perform common actions for managing external identity providers. External identity provider use cases often call the following platform API resources:
Platform API | Description |
---|---|
Identity Provider Management | The identity provider endpoints manage external identity provider configurations. |
Gateway Management | The gateways endpoints connect resources in one security domain (for example, an on-premises datacenter or a hosted private cloud) with an environment in the PingOne platform. |
Identity Propagation | The identity propagation endpoints provide for configurable and audit-capable propagation of identities and their attributes between identity stores owned or managed by a customer. |
Configure Facebook as an Identity Provider
PingOne supports several external identity providers, including Facebook. A sign-on policy configuration in PingOne for Facebook as an identity provider allows users to authenticate and gain access to a configured application using the Facebook sign-on flow and their Facebook credentials.
If the client secret has been updated, you must also update the client secret in both the PingOne configuration for the OIDC external identity provider, and the external OpenID provider.
This scenario illustrates the following common operations supported by the PingOne APIs:
- Create an identity provider configuration
- Create an optional identity provider attribute mapping
- Create a population for Facebook users
- Create a sign-on policy
- Create a sign-on policy action
- Create an application
- Associate the sign-on policy with the application
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To create a sign-on policy that specifies Facebook as a supported external identity provider, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/identityProviders
to create the identity provider configuration for Facebook. -
Make a
POST
request to/environments/{{envID}}/identityProviders/{{providerID}}/attributes
to map the Facebookemail
attributes to PingOneemail
attributes. This step is optional. -
Make a
POST
request to/environments/{{envID}}/populations
to create a population for users who will use their Facebook credentials to sign on. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{policyID}}/actions
to create a new LOGIN sign-on policy action, which is associated with the new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/resources
to return a list of all resource entities associated with the specified environment to get the ID for the PingOne platform resource. -
Make a
GET
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to list all scopes associated with a specified resource (the PingOne platform resource). -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create the new identity provider resource
Step 2: Create an optional attribute mapping
Step 3: Create a population for Facebook users
Step 4: Create the new sign-on policy
Step 5: Create the sign-on policy action
Step 6: Create an application
Step 7: Get the list of resources
Step 8: Get all scopes
Step 9: Create the application's resource access grant
Step 10: Assign the sign-on policy to an application
Step 11: Send an authorization request
Configure a SAML Identity Provider
An external identity provider configuration in PingOne to support a SAML identity provider allows users to authenticate and gain access to application resources using a SAML sign-on flow and credentials.
The SAML identity provider's verification certificate and the signing key can be imported using the PingOne certificate management service. For information about importing certificates, see Certificate management.
This scenario illustrates the following operations supported by the PingOne APIs:
- Create an identity provider configuration
- Create a sign-on policy
- Create a sign-on policy action
- Assign the sign-on policy to an application
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To create a sign-on policy that supports a SAML external identity provider, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/certificates
to upload the SAML external identity provider's verification certificate and (optionally) to/environments/{{envID}}/keys
to upload the signing key. -
Make a
POST
request to/environments/{{envID}}/identityProviders
to create the SAML identity provider configuration. -
Make a
POST
request to/environments/{{envID}}/populations
to create a population for users who will use their SAML credentials to sign on. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{policyID}}/actions
to create a new LOGIN sign-on policy action, which is associated with the new sign-on policy.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1a: Upload the SAML application's verification certificate
Step 1b: Upload the SAML application's signing key (Optional)
Step 2: Create the new identity provider resource
Step 3: Create a population for SAML users
Step 4: Create the new sign-on policy
Step 5: Create the sign-on policy action
Identity Propagation
PingOne can propagate user identity information from the PingOne directory to a target identity store, or from a source identity store to the PingOne directory. The service continually synchronizes changes to and from the source and target identity stores. Propagation events are triggered by any addition, change, or deletion of users or user information in the source identity store.
These tasks show you how to use the platform APIs to perform common actions for managing identity propagations. Identity propagation use cases often call the following platform API resources:
Platform API | Description |
---|---|
Propagation Plans | The propagation plans service implements unidirectional provisioning relationships between pairs of identity stores. |
Propagation Stores | The propagation stores service implements connections to an identity store owned by a customer. |
Propagation Rules | The propagation rules service implements unidirectional provisioning relationships between a subset of identities on a source identity store and a target identity store. |
Propagation Mappings | The propagation mappings service implements attribute mappings associated with identity propagation rules. |
See Provisioning for more information regarding propagation of identities and Inbound and outbound provisioning for more information regarding inbound versus outbound identity stores.
Create a Workday Propagation Connection
This use case shows you how to create a propagation connection between a Workday source identity store and your PingOne directory target identity store.
A Workday propagation connection is unique in requiring a writeback of information from the target, PingOne directory, to the source, Workday. Workday is demonstrated because of its unique writeback requirement. This use case guides you in successfully creating a Workday propagation connection.
This scenario illustrates the following common operations:
- Create a propagation plan.
- Create a propagation store.
- Create a writeback propagation store (applicable only to Workday).
- Create a propagation rule.
- Create a writeback propagation rule (applicable only to Workday).
- Create propagation rule mappings.
- Create writeback propagation rule mappings (applicable only to Workday).
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To create a Workday inbound propagation connection, you will need to complete the following tasks:
- Make a
POST
request to/environments/{{envID}}/passwordPolicies
to create a password policy for the population of users to synchronize with Workday. - Make a
POST
request to/environments/{{envID}}/populations
to create a population of users to synchronize with Workday. - Make a
POST
request to/environments/{{envID}}/propagation/plans
to create a Workday propagation plan. - Make a
POST
request to/environments/{{envID}}/propagation/stores
to create a Workday inbound source propagation store with atype
ofWorkday
. - Make a
POST
request to/environments/{{envID}}/propagation/stores
to create a Workday inbound target propagation store with atype
ofPingOne
. - Make a
POST
request to/environments/{{envID}}/propagation/stores
to create a Workday writeback source propagation store oftype
directory (applicable only to Workday). No separate writeback target propagation store is required, the target is the Workday inbound source propagation store. - Make a
POST
request to/environments/{{envID}}/propagation/plans/{{planID}}/rules
to create a Workday propagation rule for mappingWorkday
attributes toPingOne
attributes. - Make a
POST
request to/environments/{{envID}}/propagation/plans/{{planID}}/rules
to create a Workday propagation rule for mappingdirectory
attributes toWorkday
attributes (applicable only to Workday). - Make a
POST
request to/environments/{{envID}}/propagation/rules/{{ruleID}}/mappings
to create a Workday inbound propagation rule mapping that associates a specific Workday attribute to a specific PingOne attribute. - Make a
POST
request to/environments/{{envID}}/propagation/plans/{{ruleID}}/rules
to create a Workday writeback propagation rule mapping that associates a specificdirectory
attribute to a specificWorkday
attribute (applicable only to Workday). - Make a
GET
request to/environments/{{envID}}/propagation/rules/{{ruleID}}/mappings
to verify Workday inbound propagation rule mappings of attributes betweenWorkday
andPingOne
. - Make a
GET
request to/environments/{{envID}}/propagation/rules/{{ruleID}}/mappings
to verify Workday writeback propagation rule mappings of attributes betweendirectory
andWorkday
(applicable only to Workday). - Make a
GET
request to/environments/{{envID}}/propagation/rules
to verify the Workday inbound propagation rule betweenWorkday
andPingOne
and the Workday writeback propagation rule betweendirectory
andWorkday
(applicable only to Workday). - Make a
GET
request to/environments/{{envID}}/propagation/stores
to verify Workday propagation stores of typesWorkday
,PingOne
, anddirectory
. - Make a
GET
request to/environments/{{envID}}/propagation/plans
to verify Workday propagation plans.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a password policy for the Workday population
Step 2: Create a population to synchronize with Workday
Step 3: Create a Workday inbound propagation plan
Step 4: Create a Workday inbound source propagation store
Step 5: Create a PingOne inbound target propagation store
Step 6: Create a directory writeback source propagation store
Step 7: Create a Workday inbound propagation rule
Step 8: Create a Workday writeback propagation rule
Step 9: Create a Workday inbound propagation rule mapping
Step 10: Create a Workday writeback propagation rule mapping
Step 11: Read inbound propagation rule mappings to verify
Step 12: Read writeback propagation rule mappings to verify
Step 13: Read all propagation rules to verify
Step 14: Read all propagation stores to verify
Step 15: Read all propagation plans to verify
Step 16: Restore your Postman and PingOne environments (Optional)
Integration Catalog
Providing a seamless integration with cloud, mobile, and on-premise applications, the rich ecosystem of available PingOne integrations provides a highly customizable platform. These integrations extend authentication, access, and directory processes of Ping solutions to support single sign-on, multi-factor authentication, native device management, risk intelligence, external identity providers, provisioning, and more.
Of course, with so many integration options available, the need for management of these assets becomes apparent. The Integration Catalog service of the PingOne API acts as a central hub for these features, providing programmatic access to the software binaries and related metadata for each integration, as well as its relevant versions. Access to this data will help administrators map and maintain their Ping integration landscape, regardless of scale.
Download an Integration Binary
Integration kits include .jar files, configuration files, templates, documentation, and other content packaged with an integration. In this use case, you will search your environment for a specific integration. Once found, you will download the integration kit as a zip file.
The purpose of this use case is to provide a simplified view of the interaction with the PingOne Integration Catalog service. In a real world environment, an administrator would expand upon this example to ensure specific integrations were available. For instance, a PingCloud administrator could establish a connection to the PingOne Integration Catalog to retrieve integration kits and include them in the automated startup of containers.
This scenario illustrates the following common operations:
- Get the environment ID.
- Get a list of integrations and their versions.
- Download the integration binary.
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To download a specific integration binary, you will need to complete the following tasks:
-
Make a
GET
request to the/environments
endpoint to get the environment resource ID. -
Make a
GET
request to/environments/{{envID}}/integrations
to retrieve a list of available integrations, using thefilter
parameter to provide a targeted result set. -
Make a
GET
request to{{apiPath}}/environments/{{envID}}/integrations/{{integrationID}}/versions
to retrieve a list of available integration versions. -
Make a
GET
request to/environments/{{envID}}/integrations/{{integrationID}}/versions/{{integrationVersionID}}/asset
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Get the environment ID
Step 2: Get a list of integrations
Step 3: Get a list of integration versions
Step 4: Download the integration zip file
Risk Management
These tasks show you how to use the platform APIs to perform common actions for managing risk policies. Risk policy use cases often call the following platform API resources:
Platform API | Description |
---|---|
Risk Policies | The risk policies service implements directory functions to manage risk policy resources. |
Risk Evaluations | Risk evaluations provides operations to retrieve risk evaluations from internal and external risk providers based on a specified risk policy. |
Create a Risk Policy Set
This activity shows you how to create a new risk policy. This scenario illustrates the following common operations supported by the PingOne APIs:
- Get the environment ID
- Create a risk policy set by defining one or more risk policies
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To create the new risk policy set, the following tasks must be completed successfully:
-
Make a
GET
request to the/environments
endpoint to get the environment resource ID. -
Make a
POST
request to/environments/{{envID}}/riskPolicies
to create a new risk policy set resource.
Click the Run in Postman button below to download the Postman collection for this use case.
Policy set logic
A risk policy set must have at least one defined risk policy, which includes the following components:
-
Condition. The policy logic to define when the policy is evaluated to
true
and when it is evaluated tofalse
. -
Result. The policy logic to define what should be returned in case the condition is evaluated to
true
. -
Priority. (Optional) A priority ranking to define the execution order of the different risk policies contained in the policy set.
For this use case, you will define a simple risk policy set that includes two risk policies: A whitelist that evaluates risk based on the user's IP address, and an anonymous network detection check.
The following JSON shows the elements defined in the whitelist risk policy. The condition.contains
expression uses the ${transaction.ip}
condition variable to get the user's IP address and compare it to a range of IP addresses that are considered safe. If the user's IP address is within the range set in condition.ipRange
, the condition evaluates to true
, and the result.level
is set to LOW
, indicating low risk for this policy condition.
"riskPolicies": [
{
"name": "WHITELIST",
"priority": 1,
"result": {
"level": "LOW"
},
"condition": {
"contains": "${transaction.ip}",
"ipRange": [
"1.1.1.1/16",
"2.2.2.2/24"
]
}
}
]
The following JSON shows the elements defined in the anonymous network detection risk policy. The condition.contains
expression uses the ${details.anonymousNetworkDetected}
condition variable to to determine whether the user is attempting to authenticate from an anonymous network. If the condition.value
evaluates to true
, then the result.level
is set to HIGH
, indicating that this is a high-risk transaction.
...
"name": "ANONYMOUS_NETWORK_DETECTION",
"priority": 2,
"result": {
"level": "HIGH",
"type": "VALUE"
},
"condition": {
"equals": true,
"value": "${details.anonymousNetworkDetected}"
},
For more information about risk policies, see Risk Policies.
Step 1: Get the environment ID
Step 2: Create a risk policy set
Create a Risk Evaluation
This activity shows you how to create a new risk evaluation. This scenario illustrates the following common operations supported by the PingOne APIs:
- Get a list of risk policy set resources
- Create a risk evaluation resource that uses a specific risk policy set
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To create the new risk evaluation, the following tasks must be completed successfully:
-
Make a
GET
request to/environments/{{envID}}/riskPolicies
to return the list of risk policy set resources associated with the environment. -
Make a
POST
request to/environments/{{envID}}/riskEvaluations
to create a new risk evaluation resource that references a risk policy set resource.
Click the Run in Postman button below to download the Postman collection for this use case.
Defining the risk evaluation resource
For the POST
request to /environments/{{envID}}/riskEvaluations
, the risk evaluation resource definition lets you specify the risk policy set to apply to the evaluation. If a particular risk policy set is not specified, the risk evaluation uses the environment's default risk policy set to determine the risk levels for the event. In this use case, the risk evaluation sets theriskPolicySet.id
property to the {{riskPolicySetID}}
Postman variable, which should contain the ID of the risk policy set that you created in the USE CASE: Create a risk policy set activity.
The risk evaluation definition must include an event
object that specifies details about the authentication action to evaluate against the risk policies defined in the risk policy set. In its most basic form, the event object defines a user (user.id
and user.type
) and an IP address (ip
). From this information, the risk evaluation can provide a meaningful risk response for all supported risk predictors (anonymousNetwork
, ipRisk
, geoVelocity
, userRiskBehavior
) except the user risk behavior predictor, which requires the targetResource
and UserAgent
properties. For more information about the risk evaluation event data model, see Risk Evaluations in the PingOne API Reference.
The risk evaluation process follows these steps:
-
The risk service receives an event that it is configured to monitor and evaluate.
-
A risk calculation is made for the event based on the configured risk policies.
-
The risk service returns the risk result to the client.
Step 1: Get risk policy set IDs
Step 2: Create a risk evaluation
Multi-factor Authentication
These tasks show you how to use the platform APIs to perform common MFA actions for non-native applications. MFA use cases often call the following platform API resources:
Platform API | Description |
---|---|
Sign-On Policies | Sign-on policies determine the account authentication flow users must complete to access applications secured by PingOne services. |
Resources | Resources are the protected endpoints that applications request access to using OAuth 2 authorization services. |
Applications | Application resources define the connection between PingOne and the actual application. |
Assign an MFA Sign-On Policy to a Web Application
This activity shows you how to define a Web application, create an MFA sign-on policy, and assign the sign-on policy to the application.
This scenario illustrates the following common operations supported by the PingOne APIs:
- Create an application
- Assign a resource grant to the application
- Create a sign-on policy
- Create a sign-on policy MFA action
- Assign a sign-on policy to an application
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To create the application specify its sign-on policy:
-
Make a
POST
request to the/environments/{{envID}}/applications
endpoint to define a new Web application. -
Make a
GET
request to/environments/{{envID}}/resources
to get the list of available resource server IDs. -
Make a get request to
/environments/{{envID}}/resources/{{resourceID}}/scopes
to get the OIDC scopes for the resource grant. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to assign a resource grant to the application. -
Make a
POST
request to the/environments/{{envID}}/signOnPolicies
endpoint to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}
to create an MFA sign-on policy action for the new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to assign the MFA sign-on policy with the new Web application.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a web application
Step 2: Get all resources
Step 3: Get all OIDC scopes
Step 4: Assign a resource grant to the web application
Step 5: Create an MFA sign-on policy
Step 6: Create a sign-on policy MFA action
Step 7: Assign the MFA sign-on policy to the web application
Configure a Passwordless Sign-On Policy
PingOne supports a sign-on flow that uses only a username and a multi-factor authentication (MFA) sign-on action to authenticate the user. This activity shows you how to create a sign-on policy that does not require a password at sign on.
This scenario illustrates the following common operations supported by the PingOne APIs:
- Create an application connection
- Create a sign-on policy
- Create a sign-on policy action
- Assign the sign-on policy to an application
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To create a sign-on policy that does not prompt for a password at login, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to create a new application connection. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{policyID}}/actions
to create a new MFA sign-on policy action, which is associated with the new (no password) sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate this sign-on policy with the specified application. -
Make a
GET
request to the authorization server to retrieve the URL for the sign-on screen, which is returned in the response's HTTPLocation
header.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create an application
Step 2: Create the new sign-on policy
Step 3: Create the sign-on policy action
Step 4: Assign the sign-on policy to an application
Step 5: Test authentication
Configure an MFA-Only Flow Using a Login Hint Token
This activity shows you how to create an MFA only authentication flow using a login_hint_token
to identify and authenticate the end-user without needing to encode the entire authentication request in a signed JWT.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a sign-on policy
- Create an SMS sign-on policy action
- Create a user
- Create a device authentication policy
- Initiate an authorize request using a
login_hint_token
- Use the OTP check API to complete the MFA action
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To complete an MFA only authentication flow, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute, which is needed for the token request. -
Make a
GET
request to/environments/{{envID}}/resources
to return a list of all resource entities associated with the specified environment. -
Make a
GET
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to list all scopes associated with a specified resource. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the SMS MFA action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/mfaEnabled
to enable MFA actions for this user. -
Make a
POST
request to/environments/{{envID}}/deviceAuthenticationPolicies
to create the device authentication policy. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/devices
to associate an SMS MFA device with this user. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
To complete the SMS MFA action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the one-time passcode. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the auth code.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a web application
Step 2: Get the application secret
Step 3: Get all resources
Step 4: Get all OIDC Scopes
Step 5: Assign a resource grant to the web application
Step 6: Create a sign-on policy
Step 7: Create an SMS MFA sign-on policy action
Step 8: Assign the sign-on policy to the web application
Step 9: Create a population for MFA users
Step 10: Create user
Step 11: Set user password
Step 12: Enable user MFA
Step 13: Create the device authentication policy
Step 14: Set user device (SMS)
Step 15: Send authorize request
Step 16: Check OTP
Step 17: Call the resume endpoint
Create an MFA Transaction Approval using SMS
This activity shows you how to create a transaction approval MFA authentication flow using a request
token to encode the request parameters in a signed JWT.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a sign-on policy
- Create an SMS sign-on policy action
- Create a device authentication policy
- Create a user
- Initiate an authorize request using a
request
token and alogin_hint_token
- Use the OTP check API to complete the MFA action
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To complete a transaction approval MFA authentication flow, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute, which is needed for the token request. -
Make a
GET
request to/environments/{{envID}}/resources
to return a list of all resource entities associated with the specified environment. -
Make a
GET
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to list all scopes associated with a specified resource. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the SMS MFA action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/templates/transaction/contents
to create a transaction notification template. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/mfaEnabled
to enable MFA actions for this user. -
Make a
POST
request to/environments/{{envID}}/deviceAuthenticationPolicies
to create the device authentication policy. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/devices
to associate an SMS MFA device with this user. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
To complete the SMS MFA action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the one-time passcode. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the auth code. -
Make a
POST
request to/{{envID}}/as/token
to exchange the auth code for an access token.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a web application
Step 2: Get the application secret
Step 3: Get all resources
Step 4: Get all OIDC Scopes
Step 5: Assign a resource grant to the web application
Step 6: Create a sign-on policy
Step 7: Create an SMS MFA sign-on policy action
Step 8: Assign the sign-on policy to the web application
Step 9: Create a transaction SMS template
Step 10: Create a population for MFA users
Step 11: Create user
Step 12: Set user password
Step 13: Enable user MFA
Step 14: Create the device authentication policy
Step 15: Set user device (SMS)
Step 16: Send authorize request for transaction approval
Step 17: Check OTP
Step 18: Call the resume endpoint
Step 19: Get the access token
Use an Email MFA Action to Authenticate Users
This activity shows you how to create a sign-on policy with an Email MFA action, initiate an authorization request, and use the flow APIs to complete the authorization.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a sign-on policy
- Create an Email MFA sign-on policy action
- Create a device authentication policy
- Create a user
- Initiate an authorize request
- Use flow APIs to complete the MFA action
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To complete a MFA sign on, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/resources
to return a list of all resource entities associated with the specified environment. -
Make a
GET
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to list all scopes associated with a specified resource. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the Email MFA action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population resource. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population resource. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/mfaEnabled
to enable MFA actions for this user. -
Make a
POST
request to/environments/{{envID}}/deviceAuthenticationPolicies
to create the device authentication policy. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/devices
to associate an Email MFA device with this user. -
Make a
POST
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the sign-on flow. -
To complete the sign-on action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's username for a user lookup action. -
To complete the Eamil MFA action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the one-time passcode. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the auth code. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute, which is needed for the token request. -
Make a
POST
request to/{{envID}}/as/token
to exchange the auth code for an access token.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a web application
Step 2: Get all resources
Step 3: Get all OIDC Scopes
Step 4: Assign a resource grant to the web application
Step 5: Create a sign-on policy
Step 6: Create an Email MFA sign-on policy action
Step 7: Assign the sign-on policy to the web application
Step 8: Create a population for MFA users
Step 9: Create a user
Step 10: Set user password
Step 11: Enable user MFA
Step 12: Create the device authentication policy
Step 13: Set user device (Email)
Step 14: Send an authorization request
Step 15: Get the flow
Step 16: Sign on with a username
Step 17: Check OTP for Email
Step 18: Call the resume endpoint
Step 19: Get the application secret
Step 20: Get the access token
Configure an MFA Sign-On Policy with an Authenticator App
This activity shows you how to define a native application, create an MFA sign-on policy that enables MFA using an authenticator application, and assign the sign-on policy to the application.
This scenario illustrates the following common operations supported by the PingOne APIs:
- Create an application
- Assign a resource grant to the application
- Create a sign-on policy
- Create a sign-on policy MFA action
- Assign a sign-on policy to an application
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To create the application and specify its sign-on policy:
-
Make a
POST
request to the/environments/{{envID}}/applications
endpoint to define a native application. -
Make a
GET
request to/environments/{{envID}}/resources
to get the list of available resource server IDs. -
Make a get request to
/environments/{{envID}}/resources/{{resourceID}}/scopes
to get the OIDC scopes for the resource grant. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to assign a resource grant to the application. -
Make a
POST
request to the/environments/{{envID}}/signOnPolicies
endpoint to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}
to create an MFA sign-on policy action for the new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to assign the MFA sign-on policy with the new application.
Step 1: Create a native application
Step 2: Get all resources
Step 3: Get all OIDC Scopes
Step 4: Assign a resource grant to the application
Step 5: Create an MFA sign-on policy
Step 6: Create a sign-on policy MFA action
Step 7: Assign the MFA sign-on policy to the application
Password Policies
Password policies are associated with an environment, and are implemented on populations in the environment. These use cases show you how to use the PingOne Platform APIs to perform common actions for setting up and managing the gateways. The use cases often call the following APIs:
Platform API | Description |
---|---|
Password Policies | Password policies are implemented on populations in a PingOne environment. |
Populations | A PingOne population defines a set of users, similar to an organizational unit (OU). |
Users | A user has a unique identity within PingOne. Users are associated with an environment and a population. |
User Passwords | Operations supporting user passwords. |
See the Managing Password Policies admin documentation for more information.
Create a Password Policy
You can use password policies to create policies for specific user populations in an environment.
This use case illustrates the following operations supported by the PingOne APIs:
- Create a password policy that will be applied to a population.
- Create a population to which the password policy is applied.
- Create a user in the population.
- Set an initial password for the new user. The password must be changed when the user first signs on.
- Enable the user to update the password.
Workflow order of operations
To create and apply a password policy, you'll need to:
-
Make a
POST
request to{{apiPath}}/environments/{{envID}}/passwordPolicies
to create the password policy you'll use. -
Make a
POST
request to{{apiPath}}/environments/{{envID}}/populations
to create a population for which you'll apply the password policy. You'll specify the password policy you created as the password policy for this population. -
Make a
POST
request to{{apiPath}}/environments/{{envID}}/users
to create a user, assigning the user to the population you created. -
Make a
PUT
request to{{apiPath}}/environments/{{envID}}/users/{{userID}}/password
to set an initial password for the new user. -
Make another
PUT
request to{{apiPath}}/environments/{{envID}}/users/{{userID}}/password
, this time enabling the new user to specify their password.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create Password Policy
Step 2: Create Population
Step 3: Create User
Step 4: Update Password (Set)
Step 5: Update Password (Self)
PingOne Authorize
These tasks show you how to use the PingOne Authorize APIs to enable fine-grained, attribute-based, dynamic authorization decisioning capabilities. PingOne Authorize use cases call the following API resources:
Platform API | Description |
---|---|
Policy Decision Service | Decision endpoints that allow efficient evaluation of policies developed in the PingOneAuthorize Policy Editor Service. |
API Access Management | The API access management service provides tools to externalize the management and evaluation of access control policies for HTTP-based APIs. |
Resources | Resources are the protected endpoints that applications request access to using OAuth 2 authorization services. |
Application Resources and Roles | The application resources and roles service provides endpoints to define custom roles and permissions within PingOne to protect external application resources. |
Show PingOne Authorize App Permissions in Token
This activity shows you how to create a custom resource and how to use PingOne Authorize endpoints to create application roles and permissions to associate with the custom resource. The custom resource configuration includes a setting to show application permissions as a claim in the access token.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a custom resource
- Create PingOne Authorize application resources, roles, and permissions
- Create a sign-on policy
- Create login sign-on policy action
- Create a user
- Initiate an authorize request
- Use flow APIs to complete the login actions
- Use the token request to get an access token for the custom resource
- Use the token introspection endpoint to show application permissions in the access token
Prerequisites
-
You must have the
PING_ONE_AUTHORIZE
capability in the Bill of Materials (BOM) for your environment to run the PingOne Authorize requests to create application resources, application roles, and application permissions. -
Get an access token from the worker application you created in 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 get an access token for the custom resource, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
GET
request to/environments/{{envID}}/applications/{{appID}}/secret
to return the new application'ssecret
attribute, which is needed for the token request. -
Make a
POST
request to/environments/{{envID}}/resources
to define the custom resource. -
Make a
POST
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to define a scope for the custom resource. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/resources/{{customResourceID}}/applicationResources
to create the application resource. -
Make a
POST
request to/environments/{{envID}}/applicationResources/{{appResourceID}}/permissions
to create the application resource permission. -
Make a
POST
request to/environments/{{envID}}/applicationRoles
to create an application role. -
Make a
POST
request to/environments/{{envID}}/applicationRoles/{{appRoleID}}/permissions
to assign an application resource permission to the specified role. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies
to create a new sign-on policy. -
Make a
POST
request to/environments/{{envID}}/signOnPolicies/{{signOnPolicyID}}/actions
to define the login action associated with this sign-on policy. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/signOnPolicyAssignments
to associate the sign-on policy with the application. -
Make a
POST
request to/environments/{{envID}}/populations
to create a new population. -
Make a
POST
request to/environments/{{envID}}/users
to create a user who will be assigned to the new population. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/password
to set the new user's password. -
Make a
POST
request to/environments/{{envID}}/users/{{customResourceUserID}}/applicationRoles
to assign the application role to a user. -
Make a
GET
request to/{{envID}}/as/authorize
to obtain an authorization grant. This request starts the authorization flow. -
Make a
GET
request to/{{envID}}/flows/{{flowID}}
to initiate the sign-on flow. -
To complete the login action, make a
POST
request toGET /{{envID}}/flows/{{flowID}}
and provide the user's login credentials. -
Make a
GET
request to/{{envID}}/as/resume?flowId={{flowID}}
to call the resume endpoint and return the auth code. -
Make a
POST
request to/{{envID}}/as/token
to exchange the auth code for an access token. -
To verify that the token includes the application permissions, make a
POST
request toGET /{{envID}}/as/introspect
to view the application permission claim in the token.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a web application
Step 2: Get the application secret
Step 3: Create a custom resource
Step 4: Create a custom resource scope
Step 5: Assign a resource grant to the web application
Step 6: Create an application resource
Step 7: Create application permissions
Step 8: Create an application role
Step 9: Create application role permissions
Step 10: Create a sign-on policy
Step 11: Create the login sign-on policy action
Step 12: Assign the sign-on policy to the web application
Step 13: Create a population
Step 14: Create a user
Step 15: Set user password
Step 16: Assign the application role to user
Step 17: Send an authorization request
Step 18: Get the flow
Step 19: Submit login credentials
Step 20: Call the resume endpoint
Step 21: Get the access token
Step 22: Token Introspection
Create and Assign App Roles
This activity shows you how to create and assign application roles to users, which helps to simplify managing application permissions.
Application permissions are used to protect application resources, and can be thought of as the actions that can be taken on a resource. Application roles are associated with application permissions, and can be assigned to users to determine which actions they can perform on an application resource.
In this activity, you'll create a custom resource and use the PingOne Authorize Endpoint to create an application permission and application role. You'll then assign the application role to a user.
The following operations are supported by the PingOne APIs:
- Create an application
- Create a custom resource
- Create PingOne Authorize application resources, roles, and permissions
- Create user application role assignments
Prerequisites
-
You must have the
PING_ONE_AUTHORIZE
capability in the Bill of Materials (BOM) for your environment to run the PingOne Authorize requests to create application resources, application roles, and application permissions. -
Create a user to get a
userID
. See Create User or Read All Users to find an existing user. AuserID
is needed to assign an application role to a user in this activity. -
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 application permissions, application roles, and assign application roles to a user, the following tasks must be completed successfully:
-
Make a
POST
request to/environments/{{envID}}/applications
to add a new application to the specified environment. -
Make a
POST
request to/environments/{{envID}}/resources
to define the custom resource. -
Make a
POST
request to/environments/{{envID}}/resources/{{resourceID}}/scopes
to define a scope for the custom resource. -
Make a
POST
request to/environments/{{envID}}/applications/{{appID}}/grants
to create a new resource access grant for the application. -
Make a
POST
request to/environments/{{envID}}/resources/{{customResourceID}}/applicationResources
to create the application resource. -
Make a
POST
request to/environments/{{envID}}/applicationResources/{{appResourceID}}/permissions
to create the application resource permission. -
Make a
POST
request to/environments/{{envID}}/applicationRoles
to create an application role. -
Make a
POST
request to/environments/{{envID}}/applicationRoles/{{appRoleID}}/permissions
to assign an application resource permission to the specified role. -
Make a
POST
request to/environments/{{envID}}/users/{{userID}}/applicationRoles
to assign the application role to a user.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create a web application
Step 2: Create a custom resource
Step 3: Create a custom resource scope
Step 4: Assign a resource grant to the web application
Step 5: Create an application resource
Step 6: Create application permissions
Step 7: Create an application role
Step 8: Create application role permissions
Step 9: Assign the application role to user
User Management
These tasks show you how to use the platform APIs to perform common actions for managing identities. Identity management use cases often call the following platform API resources:
Platform API | Description |
---|---|
Roles | Roles determine which actions a user is allowed to perform. |
Users | User resources are unique identities within PingOne that interact with the applications and services in the environment to which the user is assigned. The users service implements directory functions to create, read, update, delete, and search for user resources. |
Assign a Role to a User
Roles determine what actions a user can perform. For example, to generate a client secret, a user must be assigned the Environment Admin role.
The PingOne roles are:
Role | Icon |
---|---|
Organization Admin | |
Environment Admin | |
Identity Data Admin | |
DaVinci Admin | |
Application Owner | |
Identity Data Read-Only Admin | |
Configuration Read-Only Admin | |
DaVinci Read-Only Admin | |
Client Application Developer |
For permissions associated with each role, see PingOne Role Permissions.
Prerequisites
-
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
-
An existing user to assign the role to.
Workflow order of operations
To assign a role to a user, complete the following tasks:
-
Make a
GET
request to{{apiPath}}/environments/{{envID}}/users
to get the ID of the user. -
Make a
GET
request to{{apiPath}}/roles
to get the ID of the role to assign. -
Make a
POST
request to{{apiPath}}/environments/{{envID}}/users/{{userID}}/roleAssignments
to create the user role assignment.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Get the user ID
Step 2: Get the role ID
Step 3: Create the user role assignment
Add User Image
This activity shows you how to update the user image for an existing user.
The following operations are supported by the PingOne APIs:
- Create a user
- Create an image
- Update the user profile
Prerequisites
- Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
- Run Read all populations to find a population ID value. You will use this value to create a user in step 1.
- Download an image file (maximum size 2 MB) to your machine. You will attach this image to the request in step 2.
Workflow order of operations
To upload and assign a user image, complete the following tasks:
- Make a
POST
request to/environments/{{envID}}/users
to create a user. - Make a
POST
request to/environments/{{envID}}/images
to upload an image to your PingOne environment. - Make a
PATCH
request to/environments/{{envID}}/users/{{userID}}
to assign the image to a user profile.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Create User
Step 2: Create Image
Step 3: Update User
Find and Terminate a User Session
This activity shows you how to find and terminate a user session.
The following operations are supported by the PingOne APIs:
- Read a user session
- Delete a user session
Prerequisites
- Create a user and initiate a user session in Configure a Simple Login.
Workflow order of operations
To configure a simple login with a username and password, you must complete the following tasks:
-
Make a
GET
request to/environments/{{envID}}/users/{{SimpleLoginUserID}}/sessions
to locate the current user session. -
Make a
DELETE
request to/environments/{{envID}}/users/{{SimpleLoginUserID}}/sessions/{{UserSessionID}}
to terminate the current user session. -
Make a
GET
request to/environments/{{envID}}/users/{{SimpleLoginUserID}}/sessions
to verify no sessions are found.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1: Read the current user session
Step 2: Delete the user session
Step 3: Verify there are no active sessions
Sign-Off User Session
This activity shows you how to create the PingOne signoff flow. This flow ends the user's SSO session, which signs them out of all applications using that session.
This scenario illustrates the following common operations supported by the PingOne APIs:
-
Get a user session.
-
Terminate the user's current session.
Prerequisites
- Create a test user and activate a user session. Complete the Configure a Simple Login use case to open an active user session.
Workflow order of operations
To end a user's active session, complete the following tasks:
-
Make a
GET
request to/environments/{{envID}}/users/{{userID}}/sessions
to verify the active user session. -
Make a
GET
request to/{{envID}}/as/signoff
to terminate the user session.
We highly recommend that you use our Postman collection for this workflow. For information about using Postman environments, see The PingOne Postman environment template.
Click the Run in Postman button below to download or fork the Postman collection for this solution.
Step 1: Get user sessions
Step 2: Sign-off user session
Metrics
These tasks show you how to use the platform APIs to perform common activities for querying metrics data. Metrics use cases often call the following platform API resources:
Platform API | Description |
---|---|
Audit Activities | Audit reporting caches incoming audit messages and provides endpoints to request audit events for a specified date range. |
Audit for Agreement Consents
This activity shows you how to use the activities endpoint to find agreements associated with users, and users associated with agreements.
The following operations are supported by the PingOne APIs:
- Use the audit activities endpoint to run a metrics query to return consent agreement history for a specified agreement.
- Use the audit activities endpoint to run a metrics query to return consent agreement history for a specified user.
Prerequisites
Get an access token from the worker application that you created in Getting Started with the PingOne APIs. To get a token from a different worker application in an alternate sandbox environment, run the token request endpoint using the client ID and client secret of your chosen worker app to authenticate the request. For more information, see GET a Worker Application Access Token.
Workflow order of operations
To complete a metrics query to return consent agreement history for a specified agreement and user, the following tasks must be completed successfully:
- Make a
GET
request to/environments/{{envID}}/activities
to return consent agreement history for a specified agreement. - Make a
GET
request to/environments/{{envID}}/activities
to return consent agreement history for a specified user.
Click the Run in Postman button below to download the Postman collection for this use case.
Step 1. View Consent History for an Agreement
Step 2. View Consent History for a User
PingOne Services
PingOne services is a set of cloud identity and access management services that supply distinct, advanced capabilities to the PingOne platform. Each service is independent of the other services, and has its own unique APIs. Your organization's licensing can include:
PingOne Authorize
PingOne Authorize provides customers with a fine-grained, attribute-based, dynamic authorization decisioning capability. PingOne Authorize moves per-transaction authorization logic from customer applications to PingOne, enabling centralized control of authorization policy and reuse of policy across applications and contexts.
-
See the PingOne Authorize admin documentation.
-
For information about creating, reading, updating, and deleting policy decision resources, see PingOne Authorize Policy Decision Service and Policy Decision Authorization.
-
For information about creating, reading, updating, and deleting API access management service resources, see PingOne Authorize API Access Management.
PingOne MFA
PingOne MFA is a cloud-based service that provides multi-factor authentication (MFA) for the customer use case, that protects an organization's network, applications, and data resources.
See Getting Started with PingOne MFA in the PingOne MFA Administration Guide, which demonstrates a basic flow of practical steps to getting started with PingOne MFA, accompanied with explanations.
The flow depicts typical interaction between admin and developer roles. There are some PingOne MFA tasks which can only be implemented using the admin UI, whereas for other tasks, there is also the option to apply some of these steps using the developer API. At each step that the API option is possible, it is noted together with a link to the relevant section in the developer API documentation.
PingOne Neo
PingOne Neo is a decentralized identity solution that gives control of identity data back to users. PingOne Neo empowers businesses to give their users full control over how they securely store and share verified credentials without unnecessary friction.
PingOne Neo also provides organizations with identity verification capabilities and the capability to issue credentials for users to store in their wallet app and verify user data with access to:
A self-service interface included to customize and issue verifiable digital credentials that users can store in their wallet app with no code required.
Enabled secure user identity verification based on a government-issued document and live face capture (a selfie) using the PingOne Verify Integration Kit. For more information, see PingOne Verify Integration Kit.
Embed identity verification and a digital wallet into your mobile applications. Works with PingOne Verify and PingOne Credentials. Android and iOS are both supported.
For more information about PingOne Neo, see PingOne Neo.
PingOne Credentials
PingOne Credentials service allows issuers to create verifiable credentials that they can issue to a user's compatible wallet app.
The issuer creates a credential template in PingOne Credentials that they can use to produce a visual credential to a user. The issuer can define individual fields on the credential in the form of name-value pairs to provide the appropriate details for the service credential they are offering to their users.
Credential details vary according to the industry and the specific credentials the issuer wants to offer. For example, in addition to name and date of birth, an insurance company might want to provide the type of insurance, policy number, and expiry date. A bank might want to include the bank account number and date of issue, and a university might want to include the type of degree, and the class obtained.
To set up and configure PingOne Credentials, you'll use:
- The PingOne console to configure PingOne Credentials.
The PingOne Credentials service maintains a unique private-key for each service provider within the PingOne environment. To simplify the creation and issuance of credentials, PingOne Credentials provides APIs that allow customers to interact programmatically and with additional customizations.
PingOne Verify
PingOne Verify enables secure user verification based on a government-issued document and live face capture (a selfie). The user ID information is captured on a user's iOS or Android device using the customer-created Verify app, and sent to the PingOne ID Verification service. The PingOne ID Verification service interacts with a service provider or providers that verify the submitted user ID information. When a user's ID information is successfully verified, the PingOne ID Verification service approves the user authentication and sends the ID verification status to the customer Verify app on a user's device.
Only the ID verification status is retained by PingOne. Any personally identifiable information (PII data) passed to PingOne is deleted by the ID Verification service.
To set up and configure PingOne Verify, you'll use:
-
The PingFederate admin console for Configuring the PingOne Verify Integration Kit.
See PingOne Verify transactions flow and Getting started with PingOne Verify in the PingOne Verify Administration Guide.
PingOne Protect
PingOne Protect is a cloud-based service that provides a single access point for event-based risk evaluations. The Protect service can be used with Ping Identity's SaaS products such as PingOne and PingOne MFA as well as with on-premise software products such as PingFederate.
See Getting Started with PingOne Protect in the PingOne Protect Administration Guide, which demonstrates a basic flow of practical steps to getting started with PingOne Protect, accompanied with explanations. The flow depicts typical interaction between admin and developer operations.
For the PingOne Protect APIs, see PingOne Protect.
Conventions
This topic describes how to call PingOne APIs, how responses are returned by the PingOne resource server, and how collections that support filtering can be fine-tuned using query parameters on the request. The following sections provide information about these conventions:
PingOne API requests
Public endpoints
This section discusses making requests to public endpoints using geographic regional domains in your PingOne environment. If you use the Postman environment template retrieved when you Download the PingOne Postman collections, set the value of {{tld}}
to the top level domain (TLD) appropriate to your region. See PingOne API domains for more information. When you set {{tld}}
, the {{...Path}}
variables are also set to the appropriate region.
The public endpoint for calling PingOne API services for environments in the North America region (excluding Canada) is api.pingone.com
, the public endpoint for environments in the Canada region is api.pingone.ca
, the public endpoint for environments in the European Union region is api.pingone.eu
, the public endpoint for environments in the Asia-Pacific region is api.pingone.asia
, and the public endpoint for environments in the Australia region is api.pingone.com.au
. In the example requests, these endpoints are defined in the Postman environment variable {{apiPath}}
as https://api.pingone.com/v1
for the North America region (excluding Canada), https://api.pingone.ca/v1
for the Canada region, https://api.pingone.eu/v1
for the Europe region, https://api.pingone.asia/v1
for the Asia-Pacific region, and https://api.pingone.com.au/v1
for the Australia region. Note that the trailing /v1
is required in the {{apiPath}}
variable.
Authentication public endpoints
PingOne offers a separate authentication service. This service requires that all authentication API requests go to an exclusive domain. As with endpoints for environments, the PingOne authentication service in each region has a separate endpoint: auth.pingone.com
for the North America region (excluding Canada), auth.pingone.ca
for the Canada region, auth.pingone.eu
for the Europe region, auth.pingone.asia
for the Asia-Pacific region, and auth.pingone.com.au
for the Australia region. In the example requests, these endpoints are defined in the Postman environment variable {{authPath}}
as 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 Europe region, https://auth.pingone.asia
for the Asia-Pacific region, and https://auth.pingone.com.au
for the Australia region. Note that nothing trails the domain in the {{authPath}}
variable.
PingOne DaVinci public endpoints
PingOne offers the PingOne DaVinci for orchestrating flows. This service requires that all management API requests go to an exclusive domain. As with endpoints for environments, the PingOne DaVinci service in each region has a separate endpoint: orchestrate-api.pingone.com
for the North America region (excluding Canada), orchestrate-api.pingone.ca
for the Canada region, orchestrate-api.pingone.eu
for the Europe region, orchestrate-api.pingone.asia
for the Asia-Pacific region, and orchestrate-api.pingone.com.au
for the Australia region. In the example requests, these endpoints are defined in the Postman environment variable {{orchestratePath}}
as https://orchestrate-api.pingone.com/v1
for the North America region (excluding Canada), https://orchestrate-api.pingone.ca/v1
, https://orchestrate-api.pingone.eu/v1
, https://orchestrate-api.pingone.asia/v1
, and https://orchestrate-api.pingone.com.au/v1
. Note that the trailing /v1
is required in the {{orchestratePath}}
variable.
SCIM public endpoints
PingOne offers the SCIM service for using the System for Cross-domain Identity Management (SCIM), an open standard protocol, for identity management via HTTP. This service requires that all SCIM API requests go to an exclusive domain. As with endpoints for environments, the SCIM service in each region has a separate endpoint: scim-api.pingone.com
for the North America region (excluding Canada), scim-api.pingone.ca
for the Canada region, scim-api.pingone.eu
for the Europe region, scim-api.pingone.asia
for the Asia-Pacific region, and scim-api.pingone.com.au
for the Australia region. the example requests, these endpoints are defined in the Postman environment variable {{scimPath}}
as, https://scim-api.pingone.com
for the North America region (excluding Canada), https://scim-api.pingone.ca
for the Canada region, https://scim-api.pingone.eu
for the Europe region, https://scim-api.pingone.asia
for the Asia-Pacific region, and https://scim-api.pingone.com.au
for the Australia region.
Authorization
To make a call to the PingOne API, you'll need an OAuth 2.0 access token for API authentication. The access token (a JSON Web Token) is accepted per RFC 6750 most commonly through the Authorization
HTTP request header. In the code samples in this document, the access token is expressed in the request header as Authorization: Bearer accessToken
, where accessToken
is a full base64url-encoded JSON web token generated by the authentication service. For more information about using access tokens, see Getting started.
HTTP methods
The PingOne API supports the following HTTP methods. Note that a resource may not support all listed methods below. When a method is not supported, the platform returns a 405 METHOD NOT ALLOWED
error in the response.
-
POST
Creates a new resource in the collection. If a specific resource is identified, it performs an operation on that resource.
-
PUT
Updates a resource in the collection. If a specific resource is identified, it updates all attribute values of the resource.
-
PATCH
Updates the attributes on an object or a partial update for the specified attributes.
-
GET
Lists or queries a collection of resources. If a specific resource is identified, it returns the attribute values for the specific resource.
-
DELETE
Deletes or unlinks a resource from the collection.
A resource supports updating either by replacing the resource (PUT
) or partially updating the resource (PATCH
).
Replacing a resource
A PUT
request is a replace operation. Requests submitted using PUT
will replace attribute values specified in the request and clear any attribute values that aren't specified.
A null value is represented in a resource by omitting the property, although you can specify null
to explicitly clear the value.
Partial updates to a resource
A PATCH
operation performs partial updates of a resource. The body of a PATCH
operation is similar to that of a PUT
operation. However, omitting an attribute in a PATCH
operation results in the attribute being ignored.
You can use a value of null
to explicitly clear the value.
Supported data exchange formats
The PingOne API supports JSON as the data exchange format with UTF-8 character encoding required for request body content. For PUT
, POST
, and PATCH
operations, the Content-type
request header identifies the format of the request body. A Content-type request header value of application/json
specifies the data exchange format as JSON, which, by default, sets the character encoding to UTF-8. Here is a sample:
curl -vX PUT "https://api.pingone.com/v1/environments/{{envID}}/populations/{{popID}}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer accessToken" \
-d "{
"name" : "Finance",
"description" : "Finance and accounting group"
}"
Data models
PingOne data models list the possible properties in a request or response body for each endpoint at a high level. The data models have five columns, described below.
-
Property
The name of the property.
-
Type
The valid data type for the property value. Possible options include: String, Integer, Boolean, Array.
-
Required?
Whether the property is required for creating, updating, or otherwise modifying or acting upon a resource.
-
Mutable?
Whether the property can be changed after its initial setting. The possible options are:
-
Mutable - Values that can be provided as input when creating, updating, or otherwise modifying or acting upon a resource.
-
Read-only - Values provided in the response resource only and not used/ignored for input.
-
Immutable - Values provided in the input when creating a resource, but otherwise treated as read-only for subsequent operations.
-
-
Description
A more detailed definition of the property. This could include a list of accepted values, the default value when left blank, circumstances in which the property is required or optional, or just an example value.
UUIDs for resource identification
Resources in PingOne are identified by their associated UUID (universally unique identifier). API requests use UUIDs in the request URL to specify the resources involved in the operation. For clarity, the code samples in this API Reference use descriptive variables such as {{envID}}
, {{userID}}
, {{appID}}
, and {{deviceID}}
to represent the UUIDs assigned to PingOne resources.
For example, the following sample request URL specifies a unique device associated with a unique user in a unique environment. The resource ID variables represent specific UUIDs for PingOne resources.
curl -X "GET" "https://api.pingone.com/v1/environments/{{envID}}/users/{{userID}}/devices/{{deviceID}}"
The actual request URL with UUIDs looks like this:
curl -X "GET" "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8ce55f02-2077-4493-9a6d-0385df1f0772/devices/4ca9eb79-be29-4a1f-9a23-b29d58606e18"
There are a few exceptions to this convention. Notifications template names in PingOne are identified by the template name {{templateName}}
rather than by a UUID. For example, the following request URL returns information about a specific template:
curl -X "GET" "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/templates/{{templateName}}
The {{templateName}}
variable is replaced by one of the pre-defined notifications template names in PingOne. The actual request URL that uses a defined notifications template called strong_authentication
looks like this:
curl -X "GET" "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/templates/strong_authentication
Placeholder syntax
Some requests use placeholder syntax to reference platform resource entities as variables. When placeholder syntax is required, the PingOne resource used as a variable is expressed in placeholder syntax format as ${attribute}
. For example, when mapping a SAML name
attribute to the PingOne username
attribute, the value of the PingOne attribute in the POST request body is expressed as ${user.username}
. In most cases where placeholder syntax is required, the placeholder references attributes in the PingOne user
schema. The variable is written as a path to the value: ${user.path.to.value}
. For example, to reference the name.family
user attribute, the variable is written as ${user.name.family}
.
Placeholder syntax is also used to express sign-on policy condition variables. For example, a condition variable to specify the last completed time the password authenticator was used for sign on is expressed as ${session.lastSignOn.withAuthenticator.pwd.at}
.
Placeholders in sign-on policy conditions often specify a value or range of values to meet the sign-on condition. For example, the sign-on policy associated with the following condition prevents sign-on from devices that contain the remote IP address value specified by the variable ${flow.request.http.remoteIp}
in the specified IP address ranges.
"condition": {
"not": {
"ipRange": [
"10.1.1.1/8",
"10.0.0.0/8"
],
"contains": "${flow.request.http.remoteIp}"
}
}
Placeholders are also used to specify external identity provider attributes. For example, to specify a Facebook attribute that is mapped to a PingOne attribute, the Facebook attribute is expressed as ${providerAttributes.<Facebook attribute name>}
. For example, the following expression maps the PingOne username
attribute to the Facebook email
attribute.
{
"name": "username",
"value": "${providerAttributes.email}"
"update": "EMPTY_ONLY",
}
The following table shows the PingOne resources that use Placeholder syntax in POST requests.
PingOn resource | Placeholder example |
---|---|
Sign-on policy actions | ${session.lastSignOn.at} ${session.lastSignOn.withAuthenticator.pwd.at} ${session.lastSignOn.withAuthenticator.mfa.at} ${flow.request.http.remoteIp} ${user.*} |
Identity providers | ${providerAttributes.<IdP attribute name>} |
Notifications templates | ${user.username} ${otp} |
Resource attributes | ${user.email} |
SAML attribute mapping | ${user.id} |
Link expansion
You can optimize the information returned by a request through link expansion. Link expansion is helpful when you need the query to return detailed information from an additional resource in the response data. You can identify a resource to expand using the expand
query string parameter in the request.
Here is a sample that requests data for a specific user and expands the passwordPolicy
attribute to show the password policy's attribute data.
curl -X GET "https://api.pingone.com/v1/environments/{{envID}}/users/{{userID}}/password?expand=passwordPolicy" \
-H "Authorization: Bearer accessToken"
When using the expand
parameter in the request, the returned JSON includes an embedded passwordPolicy
resource to show the details of the password policy associated with this user:
{
"_links": {
"self": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/b94f4977-0d52-4c9d-a5da-e7d42a82f613/password"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c"
},
"user": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/b94f4977-0d52-4c9d-a5da-e7d42a82f613"
},
"passwordPolicy": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/passwordPolicies/9ad15e9e-3ac6-43f7-86d3-01018f6ef0ad"
},
"password.check": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/b94f4977-0d52-4c9d-a5da-e7d42a82f613/password"
},
"password.reset": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/b94f4977-0d52-4c9d-a5da-e7d42a82f613/password"
},
"password.set": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/b94f4977-0d52-4c9d-a5da-e7d42a82f613/password"
},
"password.recover": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/b94f4977-0d52-4c9d-a5da-e7d42a82f613/password"
}
},
"environment": {
"id": "5caa81af-ec05-41ff-a709-c7378007a99c"
},
"user": {
"id": "b94f4977-0d52-4c9d-a5da-e7d42a82f613"
},
"passwordPolicy": {
"id": "9ad15e9e-3ac6-43f7-86d3-01018f6ef0ad"
},
"status": "NO_PASSWORD",
"lastChangedAt": "2019-05-21T18:01:07.413Z",
"_embedded": {
"passwordPolicy": {
"_links": {
"self": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/passwordPolicies/9ad15e9e-3ac6-43f7-86d3-01018f6ef0ad"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c"
}
},
"id": "9ad15e9e-3ac6-43f7-86d3-01018f6ef0ad",
"environment": {
"id": "5caa81af-ec05-41ff-a709-c7378007a99c"
},
"name": "Standard",
"description": "A standard policy that incorporates industry best practices",
"excludesProfileData": true,
"notSimilarToCurrent": true,
"excludesCommonlyUsed": true,
"maxAgeDays": 182,
"minAgeDays": 1,
"maxRepeatedCharacters": 2,
"minUniqueCharacters": 5,
"history": {
"count": 6,
"retentionDays": 365
},
"lockout": {
"failureCount": 5,
"durationSeconds": 900
},
"length": {
"min": 8,
"max": 255
},
"minCharacters": {
"1234567890": 1,
"abcdefghijklmnopqrstuvwxyz": 1,
"ABCDEFGHIJKLMNOPQRSTUVWXYZ": 1,
"~!@#$%^&*()-_=+[]{}|;:,.<>/?": 1
},
"default": true
}
}
}
Cross-origin resource sharing
PingOne supports cross-origin resource sharing (CORS), which gives applications running at different domains permission to access resources on PingOne servers. For example, an application at https://myapp.com that uses PingOne to authenticate users needs to request permission to access resources at https://auth.pingone.com before authentication operations are executed. In this case, a request is made to the resource owner (auth.pingone.com) from the requestor (myapp.com) using CORS headers to ask for access privileges. The response from auth.pingone.com returns the CORS Access-Control-Allow-Origin
header with a value that confirms the requestor's access rights.
PingOne servers are configured to trust all origins when using access tokens. However, when requesting sensitive resources that use PingOne session cookies for authentication, only specified origins will be trusted. The following endpoints require session cookies for authentication, and only the origins specified in the application’s corsSettings
property will be trusted when calling these endpoints:
/{envId}/saml20/idp/sso
/{envId}/saml20/idp/startsso
/{envId}/saml20/resume
/{envId}/saml20/idp/slo
/{envId}/as/authorize
/{envId}/as/resume
/{envId}/as/signoff
/{envId}/wsf/sts/{appId}
/{envId}/wsf/mex/{appId}
/{envId}/wsf/prp/{appId}
/{envId}/wsf/prp/resume
When using session cookies for authentication, no origins will be trusted when calling these endpoints:
/{envId}/rp/authenticate/{envId}/rp/callback/{callbackId}
/{envId}/saml20/sp/sso
/{envId}/saml20/sp/acs
/{envId}/saml20/sp/jwtacs
/{envId}/as/txs
Consequently, when defining an application's connection to PingOne, you generally do not need to add your application's domain to a list of trusted origins. Cross-origin requests that use HTTP methods to modify the resource, such as PUT
, PATCH
, POST
, and DELETE
, trigger a preflight request to ensure that the initial request can be sent. The browser initiates a preflight HTTP OPTIONS
request to verify that the HTTP method used in the actual request is allowed. In these cases, the response from auth.pingone.com to the preflight request returns a response with the CORS Access-Control-Allow-Methods
header to specify the allowed methods.
When making CORS requests, only these headers can be used:
Accept
Accept-Language
Content-Language
Content-Type
Range
Authorization
Content-Length
Cookie
Correlation-Id
Origin
Origin-Cookies
Referer
orReferrer
X-Amz-Date
X-Amz-Security-Token
X-Api-Key
X-client-version
X-Content-Type-Options
When accessing CORS responses, you're restricted to reading only the Correlation-Id
header (as well as the request body).
Attempting to submit or access headers that are not listed above may prevent you from making CORS requests or reading the responses.
Forced type conversion of floating point numbers in requests
PingOne truncates a float
value submitted in the JSON request body to a matching int
value for services other than flow orchestration. For example, in the following request body JSON, the minAgeDays
value can be submitted with a value of 1.5
.
{
"name": "Standard",
"description": "A standard policy that incorporates industry best practices",
"excludesProfileData": true,
"notSimilarToCurrent": true,
"excludesCommonlyUsed": true,
"maxAgeDays": 182,
"minAgeDays": 1.5,
"maxRepeatedCharacters": 2,
"minUniqueCharacters": 5,
"history": {
"count": 6,
"retentionDays": 365
},
"lockout": {
"failureCount": 5,
"durationSeconds": 900
},
"length": {
"min": 8,
"max": 255
},
"minCharacters": {
"~!@#$%^&*()-_=+[]{}|;:,.<>/?": 1,
"0123456789": 1,
"ABCDEFGHIJKLMNOPQRSTUVWXYZ": 1,
"abcdefghijklmnopqrstuvwxyz": 1
},
"default": true
}
The request will execute. However, the response shows that the minAgeDays
value is converted automatically to an int
value:
{
"_links": {
"self": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/passwordPolicies/ad53ea0b-28b3-413f-a762-46eaf929ab78"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c"
}
},
"id": "ad53ea0b-28b3-413f-a762-46eaf929ab78",
"environment": {
"id": "5caa81af-ec05-41ff-a709-c7378007a99c"
},
"name": "Standard",
"description": "A standard policy that incorporates industry best practices",
"excludesProfileData": true,
"notSimilarToCurrent": true,
"excludesCommonlyUsed": true,
"maxAgeDays": 182,
"minAgeDays": 1,
"maxRepeatedCharacters": 2,
"minUniqueCharacters": 5,
"history": {
"count": 6,
"retentionDays": 365
},
"lockout": {
"failureCount": 5,
"durationSeconds": 900
},
"length": {
"min": 8,
"max": 255
},
"minCharacters": {
"~!@#$%^&*()-_=+[]{}|;:,.<>/?": 1,
"0123456789": 1,
"ABCDEFGHIJKLMNOPQRSTUVWXYZ": 1,
"abcdefghijklmnopqrstuvwxyz": 1
},
"default": true
}
Note that the value of the floating point number is not rounded. It is trimmed by removing the decimal portion of the value.
For flow orchestration services such as sign-on policy actions, float
values submitted in the JSON request body generate an INVALID_VALUE
error. For example, the following request body with a priority
attribute value of 1.5
generates an error:
{
"priority": 1.5,
"type": "MULTI_FACTOR_AUTHENTICATION",
"recovery": {
"enabled": false
},
"sms": {
"enabled": true
},
"voice": {
"enabled": true
},
"email": {
"enabled": true
},
"applications": [
{
"id": "5e81bba1-1234-457c-926a-aae0e9876543",
"autoEnrollment":{"enabled":true}
}
]
}
The response error looks like this:
{
"id": "15051F81-2500-4BBB-BE4A-0AF31DD50205",
"code": "INVALID_REQUEST",
"message": "The request could not be completed. The request was malformed or invalid.",
"details": [
{
"code": "INVALID_VALUE",
"target": "priority",
"message": "Invalid value for attribute."
}
]
}
PingOne API responses
HTTP response headers
The PingOne API includes information about the result of the operation in the HTTP headers. This enables you to determine the appropriate action to take without having to parse the response body.
The following HTTP Headers are returned by every operation:
-
Access-Control-Allow-Headers
Used in response to a cross-origin resource sharing (CORS) preflight request to indicate the HTTP headers that can be used when making a request.
-
Access-Control-Allow-Max-Age
Specifies how long the results of a CORS preflight request can be cached.
-
Access-Control-Allow-Methods
Specifies the method or methods allowed when accessing the resource in response to a CORS preflight request.
-
Cache-Control
Specifies directives for caching mechanisms in both requests and responses.
-
Content-Type
Specifies the data exchange format for the response data.
-
Correlation-Id
A custom header.
-
Date
Shows the date the response was sent.
-
Expires
Shows the date and time when the response expires.
-
Pragma
Used for backwards compatibility with HTTP/1.0 caches in which the Cache-Control HTTP/1.1 header is not yet present.
-
Strict-Transport-Security
Allows a web site to tell browsers that the site should only be accessed using HTTPS, instead of HTTP.
-
Transfer-Encoding
Specifies the form of encoding used to safely transfer the entity to the user.
-
Vary
Determines how to match future request headers to decide whether a cached response can be used rather than requesting a fresh one from the origin server. It is used by the server to indicate which headers it used when selecting a representation of a resource in a content negotiation algorithm.
-
Via
Used for tracking message forwards, avoiding request loops, and identifying the protocol capabilities of senders along the request/response chain.
-
X-Content-Type-Options
A marker used by the server to indicate that the MIME types advertised in the Content-Type headers should not be changed and be followed.
-
X-Frame-Options
This denies rendering in a frame where there is a frame mismatch.
-
X-XSS-Protection
A feature of Internet Explorer, Chrome, and Safari that stops pages from loading when the browsers detect reflected cross-site scripting (XSS) attacks.
HTTP response codes
The PingOne API returns the status of an operation as a registered HTTP response code. The HTTP response codes can be summarized as:
-
200-299
Confirms a successful call.
-
300-399
Indicates that the call or subsequent calls should be made to another resource.
-
400-499
Shows that an exception occurred, generally due to client code, insufficient permissions, or incorrect parameters.
-
500-599
Shows that an error occurred, generally due to an issue with the service (for example, a service outage).
Operations can also return additional information about a failed operation in the HTTP response body.
Synchronous responses
Responses for synchronous operations have the following behavior:
-
GET
operationsA request that returns a body also returns the code
200 OK
with the resource in the body of the response. -
POST
operationsA request that creates a new resource returns
201 CREATED
with aLocation
header containing the location of the created resource. -
PUT
orPATCH
operationsA request that updates a resource returns
200 OK
and the full resource in the body. -
DELETE
operationsA request that deletes a resource returns
204 NO CONTENT
.
Asynchronous responses
The PingOne API can create a long-running or asynchronous operation that can be monitored by a client. An asynchronous operation will have the following behavior:
-
POST
operationsResponses include
202 ACCEPTED
with aLocation
header containing the location of the newly created operation. The client can poll the provided location to check the status of the operation. The operation may also return a suggested number of seconds for the client to recheck the status using theRetry-After
HTTP header. -
Canceling long-running operations
Some resources may allow the client to cancel an operation by performing a
DELETE
request on the created resource. -
Clean up
The PingOne API will clean up operation history according to the application requirements (such as, keep the last
n
results, or purge results after the client has verified its success).
Response data structure
HAL (Hypertext Application Language) is a formatting convention that provides hyperlinks to related resources returned by an API request. For example, a GET /environments/{{envID}}/users/{{userID}}
request returns data for a specific user resource. The _links
object in the JSON response data shows the hyperlinks to related resources associated with this user. You can use the roleAssignments
link to get role assignments associated with this user, or the password.reset
link to perform password management actions on this user resource.
{
"_links": {
"self": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c"
},
"population": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/populations/60971d3b-cc5a-4601-9c44-2be541f91bf1"
},
"devices": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/devices"
},
"roleAssignments": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/roleAssignments"
},
"password": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password"
},
"password.reset": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password"
},
"password.set": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password"
},
"password.check": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password"
},
"password.recover": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password"
},
"linkedAccounts": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/linkedAccounts"
},
"account.sendVerificationCode": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab"
}
},
"_embedded": {
"password": {
"status": "PASSWORD_EXPIRED"
},
"population": {
"_links": {
"self": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/populations/60971d3b-cc5a-4601-9c44-2be541f91bf1"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c"
}
},
"id": "60971d3b-cc5a-4601-9c44-2be541f91bf1"
}
},
"id": "8376797d-641c-4e7b-8bc1-2fdf71916cab",
"environment": {
"id": "5caa81af-ec05-41ff-a709-c7378007a99c"
},
"createdAt": "2020-02-18T20:50:14.092Z",
"email": "tomjones@example.com",
"enabled": true,
"lifecycle": {
"status": "ACCOUNT_OK"
},
"mfaEnabled": false,
"name": {
"given": "Tom",
"family": "Jones"
},
"population": {
"id": "60971d3b-cc5a-4601-9c44-2be541f91bf1"
},
"updatedAt": "2020-02-18T20:50:14.092Z",
"username": "tomjones"
}
In addition, the _embedded
resources returned by the request can be used as a navigation option to explore related resources. For example, population
is returned as an _embedded
resource in the response, and you can use the embedded resource's self
link to initiate a GET /environments/{{envID}}/populations/{{popID}}
request to return data about the population associated with this user.
Relationships, links, and references
Relationships between resources or operations can be described as follows:
-
Relationships (one-to-one)
Where a resource is directly related to another resource (such as employee to manager, user to population, logo to brand), the relationship is generally represented by an attribute as a first-class citizen of the resource. For example:
-
_links
object : Contains an href to the actual resource. -
Payload : Contains the reference as an attribute with the ID. The name of the
_links
attribute and the attribute in the payload must be the same). -
Expandable : Yes.
-
-
Relationships (one-to-many or many-to-one)
Where a resource or resources may be related to a collection or to many resources. For example, a user to group membership:
-
_links
object : Contains an href to the actual resource or collection. -
Payload : May contain the reference as an attribute with the ID. The name of the
_links
attribute and the attribute in the payload must be the same). -
Expandable : No.
-
-
Informal relationships and links
Provides navigation and self-discovery of the API and its related resources (such as next page of search results, next authentication service to invoke, or with which environment the resource is associated). For example:
-
_links
object : Contains an href to the actual resource, collection, or URL. -
Payload : Cannot contain the reference as an attribute.
-
Expandable : No.
-
These relationships and references are represented as follows:
-
Links are represented using JSON HAL conventions (such as in a
_links
object). -
Links are represented as absolute URLs.
-
Links can be expanded using the
expand
parameter. The links can also be referenced using the "property-as-resource" pattern. -
References as attributes have an
id
value and can also have additional attributes (such asdisplayName
).
Caching
The PingOne API generally implements HTTP caching of operation responses. When HTTP caching is implemented, the following HTTP response headers are included:
-
ETag
An arbitrary string for the version of a representation. This includes the media type in the hash value. For example:
ETag
:"686897696a7c876b7e"
. -
Date
The date and time the response was returned. For example:
Date
:Sun, 06 Nov 1994 08:49:37 GMT
. -
Cache-Control
The maximum number of seconds a response can be cached. If caching is not supported for the response, the value is
no-cache
. For example:Cache-Control
:360
orCache-Control
:no-cache
. -
Expires
If
Cache-Control
is supplied, this header contains the timestamp for when the response expires. If caching is not supported for the response, this header is not present. For example:Expires
:Sun, 06 Nov 1994 08:49:37 GMT
. -
Pragma
When the
Cache-Control
value isno-cache
, this header is also set tono-cache
. If caching is not supported for the response, this header is not present. For example:Pragma
:no-cache
. -
Last-Modified
The timestamp for when the resource itself was last modified. For example:
Last-Modified
:Sun, 06 Nov 1994 08:49:37 GMT
. -
Varies
This header is included for user-specific headers (such as
Authorization
) in multi-tenant scenarios.