Organisations et délégation d'administration

Dès qu’une plateforme IAM sert des partenaires, deux questions arrivent vite. Comment rattacher chaque compte à son entreprise, avec la bonne méthode de connexion ? Et qui administre ces comptes : l’équipe centrale seule, ou aussi un correspondant chez chaque partenaire ? Keycloak 26 apporte deux réponses natives : la fonction Organizations et les fine-grained admin permissions v2 (permissions d’administration fines). Ce cours montre ce qu’elles font, comment elles se combinent et ce qui reste à construire.

Organizations : le B2B dans un seul realm

Une organisation représente un tiers : un partenaire, un client, une filiale. Ses membres restent des utilisateurs du realm, mais ils sont reliés à l’organisation. Le realm garde le SSO, les clients et les politiques de sécurité communs, et chaque organisation apporte son contexte.

La fonction s’active realm par realm (Realm settings, interrupteur Organizations). Une organisation porte :

• un nom et un alias (l’alias est figé après création et sert dans les scopes) ;
• des domaines : acme.fr, ou .acme.fr pour inclure les sous-domaines. Un domaine n’appartient qu’à une organisation par realm ;
• des membres, des attributs, des groupes d’organisation (26.6 et suivantes) ;
• des fournisseurs d’identité liés, pour l’identity brokering (délégation de l’authentification à un IdP externe) propre à l’organisation.

Membres gérés et non gérés

Un membre non géré (unmanaged) est un utilisateur du realm ajouté à l’organisation : si l’organisation disparaît, le compte reste. Un membre géré (managed) est né de l’IdP de l’organisation : supprimer l’organisation ou le membre supprime le compte. Le choix se fait au moment de lier l’IdP. Il traduit une décision d’architecture : qui est la source de vérité de l’identité du partenaire ?

Connexion « identity-first » et routage par domaine

Dès qu’une organisation existe dans le realm, le flux navigateur demande d’abord l’identifiant ou l’e-mail, puis décide de la suite. Si le domaine de l’e-mail correspond à une organisation dont le domaine est routé vers un IdP avec redirection automatique, l’utilisateur part directement chez son IdP. Sinon, il saisit ses identifiants locaux.

En 26.8, ce routage se règle sur le domaine (IdP cible et Auto redirect). Dans les versions précédentes, il se réglait sur le lien entre l’IdP et l’organisation (option de redirection quand le domaine de l’e-mail correspond). Le principe reste le même. À savoir : un utilisateur qui possède déjà un mot de passe local n’est pas redirigé automatiquement, il est invité à s’authentifier avec ses identifiants.

Ce que voient les applications

Le client demande le scope organization, client scope optionnel créé par défaut. Le jeton contient alors un claim organization qui désigne les organisations de l’utilisateur par leur alias. Si vous activez les options d’identifiant et d’attributs du mapper Organization Membership, il prend cette forme :

"organization": {
  "acme": {
    "id": "42c3e46f-2477-44d7-a85b-d3b43f6b31fa",
    "secteur": ["aeronautique"]
  }
}

Sans ces options, l’identifiant et les attributs n’apparaissent pas : vérifiez la forme exacte du claim dans l’onglet Evaluate de votre version. Les variantes organization:acme (une organisation précise) et organization:* (toutes) servent aux utilisateurs membres de plusieurs organisations. Sans précision, l’utilisateur multi-organisation choisit au moment de la connexion.

Fine-grained admin permissions v2

Les rôles du client realm-management (manage-users, view-users, manage-clients…) donnent un droit sur tout le realm. Les permissions fines restreignent un administrateur délégué à un sous-ensemble : certains utilisateurs, certains groupes, certains clients.

La version 2, supportée depuis 26.2, remplace la v1, désormais dépréciée. Elle s’active par realm (Realm settings, Admin Permissions). Un menu Permissions apparaît, avec trois onglets : permissions, policies (conditions) et évaluation.

Une permission associe un type de ressource, des scopes (opérations), un périmètre (toutes les ressources ou certaines) et des policies qui désignent les administrateurs concernés (par utilisateur, groupe, rôle, ou agrégation).

Type de ressource	Scopes principaux
Users	view, manage, manage-group-membership, map-roles, impersonate, reset-password
Groups	view, manage, view-members, manage-members, manage-membership, impersonate-members
Clients	view, manage, map-roles, map-roles-composite, map-roles-client-scope
Roles	map-role, map-role-composite, map-role-client-scope
Organizations (26.7 et suivantes)	view, manage

Quatre règles à retenir pour concevoir un modèle :

1. Les scopes sont indépendants. manage sans view rend l’utilisateur invisible. Il faut accorder chaque opération explicitement.
2. Le spécifique l’emporte sur le général. Une permission sur un groupe précis prime sur une permission « tous les groupes ». Un seul DENY suffit à refuser.
3. Les rôles d’administration court-circuitent tout. Un délégué qui a manage-users n’est plus filtré. L’administrateur délégué reçoit seulement les rôles query-* qui ouvrent les menus de la console, et les permissions font le reste.
4. Les membres se protègent par les scopes de membres. view-members et manage-members se propagent aux sous-groupes ; un refus sur un parent s’applique à toute la descendance.

Le modèle se pense en groupes : une permission par groupe de partenaires, une policy par groupe de correspondants. La documentation insiste sur ce point pour les performances, car le filtrage des listes se fait en base de données.

Organisation ou groupe : comment choisir

Besoin	Groupe du realm	Organisation
Porter des rôles hérités	Oui	Oui, via les groupes d’organisation (26.6 et suivantes)
Router la connexion selon le domaine de l’e-mail	Non	Oui
IdP propre au partenaire, adhésion automatique	Non natif	Oui
Invitations par e-mail	Non	Oui
Claim dédié dans le jeton	Mapper de groupe	Scope organization
Délégation fine de l’administration	Oui (26.2 et suivantes)	Oui (26.7 et suivantes)
Comptes LDAP non importés	Oui	Non

En pratique, les deux se combinent : l’organisation porte l’identité du partenaire et sa méthode de connexion, et un groupe (du realm ou de l’organisation) porte les droits et sert de périmètre de délégation.

Ce qui reste à construire

Keycloak fournit les briques de droits, pas un processus de délégation complet. Pour une délégation qui tienne devant des correspondants métier, il manque en général :

• Des écrans dédiés. La console d’administration filtrée reste une console technique. Un correspondant partenaire attend un écran simple : ses salariés, un bouton « inviter », un bouton « désactiver ». Cet écran est une application cliente de l’Admin REST API.
• Des règles d’affectation. Qui attribue quel rôle, selon quel critère, avec quelle validation ? Les permissions disent qui peut agir, pas qui doit valider. Les Workflows, supportés depuis 26.6, automatisent certaines tâches de cycle de vie ; leur couverture est à évaluer face au besoin.
• La traçabilité. Les événements d’administration enregistrent qui a fait quoi, mais leur exploitation (alerte, revue périodique) relève du SOC ou d’un outil de gouvernance.

Une organisation partenaire et un correspondant délégué

30 min

Installer le lab

1. Dans la console (http://localhost:8080/admin, admin/admin), créez un realm approfondir. Dans Realm settings, onglet General, activez Organizations et Admin Permissions, puis enregistrez.
2. Dans Organizations, créez l’organisation Acme (alias acme) avec le domaine acme.test.
3. Créez l’utilisateur alice avec l’e-mail alice@acme.test, marqué comme vérifié, et un mot de passe non temporaire. Ajoutez-la comme membre de acme (Add member, Add realm user).
4. Créez un client OIDC portail (Client authentication désactivé, flux standard). Dans son onglet Client scopes, sous-onglet Evaluate, choisissez alice, ajoutez le scope optionnel organization et générez l’access token : vérifiez le claim organization.
5. Ouvrez http://localhost:8080/realms/approfondir/account dans une fenêtre privée : la page demande d’abord l’identifiant seul. C’est la connexion identity-first.
6. Créez un groupe partenaires-acme, ajoutez-y alice. Créez un utilisateur bob (sans groupe) et un utilisateur corresp-acme avec un mot de passe. Assignez à corresp-acme le rôle client realm-management query-users, et lui seul.
7. Dans Permissions, créez une permission de type Groups, scopes view-members et manage-members, sur le groupe partenaires-acme, avec une nouvelle policy de type User qui désigne corresp-acme.
8. Dans l’onglet Evaluation, évaluez l’accès de corresp-acme au type Users pour alice, puis pour bob. Le premier est accordé, le second refusé.
9. Connectez-vous en fenêtre privée sur http://localhost:8080/admin/approfondir/console/ avec corresp-acme. Vérifiez qu’il voit alice et pas bob.

À retenir pour l’architecture

Le découpage « un realm par partenaire » est rarement la bonne réponse depuis Keycloak 26 : les organisations offrent l’isolement utile sans perdre le SSO. La délégation native est réelle mais technique. Inscrivez dans le document d’architecture la version mineure minimale requise, le modèle de groupes qui sert de périmètre de délégation, et la liste des écrans à construire si des correspondants métier doivent administrer eux-mêmes.