Introduction / Objectif

Ce guide explique comment utiliser des groupes Microsoft Entra ID pour gérer les droits dans Wikit en s’appuyant sur des App Roles.
Le principe :

1. Le client crée des App Roles dans l’application Entra ID “Wikit”.
2. Le client assigne des groupes à ces App Roles dans “Enterprise applications”.
3. Entra ID renvoie automatiquement les rôles dans le claim roles du jeton OpenID Connect.
4. Wikit/IAM mappe ce claim vers les rôles/groupes Wikit.

Cette méthode est adaptée au SaaS multi-tenant car les App Roles sont portables et spécifiques à l’application.

Prérequis

• Droits administrateur Entra ID permettant de gérer les applications (ex. Cloud Application Administrator).
• Application Wikit déjà créée dans Entra ID (voir guide SSO OIDC Wikit/Entra).
• URL de redirection fournie par Wikit, sous la forme :
  https://auth.wikit.ai/realms/{realm}/broker/{slug-organisation}/endpoint
• Un ou plusieurs groupes Entra ID existants, contenant les utilisateurs à autoriser.
• Licence Entra ID P1/P2 requise si vous assignez des groupes à une application.

Étapes côté client (Microsoft Entra ID)

Les étapes 1 à 6 ci-dessous complètent votre procédure SSO existante.
Si l’application Wikit n’est pas encore créée, suivez d’abord le guide “Configuration OpenID Connect avec Microsoft Entra ID”.

Étape 1 : Accéder au Portail Azure

1. Connectez-vous au portail Azure.
2. Naviguez jusqu’à Inscriptions d’applications (App registrations).

Étape 2 : Ouvrir l’application Wikit

1. Dans Inscriptions d’applications, sélectionnez l’application Wikit que vous avez créée (ex. Wikit - {slug-organisation}).

Étape 3 : Créer les App Roles

1. Dans le menu de l’application, cliquez sur App roles.

2. Cliquez sur Create app role.

3. Renseignez les champs :

   • Display name : nom lisible du rôle (ex. Admin Wikit).
   • Allowed member types : Users/Groups (obligatoire pour assigner des groupes).
   • Value : valeur technique envoyée dans le token (ex. wikit_admin, wikit_editor, wikit_viewer).
   • Description : courte description (ex. “Accès administrateur Wikit”).
   • Do you want to enable this app role? : Yes.

4. Cliquez sur Apply.

5. Répétez pour chaque rôle nécessaire.

Hypothèse raisonnable : les valeurs Value seront utilisées telles quelles côté Wikit.
Si vous souhaitez une autre nomenclature, transmettre une table de correspondance à Wikit (voir section dédiée).

Étape 4 : Assigner des groupes aux App Roles

1. Dans Azure, allez dans Applications d’entreprise (Enterprise applications).
2. Sélectionnez l’application Wikit correspondante.
3. Menu Users and groups.
4. Cliquez sur Add user/group.
5. Dans Users and groups, sélectionnez le groupe à associer.
6. Dans Select a role, choisissez l’App Role créé à l’étape 3.
7. Cliquez sur Assign.

Répétez pour chaque couple groupe ↔ App Role.

Étape 5 : Vérifier que roles est bien émis

Dès qu’un App Role est assigné à un utilisateur (directement ou via groupe), Entra ID ajoute automatiquement un claim roles dans le token OIDC.

Vous pouvez le vérifier en effectuant une connexion test et en inspectant l’ID token (outil type jwt.ms).

Test de connexion

1. Ajoutez un utilisateur test dans un groupe assigné à un App Role.
2. Connectez-vous à Wikit via Entra ID.
3. Vérifiez que :
   • l’utilisateur accède bien à Wikit,
   • les droits correspondent au rôle attendu.

Si besoin, Wikit pourra valider la présence du claim roles dans IAM après connexion.

Dépannage / erreurs courantes

Le claim roles est absent du token

• Aucun App Role n’est assigné à l’utilisateur / groupe.
  → Vérifiez Enterprise applications > Users and groups. oai_citation:7‡Microsoft Learn
• L’App Role a été créé avec Allowed member types = Applications uniquement.
  → Recréez le rôle avec Users/Groups.

Les droits Wikit ne correspondent pas

• Mauvaise valeur Value communiquée ou mappée.
  → Vérifiez la valeur technique exacte de l’App Role.
• Un utilisateur appartient à plusieurs groupes assignés à des App Roles différents.
  → Le token contient plusieurs valeurs dans roles. Wikit appliquera l’ensemble ou une priorité selon votre configuration.

Les changements de groupe ne sont pas pris en compte

• Les rôles sont recalculés à chaque authentification.
  → Demander à l’utilisateur de se déconnecter / reconnecter.

Points d’attention

• Stabilité des valeurs : privilégiez des Value génériques et durables (ex. wikit_admin) plutôt que des noms liés à une organisation.
• Moins de rôles = mieux : une hiérarchie simple limite les combinaisons ambigües.
• Gestion des accès : l’assignation de groupes à l’application Wikit contrôle aussi la visibilité dans “Mes applications”.
• Ne pas utiliser acceptMappedClaims ou des politiques de transformation avancées pour une app multi-tenant, sauf besoin explicite.