Access Token Refresh

Overview

The refresh token mechanism ensures that user sessions maintain valid access tokens by periodically checking and refreshing them before they expire. This is critical for uninterrupted user experience and secure access control.

The refresh token mechanism can be triggered in two ways:

  1. A background job that runs every 30 seconds (with an initial delay of 30 seconds) and checks if the Access Token is expired or about to expire. To disable background, you need to edit the OIDCAuth Extension configuration. See section Background Job for details.

  2. When Script Function Auth:GetAccessToken from the OIDCAuth Extension is called to get the current valid user access token. See Script Function for details.

Background Job

As mentioned above, the token can be refreshed by a background job that runs every 30 seconds and checks if the Access Token is expired or about to expire.

How It Works

  • Scheduled Refresh:

    • A scheduler runs at a fixed interval, every 30 seconds.

    • A background task processes all active sessions.

  • Session Iteration:

    • Each session is checked for validity and user activity.

    • Inactive sessions or sessions without a refresh token are skipped.

  • Refresh Eligibility:

    • For each eligible session, the expiration time of the access token is calculated.

    • If the token expires within a lead time of 60 seconds, a refresh is triggered.

  • Token Refresh:

    • The refresh token is used to request new tokens from the OpenID provider (Keycloak).

    • If successful, the session is updated with new tokens and user information.

  • Validation and Update:

    • If a new ID token is received, it is validated.

    • User roles and principal are updated, if needed.

    • The refreshed authorization is stored in the session.

  • Error Handling:

    • If the token cannot be refreshed due to authorization errors returned by the OIDC Authentication Server, the session is invalidated and the user is logged out.

    • If the token cannot be refreshed due to technical issues (e.g., network failures, timeouts, or connection errors), the session is preserved.

Example

Let's suppose a token was released at 12:00. The scheduler runs every 30 seconds and the lead time is 60 seconds:

  • The token expires at 12:05:00

  • The scheduler runs at 12:03:30, 12:04:00, 12:04:30, ...

  • At 12:04:00, the token has 60 seconds left. The refresher triggers a refresh, obtains new tokens, and updates the session. The user continues working seamlessly.

Key Points

  • Lead Time: Tokens are refreshed before expiration, typically 60 seconds in advance.

  • Interval: The scheduler interval is set to 30 seconds.

  • Validation: New tokens are validated for compliance and user identity.

  • Session Update: Refreshed tokens and user informaion are stored in the session.

  • Error Handling: Adopt a security-first approach to ensure robustness.

Script Function

The second method to refresh the token is calling Script Function Auth:GetAccessToken from the OIDCAuth Extension.

How It Works

  • User action:

    • A user calls the Auth:GetAccessToken Script Function form an FNZ Studio Solution point.

  • Refresh Eligibility:

    • For the current session, the expiration time of the access token is calculated.

    • If the token expires within a lead time of 60 seconds, a refresh is triggered.

  • Token Refresh:

    • The refresh token is used to request new tokens from the OpenID provider (Keycloak).

    • If successful, the session is updated with new tokens and user information.

  • Validation and Update:

    • If a new ID token is received, it is validated.

    • User roles and principal are updated if needed.

    • The refreshed authorization is stored in the session.

  • Error Handling:

    • If the token cannot be refreshed due to authorization errors returned by the OIDC Authentication Server, the session is invalidated and the user is logged out.

    • If the token cannot be refreshed due to technical issues (e.g., network failures, timeouts, or connection errors):

      • If the token is not expired yet, the session is preserved and the current (unrefreshed) access token is returned.

      • If the token is expired, the session is invalidated and the user is logged out.

Further Notes

User Inactivity

  • User inactivity is determined by evaluating the session's idle time against a predefined threshold.

  • The threshold is set to 4 minutes, calculated as a base duration of 5 minutes minus a 1-minute margin.

  • If the session's idle time surpasses this 4-minute threshold, the user is classified as inactive.

This mechanism ensures continuous authentication and secure session management for users in FNZ Studio.