When a user authenticates themselves, they receive a session. Sessions are stored server-side; we only store a session identifier at the end-user's user agent.
A session has three states:
- active - the session is valid
- inactive - the session has reached the inactivity timeout and is considered invalid
- expired - the session has reached its maximum lifetime and is considered invalid
Requests with an invalid session are considered unauthenticated.
User agents can access their own session metadata by using the /oauth2/session endpoint.
Every session has a maximum lifetime.
The lifetime is indicated by the session.ends_at and session.ends_in_seconds fields in the session metadata.
When the session reaches the maximum lifetime, it is considered to be expired, after which the user is essentially unauthenticated.
A new session must be acquired by redirecting the user to the /oauth2/login endpoint again.
The maximum lifetime can be configured with the session.max-lifetime flag.
The tokens within the session will usually expire before the session itself.
This is indicated by the tokens.expire_at and tokens.expire_in_seconds fields in the session metadata.
If you've configured a session lifetime that is longer than the token expiry, you'll probably want to refresh the tokens to avoid redirecting end-users to the /oauth2/login endpoint whenever the access tokens have expired.
The ability to refresh tokens requires the session.refresh flag to be enabled.
The behaviour for refreshing depends on the runtime mode for Wonderwall.
In standalone mode, tokens can automatically be refreshed by enabling the session.refresh-auto flag.
If enabled, token will at the earliest automatically be renewed 5 minutes before they expire.
If the token already has expired, a refresh attempt is still automatically triggered as long as the session itself not has ended or is marked as inactive.
Automatic refreshes happens whenever the end-user visits or requests any path that is proxied to the upstream application.
In SSO mode, tokens can not be automatically refreshed. They must be refreshed by performing a request to the /oauth2/session/refresh endpoint.
A session can be marked as inactive before it expires (reaches the maximum lifetime). This happens if the time since the last refresh exceeds the given inactivity timeout.
An inactive session cannot be refreshed; a new session must be acquired by redirecting the user to the /oauth2/login endpoint.
This is useful if you want to ensure that an end-user can re-authenticate with the identity provider if they've been gone from an authenticated session for some time.
Inactivity support is enabled with the session.inactivity option, which also requires session.refresh.
The activity state of the session is indicated by the session.active field in the session metadata.
The time until the session will be marked as inactive are indicated by the session.timeout_at and session.timeout_in_seconds fields in the session metadata.
The timeout is configured with session.inactivity-timeout.
If this timeout is shorter than the token expiry, the session metadata fields tokens.expire_at and tokens.expire_in_seconds will be reduced accordingly to reflect the inactivity timeout.