Authenticate to Identity Cloud REST API with access token

Overview

You need an access token to authenticate to the following Identity Cloud REST API endpoints:

/am/*
/openidm/*
/.well-known/*
/environment/promotion/* (self-service promotion endpoints)
/variables, /secrets, /restart (ESV endpoints)

Summary of use:

Create a service account in the Identity Cloud admin UI and download a private key.
Create a JWT and sign it using the private key.
Create an access token using the JWT profile for OAuth 2.0 authorization grant flow.
Set the access token as a bearer token in the Authorization HTTP header for each API request:
```
Authorization: Bearer <access-token>
```

Get an access token

Prerequisites

You need the jose command-line tool to run some of the commands below. To find installation instructions for your particular package manager, refer to https://command-not-found.com/jose.

Step 1: Create a service account and download its private key

Follow the steps in Create a new service account.
1. In step 9, save the private key as a local file called key.jwk.
2. Make a note of the ID for the service account you created. An example of an ID is 449d7e27-7889-47af-a736-83b6bbf97ec5.

Step 2: Create and sign a JWT

Set the following variables in your terminal, to be used as claims in a JWT payload:
1. Set SERVICE_ACCOUNT_ID to hold the ID of the service account. For use in the iss (issuer) and sub (subject) claims.
  $ SERVICE_ACCOUNT_ID="<service-account-id>"(1)
  1 Replace <service-account-id> with the service account ID; for example, 449d7e27-7889-47af-a736-83b6bbf97ec5.
2. Set AUD to hold the URL (including port number) where the JWT will be used to request the access token. For use in the aud (audience) claim.
  $ AUD='https://<tenant-env-fqdn>:443/am/oauth2/access_token'
3. Set EXP to hold a 3-minute expiration time for the JWT, expressed as number of seconds since the Unix epoch. For use in the exp (expiration time) claim.
  $ EXP=$(($(date -u +%s) + 180))
4. Set JTI to hold a unique ID for the JWT. For use in the jti (JWT ID) claim.
  $ JTI=$(openssl rand -base64 16)

Combine the claims to create a payload for the JWT:

$ echo -n "{
    \"iss\":\"${SERVICE_ACCOUNT_ID}\",
    \"sub\":\"${SERVICE_ACCOUNT_ID}\",
    \"aud\":\"${AUD}\",
    \"exp\":${EXP},
    \"jti\":\"${JTI}\"
}" > payload.json

Sign the JWT using the private key you downloaded and saved as key.jwk in step 1a:
```
$ jose jws sig -I payload.json -k key.jwk -s '{"alg":"RS256"}' -c -o jwt.txt
```

Step 3: Get an access token using the JWT profile authorization grant

Request an access token from the /oauth2/access_token endpoint using the JWT:

$ curl \
--request POST ${AUD} \
--data "client_id=service-account" \(1)
--data "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \(2)
--data "assertion=$(< jwt.txt)" \(3)
--data "scope=<scope>"(4)

1	The client ID `service-account` targets the statically configured OAuth 2.0 public client for service accounts. This client is created by ForgeRock and is accessible from all customer realms. The client only allows the JWT profile for OAuth 2.0 authorization grant flow.
2	The grant type `urn:ietf:params:oauth:grant-type:jwt-bearer` represents the JWT profile for OAuth 2.0 authorization grant flow.
3	The `assertion` parameter is populated with the output of the signed JWT from step 2c.
4	Replace `<scope>` with a scope or a space delimited set of scopes; for example, `fr:idc:esv:` or `fr:am: fr:idm:*`. Refer to Service account scopes. The specified scopes must be the same as (or a subset of) the scopes that you assigned to the service account.

Examine the response to find the access token, represented as access_token:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... ...8ECmkyDJKow8Qp_Tnp_lGNRJzLWi18iUGQrCTtxyTXw",
    "scope": "fr:am:* fr:idm:*",
    "token_type": "Bearer",
    "expires_in": 180
}

Use an access token

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>/openidm/managed/<realm>_user?_fields=userName,givenName,sn,mail,accountStatus&_prettyPrint=true&_queryFilter=true' \(1)
--header 'Authorization: Bearer <access-token>'(2)

1	Replace <realm> with the realm where you created the access token.
2	Replace <access-token> with the `access_token` in the authentication response (refer to Get an access token).

Show response

{
    "result": [
        {
            "_id": "f413db4c-cebd-4950-81e6-57bdb47921a4",
            "_rev": "0000000016e6754b",
            "userName": "exampleuser",
            "accountStatus": "active",
            "givenName": "Example",
            "sn": "User",
            "mail": "exampleuser@example.com"
        },
        {
            "_id": "15249a65-8f9a-4063-9586-a2465963cee4",
            "_rev": "0000000016e6754b",
            "userName": "exampleuser2",
            "accountStatus": "active",
            "givenName": "Example",
            "sn": "User",
            "mail": "exampleuser2@example.com"
        },
        {
            "_id": "30485bc4-fdbb-4946-8ce4-1a53c6824d92",
            "_rev": "0000000016e6754b",
            "userName": "exampleuser3",
            "accountStatus": "active",
            "givenName": "Example",
            "sn": "User",
            "mail": "exampleuser3@example.com"
        }
    ],
    "resultCount": 3,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "NONE",
    "totalPagedResults": -1,
    "remainingPagedResults": -1
}