Configure AM for Client-Based OAuth 2.0 Tokens

When configured for client-based tokens, AM returns a token (instead of the token reference it returns when configured for CTS-based tokens) to the client after successfully completing one of the grant flows. For more information about client-based and CTS-based tokens, see Token Storage Location.

Enable Client-Based OAuth 2.0 Tokens

These steps configure AM to issue client-based access and refresh tokens:

  1. In the AM Admin UI, go to Realms > Realm Name > Services > OAuth2 Provider.

  2. On the Core tab, enable Use Client-Based Access & Refresh Tokens.

  3. Enable Issue Refresh Tokens and/or Issue Refresh Tokens on Refreshing Access Tokens.

  4. Save your changes.

  5. Configure client-based token blacklisting.

    For more information, see Client-Based OAuth 2.0 Token Blacklisting.

  6. Configure either client-based token signature or client-based token encryption.

    Token signature is enabled by default when client-based tokens are enabled. By default, token signature is configured using a demo key that you must change in production environments. If you enable token encryption, token signature is disabled, because encryption is performed using direct symmetric encryption.

Client-Based OAuth 2.0 Token Blacklisting

Token blacklisting prevents client-based tokens from being reused if the authorization code has been replayed, or if tokens have been revoked by either the client or the resource owner.

Client-based refresh tokens have corresponding entries in a CTS whitelist, rather than a blacklist. When presenting a client-based refresh token, AM checks that a matching entry is found in the CTS whitelist, and prevents reissue if the record does not exist.

Adding a client-based OAuth 2.0 token to the blacklist also removes associated refresh tokens from the whitelist.

  1. In the AM Admin UI, go to Configure > Global Services > Global > OAuth2 Provider.

  2. Under Global Attributes, enter the number of blacklisted tokens in the Token Blacklisting Cache Size field.

    This cache size determines the number of blacklisted tokens to cache in memory, to speed up blacklist checks. Enter a number based on the estimated number of token revocations that a client will issue (for example, when the user gives up access or when an administrator revokes a client’s access).

    Default: 10000

  3. In the Blacklist Poll Interval field, enter the interval, in seconds, for AM to check for token blacklist changes from the CTS data store.

    The longer the polling interval, the more time a malicious user has to connect to other AM servers in a cluster and make use of a stolen OAuth v2.0 access token. Shortening the polling interval improves the security for revoked tokens but might incur a minimal decrease in overall AM performance due to increased network activity.

    Default: 60 seconds

  4. In the Blacklist Purge Delay field, enter the length of time, in minutes, that blacklist tokens can exist before being purged beyond their expiration time.

    When client-based token blacklisting is enabled, AM tracks OAuth v2.0 access tokens over the configured lifetime of those tokens plus the blacklist purge delay. For example, if the access token lifetime is set to 6000 seconds and the blacklist purge delay is one minute, then AM tracks the access token for 101 minutes. You can increase the blacklist purge delay if you expect system clock skews in an AM server cluster to be greater than one minute. There is no need to increase the blacklist purge delay for servers running a clock synchronization protocol, such as Network Time Protocol.

    Default: 1 minute

  5. Click Save to apply your changes.

Configure Client-Based OAuth 2.0 Token Encryption

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

  1. Go to Realms > Realm Name > Services > OAuth2 Provider.

  2. On the Core tab, enable Use Client-Based Access & Refresh Tokens.

  3. On the Advanced tab, enable Client-Based Token Encryption.

  4. Save your changes.

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

Client-Based OAuth 2.0 Token Digital Signatures

AM supports digital signature algorithms that secure the integrity of client-based tokens.

Client-based 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.

AM exposes the public key to validate client-based token signatures in its JWK URI. See /oauth2/connect/jwk_uri.

These steps configure the OAuth 2.0 provider to sign client-based tokens:

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

  3. Save your changes.

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