Raccourcis clavier

Appuyez sur ← ou → pour passer d'un chapitre à l'autre

Appuyez sur S ou / pour rechercher dans la documentation

Appuyez sur ? pour afficher cette aide

Appuyez sur Échap pour masquer cette aide

SSO Authentik

Authentik (licence permissive, auto-hébergé) est le fournisseur d'identité de l'opérateur. L'application s'y connecte en OpenID Connect avec le flux à code d'autorisation et PKCE. Un mot de passe avec second facteur reste le repli quand le SSO n'est pas configuré.

Ce qui est en place

ÉlémentDétail
FournisseurAuthentik, service du plan de la plateforme
ProtocoleOIDC, flux à code d'autorisation, PKCE, state et nonce
État de session de connexionstocké dans Valkey, 10 minutes
Jeton de session applicatifémis par l'application après la connexion, en cookie
Replisi la configuration SSO est absente, la route répond 503 SSO_UNAVAILABLE et l'interface retombe sur mot de passe plus second facteur
IdP national luxembourgeoisun second fournisseur est prévu sur le même callback, comme point d'entrée pour l'espace européen de données de santé. C'est un échafaudage, qui exige une configuration et un client enregistré

Parcours de connexion

  1. GET /api/v1/auth/oidc/login : l'application génère state, vérifieur PKCE et nonce, les place dans Valkey, puis redirige vers Authentik.
  2. L'utilisateur s'authentifie chez Authentik.
  3. GET /api/v1/auth/oidc/callback : l'application relit l'état, échange le code, et refuse la connexion dans les cas suivants :
    • état expiré ou inconnu ;
    • nonce du jeton d'identité absent ou différent (protection contre le rejeu) ;
    • adresse courriel non vérifiée par le fournisseur (email_verified), sauf option explicite de l'opérateur (OIDC_ALLOW_UNVERIFIED_EMAIL=1) ;
    • adresse déjà utilisée par un compte local créé avec un mot de passe. Un compte fédéré ne s'attache jamais en silence à un compte local : c'est la parade contre la prise de compte par SSO.
  4. Sinon, l'application trouve ou crée l'utilisateur local, émet son jeton et redirige vers le tableau de bord.

Chaque échec est écrit au journal d'audit, avec un code d'erreur.

Diagramme de séquence entre le navigateur, Authentik, l'application et Valkey : demande de connexion, redirection, authentification, retour avec le code, quatre cas de refus, puis jeton de session et tableau de bord.

Figure 8 : le parcours de connexion SSO par OpenID Connect, avec ses quatre cas de refus.

Configuration de l'application

Le SSO est actif quand ces variables d'environnement sont définies :

  • AUTHENTIK_SERVER_URL
  • AUTHENTIK_CLIENT_ID
  • AUTHENTIK_CLIENT_SECRET
  • AUTHENTIK_REDIRECT_URI (le défaut est une adresse de développement : posez-la en production)

Avant de poser ces variables, créez dans Authentik un fournisseur OAuth2/OIDC et l'application qui l'utilise : l'identifiant et le secret du client alimentent AUTHENTIK_CLIENT_ID et AUTHENTIK_CLIENT_SECRET, AUTHENTIK_SERVER_URL est l'adresse du serveur Authentik, et l'URL de retour enregistrée chez Authentik doit être exactement la valeur de AUTHENTIK_REDIRECT_URI, qui se termine par la route de retour /api/v1/auth/oidc/callback. Le serveur demande les portées openid, profile et email : le fournisseur doit les accorder. Les écrans d'Authentik dépendent de sa version et ne sont pas décrits ici.

Résultat attendu : GET /api/v1/auth/oidc/login répond par une redirection vers Authentik. Une réponse 503 SSO_UNAVAILABLE signifie que AUTHENTIK_SERVER_URL, AUTHENTIK_CLIENT_ID ou AUTHENTIK_CLIENT_SECRET manque ; l'interface retombe alors sur le mot de passe et le second facteur.

Les valeurs de secrets ne se placent pas dans le dépôt. Elles suivent la chaîne décrite dans le chapitre OpenBao et secrets.

Second facteur

Par défaut, FORCE_2FA vaut true : la connexion par mot de passe exige un second facteur, code TOTP si le compte l'a enrôlé, sinon code envoyé par courriel. L'obligation d'enrôler le TOTP est, elle, un réglage de déploiement :

  • FORGE_MFA_REQUIRED_ROLES exige l'enrôlement TOTP pour les rôles listés (par exemple admin,owner) ;
  • FORGE_MFA_TOTP_REQUIRED l'exige pour tous les comptes.

Un compte soumis à l'obligation et sans TOTP actif se voit refuser la connexion jusqu'à son enrôlement. Les mécanismes disponibles sont TOTP, WebAuthn et des codes de secours. Si l'opérateur n'a posé aucun des deux réglages, rien n'oblige un rôle particulier au TOTP, et le code par courriel reste exigé tant que FORCE_2FA n'est pas désactivée. Un compte créé par le parcours SSO ci-dessus n'a pas de second facteur applicatif (commentaire du code : « Authentik handles MFA upstream ») : l'authentification multifacteur de ces comptes relève de la configuration d'Authentik.

Autres services du plan client

Plusieurs outils du plan client (par exemple Grafana, Forgejo, Mattermost) peuvent être reliés à Authentik. Chaque outil se configure selon ses propres capacités :

  • OIDC natif quand l'outil le supporte : application et fournisseur OAuth2/OIDC dans Authentik, URI de redirection côté outil.
  • Proxy d'authentification quand il ne le supporte pas : Authentik fournit un point d'entrée de type outpost. Une unité Quadlet authentik-proxy existe dans le dépôt.

Le dépôt ne recense pas, service par service, lequel est relié à Authentik en production. Cette liste relève de l'opérateur du plan.

Points d'attention

  • Le SSO de l'application ne dépend pas du proxy frontal : la redirection OIDC est gérée par le serveur API lui-même. La configuration du proxy d'entrée (Caddy et Traefik ont chacun des fichiers dans le dépôt) ne change pas ce parcours.
  • Si l'IdP n'émet pas email_verified, ne pas contourner la vérification sans en mesurer le risque.
  • Le jeton de session est classique par défaut. Une signature post-quantique ML-DSA-65 s'y ajoute quand FORGE_PQC_ENABLED=1.

Voir aussi