Configuration¶

This page has not been translated yet. See the French version for the full content.

XOLO_STORAGE_AUTO_MIGRATE¶

Apply migrations at startup (default: true). With false, schema compatibility is checked without migration. See the UUID upgrade procedure; all old replicas must be stopped.

In-process caches across replicas¶

Each instance caches users, API tokens (with their owner's application), providers and LLM models in memory. Every write that invalidates one of these caches is announced through the database, and every instance checks for announcements every XOLO_STORAGE_DATABASE_CACHE_COHERENCE_INTERVAL (default: 1s). A revoked token, a deactivated application or a changed provider key therefore stops being served by the other instances within that interval. This covers writes from the web UI, the API and the provisioning API alike.

0 turns the check off: the other instances then keep their entries until the cache TTL (XOLO_STORAGE_DATABASE_CACHE_USERS_TTL, _PROVIDERS_TTL, 60 min by default), which is only safe with a single instance. Every instance of a deployment must share these settings.

OIDC sessions and back-channel logout¶

An interactive sign-in through an OAuth2/OIDC provider opens a session stored in the database; the cookie only carries its identifier. A copied cookie does not survive the logout, and a session stays valid across restarts and replicas as long as they all share XOLO_HTTP_SESSION_KEYS. A session expires after XOLO_HTTP_SESSION_COOKIE_MAX_AGE (default: 24h), which must be positive or the server refuses to start. Every replica removes the expired entries every 10 minutes.

An unauthenticated browser asking for a web UI page returns to it after signing in. With a single interactive provider, it is sent straight to that provider without the choice page, so an open session at the provider signs it in without interaction. To avoid a loop when the sign-in fails, this happens at most once every 30 seconds (cookie xolo_auto_sign_in); otherwise the login page is shown.

An ID token presented to the API (oidctoken) is accepted whatever its audience unless XOLO_HTTP_AUTHN_OIDC_PROVIDER_<ID>_ALLOWED_AUDIENCES lists the accepted aud values (comma list). A token signed with a key ID missing from the cached JWKS triggers one JWKS refetch, at most once a minute per provider.

A sign-in must start at Xolo (/auth/oidc/providers/{provider}) and come back to the same browser within 15 minutes. A sign-in initiated by the identity provider, or a callback without the cookie set at the start, fails with sign-in start missing in the log: the user signs in again from Xolo.

An OIDC provider can revoke sessions through OpenID Connect Back-Channel Logout at https://{host}/auth/oidc/providers/{provider}/backchannel-logout:

• only providers proving their issuer, with a client ID and a valid jwks_uri, accept it (named OIDC providers, Gitea with DISCOVERY_URL, Google); the others answer 404;
• the logout_token must be signed (RS256, RS384 or RS512) by the issuer, for the client ID, and carry sub and jti. Revocation is by subject: every session of that issuer and subject is closed, in every tenant, and a sign-in started before it is refused. A token carrying only sid is refused (400);
• a token is only accepted within 5 minutes of its issuance; a token already processed answers 200 without effect. Replica and provider clocks must agree within 5 minutes;
• in multi-tenant mode any active domain works. The route is not rate limited per IP: each request is authenticated by its signed token.

Durable logout only covers these interactive sessions. An OIDC ID token presented to the API (oidctoken) stays valid until exp plus XOLO_HTTP_AUTHN_OIDCTOKEN_EXPIRY_LEEWAY; an opaque access token (oauth2token) until its validation cache entry expires (XOLO_HTTP_AUTHN_OAUTH2TOKEN_CACHE_TTL, 60s); a /auth/token/login session for the lifetime of its cookie. A local logout does not end the session at the identity provider. See the French version for details.

Resource lifecycle¶

Deferred deletion of tenants, organizations and members through the provisioning API. See Resource lifecycle.

Language¶

The web interface is available in English, French and Spanish. Each request uses the language the signed-in member chose, kept with their account (or a close one, fr-CA giving French), otherwise the language chosen with the language switch on this browser (stored in the xolo_locale cookie), otherwise the best match of the browser's Accept-Language header, otherwise the default below.