PingAM 7.5.1

Configure AM for client-side OAuth 2.0 tokens

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

Enable client-side OAuth 2.0 tokens

These steps configure AM to issue client-side 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-Side Access & Refresh Tokens.

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

  4. Save your changes.

  5. Configure client-side token denylisting.

    For more information, refer to Client-side OAuth 2.0 token denylist.

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

    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.

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

    For more information, refer to Client-side OAuth 2.0 token encryption and Client-side OAuth 2.0 token digital signatures.

Client-side OAuth 2.0 token denylist

Adding tokens to the denylist prevents client-side 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-side refresh tokens have corresponding entries in a CTS allowlist, rather than a denylist. When presenting a client-side refresh token, AM 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 also removes associated refresh tokens from the allowlist.

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

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

    This cache size determines the number of denylisted tokens to cache in memory, to speed up denylist 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 Denylist Poll Interval field, enter the interval in seconds for AM to check for token denylist 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 Denylist Purge Delay field, enter the length of time, in minutes, that denylist tokens can exist before being purged beyond their expiration time.

    When client-side token denylisting is enabled, AM tracks OAuth v2.0 access tokens over the configured lifetime of those tokens plus the denylist purge delay. For example, if the access token lifetime is set to 6000 seconds and the denylist purge delay is one minute, then AM tracks the access token for 101 minutes. You can increase the denylist 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 denylist purge delay for servers running a clock synchronization protocol, such as Network Time Protocol.

    Default: 1 minute

  5. Save your changes.

Client-side OAuth 2.0 token encryption

To protect OAuth 2.0 client-side 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-side tokens if token encryption is disabled.

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

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

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

    The alias mapped to the algorithm is defined in the secret stores, as shown in the table below:

    Encrypt client-side OAuth 2.0 tokens

    This table shows the secret label mapping used to encrypt client-side access tokens:

    Secret label Default alias Algorithms

    am.services.oauth2.stateless.token.encryption

    directentest

    A128CBC-HS256

    By default, secret labels are mapped to demo keys contained in the default keystore provided with AM and mapped to the default-keystore keystore 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 labels to aliases, refer to Secrets, certificates, and keys.

  4. Save your changes.

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

Client-side OAuth 2.0 token digital signatures

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

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.

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

These steps configure the OAuth 2.0 provider to sign client-side 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-side tokens.

    The alias mapped to the algorithm is defined in the secret stores, as shown in the table below:

    Sign client-side OAuth 2.0 tokens

    This table shows the secret label mappings used to sign client-side access tokens:

    Secret label 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 labels are mapped to demo keys contained in AM’s default keystore and mapped to the default-keystore secret store. Use these keys for demo and test purposes only. In 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 labels to aliases, refer to Secrets, certificates, and keys.

  3. Save your changes.

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