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.

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.

Stockage¶

Choisir entre SQLite et PostgreSQL¶

SQLite reste le défaut : aucune dépendance externe, idéal pour une instance unique. 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, et un hôte ne correspondant à aucun tenant répond 404 : un sous-domaine inconnu ne doit pas révéler que l'instance existe.

Les tenants se créent exclusivement par l'API de provisioning ; POST /v1/tenants 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 tenant dérive la sienne : son schéma et son chemin sont conservés, son hôte est remplacé par celui de la requête. Liens, redirections et URL de rappel OAuth restent ainsi sur l'hôte 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 tenant :

https://{tenant}.xolo.example.com/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 sous-domaine, ce qui les rend impraticables au-delà de quelques tenants.

Prévoyez enfin un DNS et un certificat TLS joker (*.xolo.example.com) 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.