1. Introduction

Keycloak est une solution open source de gestion des identités qui permet, entre autres, de mettre en place une fédération d'identité entre deux organisations. Concrètement, cela signifie qu'un utilisateur appartenant à un domaine peut accéder aux ressources d'un autre domaine, sans créer de compte supplémentaire, grâce à une relation de confiance établie entre leurs fournisseurs d'identité respectifs.

Cet article montre comment mettre en place cette fédération avec Keycloak, depuis la configuration de l'IdP source jusqu'à l'accès effectif de l'utilisateur à une application. Pour illustrer chaque étape, nous nous appuierons sur un cas concret : la plateforme ACRA, déployée dans le réseau de l'IREX, où les membres de l'organisation doivent pouvoir accéder à Grafana en étant authentifiés par l'IdP de l'IREX — sans créer de compte supplémentaire.

La configuration se déroule en quatre grandes étapes : préparer les realms, déclarer les clients OIDC, configurer le broker, puis propager les attributs nécessaires à l'application.

2. Prérequis

Avant de commencer, les éléments suivants doivent être en place :

• Deux instances Keycloak déployées et accessibles, chacune adossée à une base de données persistante (PostgreSQL recommandé). La base H2 par défaut de Keycloak fonctionne en mémoire en mode développement : toute configuration est perdue au redémarrage du conteneur, ce qui rend le broker inutilisable en pratique.
• Accès administrateur aux deux consoles Keycloak.
• Une application cible supportant l'authentification OIDC native. Dans notre cas : Grafana, accessible via acra.dev.onesi.ca.
• Les trois composants (IdP source, broker, application) doivent être joignables mutuellement sur le réseau.

3. Les realms : isoler les domaines d'identité

Dans Keycloak, un realm est un espace logique isolé qui contient ses propres utilisateurs, clients, rôles et politiques de sécurité. Deux instances de Keycloak sur deux serveurs différents correspondent donc à deux domaines d'identité entièrement séparés — c'est précisément ce qui justifie une fédération plutôt qu'un simple SSO.

Dans une configuration de fédération OIDC, deux realms sont impliqués :

• Le realm de l'IdP source : celui qui détient les comptes des utilisateurs. Il reste la source de vérité et n'a pas à être modifié structurellement — il faut simplement y déclarer un client OIDC représentant le broker. Dans notre cas : le realm ACRA sur Keycloak IREX.
• Le realm du broker : celui qui fait confiance à l'IdP source et sert de relais vers l'application. C'est ici que le provider OIDC externe sera déclaré. Dans notre cas : le realm ACRA Platform sur Keycloak ACRA.

Si le realm du broker n'existe pas encore, il doit être créé depuis la console d'administration de Keycloak : Menu → Create Realm → Définir un nom → Save.

4. Déclarer le broker comme client sur l'IdP source

Pour qu'un broker puisse s'authentifier auprès d'un IdP source, l'IdP source doit connaître ce broker. Cela se fait en créant un client OIDC dans le realm de l'IdP source, qui représente le broker à ses yeux.

Depuis la console de l'IdP source, dans son realm :

1. Aller dans Clients → Create client.
2. Choisir OpenID Connect comme type de client.
3. Définir un Client ID explicite qui identifie le broker — par exemple acra-broker.
4. Activer Client authentication (mode confidentiel) afin de générer un Client Secret.
5. Dans Valid Redirect URIs, renseigner l'URL de callback du broker, de la forme :
   https://<broker-host>/realms/<broker-realm>/broker/<alias>/endpoint
   
6. Sauvegarder, puis noter le Client Secret généré dans l'onglet Credentials.

Ce Client ID et ce Client Secret seront utilisés à l'étape suivante pour configurer le broker.

5. Configurer le broker OIDC sur l'IdP intermédiaire

C'est l'étape centrale. Il s'agit de déclarer l'IdP source comme fournisseur d'identité de confiance dans le realm du broker, en renseignant les paramètres OIDC nécessaires à l'établissement de la relation de confiance.

Depuis la console du broker, dans son realm :

1. Aller dans Identity Providers → Add provider → OpenID Connect v1.0.
2. Définir un Alias pour ce provider. Cet alias est important : il apparaît dans l'URL de callback déclarée côté IdP source à l'étape précédente. Le modifier après coup invaliderait cette URL. Dans notre cas : irex-keycloak.
3. Renseigner la Discovery URL de l'IdP source :
   https://<idp-source-host>/realms/ACRA/.well-known/openid-configuration
   Keycloak récupère automatiquement tous les endpoints OIDC (autorisation, token, userinfo…) depuis ce document de découverte.
4. Renseigner le Client ID et le Client Secret obtenus à l'étape précédente.
5. Sauvegarder.

À ce stade, la page de connexion du realm broker propose automatiquement de s'authentifier via l'IdP source. L'utilisateur qui choisit cette option est redirigé vers la page de connexion de l'IdP source, s'y authentifie avec ses identifiants habituels, puis revient sur le broker muni d'un token valide — sans jamais avoir créé de compte dans le realm broker.

Dans notre cas : un membre de l'IREX qui accède à Grafana via acra.dev.onesi.ca est redirigé vers Keycloak ACRA (realm ACRA Platform), puis vers Keycloak IREX (realm ACRA) où il saisit ses identifiants IREX habituels.

6. Déclarer l'application comme client sur le broker

L'application qui consomme la fédération doit également être déclarée comme client OIDC dans le realm du broker. C'est ce client qui définit les paramètres d'échange de tokens entre le broker et l'application.

Depuis la console du broker, dans son realm :

1. Aller dans Clients → Create client → OpenID Connect.
2. Définir un Client ID identifiant l'application. Dans notre cas : grafana.
3. Activer Client authentication pour générer un Client Secret.
4. Renseigner la Redirect URI de l'application. Dans notre cas : https://acra.dev.onesi.ca/login/generic_oauth.
5. Sauvegarder et noter le Client Secret.

Ces informations (Client ID, Client Secret, et les URLs des endpoints OIDC du broker) sont ensuite renseignées dans la configuration de l'application pour qu'elle puisse déléguer l'authentification au broker.

7. Propager les rôles et attributs

Une fois la relation de confiance établie, le broker reçoit un ID token de l'IdP source contenant des claims — des informations sur l'utilisateur : identifiant, email, groupes, rôles. Ces claims ne sont pas automatiquement retransmis à l'application : des mappers doivent être configurés pour les extraire et les injecter dans le token que le broker émettra à destination de l'application.

Cette propagation s'effectue en deux niveaux :

• Au niveau du broker (Identity Providers → <alias> → Mappers) : pour extraire les claims du token de l'IdP source et les rendre disponibles comme attributs dans le realm broker.
• Au niveau du client applicatif (Clients → <client-id> → Client Scopes → Mappers) : pour injecter ces attributs dans le token transmis à l'application, sous la forme de claims que l'application sait lire.

Dans notre cas : un utilisateur appartenant au groupe acra-admins dans Keycloak IREX peut se voir attribuer automatiquement le rôle GrafanaAdmin dans Grafana, via une chaîne de mappers traversant les deux realms.

8. Vérifier le flux complet

Une fois tous les composants configurés, le flux de bout en bout peut être vérifié. Les étapes à valider sont les suivantes :

1. L'application redirige bien vers le broker pour l'authentification.
2. Le broker propose bien l'IdP source comme option de connexion, ou y redirige directement.
3. L'utilisateur s'authentifie sur l'IdP source avec ses identifiants habituels.
4. Après authentification, l'utilisateur est bien redirigé vers l'application avec les droits attendus.
5. En cas d'erreur, les logs de chaque composant (application, broker, IdP source) doivent être consultés indépendamment pour identifier le maillon défaillant.

Le point d'attention le plus fréquent en pratique concerne les rôles : si l'utilisateur accède à l'application sans les droits attendus, la cause est presque toujours dans la chaîne de mappers. Il faut vérifier que le claim attendu par l'application correspond bien à ce que le broker injecte dans le token.

9. Bonnes pratiques

10. Conclusion

Mettre en place une fédération OIDC avec Keycloak revient à configurer une chaîne de confiance précise entre quatre composants : l'IdP source, le broker, le client applicatif dans le realm broker, et l'application elle-même. Chaque maillon doit être cohérent avec les autres — un Client ID, une Redirect URI ou un alias mal renseigné suffit à casser l'ensemble du flux.

Une fois cette chaîne en place, le résultat est immédiat : les utilisateurs du domaine source accèdent aux ressources du domaine cible avec leurs identifiants habituels, sans compte supplémentaire. Dans le projet ACRA, les membres de l'IREX accèdent ainsi à Grafana en s'authentifiant uniquement auprès de l'IdP de l'IREX.

Cette architecture est également évolutive : intégrer un nouveau service dans la fédération ne nécessite que d'ajouter un client OIDC dans le realm broker, sans toucher à la configuration du broker lui-même ni à l'annuaire de l'IdP source.

11. Voir aussi

• Comprendre la fédération d'identité : concepts et enjeux
• OAuth2-Proxy : le gardien silencieux de vos applications sans authentification