Skip to main content

Token Invalidation

This guide explains how user sessions, token invalidation, and blacklist configuration work in Witboost. It is intended for system configurators and platform administrators.

User Sessions Overview​

Witboost uses JWT (JSON Web Token) based sessions.
When a user logs in, they receive a token that they can use to access protected resources until their token expires. These tokens are valid for a configurable amount of time controlled by configuration backend.auth.tokenDurationSeconds. Make sure this value is aligned with your organization's session policies.

Token Invalidation​

A token invalidation mechanism is in place to enhance security. This ensures that tokens can be explicitly revoked before they naturally expire.

When Tokens Are Invalidated​

Tokens can be invalidated in two main ways:

  1. On Logout (Optional Configuration)

    • When enabled, all tokens issued to a user are automatically invalidated when the user logs out.
    • This setting is controlled by configuration auth.tokenInvalidation.invalidateOnLogout.

  2. Manual Invalidation by Administrators

    • Platform administrators with the RBAC permission platform.users.auth.invalidate-tokens can manually invalidate all tokens issued for a specific user from the user's page.
    • This is useful if you suspect the user's tokens have been compromised.
note

The manual invalidation process is not a user ban or a forced logout. The user will need to re-authenticate or refresh their session through the authentication provider to regain access. It should only be used if you suspect the user's tokens have been compromised or tampered with.

Blacklist and Configuration​

When a non-expired token is invalidated, it is added to a blacklist to ensure that it can no longer be used.

note

Expired tokens are naturally rejected by the system, regardless of whether they have been blacklisted.

Blacklist Entry TTL (Time To Live)​

  • The Blacklist Entry TTL controls how long each blacklist entry is kept.
  • This is configured with the auth.tokenInvalidation.blacklistEntryTTL (in seconds) setting. By default, this is set to the same value as backend.auth.tokenDurationSeconds. You should set this value based on the longest token lifetime ever configured to ensure all issued tokens can be properly invalidated if needed.

Example:

If your tokens expire after 1 hour (3600 seconds), the blacklistEntryTTL should also be set to at least 3600 seconds.

note

Setting blacklistEntryTTL to 0 will disable the blacklist cleanup. This is strongly discouraged because it can cause memory issues as invalidated tokens will never be removed.