Intégration Microsoft Entra ID

Architecture Platform utilise Keycloak comme broker OIDC entre votre annuaire Entra ID et l'application. Vous ne câblez jamais Entra à arch-platform directement — c'est Keycloak qui joue le rôle d'Identity Provider fédéré.

Le flow complet, du 1er login au rôle assigné :

1. L'user clique Sign in with Microsoft Entra ID sur /login.
2. Redirect vers login.microsoftonline.com — l'user authenticate (mot de passe + MFA si activé côté conditional access).
3. Entra renvoie un token OIDC signé à Keycloak. Le token contient email, given_name, family_name, et — si configuré — la liste des groups.
4. Keycloak crée un user JIT (Just-In-Time) dans son realm avec l'attribute tenant_id pré-rempli.
5. Les mappers KC assignent les rôles client arch-platform selon vos groupes Entra (ex : LD-ARB-Architects → architect).
6. Keycloak émet son propre JWT (avec les rôles) et redirige vers arch-platform.
7. Un cron de sync 5 min pousse ce user dans la table tenant_member_role — il apparaît alors dans /admin/team côté DSI.

Vous devez avoir :

• Un tenant Microsoft Entra ID (anciennement Azure AD). Un tenant gratuit obtenu via Azure Free Tier suffit pour tester.
• Un compte avec le rôle Application Administrator ou Global Administrator pour créer une app registration.
• Vos groupes AD déjà créés (ex : LD-ARB-Admins, LD-ARB-Architects, LD-ARB-Viewers). Si vous n'en avez pas encore, créez-les dans Entra ID → Groups → New Group avant de continuer.

Dans le portail Azure (portal.azure.com) → Entra ID → App registrations →New registration :

1. Name : ex arch-platform-prod-ld (peu importe, c'est interne).
2. Supported account types : « Accounts in this organizational directory only ».
3. Redirect URI : plateforme Web, URI exacte :
   https://auth.arch-platform.com/realms/arch-prod/broker/entra_id-<votre-slug>/endpoint
   Remplacez <votre-slug> par le slug de votre tenant (ex : lefebvre-dalloz). Le wizard côté arch-platform vous affiche cette URI exacte à copier-coller.

Une fois créée, notez ces 2 valeurs :

• Application (client) ID — visible en tête de la page Overview de l'app.
• Directory (tenant) ID — visible juste en dessous, format UUID.

Créer le client secret

Toujours dans l'app registration → Certificates & secrets → New client secret :

• Description : arch-platform-prod
• Expires : 24 mois (max recommandé pour prod)
• Copiez IMMÉDIATEMENT la valeur affichée — la colonne Value, pas Secret ID. La Value n'est visible qu'une seule fois : si vous quittez la page sans copier, il faudra en créer une nouvelle.

Loggez-vous en tant que tenant-admin sur votre tenant arch-platform, puis :

1. Menu latéral → Administration → SSO / Authentication (/admin/sso).
2. Clique Add SSO provider → sélectionne Microsoft Entra ID.
3. Step 2 : la page t'affiche les URIs à copier dans la console Entra (redirect URI + logout URI). Si tu n'as pas encore créé l'app registration Entra, fais-le maintenant (§3 ci-dessus).
4. Step 3 : colle le Directory (tenant) ID, le Application (client) ID, et le client secret Value. Le champ Email domains est optionnel — utilisé pour le tenant-routing quand un user tape son email sur /login (matche le domain → redirect direct vers Entra).
5. Step 4 : configure le mapping groupes (voir §6) et le rôle par défaut (fallback si un user Entra n'a aucun groupe qui matche).
6. Create provider → l'IdP est provisionné côté KC.
7. Active le provider via le toggle sur la card provider — sans ça, aucun bouton n'apparaît sur la page login KC.

Par défaut, Entra n'émet PAS la liste des groupes AD dans le token OIDC. Vous devez l'activer explicitement.

Dans votre app registration → Token configuration → Add groups claim :

• Sélectionne Security groups (ou All groups si tu utilises aussi des Distribution lists — plus lourd).
• Sous Customize token properties by type → ID token : choisis Group Name (pas Group ID). Attention — c'est crucial : arch-platform matche par nom de groupe côté mapping, pas par UUID.

Dans le wizard SSO arch-platform, Step 4, le champ Group Role Mapping (JSON) accepte un objet JSON qui mappe chaque nom de groupe Entra à un rôle ARB arch-platform :

{
  "LD-ARB-Admins":       "tenant-admin",
  "LD-ARB-Architects":   "architect",
  "LD-ARB-Reviewers":    "arb-member",
  "LD-Portfolio-Mgrs":   "portfolio-manager",
  "LD-App-Contributors": "contributor",
  "LD-ARB-Readers":      "viewer"
}

Les 6 rôles ARB disponibles :

• tenant-admin — gère /admin/team, /admin/sso, quotas, config globale
• architect — crée DAS, ADR, Notice, référentiel
• arb-member — architect + vote en session ARB
• portfolio-manager — lecture tout + valide sessions/notices + pipeline
• contributor — édite UNIQUEMENT les apps où il est Contact IT ou Contact Métier
• viewer — lecture seule

Une fois le SSO câblé et activé, les users Entra qui se loggent sont provisionnés automatiquement — sans invitation préalable. Deux mécanismes tournent en parallèle :

Just-In-Time provisioning (au 1er login)

Au tout premier login SSO d'un user Entra, Keycloak crée un user local dans son realm et lui assigne :

• L'attribute tenant_id = votre slug (ex lefebvre-dalloz) — utilisé partout côté backend pour l'isolation multi-tenant.
• Les rôles client selon le mapping groupes (§6). Si aucun groupe ne match, l'user reçoit le rôle par défaut configuré dans le wizard step 4 (viewer par défaut).

L'user est fonctionnel dans arch-platform immédiatement — il peut naviguer, créer (selon ses droits), etc.

Sync cron 5 min (vers /admin/team)

Toutes les 5 minutes, un scheduler backend liste les users KC du tenant et upsert dans la table tenant_member_role (source =ENTRA_GROUP). Après ce sync, les users apparaissent dans /admin/team — visibles par le tenant-admin qui peut alors ajuster leur rôle si besoin.

Une fois vos users Entra provisionnés, ils deviennent disponibles dans les champs autocomplete de l'application :

• DAS : Owner + Tech Lead (/das/new)
• ADR : Authors multi-select (/adr/<id>)
• Sessions ARB : invités attendees (/sessions/<id>)
• Topics : owners
• Notice : speaker, assignees des recommandations et action items
• Impact Action Plan : owner

Le composant PeoplePicker autocomplete par prénom, nom ou email — cherche dans les users KC du tenant courant. Cache 60s côté backend pour la réactivité.

Si un user tape un email libre qui ne matche aucun user KC (ex : un consultant externe qui n'a pas de compte arch-platform), c'est accepté quand même — le champ fallback text libre.

Dans /admin/team (tenant-admin only), chaque ligne de Membres actifs a un dropdown Rôle :

1. Sélectionne le nouveau rôle dans le dropdown → mutation immédiate côté backend.
2. Backend : révoque les anciens grants (soft-delete, audit trail préservé) + insert le nouveau grant en source=IN_APP + sync KC client roles.
3. L'user récupère son nouveau rôle au prochain refresh token (moins de 30 min).

Les erreurs les plus fréquentes :

AADSTS50011 : Redirect URI mismatch

L'URI configurée dans Entra ne matche pas exactement celle que KC envoie. Vérifier :

• Format exact : https://auth.arch-platform.com/realms/arch-prod/broker/entra_id-<slug>/endpoint
• Pas de trailing slash
• Slug du tenant en minuscules
• Plateforme Web (pas SPA, pas Mobile)

AADSTS7000215 : Invalid client secret

Vous avez copié le Secret ID au lieu de la Value. Retour dans Certificates & secrets → si vous ne pouvez plus voir la Value (masquée), créez un nouveau secret et récupérez la Value IMMÉDIATEMENT après création. Puis update le provider dans /admin/sso.

Bouton "Sign in with X" absent sur /login

Vérifier que le toggle Enabled est ON sur la card provider dans /admin/sso. Depuis v0.4.2.2 les providers sont créés enabled par défaut, mais les anciens nécessitent activation manuelle.

User Entra reste en viewer malgré son groupe

Deux causes possibles :

1. Groups claim pas émis — vérifier dans Entra → App registrations → Token configuration → Groups claim doit être présent avec "Group Name" sélectionné.
2. Nom de groupe mal orthographié dans le JSON mapping — la comparaison est case-sensitive. Copier-coller depuis Entra pour éviter les typos.

Debug : demander à l'user de se déconnecter puis reloguer. Si le rôle n'est toujours pas assigné, checker les logs KC (côté ops arch-platform) sur l'event IDENTITY_PROVIDER_FIRST_LOGIN — les mappers exécutés y sont tracés.