Authenticate to Identity Cloud REST API with access token

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)

The client ID service-account targets the built-in OAuth 2.0 public client for service accounts. The client only allows the JWT profile for OAuth 2.0 authorization grant flow.

Access the built-in OAuth 2.0 public client using the tenant FQDN. You cannot access it using an Alpha or Bravo realm alias URL or a custom domain URL.

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
}