Keycloak – exemple d’une fédération d’identités avec 3 annuaires dont 1 annuaire AD

Introduction

La fédération d’identités permet de rassembler plusieurs sources d’identités en une seule, permettant ainsi aux utilisateurs de s’authentifier et d’accéder à divers services à partir d’un point central. Keycloak est un serveur d’identité et d’accès de source ouverte qui offre des fonctionnalités telles que la gestion des identités, l’authentification unique (SSO), et bien plus encore.

Dans cet article, nous allons aborder comment configurer une fédération d’identités avec Keycloak en intégrant deux annuaires Oracle Directory Server et un annuaire Active Directory (AD). Nous utiliserons le champ « mail » comme identifiant unique pour l’authentification.

Prérequis

• Installation de Keycloak
• Deux instances d’Oracle Directory Server
• Une instance d’Active Directory
• Connaissance de base en LDAP et SAML

Étape 1 : Configuration initiale de Keycloak

1. Lancez Keycloak et connectez-vous à la console d’administration.
2. Créez un nouveau Realm ou utilisez le realm master.

Étape 2 : Configurer les annuaires dans « User Federation »

Configuration du premier Oracle Directory Server

1. Allez dans User Federation dans le menu de navigation à gauche.
2. Cliquez sur Add provider et choisissez LDAP.
3. Remplissez les détails de votre premier Oracle Directory Server.
   • Vendor: Other
   • Connection URL: ldap://odserver1.example.com
   • Port: 389 ou 636 pour LDAPS
   • Users DN: dc=example,dc=com
   • User Object Classes: inetOrgPerson, organizationalPerson

Modifier les mappers pour le premier Oracle Directory Server

1. Après avoir sauvegardé la configuration, cliquez sur Mappers.
2. Trouvez le mapper username et cliquez dessus pour le modifier.
3. Changez le LDAP attribute à mail et assurez-vous que le User Model Attribute est également mis à username.

Configuration du deuxième Oracle Directory Server

Répétez les étapes ci-dessus pour le deuxième Oracle Directory Server, en vous assurant de modifier le Hostname et les autres détails uniques à cette instance.

Configuration de l’Active Directory

1. Allez dans User Federation et cliquez sur Add provider, puis choisissez LDAP.
2. Remplissez les détails pour l’annuaire Active Directory.
   • Vendor: Active Directory
   • Connection URL: ldap://ad.example.com
   • Port: 389 ou 636 pour LDAPS
   • Bind type : simple
   • Bind DN: DOMAINE\keycloak.bind
   • Bind credentials : password
   • Users DN : DC=company,DC=com

Modifier les mappers pour l’Active Directory

1. Cliquez sur Mappers.
2. Trouvez le mapper, généralement appelé username ou sAMAccountName, et modifiez-le.
3. Changez le LDAP attribute à mail et assurez-vous que le User Model Attribute est mis à username.

Mappers – ajout de nouveaux attributs

L’ajout de nouveaux attributs dans les mappers est une étape essentielle pour personnaliser la manière dont les attributs des utilisateurs sont mappés entre l’annuaire LDAP/Active Directory et Keycloak.

Ajout de nouveaux attributs dans les Mappers pour Oracle Directory Server et Active Directory

Étape 1 : Accédez à « User Federation »

1. Connectez-vous à la console d’administration de Keycloak.
2. Sélectionnez votre Realm et allez dans User Federation.

Étape 2 : Sélectionnez le fournisseur LDAP

1. Dans la liste des fournisseurs, cliquez sur le fournisseur LDAP que vous avez précédemment configuré (Oracle Directory Server ou Active Directory).

Étape 3 : Accédez à « Mappers »

1. Après avoir sélectionné le fournisseur, allez dans l’onglet Mappers.

Étape 4 : Ajoutez un nouveau Mapper

1. Cliquez sur Create pour ajouter un nouveau mapper.
2. Remplissez les détails nécessaires :
   • Name: Nom unique pour identifier le mapper.
   • Mapper Type: Sélectionnez le type de mapper. Pour des attributs simples, vous pouvez choisir user-attribute-ldap-mapper.
   • LDAP Attribute: Nom de l’attribut dans l’annuaire LDAP/Active Directory.
   • User Model Attribute: Nom de l’attribut dans le modèle d’utilisateur de Keycloak.
   • Read Only: Cochez cette case si l’attribut ne doit pas être modifiable.

Étape 5 : Sauvegardez les changements

1. Cliquez sur Save pour enregistrer le nouveau mapper.

Étape 6 : (Optionnel) Synchronisez les utilisateurs

Si vous avez déjà des utilisateurs synchronisés, effectuez une nouvelle synchronisation pour appliquer les changements.

Étape 7 : Vérifiez l’ajout de l’attribut

1. Accédez à Users dans la console d’administration.
2. Sélectionnez un utilisateur et vérifiez si le nouvel attribut est correctement mappé.

Exemple pour l’attribut UID

Dans mon cas, j’ai eu à ajouter l’attribut uid pour les différents annuaires afin que cela remonte dans les métadonnées.

Cette configuration vous permet de remonter les éléments souhaités au niveau de la fiche utilisateur avec le username qui corresponde bien à l’adresse email ce qui garantit une unicité entre vos différents référentiels, l’adresse email étant censé être unique.

Ajout d’un Client Scope pour utiliser l’UID

Un aspect souvent négligé mais essentiel de cette configuration est l’utilisation de « Client Scopes ». Dans Keycloak, un « Client Scope » est une manière de définir des paramètres communs qui peuvent être partagés entre différents clients (applications). Il s’agit notamment de la manière dont les tokens OIDC (OpenID Connect) ou SAML sont générés, quels rôles ou attributs d’utilisateurs sont inclus dans ces tokens, etc. Nous alons donc ajouter un « Client Scope » qui utilise l’attribut uid pour personnaliser la génération du token pour une application spécifique.

Étape 1 : Accédez à « Client Scopes »

1. Dans la console d’administration de Keycloak, allez dans Client Scopes.

Étape 2 : Créez un nouveau Client Scope

1. Cliquez sur Create.
2. Donnez un nom au Client Scope, par exemple use-uid.
3. Cliquez sur Save.

Étape 3 : Configurez le Mapper

1. Après avoir créé le Client Scope, allez dans Mappers.
2. Cliquez sur Create.
3. Remplissez les champs comme suit :
   • Name: UID Mapper
   • Mapper Type: User Attribute
   • User Attribute: uid
   • Token Claim Name: uid
   • Claim JSON Type: String
4. Cliquez sur Save.

Étape 4 : Associez le Client Scope à un client

1. Allez dans Clients.
2. Sélectionnez le client qui doit utiliser ce Client Scope.
3. Allez dans l’onglet Client Scopes.
4. Dans Available Client Scopes, trouvez UID Mapper et ajoutez-le à Assigned Client Scopes.

Utilité

L’ajout d’un « Client Scope » spécifique devient indispensable si le plugin d’authentification OpenID de votre application s’attend à trouver un attribut uid pour identifier de manière unique chaque utilisateur. Sans cet attribut, le plugin ne serait pas en mesure de correspondre au modèle d’utilisateur attendu, ce qui pourrait entraîner des échecs d’authentification ou des comportements imprévus.

L’utilisation d’un « Client Scope » spécifique dans Keycloak va affecter les métadonnées SAML ou OpenID Connect générées pour l’application cliente. Ces métadonnées sont utilisées pour configurer l’intégration entre l’application cliente et Keycloak. Lorsque vous ajoutez un « Client Scope » qui inclut un attribut spécifique comme l’uid, cet attribut sera inclus dans les tokens générés pour l’application et, par conséquent, dans les métadonnées.

Impact sur les métadonnées

OpenID Connect

Si vous utilisez OpenID Connect, le nouvel attribut uid sera ajouté au token ID généré pour l’application. Les métadonnées OpenID Connect vont inclure des informations sur ce nouvel attribut, en fonction de la manière dont vous configurez les scopes et les claims dans Keycloak.

SAML

Pour SAML, l’ajout du nouvel attribut affectera le fichier de métadonnées XML qui est utilisé pour configurer la relation de confiance entre l’application et Keycloak. Le nouvel attribut uid sera ajouté comme un élément d’attribut dans le fichier de métadonnées, indiquant que cet attribut est disponible et peut être utilisé par l’application.

Conclusion

La mise en place d’une fédération d’identités avec Keycloak offre une solution robuste pour centraliser la gestion des identités, en intégrant divers technologies de référentieles d’identité (dans notre exemple : Oracle Directory Servers et Active Directory). L’utilisation de la section « User Federation » de Keycloak et la personnalisation des mappers pour utiliser le champ mail comme identifiant unique sont des étapes clés pour réussir cette intégration. De plus, nous avons exploré comment ajouter de nouveaux attributs aux mappers pour personnaliser davantage l’intégration.

Ces configurations permettent non seulement une authentification cohérente à travers divers services, mais elles offrent également une grande flexibilité pour gérer des attributs et des rôles spécifiques aux utilisateurs. Ainsi, les administrateurs peuvent bénéficier d’une gestion centralisée tout en fournissant une expérience utilisateur transparente.

En suivant ces étapes, vous aurez une configuration robuste et flexible qui peut s’adapter à des besoins divers et complexes en matière de gestion des identités.