Configuring Identity Cloud for Client-Based OAuth 2.0 Tokens

When configured for client-based tokens, Identity Cloud 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 "About Token Storage Location".

To configure client-based tokens, perform the following tasks:

Enabling Client-Based OAuth 2.0 Tokens

Perform the steps in the following procedure to configure Identity Cloud to issue client-based access and refresh tokens:

To Enable Client-Based OAuth 2.0 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. (Optional) 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 "Configuring 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. Enabling token encryption disables token signing as encryption is performed using direct symmetric encryption.

    For more information, see "Configuring Client-Based OAuth 2.0 Token Encryption" and "Configuring Client-Based OAuth 2.0 Token Digital Signatures".

    Client-based access and refresh tokens are ready for use.

Configuring Client-Based OAuth 2.0 Token Blacklisting

Identity Cloud provides a blacklisting feature that prevents client-based tokens from being reused if the authorization code has been replayed or tokens have been revoked by either the client or resource owner.

Note

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

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

To Configure Client-Based OAuth 2.0 Token Blacklisting

Perform the following steps to configure client-based token blacklisting:

  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.

    Token Blacklisting Cache Size determines the number of blacklisted tokens to cache in memory to speed up blacklist checks. You can 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 an administrator revokes a client's access).

    Default: 10000

  3. In the Blacklist Poll Interval field, enter the interval in seconds for Identity Cloud 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 Identity Cloud 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 Identity Cloud 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, Identity Cloud 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 Identity Cloud tracks the access token for 101 minutes. You can increase the blacklist purge delay if you expect system clock skews in an Identity Cloud 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.

Configuring Client-Based OAuth 2.0 Token Encryption

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

To Enable Client-Based OAuth 2.0 Token Encryption
  1. Navigate 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.

    The following table shows the secret ID mapping used to encrypt client-based access tokens:

    Secret IDDefault AliasAlgorithms
    am.services.oauth2.stateless.token.encryptiondirectentestA128CBC-HS256
  4. Save your changes.

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

Configuring Client-Based OAuth 2.0 Token Digital Signatures

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

Important

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.

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

To Configure the OAuth 2.0 Provider to Sign Client-Based Tokens

Perform the steps in this procedure to configure the OAuth 2.0 provider to sign client-based tokens:

  1. Navigate to Realms > Realm Name > Services, and then click OAuth2 Provider.

  2. On the Advanced tab, in the OAuth2 Token Signing Algorithm drop-down 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.

Read a different version of :