Configuration¶

Xolo se configure entièrement par variables d'environnement, préfixées XOLO_. Le fichier .env.dist du dépôt sert de modèle de référence pour un déploiement depuis les sources ; en Docker, passez ces mêmes variables avec -e ou un fichier d'environnement.

Secret et session¶

HTTP¶

Authentification¶

Xolo authentifie les utilisateurs via un ou plusieurs fournisseurs OAuth2/OIDC. Au moins un doit être configuré.

Fournisseurs OIDC nommés¶

Pour un ou plusieurs fournisseurs OIDC génériques (Auth0, Keycloak, Authelia…), listez leurs identifiants puis configurez chacun sous un préfixe dédié :

XOLO_HTTP_AUTHN_OIDC_PROVIDERS=keycloak,auth0

XOLO_HTTP_AUTHN_OIDC_PROVIDER_KEYCLOAK_DISCOVERY_URL=https://idp.example.com/.well-known/openid-configuration
XOLO_HTTP_AUTHN_OIDC_PROVIDER_KEYCLOAK_KEY=xolo
XOLO_HTTP_AUTHN_OIDC_PROVIDER_KEYCLOAK_SECRET=change-me
XOLO_HTTP_AUTHN_OIDC_PROVIDER_KEYCLOAK_LABEL="Mon SSO"
XOLO_HTTP_AUTHN_OIDC_PROVIDER_KEYCLOAK_SCOPES=openid,profile,email

L'URL de découverte est obligatoire. Xolo télécharge le document au démarrage, avec un délai maximal de 10 secondes. Si le document est inaccessible ou incomplet, le serveur refuse de démarrer, en mode mono-tenant comme en multi-tenant. Le document doit contenir issuer, authorization_endpoint et token_endpoint. Chacun de ces champs, ainsi que userinfo_endpoint, introspection_endpoint et end_session_endpoint quand ils sont présents, doit être une URL absolue en http ou https.

Le champ jwks_uri n'est pas obligatoire : un IdP non conforme peut démarrer sans bloquer l'instance. Dans ce cas, Xolo émet un avertissement au démarrage qui cite le fournisseur concerné et indique que la validation JWT des ID Tokens est désactivée pour ce fournisseur. La validation d'introspection et de UserInfo reste active : le fournisseur reste enregistré dans la liste interne avec un JWKSURL vide, oidctoken ignore ce fournisseur (errInvalidToken, que la boucle d'authentification passe), tandis que oauth2token valide les jetons opaques via l'introspection_endpoint ou, à défaut, l'userinfo_endpoint documenté. C'est le cas type d'un IdP qui émet des jetons opaques validés par introspection — voir l'issue #27.

Pour valider des jetons d'accès opaques côté API (introspection RFC 7662, ou UserInfo à défaut) plutôt que des ID Tokens OIDC autoportés, activez XOLO_HTTP_AUTHN_OAUTH2TOKEN_ENABLED=true.

Un ID Token présenté à l'API (en-tête Authorization: Bearer ou cookie, oidctoken) est accepté par défaut quelle que soit son audience, pourvu qu'il soit signé par l'émetteur du fournisseur. Quand plusieurs applications partagent le même fournisseur, restreignez les audiences acceptées :

XOLO_HTTP_AUTHN_OIDC_PROVIDER_KEYCLOAK_ALLOWED_AUDIENCES=xolo,mon-frontend

Le claim aud du jeton doit alors contenir au moins une de ces valeurs, sinon le jeton est refusé (401). Si un jeton désigne une clé (kid) absente du JWKS en cache, Xolo recharge le JWKS une fois, au plus une fois par minute et par fournisseur, pour suivre une rotation de clés sans redémarrage.

Fournisseur Gitea¶

Le fournisseur Gitea est aligné sur les fournisseurs OIDC nommés dès que XOLO_HTTP_AUTHN_PROVIDERS_GITEA_DISCOVERY_URL est configuré : le document téléchargé doit alors contenir issuer, authorization_endpoint et token_endpoint. Si le document est inaccessible, mal formé ou incomplet, le serveur refuse de démarrer.

XOLO_HTTP_AUTHN_PROVIDERS_GITEA_DISCOVERY_URL est cependant optionnel : sans lui, Xolo démarre avec un avertissement de démarrage, et le login interactif utilise directement les champs AUTH_URL / TOKEN_URL / PROFILE_URL configurés. Lorsque DISCOVERY_URL est configuré et que le document est validé, ses authorization_endpoint et token_endpoint priment toujours sur la configuration statique : validateOIDCDiscovery exige que ces deux champs soient présents et absolus, donc la branche statique n'est consultée que sur le chemin DISCOVERY_URL vide (que la validation préalable refuse si AUTH_URL ou TOKEN_URL manquent). Pour PROFILE_URL, le document de découverte tient lieu de repli lorsqu'il publie un userinfo_endpoint et que le champ statique est vide ; avec DISCOVERY_URL, si PROFILE_URL est vide et que le document ne publie pas userinfo_endpoint, le fournisseur refuse de démarrer avec un message explicite plutôt que d'échouer à la première connexion.

Sur le chemin statique (DISCOVERY_URL vide), PROFILE_URL est également obligatoire : sans lui, aucun userinfo_endpoint n'est disponible en repli et la première connexion échouerait avec une erreur goth opaque. Le serveur refuse alors de démarrer avec le message gitea provider requires PROFILE_URL or a discovery document that publishes userinfo_endpoint, aligné sur le comportement de la branche découverte.

Qu'il passe par la découverte ou par la configuration statique, un fournisseur Gitea a besoin d'au moins un de ces deux chemins :

• DISCOVERY_URL renseigné et résolu (avec un document complet),
• AUTH_URL et TOKEN_URL renseignés (avec éventuellement PROFILE_URL).

Un fournisseur configuré avec uniquement KEY / SECRET est refusé au démarrage avec l'erreur gitea provider requires either DISCOVERY_URL or both AUTH_URL and TOKEN_URL. C'est un changement de comportement par rapport aux versions précédentes, qui acceptaient ce mode et échouaient à la première connexion ; l'erreur explicite permet aujourd'hui de repérer la mauvaise configuration dès le boot.

Comme pour les fournisseurs OIDC nommés, jwks_uri est optionnel : en son absence, ou lorsqu'il est présent mais mal formé (URL relative, scheme non http(s)), un avertissement est émis au démarrage et la validation JWT des ID Tokens est désactivée pour ce fournisseur — l'introspection reste active si le document la publie.

Sessions OIDC et déconnexion back-channel¶

Une connexion interactive par un fournisseur OAuth2/OIDC ouvre une session enregistrée en base ; le cookie ne porte que son identifiant. Chaque requête vérifie la session par une simple lecture : un cookie copié ne survit pas à la déconnexion, et une session reste valide après un redémarrage et d'un réplica à l'autre, pourvu que tous partagent XOLO_HTTP_SESSION_KEYS. Une session expire au bout de XOLO_HTTP_SESSION_COOKIE_MAX_AGE. Les sessions expirées et les entrées devenues inutiles sont supprimées toutes les 10 minutes par chaque réplica.

Un navigateur non authentifié qui demande une page de l'interface y revient après la connexion. Si un seul fournisseur interactif est configuré, il y est envoyé directement, sans page de choix : avec une session déjà ouverte chez le fournisseur, la connexion se fait sans interaction. Pour éviter une boucle si la connexion échoue, ce saut n'a lieu qu'une fois toutes les 30 secondes (cookie xolo_auto_sign_in) ; sinon la page de connexion s'affiche.

Une connexion doit commencer chez Xolo (/auth/oidc/providers/{fournisseur}) et revenir sur le même navigateur dans les 15 minutes. Une connexion initiée par le fournisseur d'identité, ou un retour sans le cookie posé au départ, échoue avec sign-in start missing dans le journal ; l'utilisateur doit relancer la connexion depuis Xolo.

Un fournisseur OIDC peut en outre révoquer les sessions par OpenID Connect Back-Channel Logout. Déclarez auprès de lui l'URL :

https://{hôte}/auth/oidc/providers/{fournisseur}/backchannel-logout

• Seuls les fournisseurs dont l'émetteur est prouvé, avec un identifiant client et un jwks_uri valide, l'acceptent : fournisseurs OIDC nommés, Gitea avec DISCOVERY_URL et Google. Les autres répondent 404.
• Le logout_token doit être signé (RS256, RS384 ou RS512) par l'émetteur, destiné à l'identifiant client, et contenir sub et jti. La révocation porte sur le sujet : toutes les sessions de cet émetteur et de ce sujet sont fermées, dans tous les tenants, et une connexion commencée avant la révocation est refusée. Un jeton ne portant qu'un sid est refusé (400).
• Un jeton n'est accepté que dans les 5 minutes qui suivent son émission. Un jeton déjà traité répond 200 sans effet, ce qui permet au fournisseur de réessayer. Les horloges des réplicas et du fournisseur doivent concorder à 5 minutes près.
• En multi-tenant, n'importe quel domaine actif convient : la révocation vaut pour tous les tenants. La route n'est pas soumise à la limitation de débit par IP, chaque requête étant authentifiée par son jeton signé.
• Le compteur xolo_oidc_backchannel_logouts_total suit les résultats (revoked, replayed, invalid, unavailable).

La déconnexion durable ne couvre que ces sessions interactives. Les autres modes d'authentification gardent leur propre mécanisme :

La déconnexion locale (/auth/oidc/logout) ferme la session Xolo ; elle ne ferme pas la session ouverte chez le fournisseur d'identité.

Stockage¶

Choisir entre SQLite et PostgreSQL¶

SQLite reste le défaut : aucune dépendance externe, idéal pour une instance unique. La base y passe en mode WAL : les écritures sont sérialisées sur une connexion, les lectures servies en parallèle par un pool de connexions en lecture seule, si bien qu'un rapport long ne bloque pas le proxy. Une base en mémoire (:memory:) n'a pas de pool de lecture. PostgreSQL est recommandé dès que plusieurs instances de Xolo partagent le même stockage, ou lorsque le volume d'événements et d'enregistrements d'usage devient important.

XOLO_STORAGE_DATABASE_DSN="postgres://xolo:motdepasse@postgres:5432/xolo?sslmode=disable"

Le schéma est créé et migré automatiquement au démarrage. Il n'existe pas de migration automatique des données d'une base SQLite existante vers PostgreSQL : la bascule suppose une base neuve.

Plugins¶

Proxy¶

Événements¶

API de provisioning¶

Écouteur d'administration dédié, protégé par TLS mutuel. Voir API de provisioning.

Multi-tenant¶

Désactivé par défaut : l'instance possède un unique tenant default, créé par la migration et jamais exposé à ses utilisateurs — pas de sous-domaine, pas de changement d'URL. Une fois activé, le tenant est identifié par l'hôte de la requête : chaque nom d'hôte est un domaine déclaré par l'API de provisioning, et un hôte qui n'est le domaine actif d'aucun tenant actif répond 404 : un hôte inconnu ne doit pas révéler que l'instance existe.

Les tenants et leurs domaines se créent exclusivement par l'API de provisioning ; la création d'un second tenant répond 409 tant que XOLO_MULTITENANCY_ENABLED vaut false.

Conséquences sur la configuration HTTP¶

XOLO_HTTP_BASE_URL doit alors être absolue — schéma et hôte — sous peine de refus de démarrage. Elle n'est plus l'URL de l'instance mais le gabarit dont chaque domaine dérive la sienne : son schéma, son port et son chemin sont conservés, son hôte est remplacé par le domaine de la requête. Liens, redirections et URL de rappel OAuth restent ainsi sur le domaine du tenant, ce qui est nécessaire : le cookie de session est propre à un hôte et la session porte le tenant sur lequel elle a été ouverte.

L'URL de rappel à déclarer auprès du fournisseur d'identité varie donc par domaine :

https://{domaine}/auth/oidc/providers/{fournisseur}/callback

Un fournisseur acceptant un redirect_uri à joker (Keycloak, Authentik…) couvre tous les tenants d'une seule déclaration. Une OAuth App GitHub n'accepte qu'une URL de rappel unique et Google n'accepte que des URI exactes : ces deux fournisseurs imposent une déclaration par domaine, ce qui les rend impraticables au-delà de quelques tenants.

Prévoyez enfin le DNS et les certificats TLS de chaque domaine — un joker (*.xolo.example.com) si les domaines partagent un suffixe — sur le reverse proxy placé devant Xolo, et passez XOLO_HTTP_SESSION_COOKIE_SECURE=true.

Taux de change et tâches de fond¶

Vérification¶

Le fichier .env.dist à la racine du dépôt liste l'ensemble des variables avec leurs commentaires. En cas de configuration invalide (secret manquant, fournisseur OIDC mal formé…), xolo-server refuse de démarrer et affiche l'erreur en clair sur la sortie standard.