Authenticate to Identity Cloud REST API with Access Token

Overview

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

  • /openidm/*

  • /.well-known/*

The access token must include:

  • IDM admin privileges

  • The fr:idm:* scope

The /openidm/* endpoint exposes many, but not all, of the IDM APIs to Identity Cloud. For an expanded list of endpoints, see IDM REST API Endpoints.

Get an access token

The following examples use a Resource Owner Password Credentials (ROPC) grant flow. This flow lets the client use the resource owner’s username and password to get an access token.

Since the resource owner shares their credentials with the client, this flow is deemed the most insecure of the OAuth 2.0 flows. The resource owner’s credentials can potentially be leaked or abused by the client application, and the resource owner has no control over the authorization process.

You should implement the ROPC grant flow only if the resource owner has a trust relationship with the client (such as the device operating system, or a highly privileged application).

See OAuth 2.0 Grant Flows for more information on the grant flows available in Identity Cloud.

  1. Create an administrative OAuth2.0 client using either the REST API or the Identity Cloud Admin UI:

  2. Create a user identity in the Identity Cloud Admin UI with authorization role openidm-admin. See Create a user identity with openidm-admin authorization role.

  3. Create an access token using an OAuth 2.0 authorization grant flow. The grant flow needs to specify the credentials of the OAuth 2.0 client (step 1) and the realm user identity (step 2):

    Show request
    $ curl \
    --request POST 'https://<tenant-name>.forgeblocks.com/am/
    oauth2/realms/root/realms/<realm>/access_token?auth_chain=PasswordGrant' \ (1)
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=password' \ (2)
    --data-urlencode 'username=<realm-user-identity-username>' \ (3)
    --data-urlencode 'password=<realm-user-identity-password>' \ (4)
    --data-urlencode 'scope=fr:idm:*' \
    --data-urlencode 'client_id=<oauth2-client-name>' \ (5)
    --data-urlencode 'client_secret=<oauth2-client-password>' (6)
    1 Replace <realm> with the realm where you want to create the access token.
    2 Note grant type password which represents Resource Owner Password Credentials Grant.
    3 Replace <realm-user-identity-username> with the username you have chosen for the realm user with IDM admin authorization.
    4 Replace <realm-user-identity-password> with the password you have chosen for the realm user with IDM admin authorization.
    5 Replace <oauth2-client-name> with the name that you have chosen for the OAuth 2.0 client.
    6 Replace <oauth2-client-password> with the password that you have chosen for the OAuth 2.0 client.
  4. View the response to see the access token, represented as access_token:

    Show response
    {
        "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... ...8ECmkyDJKow8Qp_Tnp_lGNRJzLWi18iUGQrCTtxyTXw",
        "scope": "fr:idm:*",
        "token_type": "Bearer",
        "expires_in": 3598
    }

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-name>.forgeblocks.com/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 (see 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
}

Create an administrative OAuth 2.0 client using REST API

  1. Create a session token by authenticating an Identity Cloud administrator username and password. See Get an administrator session token.

  2. Use the session token to create an administrative OAuth 2.0 client with scope fr:idm:*:

    Show request with abridged body
    $ curl \
    --request PUT 'https://<tenant-name>.forgeblocks.com/am/
    json/realms/root/realms/<realm>/realm-config/agents/OAuth2Client/<oauth2-client-name>' \ (1) (2)
    --header 'accept: application/json' \
    --header 'Content-Type: application/json' \
    --header '<session-cookie-name>: <session-token>' \ (3) (4)
    --data-raw '{
      "coreOAuth2ClientConfig": {
        ...
        "userpassword": "<oauth2-client-password>", (5)
        "clientType": {
          "inherited": false,
          "value": "Confidential"
        },
        ...
        "scopes": {
          "inherited": false,
          "value": [
            "fr:idm:*" (6)
          ]
        },
        ...
      },
      "advancedOAuth2ClientConfig": {
        ...
        "grantTypes": {
          "inherited": false,
          "value": [
            "password" (7)
          ]
        },
        ...
      },
      ...
    }'
1 Replace <realm> with the realm where you want to create the OAuth 2.0 client.
2 Replace <oauth2-client-name> with the name that you have chosen for the OAuth 2.0 client.
3 Replace <session-cookie-name> with the session cookie name configured for the tenant.
4 Replace <session-token> with the tokenId in the authentication response (see Get an administrator session token).
5 Replace <oauth2-client-password> with the password that you have chosen for the OAuth 2.0 client.
6 Note scope fr:idm:* which lets the client grant access to managed identities.
7 Note grant type password which represents Resource Owner Password Credentials Grant.
Show request with full body
$ curl \
--request PUT 'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/<realm>/realm-config/agents/OAuth2Client/<oauth2-client-name>' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header '<session-cookie-name>: <session-token>' \
--data-raw '{
  "coreOAuth2ClientConfig": {
    "agentgroup": "",
    "status": {
      "inherited": false,
      "value": "Active"
    },
    "userpassword": "<oauth2-client-password>",
    "clientType": {
      "inherited": false,
      "value": "Confidential"
    },
    "loopbackInterfaceRedirection": {
      "inherited": true,
      "value": true
    },
    "redirectionUris": {
      "inherited": false,
      "value": [
        "https://httpbin.org/anything"
      ]
    },
    "scopes": {
      "inherited": false,
      "value": [
        "fr:idm:*"
      ]
    },
    "defaultScopes": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "clientName": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "authorizationCodeLifetime": {
      "inherited": true,
      "value": 0
    },
    "refreshTokenLifetime": {
      "inherited": true,
      "value": 0
    },
    "accessTokenLifetime": {
      "inherited": true,
      "value": 0
    }
  },
  "advancedOAuth2ClientConfig": {
    "name": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "descriptions": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "requestUris": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "responseTypes": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "grantTypes": {
      "inherited": false,
      "value": [
        "password"
      ]
    },
    "contacts": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "tokenEndpointAuthMethod": {
      "inherited": true,
      "value": "string"
    },
    "sectorIdentifierUri": {
      "inherited": true,
      "value": "string"
    },
    "subjectType": {
      "inherited": true,
      "value": "string"
    },
    "updateAccessToken": {
      "inherited": true,
      "value": "string"
    },
    "clientUri": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "logoUri": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "policyUri": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "isConsentImplied": {
      "inherited": true,
      "value": true
    },
    "mixUpMitigation": {
      "inherited": true,
      "value": true
    }
  },
  "coreOpenIDClientConfig": {
    "claims": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "postLogoutRedirectUri": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "clientSessionUri": {
      "inherited": true,
      "value": "string"
    },
    "defaultMaxAge": {
      "inherited": true,
      "value": 0
    },
    "defaultMaxAgeEnabled": {
      "inherited": true,
      "value": true
    },
    "defaultAcrValues": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "jwtTokenLifetime": {
      "inherited": true,
      "value": 0
    }
  },
  "signEncOAuth2ClientConfig": {
    "jwksUri": {
      "inherited": true,
      "value": "string"
    },
    "jwksCacheTimeout": {
      "inherited": true,
      "value": 0
    },
    "jwkStoreCacheMissCacheTime": {
      "inherited": true,
      "value": 0
    },
    "tokenEndpointAuthSigningAlgorithm": {
      "inherited": true,
      "value": "string"
    },
    "jwkSet": {
      "inherited": true,
      "value": "string"
    },
    "idTokenSignedResponseAlg": {
      "inherited": true,
      "value": "string"
    },
    "idTokenEncryptionEnabled": {
      "inherited": true,
      "value": true
    },
    "idTokenEncryptionAlgorithm": {
      "inherited": true,
      "value": "string"
    },
    "idTokenEncryptionMethod": {
      "inherited": true,
      "value": "string"
    },
    "idTokenPublicEncryptionKey": {
      "inherited": true,
      "value": "string"
    },
    "clientJwtPublicKey": {
      "inherited": true,
      "value": "string"
    },
    "mTLSTrustedCert": {
      "inherited": true,
      "value": "string"
    },
    "mTLSSubjectDN": {
      "inherited": true,
      "value": "string"
    },
    "mTLSCertificateBoundAccessTokens": {
      "inherited": true,
      "value": true
    },
    "publicKeyLocation": {
      "inherited": true,
      "value": "string"
    },
    "userinfoResponseFormat": {
      "inherited": true,
      "value": "string"
    },
    "userinfoSignedResponseAlg": {
      "inherited": true,
      "value": "string"
    },
    "userinfoEncryptedResponseAlg": {
      "inherited": true,
      "value": "string"
    },
    "userinfoEncryptedResponseEncryptionAlgorithm": {
      "inherited": true,
      "value": "string"
    },
    "requestParameterSignedAlg": {
      "inherited": true,
      "value": "string"
    },
    "requestParameterEncryptedAlg": {
      "inherited": true,
      "value": "string"
    },
    "requestParameterEncryptedEncryptionAlgorithm": {
      "inherited": true,
      "value": "string"
    },
    "tokenIntrospectionResponseFormat": {
      "inherited": true,
      "value": "string"
    },
    "tokenIntrospectionSignedResponseAlg": {
      "inherited": true,
      "value": "string"
    },
    "tokenIntrospectionEncryptedResponseAlg": {
      "inherited": true,
      "value": "string"
    },
    "tokenIntrospectionEncryptedResponseEncryptionAlgorithm": {
      "inherited": true,
      "value": "string"
    }
  },
  "coreUmaClientConfig": {
    "claimsRedirectionUris": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    }
  }
}'
Show response
{
    "_id": "<oauth2-client-name>",
    "_rev": "1881599229",
    "coreOAuth2ClientConfig": {
        "agentgroup": null,
        "userpassword": null,
        "userpassword-encrypted": "AAAAA0FFUwIQySwvWyQsAjcFmGkkCz/irQfToaS98EKCAfPfemvgl9cTtaL09rFoUg==",
        "scopes": {
            "inherited": false,
            "value": [
                "fr:idm:*"
            ]
        },
        "clientType": {
            "inherited": false,
            "value": "Public"
        },
        "redirectionUris": {
            "inherited": false,
            "value": [
                "https://httpbin.org/anything"
            ]
        },
        "status": {
            "inherited": false,
            "value": "Active"
        }
    },
    "advancedOAuth2ClientConfig": {
        "grantTypes": {
            "inherited": false,
            "value": [
                "password"
            ]
        }
    },
    "_type": {
        "_id": "OAuth2Client",
        "name": "OAuth2 Clients",
        "collection": true
    }
}

Create an administrative OAuth 2.0 client using Identity Cloud Admin UI

  1. Using the realm menu, navigate to the realm where you want to create the OAuth 2.0 client.

  2. Follow the steps in Register an app or service:

    1. In step 2, choose an app type of Service / Machine-to-machine.

  3. Follow the steps in Create a client profile.

    1. In step 4, enter the following:

      Grant Types

      Resource Owner Password Credentials

      Scopes

      fr:idm:*

    2. Skip the Advanced Settings in step 5.

Create a user identity with openidm-admin authorization role

  1. Using the realm menu, navigate to the realm where you want to create the user identity.

  2. Go to Identities > Manage > Users, and then click + New User.

  3. Enter a user name.

  4. Complete the remaining fields, and then click Save.

  5. On the Manage Identities page, click the user you just created.

  6. Click Reset Password, then enter a new password.

    Make sure that you use a strong password.

  7. Select Authorization Roles, and then click Add Authorization Roles.

  8. Add the openidm-admin role, and then click Save.