3.9.10 Tokens

The Tokens tab in Keycloak allows you to configure settings related to token lifespans, authorization flows, refresh tokens, and user actions. This guide explains each configuration option in detail to help you manage security and session behaviors effectively.

Fig 3.9.10.a: Token Configuration and Management

1. Default Signature Algorithm

   • Purpose: Defines the algorithm used to sign tokens for the realm.

   • Default: RS256

   • How to Configure: Select an algorithm from the dropdown menu according to your security and compatibility requirements.

Fig 3.9.10.b: Token, Token default signature algorithm

You can choose the most suitable option from the dropdown menu based on your needs.

1. OAuth 2.0 Device Code Lifespan

   • Purpose: Sets the maximum lifespan of the device code and user code before they expire.

   • Recommendation:

     • Keep it long enough to allow users to retrieve their secondary device, navigate to the verification URL, and log in.

     • Keep it short enough to minimize risks like phishing or code misuse.

   • Configuration: Adjust the duration using the input field and select the unit (Seconds, Minutes, Hours, or Days) from the dropdown.

Fig 3.9.10.c: Token, OAuth 2.0 Device Code Lifespan

1. OAuth 2.0 Device Polling Interval

• Purpose: Defines the waiting period (in seconds) between successive polling requests to the token endpoint.

• Recommendation: Set an appropriate value to balance responsiveness and server load.

Fig 3.9.10.d: Token, OAuth 2.0 Device Polling Interval

1. Short Verification URI (Device Authorization Flow)

• Purpose: Specifies the short verification URL returned during the Device Authorization flow.

• Usage: Helps users quickly access the verification page on secondary devices.

1. Revoke Refresh Token

   • Purpose: Controls whether refresh tokens should be revoked after a certain number of uses.

   • Behavior:

     • Enabled (ON) → Refresh tokens are revoked after reaching the Refresh Token Max Reuse limit.

     • Disabled (OFF) → Refresh tokens remain valid for multiple uses without revocation.

Fig 3.9.10.e: Token, Revoke refresh token

This is a toggle button, when activated (toggled ON), refresh tokens are revoked after reaching Refresh Token Max Reuse (which can be customized as per your requirements), allowing their use until then. Otherwise, refresh tokens are not revoked and they remain valid for multiple uses.

When deactivated (toggled OFF), they function as usual without revocation.

Fig 3.9.10.f: Token, Refresh token

1. Refresh Token Max Reuse

   • Purpose: Defines the maximum number of times a refresh token can be reused before being revoked.

   • Configuration:

     • Available only when Revoke Refresh Token is enabled.

     • Adjust the value using the arrow buttons.

Fig 3.9.10.f: Token, Access token

1. Access Token Lifespan

   • Purpose: Specifies how long an Access Token remains valid before expiration.

   • Recommendation: Set this shorter than the SSO session timeout for better security.

   • Configuration: Adjust the duration and choose the unit (Minutes, Hours, or Days).

Fig 3.9.10.g: Token, Access token lifespan

This defines the maximum lifespan of an Access Token before it gets expired.

It is mostly recommended to keep this shorter than the SSO Timeout duration.

You can adjust the values and select the duration unit from the dropdown menu as required.

8. Access Token Lifespan (Implicit Flow)

• Purpose: Sets the lifespan for Access Tokens generated during the OpenID Connect Implicit Flow.

• Important:

  • Tokens issued in this flow cannot be refreshed.

  • Recommended to set a shorter duration than the regular access token lifespan.

Fig 3.9.10.h: Token, Access token lifespan for implict flow

This is the maximum lifespan for Access Tokens generated during the OpenID Connect Implicit Flow.

This value is recommended to be shorter than the SSO Timeout.

Unlike other flows, tokens here cannot be refreshed, that is why this is a separate timeout different to Access Token Lifespan.

You can adjust the values and select the duration unit from the dropdown menu as required.

9. Client Login Timeout

• Purpose: Sets the maximum duration for clients to complete the Authorization Code Flow in OpenID Connect.

• Recommendation: Keep it short — typically 1 minute.

• Configuration: Adjust the duration and select the unit from the dropdown.

Fig 3.9.10.i: Token, Client login timeout

This refers to the maximum duration for clients to complete the Authorization Code Flow in OIDC

It is typically recommended to be about 1 minute.

You can adjust the values and select the duration unit from the dropdown menu as required.

Fig 3.9.10.j: Token, Action token

10. User-Initiated Action Lifespan

• Purpose: Specifies how long a user action token remains valid. Examples: Forgot Password, Verify Email.

• Recommendation: Set a short duration since these actions are expected to be completed quickly.

Fig 3.9.10.k: Token, User-Initiated action lifespan

This refers to the maximum time after which a user's action permission (such as a Forgot Password email) expires.

It's kept short as users are expected to respond to such actions promptly.

You can adjust the values and select the duration unit from the dropdown menu as required.

11. Default Admin-Initiated Action Lifespan

• Purpose: Defines the validity period of action tokens sent by administrators. Examples: Update Password, Verify Email.

• Recommendation: Keep this longer to support offline users.

• Configuration: Administrators can modify this before sending tokens.

Fig 3.9.10.l: Token, Default Admin-Initiated Action Lifespan

This refers to the maximum duration before an action permit sent by the administrator to the user expires.

It's recommended to keep this duration long to accommodate offline users.

Administrators can adjust this timeout before issuing the token.

12. Email Verification Timeout

• Purpose: Sets the expiration time for email verification links.

• Configuration: Adjust based on your security policies.

Fig 3.9.10.m: Token, Email verification timeout

This sets a separate timeout for email verification. You can adjust this setting according to your needs.

13. IdP Account Email Verification Timeout

• Purpose: Defines a separate timeout for verifying email addresses associated with Identity Providers (IdP).

Fig 3.9.10.n: Token, IdP Account Email Verification Timeout

This sets a separate timeout for Identity Provider (IdP) account email verification. You can customize this setting according to your needs.

1. Forgot Password Timeout

• Purpose: Sets the timeout for forgot password requests.

• Recommendation: Keep it short to ensure security.

Fig 3.9.10.o: Token, Forgot password timeout

This sets a separate timeout for forgot password requests. You can customize this setting according to your needs.

15. Execute Actions Timeout

• Purpose: Defines the timeout for completing admin-triggered actions like password updates or configuring MFA.

Fig 3.9.10.p: Token, Execute Actions Timeout

This sets a separate timeout for executing actions. You can customize this setting according to your needs.

Save and Revert

• Save: Applies all changes you’ve made in the Tokens tab.

• Revert: Discards any unsaved modifications and restores the previous configuration.