Intégration avec Keycloak
Introduction
Keycloak est un fournisseur d'identité libre, commun et puissant. Il est souvent utilisé comme agrégateur d'identité.
Keycloak peut, comme Bravas, être utilisé comme fournisseur d'identité principal, permettant de gérer l'ensemble de vos identités et d'y fédérer vos fournisseurs de services tiers.
Mais il peut également être utilisé comme agrégateur d'identité par des équipes de développement interne comme par des fournisseurs de services.
L'idée est simple, vos applications métiers internes utilisent Keycloak comme annuaire interne (pour leurs utilisateurs, groupes et rôles) et délèguent à Keycloak la responsabilité de gestion des identités.
Keycloak peut alors être configuré pour permettre l'accès à vos applications métiers via son annuaire interne, ou via une fédération en cascade vers le fournisseur d'identité de votre entreprise, Bravas.
C'est l'objet de cet article, configurer un royaume Keycloak pour de la fédération d'identité.
Cet article couvre uniquement la configuration entre Keycloak et Bravas. Charge à vos développeurs de lire la documentation de Keycloak pour s'en service comme d'un microservice dédié aux opérations d'annuaire.
Les royaumes Keycloak
Chaque déploiement de Keycloak est organisé via un système de royaume. Un royaume est ici analogue à la notion de locataire (tenant) dans l'esprit d'une solution SaaS. Bien que cette analogie soit vraie, il reste important de comprendre que la notion de royaume se rapporte à une notion particulière dans le domaine de la gestion d'identité.
Un royaume est un ensemble d'identité, de groupes, de méthodes d'authentification, et de services associés, qui fonctionnent tous ensemble. Cela représente l'ensemble de votre chaine d'identité.
En travaillant avec Keycloak, assurez-vous de ne jamais configurer de services ou d'identité sur le royaume nommé "master". Celui-ci ne doit être utilisé que pour les besoins de gestion de votre instance Keycloak.
Le royaume maitre ne sert qu'à créer les autres royaumes pour ensuite travailler avec.
Le nombre de royaumes dépendra de votre besoin. Si vous êtes un concurrent de Microsoft 365 par exemple, vous pourriez créer un royaume par client pour offrir plusieurs services finaux construits autour de la même identité.
Ou vous pourriez créer un royaume par service interne à votre organisation pour permettre à chaque équipe de développeurs de disposer de sa propre copie de vos identités.
Ce sont là deux exemples classiques d'usage, mais bien entendu, vous pouvez retenir l'architecture qui vous convient le mieux, tant que cela reste cohérent du point de vue du cycle de vie des identités et que vous vous assurez de l'isolation entre services et clients.
Configuration initiale de Keycloak
Pour fédérer un royaume spécifique avec Bravas, vous devez vous rendre dans la section Identity Provider du menu principal.
Cette section vous permet de créer un ou plusieurs fournisseurs d'identités pour le même ensemble de comptes, et propose plusieurs protocoles de fédération.
La section User-defined est celle qui nous intéresse pour permettre une fédération avec un fournisseur comme Bravas. L'autre section est dédiée à la fédération avec les outils de réseaux sociaux (si vous voulez offrir une connexion avec le compte GitHub par exemple).
Pour vous intégrer avec Bravas, utilisez l'option SAML v2.0.
Maintenant que vous êtes sur la page Add SAML provider laissez Keycloak de côté et dans un nouvel onglet, connectez-vous à votre console d'administration Bravas pour ajouter une nouvelle application à votre catalogue de type SAML Metadata.
Parcourez l'assistant de configuration SAML et copiez l'URL des métadonnées Bravas lors de la seconde étape. Quelque chose comme https://YOUR_CORP.bravas.tech/idp/metadata.
Retournez à l'onglet Keycloak sans fermer Bravas, et copiez cette URL dans le champ SAML entity descriptor puis donnez un nom à cette configuration. Assurez-vous de garder l'option Use entity descriptor active.
Une fois le nom de votre configuration mis, vous pouvez ajouter le fournisseur. Vous verrez que Keycloak a lu et consommé les métadonnées Bravas pour s'autoconfigurer.
Dès lors, dans la première section de l'interface, vous verrez un lien SAML 2.0 Service Provider Metadata.
Copiez ce lien et collez-le du côté de Bravas dans la section suivante de notre assistant, là où l'URL de métadonnées SAML est demandée en entrée.
Il ne vous reste plus qu'à configurer dans Bravas un lien de lancement pour votre application. Quelque chose qui, lorsque l'utilisateur sera redirigé dessus, déclenchera le processus d'authentification avec Keycloak.
Une fois fait, vous pouvez aller à l'étape suivante de cette documentation : configurer les associations de champs avec Keycloak.
Associations de champs Keycloak
De retour dans Keycloak, vous verrez en haut des détails d'intégrations avec Bravas l'onglet Mappers où vous devez vous rendre.
Cette section vous permettra d'indiquer à Keycloak comment lire et interpréter les attributs présents dans la réponse SAML retournée par Bravas.
Vous devez ajouter une entrée pour chaque élément du tableau suivant, en accord avec notre documentation sur les attributs standards de notre réponse SAML. Tous les "Mappers" que vous allez configurer avec le tableau suivant doivent utiliser le mode de synchronisation Force et être de type Attribute Importer avec un format de nom mis à ATTRIBUTE_FORMAT_URI.
| Name | Attribute Name | User Attribute Name |
|---|---|---|
| Surname | urn:oid:2.5.4.4 | lastName |
| Given Name | urn:oid:2.5.4.42 | firstName |
| E-mail Address | urn:oid:0.9.2342.19200300.100.1.3 |
Dès cette configuration réalisée, vous pouvez vous authentifier avec Bravas, même si vos comptes n'existent pas encore dans Keycloak, ils seront créés au premier accès. N'oubliez pas d'assigner votre application à des groupes dans Bravas.
Configuration avancée de Keycloak
Même si cette configuration est fonctionnelle, il est possible d'améliorer l'expérience utilisateur en faisant quelques changements dans la configuration par défaut.
Validation des e-mails
Pour commencer, Keycloak a une notion de validation des adresses e-mail, où chaque usager doit confirmer la bonne possession de son adresse e-mail en cliquant sur un lien de validation émis par Keycloak.
Lorsque fédéré avec Bravas, ce processus n'est pas nécessaire, les informations retournées par Bravas sont de confiance. Pour que Keycloak considère les e-mails fournis par Bravas comme fiables, il vous faut revenir dans la section Identity Provider du menu principal puis cliquer sur votre configuration Bravas. En allant en fin de page, dans la section Advanced settings vous pourrez activer l'option Trust Email.
Méthode d'authentification par défaut
Par défaut, Keycloak est conçu pour permettre à une identité donnée de dispose de plusieurs méthode d'authentification, et de lier une identité Keycloak avec plus d'un fournisseur d'identité tiers. C'est là une très bonne architecture, pensée pour le futur, permettant l'extension de vos identités et de leurs méthodes d'authentification. Mais ce fonctionnement par défaut n'est pas forcément souhaitable pour une application métier interne où l'on veut simplement s'authentifier avec Bravas.
Pour changer ce comportement et permettre à vos usagers d'être authentifiés par défaut avec Bravas, vous devez changer le scénario d'authentification pour les accès basés sur le navigateur.
Depuis le menu principal, allez dans la section Authentication puis ouvrez le scénario Browser.
Le scénario d'accès basé sur le navigateur permet de configurer une expérience d'authentification complexe, en demandant une série de vérification pour permettre les accès. Par défaut une vérification de session existante par cookie est réalisée, et sinon propose une authentification interactive avec à la fois l'accès par mot de passe et par fédération disponible.
Vous devez modifier ce scénario pour ne garder que les sessions existantes par cookie et l'option Identity Provider Redirector.
Cliquez également sur le bouton des réglages pour la ligne des fournisseurs d'identité afin de spécifier le fournisseur par défaut à utiliser. Le premier normalement créé se nomme saml. Vous pouvez vérifier cela en retournant dans les options de l'intégration Bravas.
Désactiver la configuration d'un mot de passe
Si vous accédez à votre profil personnel Keycloak, vous verrez qu'en tant qu'usager, vous pouvez toujours configurer un mot de passe ou enregistrer un second facteur. Ces options ne sont pas nécessaires lorsque vous utilisez Keycloak avec Bravas comme fournisseur d'identité.
Pour modifier cela, vous devez aller dans la section Authentication du menu principal, puis dans l'onglet Required actions pour désactiver toutes les options disponibles. Elles sont uniquement nécessaires si vous utilisez Keycloak comme fournisseur d'identité principal.