Skip to content

Refresh Token Policy

SSL Teams stores the JWT policy under auth.jwt.policy. The lifetime settings are read when tokens are issued or rotated. They do not rewrite expiry timestamps already stored on refresh-token rows.

Lifetime settings

Setting Default Meaning Enforcement
access_ttl_seconds 900 How long an access token is valid after issuance. Applied when an access token is issued, including after refresh.
refresh_ttl_seconds 604800 How long each individual refresh token is valid after it is issued. Applied to the stored expires_at of new login and rotation tokens.
refresh_idle_timeout_seconds 86400 The maximum time since the current refresh token was issued. A successful rotation issues a new token and starts a new idle window. Checked when a refresh is presented.
refresh_absolute_ttl_seconds 1209600 The maximum lifetime of the refresh-token family, measured from the earliest token issued in that family. Rotation does not extend this limit. Checked when a refresh is presented.

The seeded auth.jwt.policy.issuer value is loaded into the runtime policy object but is not currently consumed by the token issuer. The JWT issuer claim remains controlled by the deployment setting sslteam.auth.jwt.issuer (for Docker, SSLTEAM_AUTH_JWT_ISSUER).

The configured idle timeout must not exceed refresh_ttl_seconds. The absolute lifetime must be at least refresh_ttl_seconds.

Worked Example: Refresh Token Lifetime Enforcement

With the default values:

  • 26 October 2026 09:00: a user signs in. The access token expires after 15 minutes, and the first refresh token expires after 7 days. The refresh family starts at this time.
  • 27 October 2026 09:01: if the current refresh token has not been used since issuance, the 24-hour idle timeout has been exceeded and refresh is denied.
  • During the following 14 days: each successful refresh rotates the token and gives the new token its own 24-hour idle window, but the family origin remains 26 October 2026 09:00.
  • 9 November 2026 09:00: continuous refresh reaches the 14-day absolute family limit and is denied, even if the latest individual refresh token is otherwise unexpired and recently used.

A denied refresh must authenticate again to create a new token family. Authorization failures such as a missing certificate permission are different from authentication expiry and are not fixed by refreshing a token.

Changing the policy

Policy changes affect newly issued access tokens and newly issued or rotated refresh tokens. Existing refresh-token rows retain their stored expires_at; the service does not migrate or rewrite those rows. Idle and absolute limits are evaluated from the existing issued_at and family_id values, so no database migration is required for those controls.

Review the effective values in the dashboard system-configuration view and record the change with the normal deployment change process. Validate a login, one refresh rotation, an idle-timeout boundary, and an absolute-family boundary in a controlled environment before relying on a changed policy.

Seeded settings that are not enforcement controls

The seeded auth.jwt.policy.issuer value is currently loaded and validated as metadata, but changing it does not change the JWT issuer claim. Use the deployment JWT issuer configuration for that behavior.

The seed catalog currently includes these auth.password.policy settings:

  • min_length
  • require_upper
  • require_lower
  • require_digit
  • require_symbol

They are persisted and validated as setting metadata, but the authentication service has no runtime consumer for them. They do not currently enforce permanent-password complexity. Do not describe those five values as active password rules until password-policy validation is implemented.