Identity Cloud

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:

  1. Create a service account in the Identity Cloud admin UI and download a private key.

  2. Create a JWT and sign it using the private key.

  3. Create an access token using the JWT profile for OAuth 2.0 authorization grant flow.

  4. 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

  1. 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

  1. 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)
  2. 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
  3. 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

  1. 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 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.
  2. 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": 899
    }

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
}
Copyright © 2010-2024 ForgeRock, all rights reserved.