PingOne Advanced Identity Cloud

Generate an access token

To access the IGA REST API endpoints, you generate an OAuth 2.0 access token using the client credentials grant type. The process involves the following key steps:

  1. Establish a service account: First, configure a dedicated service account within Advanced Identity Cloud.

  2. Generate a signed JWT: Then, create a digitally signed JSON Web Token (JWT).

  3. Exchange JWT for access token: Finally, exchange the generated JWT within Advanced Identity Cloud tenant to receive the OAuth 2.0 access token.

These steps provide you with the necessary credentials to authenticate and interact with the Identity Governance REST API.

Generate an access token

Step 1: Create a service account

Service accounts let you request access tokens for REST API endpoints without a human user account. You can create a service account within the Advanced Identity Cloud.

  1. In the Advanced Identity Cloud admin console, open the TENANT menu (upper right).

  2. Go to Tenant settings > Global Settings > Service Accounts.

  3. On the Service Accounts page, click add New Service Account.

  4. In the New Service Account modal, enter the following:

    1. Enter a Name and optional Description for the service account.

    2. In the Scopes section, select the scopes that the service application can grant to an access token. Select the scopes:

    3. Click Save.

    4. When the Service account successfully created! message shows, note the service account ID, found in the ID field.

    5. Click Download Key to download the service account private key. Save it as key.jwk.

      You must download the private key at this point, as it will not be available again.

    6. Click Done.

Step 2: Obtain an access token

Follow the instructions in Create and sign a JWT.

Step 3: Get an access token

Follow the instructions in Get an access token using the JWT profile authorization grant.

In your access token request, make sure to include the following scopes: fr:am:* fr:idm:* fr:iga:*.

curl \
--request POST ${AUD} \
--data "client_id=service-account" \
--data "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
--data "assertions=$(< jwt.txt)" \
--data "scope=fr:am:* fr:idm:* fr:iga:*"

Step 4: Use the access token to an IGA endpoint

To use the access token with the REST API, set it as a bearer token in the Authorization HTTP header for each API request.

The following example uses the access token to get a list of identities:

Show request 
$ curl \
--request GET 'https://<tenant-env-fqdn>/iga/governance/application?_pageSize=10&_queryFilter=true' \(1)
--header 'Authorization: Bearer <access-token>'(2)
1 Replace <tenant-env-fqdn> with the fully qualified domain name of your tenant.
2 Replace <access-token> with the access_token in the authentication response (learn more in Step 3: Get an access token).
Show response 
{
  "result": [
    {
      "application": {
        "_rev": "ea896341-28d2-48d3-a01a-430c78acc019-123140",
        "authoritative": false,
        "connectorId": "SNOW",
        "description": "Sanjay's SNOW",
        "fr": {
          "realm": "alpha"
        },
        "icon": "",
        "id": "e35d09cd-2b9b-41bc-8246-dc23d4a36502",
        "mappingNames": [
          "systemSnowUser_managedAlpha_user",
          "systemSnowRole_managedAlpha_assignment",
          "systemSnowGroup_managedAlpha_assignment",
          "managedAlpha_user_systemSnowUser",
          "systemSnowDepartment_managedAlpha_assignment",
          "systemSnowLocation_managedAlpha_assignment",
          "systemSnowCompany_managedAlpha_assignment",
          "systemSnowCostcenter_managedAlpha_assignment"
        ],
        "metadata": {
          "entityType": "/openidm/managed/application",
          "created": "2025-03-25T05:23:13.825Z"
        },
        "name": "SNOW",
        "objectTypes": [
          {
            "name": "Role",
            "accountAttribute": "__user_role_ids__"
          },
          {
            "name": "Group",
            "accountAttribute": "__user_group_ids__"
          },
          {
            "name": "Department",
            "accountAttribute": "department"
          },
          {
            "name": "Company",
            "accountAttribute": "company"
          },
          {
            "name": "User"
          },
          {
            "name": "CostCenter",
            "accountAttribute": "costCenter"
          },
          {
            "name": "Location",
            "accountAttribute": "location"
          }
        ],
        "templateName": "servicenow",
        "templateVersion": "3.3"
      },
      "applicationOwner": [
        {
          "id": "75982e79-40dc-4ad2-8b85-abe1ebd2e2b9",
          "userName": "fyork",
          "givenName": "Frank",
          "sn": "York",
          "mail": "fyork@example.com"
        }
      ],
      "glossary": {
        "idx": {
          "/application": {
            "num": 0
          }
        },
        "types": [
          {
            "attrKey": "/application",
            "modified": "2025-03-18T20:12:01.161921627Z",
            "type": "entityType/id/realm"
          }
        ]
      },
      "id": "e35d09cd-2b9b-41bc-8246-dc23d4a36502",
      "item": {
        "type": "accountGrant"
      },
      "latestModified": {
        "application": "2025-03-25T05:23:13.825Z",
        "applicationOwner": {
          "75982e79-40dc-4ad2-8b85-abe1ebd2e2b9": "2025-04-30T14:43:16.44Z"
        },
        "glossaries": {
          "/application": {
            "entityType/id/realm": "2025-03-18T20:12:01.161921627Z"
          }
        }
      },
      "scopes": {
        "view": [
          {
            "id": "ff7f878c-ea21-4ea1-adf9-e91688301408",
            "timestamp": "2025-03-21T15:11:03.146Z"
          },
          {
            "id": "9d9b6f44-7cd5-40a0-83ed-19c4ff16ffe1",
            "timestamp": "2025-05-06T03:02:21.387Z"
          },
          {
            "id": "62866922-48f8-4a1a-bcf8-07e3168efbe7",
            "timestamp": "2025-05-08T18:02:03.64Z"
          }
        ],
        "createEntitlement": [
          {
            "id": "ff7f878c-ea21-4ea1-adf9-e91688301408",
            "timestamp": "2025-03-21T15:11:03.146Z"
          },
          {
            "id": "9d9b6f44-7cd5-40a0-83ed-19c4ff16ffe1",
            "timestamp": "2025-05-06T03:02:21.387Z"
          },
          {
            "id": "62866922-48f8-4a1a-bcf8-07e3168efbe7",
            "timestamp": "2025-05-08T18:02:03.64Z"
          }
        ]
      },
      "metadata": {
        "modifiedDate": "2025-05-08T18:42:14.146Z",
        "createdDate": "2025-03-18T20:15:18.276732519Z"
      },
      "permissions": {
        "createEntitlement": true
      }
    },
    ...
    {
      "application": {
        "_rev": "ea896341-28d2-48d3-a01a-430c78acc019-240426",
        "fr": {
          "realm": "alpha"
        },
        "id": "ade13837-93de-4993-9c86-20254c76dbe3",
        "metadata": {
          "entityType": "/openidm/managed/application",
          "created": "2025-03-26T06:19:22.012Z"
        },
        "name": "my_application_5397010386186912",
        "ssoEntities": {
          "oidcId": "my_application_5397010386186912"
        },
        "templateName": "native-override",
        "templateVersion": "1.0"
      },
      "applicationOwner": [
        {
          "id": "ca204525-7c4e-4433-8ac1-14eafaf7ba78",
          "userName": "e2eTestUser4147855424107766",
          "givenName": "e2eTestUser4147855424107766",
          "sn": "test",
          "mail": "forgerockdemo@example.com"
        }
      ],
      "id": "ade13837-93de-4993-9c86-20254c76dbe3",
      "item": {
        "type": "accountGrant"
      },
      "latestModified": {
        "application": "2025-03-26T06:19:22.012Z",
        "applicationOwner": {
          "ca204525-7c4e-4433-8ac1-14eafaf7ba78": "2025-03-26T06:19:15.176Z"
        }
      },
      "scopes": {
        "view": [
          {
            "id": "ff7f878c-ea21-4ea1-adf9-e91688301408",
            "timestamp": "2025-03-21T15:11:03.146Z"
          },
          {
            "id": "62866922-48f8-4a1a-bcf8-07e3168efbe7",
            "timestamp": "2025-05-08T18:02:03.64Z"
          }
        ],
        "createEntitlement": [
          {
            "id": "ff7f878c-ea21-4ea1-adf9-e91688301408",
            "timestamp": "2025-03-21T15:11:03.146Z"
          },
          {
            "id": "62866922-48f8-4a1a-bcf8-07e3168efbe7",
            "timestamp": "2025-05-08T18:02:03.64Z"
          }
        ]
      },
      "metadata": {
        "modifiedDate": "2025-05-08T18:42:15.27Z",
        "createdDate": "2025-03-26T06:25:55.833413183Z"
      },
      "permissions": {
        "createEntitlement": true
      }
    }
  ],
  "searchAfterKey": [
    "30bb18e30bad14e27f73c90390b0f16df0d0208a5ecfb5f38fca8ac44f350a802a9ded2ee244acca76325e222df57a058bb646ecccf402ac0899304b2a0b684a"
  ],
  "totalCount": 83,
  "resultCount": 10
}

Token modification scripts

Developers can use token modification scripts to augment standard access tokens with additional claims, adjust token lifespans, and incorporate custom attributes to meet specific application authorization requirements. These scripts serve as extension points within the access token issuance process, enabling the customization of generated tokens.

Learn more about the development, configuration, and deployment of these scripts and view an example script in Access tokens. This resource provides the necessary guidance for effectively tailoring access tokens for client credential-based authentication scenarios.

Override OAuth 2.0 claims

Developers configuring OAuth 2.0 access tokens in Advanced Identity Cloud can override claims included in these tokens. A claim is a piece of information asserted about a subject, typically the user or the client application.

The claim override feature allows for direct modification of the claims within the generated access tokens, providing granular control over their content. By overriding claims, developers can define and inject specific claims tailored to the unique authorization requirements of their client applications, facilitating the inclusion of essential authorization data or custom attributes directly within the token.

Learn more about overriding claims in OIDC claims. This resource provides crucial information for effectively managing access token claims within your deployment.