mirror of
https://github.com/nais/wonderwall.git
synced 2026-05-11 10:56:53 +00:00
3143940b08
These feature flags were enabled by default. We specifically disallowed the use of automatic refresh with the SSO mode, though this poses some complexity if using the forward-auth feature. To simplify configuration and code, we remove the flags in their entirety as session refresh behaviour is mostly already handled by the implementation of GetSession() in the handlers. Specifically: - the Standalone handler needs to refresh sessions when reverse-proxying to the upstream. - the SSO server handler needs to refresh sessions only when using the forward-auth feature. It does not have an upstream to reverse proxy to. - the SSO proxy handler is a read-only upstream proxy and does not possess the ability to refresh sessions itself, though it will delegate traffic for the session endpoints to the configured SSO server. Automatic refreshing is thus only disabled when running in SSO mode without the forward-auth feature.
62 lines
3.3 KiB
Markdown
62 lines
3.3 KiB
Markdown
# Session Management
|
|
|
|
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_.
|
|
|
|
## Session Metadata
|
|
|
|
User agents can access their own session metadata by using [the `/oauth2/session` endpoint](endpoints.md#oauth2session).
|
|
|
|
## Session Expiry
|
|
|
|
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](endpoints.md#oauth2login) again.
|
|
|
|
The maximum lifetime can be configured with the `session.max-lifetime` flag.
|
|
|
|
## Session Refreshing
|
|
|
|
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.
|
|
|
|
### Automatic vs Manual Refresh
|
|
|
|
The behaviour for refreshing depends on the [runtime mode](configuration.md#modes) for Wonderwall.
|
|
|
|
In standalone mode, tokens are automatically refreshed.
|
|
Tokens 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](endpoints.md#oauth2sessionrefresh).
|
|
|
|
## Session Inactivity
|
|
|
|
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.
|
|
|
|
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.
|