ADR - authentik OIDC/MFA pour Nexus

Decision

Nexus adopte authentik comme fournisseur d'identite central pour les utilisateurs humains et les applications externes.

La decision d'architecture est la suivante :

authentik authentifie les utilisateurs, gere l'enrolement MFA et emet les tokens OIDC/OAuth2;
Nexus ne gere plus l'enrolement MFA et ne doit plus gerer les mots de passe utilisateur en flux normal;
Nexus conserve l'autorisation metier : roles Nexus, isolation tenant, source_app, workspace, project, corpus, traces, exports et actions sensibles;
les flux humains utilisent OIDC Authorization Code + PKCE;
les flux machine-to-machine utilisent OAuth2 Client Credentials, sans MFA interactive;
les webhooks entrants utilisent HMAC signe, pas OIDC interactif.

Contexte Nexus actuel

Le code Nexus contient aujourd'hui une authentification locale dans api/admin/auth.py :

login password;
sessions user_sessions;
JWT local HMAC via JWT_SECRET;
cookie AUTH_COOKIE_NAME;
compatibilite RETURN_JWT_IN_BODY;
OAuth Google optionnel.

La gestion admin utilisateurs existe dans api/admin/users.py, avec creation/mise a jour utilisateur et reset mot de passe.

Ces mecanismes ne sont pas supprimes dans ce lot. Ils doivent etre migres par les lots suivants avec tests cibles.

Architecture cible

Navigateur utilisateur
  -> Nexus UI
  -> /auth/login
  -> authentik Authorization Code + PKCE
  -> /auth/callback server-side
  -> session Nexus httpOnly secure
  -> API Nexus avec session/principal valide

Pour les integrations machine :

Connecteur / n8n / worker
  -> authentik token endpoint client_credentials
  -> access_token machine
  -> API Nexus
  -> validation JWT + scopes + tenant + client_id

Pour les webhooks :

Systeme externe
  -> X-Nexus-Timestamp + X-Nexus-Key-Id + X-Nexus-Signature
  -> API Nexus
  -> verification HMAC sur timestamp + "." + raw_body

Nexus cree ensuite une session locale via cookie httpOnly, secure en production, SameSite=lax par defaut. Les access tokens et refresh tokens OIDC ne doivent pas etre stockes durablement dans localStorage, sessionStorage ou un etat JavaScript.

RETURN_JWT_IN_BODY=false reste la posture de production. Toute compatibilite bearer navigateur doit etre traitee comme legacy et bornee.

OIDC et signature

Le provider authentik Nexus doit utiliser une cle de signature asymetrique. Nexus valide les tokens via le jwks_uri du discovery document.

Nexus refuse les tokens OIDC signes symetriquement avec le secret client, notamment HS256, meme si l'ancien JWT local Nexus utilise encore HMAC pendant la migration.

Les verifications minimales cote FastAPI sont :

iss strictement egal a l'issuer attendu;
aud contenant l'audience Nexus API;
signature et algorithme autorise;
exp, nbf si present, iat raisonnable;
scope ou scp;
tenant_id ou mapping Nexus verifie;
groups ou claims equivalents;
client_id pour les machines.

Issuer authentik

Le mode recommande est l'issuer par provider authentik, du type :

https://auth.example.com/application/o/nexus/

L'URL OIDC_ISSUER_URL doit correspondre exactement a l'issuer du document discovery. Nexus ne doit pas accepter un issuer global ou approximatif si le provider authentik utilise un issuer par application.

Migration auth locale

La migration se fait en trois etapes :

OIDC devient le chemin nominal pour les humains.
Le login password local est masque cote UI et borne cote API selon une decision explicite.
Les mots de passe utilisateurs Nexus ne sont plus crees ni resettes en flux normal.

Un compte break-glass local peut etre conserve pour exploitation d'urgence self-hosted, mais il doit respecter ces contraintes :

desactive ou inaccessible en parcours UI normal;
active seulement par configuration serveur explicite;
reserve a un admin d'exploitation;
secret stocke hors depot;
evenement d'audit obligatoire;
rotation imposee apres usage.

Google OAuth existant

Google OAuth direct devient un chemin legacy. Il ne doit pas etre enrichi ni etendu pendant la migration authentik.

Options retenues :

court terme : conserver sans modification pour ne pas casser les installations existantes;
moyen terme : migrer Google comme source ou federation cote authentik;
suppression eventuelle seulement apres adoption OIDC authentik et tests de rollback.

API keys admin et tokens service MCP

Les admin_api_keys et tokens service MCP existants ne sont pas remplaces dans NX-AUTH-001.

Regle cible :

les integrations applicatives nouvelles doivent aller vers OAuth2 Client Credentials;
les tokens service MCP existants restent intacts tant qu'un lot dedie ne les migre pas;
les API keys admin restent reservees au bootstrap/admin automation, pas aux integrations metier ordinaires.

Machine-to-machine

Les flux M2M ne doivent jamais demander de MFA interactive.

Pour NX-AUTH-006, la preference Nexus est :

comptes service nommes ou app passwords authentik pour les integrations qui exigent une forte tracabilite;
provider/client dedie par integration ou famille d'integration;
scopes minimaux;
rotation documentee;
audit par client_id, subject/service account et tenant.

L'usage d'un service account automatique authentik via client_secret peut etre accepte pour un POC, mais doit etre documente comme moins explicite pour la gouvernance si le nommage/service account n'est pas suffisamment controlable.

Webhooks

Les webhooks entrants ne doivent pas passer par OIDC interactif.

Le schema cible est :

X-Nexus-Key-Id: <tenant_or_source_key_id>
X-Nexus-Timestamp: <unix_seconds>
X-Nexus-Signature: sha256=<hex_hmac>

La signature porte sur :

timestamp + "." + raw_body

Nexus doit verifier :

tolerance anti-replay;
secret par tenant/source;
comparaison constant-time;
audit systematique;
absence de secret dans les logs.

MFA et step-up

Nexus ne recree pas d'UI d'enrolement TOTP/WebAuthn/e-mail OTP.

Les utilisateurs gerent leurs methodes d'authentification dans authentik.

Pour les actions sensibles, Nexus pourra exiger une authentification recente si authentik fournit des claims fiables :

auth_time;
amr ou acr;
information permettant de distinguer MFA forte et fallback e-mail.

Si ces claims ne sont pas disponibles, le lot step-up doit bloquer plutot que simuler une garantie MFA.

Politique MFA cible

Profil	Exigence cible
Admin Aurora / Nexus / tenant owner	WebAuthn/passkey recommande ou obligatoire selon contexte, TOTP ou recovery codes en secours; e-mail OTP interdit comme seul second facteur
Admin client	MFA obligatoire; WebAuthn/passkey recommande, TOTP autorise
Utilisateur salarie/client standard	TOTP par defaut; WebAuthn/passkey optionnel; aucune biometrie imposee par l'employeur
Invite / faible privilege	TOTP ou e-mail OTP fallback selon politique tenant
Machine-to-machine	Pas de MFA interactive; Client Credentials + scopes minimaux

L'e-mail OTP est accepte uniquement comme fallback ou pour profils a faible privilege. Il ne constitue pas une MFA forte suffisante pour un administrateur.

Pour WebAuthn/passkey, Nexus et authentik ne doivent pas stocker d'empreinte digitale ou de visage. La verification biometrique eventuelle reste locale a l'appareil ou au gestionnaire de passkeys de l'utilisateur; une methode alternative comme TOTP doit rester disponible pour les clients/salaries.

References officielles

authentik OAuth2/OIDC Provider : https://docs.goauthentik.io/add-secure-apps/providers/oauth2/
authentik M2M Client Credentials : https://docs.goauthentik.io/add-secure-apps/providers/oauth2/machine_to_machine/
authentik Email Authenticator : https://docs.goauthentik.io/add-secure-apps/flows-stages/stages/authenticator_email/
OpenID Connect Discovery : https://openid.net/specs/openid-connect-discovery-1_0.html
OAuth2 PKCE RFC 7636 : https://datatracker.ietf.org/doc/html/rfc7636
OWASP MFA Cheat Sheet : https://cheatsheetseries.owasp.org/cheatsheets/Multifactor_Authentication_Cheat_Sheet.html

Lots d'implementation

L'ADR debloque les lots suivants :

NX-AUTH-002 : OIDC humain server-side et session Nexus;
NX-AUTH-003 : validation JWT/JWKS et principal unifie;
NX-AUTH-004 : RBAC tenant Nexus;
NX-AUTH-005 : migration auth locale/users/admin;
NX-AUTH-006 : M2M Client Credentials;
NX-AUTH-007 : webhooks HMAC;
NX-AUTH-008 : step-up MFA.

Consequences

Positives

Nexus cesse de porter la complexite MFA.
Les politiques MFA sont centralisees dans authentik.
Le backend garde une autorisation metier explicite et testable.
Les flux humains, machines et webhooks sont separes.

Cout / vigilance

Les claims authentik doivent etre configures et testes avant l'implementation step-up.
La migration de l'auth locale doit rester progressive pour eviter de verrouiller l'exploitation.
Les tokens existants MCP/API keys ne doivent pas etre casses hors lot dedie.
Les tests doivent utiliser JWKS/tokens fake pour ne pas rendre la suite dependante d'un authentik reel.