Identity Cloud

Client-side tokens

Identity Cloud returns a token to the client after successfully completing one of the grant flows.

In this example, the token is stored in the access_token property:

{
   "access_token":"eyJ0eXAiOiJKV1QiLOT05FIiwiYWxnQY1lIjoxNTM5MDEzMzYyLsbSI6Ii8iLCj...",
   "scope":"write",
   "token_type":"Bearer",
   "expires_in":3599
}
Example decoded access token
{
     typ: "JWT",
     zip: "NONE",
     alg: "HS256"
}
{
     sub: "(usr!myClient)",
     subname" "myClient",
     cts: "OAUTH2_STATELESS_GRANT",
     auditTrackingId: "f20f4099-5248-4399-a7f0-2d54d4020099-108676",
     iss: "https://<tenant-env-fqdn>/am/oauth2",
     tokenName: "access_token",
     token_type: "Bearer",
     authGrantId: "1LUgI8zcDWqcfEnnLdZDnNqA2wc",
     aud: "myClient",
     nbf: 1539075967,
     grant_type: "client_credentials",
     scope: [
      "write"
     ],
     auth_time: 1539075967,
     realm: "/alpha",
     exp: 1539079567,
     iat: 1539075967,
     expires_in: 3600,
     jti: "FTQT6eZkDhm6PHEaSthORoTLB80"
}
[signature]

Client-side tokens:

  • Are larger than the reference returned for server-side tokens.

    Consider their size if they must be sent in a header because the size of the token cannot exceed the maximum header size allowed by your end users' browsers.

    The size of client-side tokens also increases when you customize Identity Cloud to store additional attributes in the tokens.

  • Are presented to the client after successfully completing an OAuth 2.0 grant flow.

    Therefore, tokens are vulnerable to tampering attacks, and you should configure Identity Cloud to sign and encrypt them.

  • Can be introspected without calling the authorization server.

  • Incur overhead when tokens are decrypted and verified because Identity Cloud does not store the decrypt sequence of the token in memory.

  • Support token denylisting.

    This feature maintains a list of revoked tokens and authorization codes stored in the CTS token store. Token denylisting protects against replay attacks and is always enabled for client-side tokens.

    Each time a client presents a client-side token in a request, Identity Cloud checks if the token was revoked in the CTS token store. If it was not revoked, Identity Cloud decrypts the token to retrieve its information.

    Client-side refresh tokens have corresponding entries in a CTS allowlist rather than a denylist. When presenting a client-side refresh token, Identity Cloud checks that a matching entry is found in the CTS allowlist, and prevents reissue if the record does not exist.

    Adding a client-side OAuth 2.0 token to the denylist removes the associated refresh token from the allowlist.

Protect client-side tokens

To protect OAuth 2.0 client-side access and refresh tokens, Identity Cloud supports encrypting their JWTs using AES authenticated encryption. Because this encryption also protects the integrity of the JWT, you only need to configure Identity Cloud to sign client-side tokens if token encryption is disabled.

Client-side tokens must be signed and/or encrypted for security reasons. If your environment does not support encrypting OAuth 2.0 tokens, you must configure signing to protect them against tampering.

Encrypt tokens

If you enable token encryption, token signature is disabled because encryption is performed using direct symmetric encryption.

To configure the OAuth 2.0 provider to encrypt client-side and refresh tokens:

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Services > OAuth2 Provider.

  2. On the Advanced tab, enable Encrypt Client-Side Tokens.

  3. Save your changes.

    Client-side OAuth 2.0 access and refresh tokens will now be encrypted.

Sign tokens

Identity Cloud supports digital signature algorithms that secure the integrity of client-side tokens.

Token signature is enabled by default when client-side tokens are enabled. By default, token signature is configured using a demo key that you must change in production environments.

Identity Cloud exposes the public key to validate client-side token signatures in its JWK URI. Refer to /oauth2/connect/jwk_uri.

To configure the OAuth 2.0 provider to sign client-side tokens:

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Services, and click OAuth2 Provider.

  2. On the Advanced tab, in the OAuth2 Token Signing Algorithm list, select the signing algorithm to use for signing client-side tokens.

  3. Save your changes.

    Client-side OAuth 2.0 access and refresh tokens will now be signed.

Copyright © 2010-2024 ForgeRock, all rights reserved.