Setting up OAuth to access the PingAccess Admin API
You can configure the PingAccess Admin API so that administrators can access it using OAuth. The API requires a JWT Bearer token for authenticating the requests. This token can be retrieved using either an authorization code flow or a client credentials flow.
Authenticate using an authorization code flow
The API supports the authorization code flow, which gets access tokens by securely redirecting users to the authorization server for authentication.
Before you begin
After user accounts are created, you can assign the appropriate user access control roles and permissions. Users can then get an access token to use with API calls. Learn more about these roles and permissions in PingAccess roles.
Steps
-
Go to the PingOne Advanced Services login URL:
https://self-service-api.<environment>-<customer>.<region>.ping.cloud/api/v1/login/pingaccess -
Enter your credentials and click Submit.
If authentication is successful, you’re redirected to the Success page and a Copy Token button displays.
-
Click Copy Token.
-
Query the API directly using tools such as Postman or cURL, and include the bearer token in the headers.
Example
{"Authorization": "Bearer {TOKEN}"}
Authenticate using a client credentials flow
The API supports the client credentials flow, designed for machine-to-machine (M2M) interactions, which allows applications to access system resources without involving a user.
| This type of flow can only be used if connections are correctly configured for self-managing administrator accounts. Learn more in Configuring connections for SSO. |
To set this up, you’ll need to:
-
Create a client credentials application in your PingOne environment
-
Generate the token
You should also restrict access to this application to PingOne administrators. Learn more in Restricting access to the application.
| In addition to the JWT Bearer token, the API uses role-based access control, as described in Administrative role mappings. The roles assigned to the accounts affect the results of the API calls. |
Creating the client credentials application
Start by creating an OpenID Connect (OIDC) application in PingOne.
Steps
-
Go to Applications > Resources.
-
Click the + icon.
-
Create the resource by completing these fields:
-
Resource name: A unique identifier for the resource.
-
Description (optional): A brief characterization of the resource that helps identify it.
-
-
Click Next.
-
On the Attributes page, click Add.
-
Name the new attribute
groups.Set the value to a hardcoded list of valid PingAccess roles. For example,
{"dev-pa-admin", "prod-pa-audit"}. You can find a complete list of the PingAccess roles and permissions in PingAccess administrative role mappings.The PingAccess attribute must be set up for it to display in the list. You can find instructions on adding this attribute in Creating custom user attributes.
-
Click Next.
-
On the Scopes page, add a new scope to map the PingAccess role to the new application. Click Add Scope and complete the following fields:
-
Scope name: A unique identifier for the scope.
-
Description (optional): A brief characterization of the scope that helps identify it.
-
-
Click Save.
-
Now, add the OIDC application. Go to Applications > Applications.
-
Click the + icon.
-
Complete the following fields:
-
Application name: A unique identifier for the application.
-
Description (optional): A brief characterization of the application that helps identify it.
-
Icon (optional): A graphic representation of the application. Use a file up to 1 MB in JPG, JPEG, GIF, or PNG format.
-
-
In the list of available application types, select OIDC Web App. Click Save.
-
On the Configuration tab, click the Pencil icon to edit the configuration.
-
Change the Response Type to none by clearing all the options.
-
Change the Grant Type to Client Credentials.
-
-
Click Save.
-
On the Resources tab, click the Pencil icon to add the scope you added in step 8 to the application.
-
Click Save and click the toggle for the application.
Generate the token
Access the new application in the PingOne console to generate an access token.
Steps
-
Follow the steps outlined in Getting an access token in the PingOne documentation.
-
Include the bearer token in the headers.
Example
{"Authorization": "Bearer {TOKEN}"}