Configuring 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 "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 AM to issue client-based access and refresh tokens:
Log in to the AM console as an administrative user. For example,
amAdmin.Navigate to Realms > Realm Name > Services > OAuth2 Provider.
On the Core tab, enable Use Client-Based Access & Refresh Tokens.
(Optional) Enable Issue Refresh Tokens and/or Issue Refresh Tokens on Refreshing Access Tokens.
Save your changes.
Configure client-based token blacklisting. For more information, see "Configuring Client-Based OAuth 2.0 Token Blacklisting".
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
AM 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 AM 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.
Perform the following steps to configure client-based token blacklisting:
Log in to the AM console as an administrative user. For example,
amAdmin.Navigate to Configure > Global Services > Global > OAuth2 Provider.
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
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
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
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, AM supports encrypting their JWTs using AES authenticated encryption. Since 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.
Navigate to Realms > Realm Name > Services > OAuth2 Provider.
On the Core tab, enable Use Client-Based Access & Refresh Tokens.
On the Advanced tab, enable Client-Based Token Encryption.
Note that the alias mapped to the algorithm is defined in the secret stores, as shown in the table below:
The following table shows the secret ID mapping used to encrypt client-based access tokens:
Secret ID Default Alias Algorithms am.services.oauth2.stateless.token.encryption directentest A128CBC-HS256 By default, secret IDs are mapped to demo keys contained in the default keystore provided with AM and mapped to the
default-keystorekeystore secret store. Use these keys for demo and test purposes only. For production environments, replace the secrets as required and create mappings for them in a secret store configured in AM.For more information about managing secret stores and mapping secret IDs to aliases, see Configuring Secrets, Certificates, and Keys.
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
AM 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.
AM exposes the public key to validate client-based token signatures in its JWK URI. See "/oauth2/connect/jwk_uri".
Perform the steps in this procedure to configure the OAuth 2.0 provider to sign client-based tokens:
Navigate to Realms > Realm Name > Services, and then click OAuth2 Provider.
On the Advanced tab, in the OAuth2 Token Signing Algorithm drop-down list, select the signing algorithm to use for signing client-based tokens.
Note that the alias mapped to the algorithm is defined in the secret stores, as shown in the table below:
The following table shows the secret ID mappings used to sign client-based access tokens:
Secret ID Default Alias Algorithms am.services.oauth2.stateless.signing.ES256 es256test ES256 am.services.oauth2.stateless.signing.ES384 es384test ES384 am.services.oauth2.stateless.signing.ES512 es512test ES512 am.services.oauth2.stateless.signing.HMAC hmacsigningtest HS256 HS384 HS512 am.services.oauth2.stateless.signing.RSA rsajwtsigningkey PS256 PS384 PS512 RS256 RS384 RS512 By default, secret IDs are mapped to demo keys contained in the default keystore provided with AM and mapped to the
default-keystorekeystore secret store. Use these keys for demo and test purposes only. For production environments, replace the secrets as required and create mappings for them in a secret store configured in AM.For more information about managing secret stores and mapping secret IDs to aliases, see Configuring Secrets, Certificates, and Keys.
Save your changes.
Client-based OAuth 2.0 access and refresh tokens will now be signed.