Pour ajouter l'authentification Keycloak à Element Web, configurez Keycloak comme fournisseur OpenID Connect (OIDC) dans Synapse, puis assurez-vous qu'Element Web utilise bien ce serveur Synapse. Synapse gère la redirection et le rappel d'authentification ; Element Web n'a pas besoin du secret client Keycloak.
Exemple de scénario (hypothétique) : une petite organisation utilise Element Web à l’adresse `<adresse_hôte>` chat.example.org, Synapse à l’adresse `<adresse_hôte>` matrix.example.orget Keycloak à l’adresse `< login.example.orgadresse_hôte>`. La même séquence s’applique aux autres noms d’hôte, mais chaque URL doit correspondre à votre configuration publique réelle. Cet exemple est donné à titre illustratif et ne décrit pas une configuration en production.
Ce dont vous avez besoin avant de modifier les paramètres
Utilisez des URL HTTPS publiques pour Keycloak et Synapse. La documentation OIDC de Synapse exige une origine sécurisée pour le fournisseur d'identité, et son service de rappel doit être accessible via l'URL publique de Synapse. Vérifiez le nom du domaine dans Keycloak, dans Synapse public_baseurlet dans l'URL du serveur principal servie à Element Web. Si un proxy inverse est placé devant l'un ou l'autre service, il doit rediriger les requêtes vers le serveur principal approprié et conserver l'hôte et le schéma HTTPS externes.
La configuration actuelle de Synapse utilise une oidc_providersliste. L'ancienne configuration à fournisseur unique oidc_configest obsolète. Conservez un compte administrateur fonctionnel et une copie de la configuration actuelle pendant vos tests. Ne désactivez pas la connexion par mot de passe ni l'inscription tant que vous n'avez pas vérifié le flux d'authentification unique et défini le mode de provisionnement des comptes.
1. Enregistrez Synapse comme client dans Keycloak.
Dans l'environnement Keycloak où se trouvent les utilisateurs de votre organisation, créez un client OpenID Connect pour Synapse. L'exemple officiel de Synapse pour Keycloak utilise un client confidentiel avec l'ID client suivant : [ID client] synapse. Définissez l'URI de redirection valide sur cette fonction de rappel, en remplaçant [nom d'hôte Synapse] par le nom d'hôte de votre environnement Synapse :
https://matrix.example.org/_synapse/client/oidc/callback
Dans cette configuration hypothétique, définissez le type d'accès client sur confidentiel et activez le client. Dans l'onglet « Identifiants », copiez le secret client généré dans votre système de gestion des secrets ; ne le rendez pas public sur le site d'Element Web config.jsonet ne le publiez pas dans un référentiel.
L'URI de redirection est une source fréquente d'erreurs. Elle doit utiliser l'URL publique de Synapse, le /_synapse/client/oidc/callbackchemin exact, ainsi que le même schéma et le même nom d'hôte que ceux utilisés par Synapse depuis le navigateur. Évitez d'utiliser une fonction de rappel générique lorsqu'une URI précise suffit. Si vous activez ultérieurement la déconnexion par canal secondaire, ajoutez également le point de terminaison de canal secondaire documenté par Synapse dans Keycloak ; cette étape est facultative et indépendante de la connexion de base.
2. Ajoutez le fournisseur Keycloak à Synapse
Modifiez l'élément actif homeserver.yaml. Remplacez le domaine et le secret ci-dessous par vos valeurs, puis vérifiez l'URL de l'émetteur à partir du document de découverte OpenID du domaine. L'émetteur standard d'un domaine Keycloak a la structure suivante :
https://login.example.org/realms/your-realm
Pour un déploiement utilisant le point de terminaison de découverte standard et les revendications illustrées dans l'exemple Keycloak de Synapse, l'entrée du fournisseur est :
oidc_providers:
- idp_id: keycloak
idp_name: "Company Login"
issuer: "https://login.example.org/realms/your-realm"
client_id: "synapse"
client_secret: "REPLACE_WITH_THE_KEYCLOAK_SECRET"
scopes: ["openid", "profile"]
user_mapping_provider:
config:
localpart_template: "{{ user.preferred_username }}"
display_name_template: "{{ user.name }}"
L'émetteur doit correspondre à l'émetteur du domaine Keycloak, et non pas seulement à la racine du serveur Keycloak. La découverte permet à Synapse d'obtenir les points de terminaison d'autorisation, de jeton et d'informations utilisateur auprès de cet émetteur. Le mappage utilise les données Keycloak preferred_usernamepour former une partie locale Matrix et namecomme nom d'affichage ; assurez-vous que ces revendications sont présentes et stables pour vos utilisateurs. Une partie locale Matrix est un identifiant de compte ; par conséquent, toute modification ultérieure du mappage peut rendre la correspondance des comptes complexe ou générer un ID Matrix différent.
Conservez la oidc_providersliste existante si d'autres fournisseurs d'identité sont configurés ; ajoutez cette entrée plutôt que de remplacer les fournisseurs non pertinents. Protégez le secret client et définissez les permissions des fichiers conformément à votre déploiement. Validez l'indentation YAML, puis redémarrez Synapse en utilisant la procédure de service ou de conteneur correspondant à votre installation. Les installations packagées peuvent déjà inclure les dépendances OIDC ; pour une installation dans un environnement virtuel, consultez la documentation de Synapse relative à l'installation matrix-synapse[oidc]. Suivez les instructions du responsable du paquet pour les autres méthodes d'installation.
3. Pointez Element Web sur le même serveur d'accueil
Element Web config.jsondoit identifier le serveur Synapse comme serveur d'accueil, par exemple via `< default_server_config.mHomeserver.base_urlURL_du_serveur_d'accueil>`. Utilisez l'URL réelle du serveur d'accueil, et non l'émetteur Keycloak. Element Web étant un client statique, redéployez ou rechargez sa configuration à l'aide de votre méthode d'hébergement après avoir modifié l'URL du serveur d'accueil. Ne placez pas le secret client Keycloak dans ce fichier, car les navigateurs peuvent le lire.
Dans cet exemple hypothétique, Element Web est hébergé à l'adresse [adresse manquante] https://chat.example.orget se connecte à [ https://matrix.example.orgadresse manquante]. Lorsqu'un utilisateur sélectionne l'option SSO sur l'écran de connexion d'Element, le navigateur doit suivre le flux de connexion Synapse jusqu'à l'environnement Keycloak, puis revenir à la fonction de rappel de Synapse. Le libellé exact du bouton et la mise en page de l'écran de connexion peuvent varier selon la version d'Element Web et la configuration du serveur ; il est donc important de tester le comportement plutôt que de se fier à une étiquette particulière.
4. Effectuez un test avec un seul compte avant d'appliquer l'authentification unique (SSO).
Ouvrez Element Web dans une fenêtre de navigation privée et sélectionnez l'option de connexion SSO. Connectez-vous avec un utilisateur Keycloak de test, approuvez l'accès demandé si nécessaire, et vérifiez que le navigateur vous redirige bien vers le serveur d'accueil prévu et ouvre le compte Matrix attendu. Assurez-vous que l'identifiant Matrix obtenu contient bien la partie locale attendue. Consultez les journaux de Synapse et de Keycloak si le navigateur renvoie une erreur.
Si la redirection échoue, comparez l'URL de rappel dans Keycloak, caractère par caractère, avec l'URL de rappel publique de Synapse. Une erreur d'« émetteur incorrect » indique un émetteur de domaine ou un nom d'hôte de proxy inverse incorrect. Un nom d'utilisateur manquant ou une erreur de mappage signifie que la revendication configurée est absente ou inappropriée ; examinez les revendications de l'utilisateur de test et ajustez le mappage en conséquence. Si le navigateur atteint Keycloak mais ne renvoie aucune réponse, vérifiez les certificats TLS et le routage du proxy pour le rappel Synapse.
Déconnexion optionnelle : Synapse prend en charge la déconnexion via le canal de retour OIDC. Pour l'utiliser, configurez backchannel_logout_enabled: truele fournisseur et l'URL de déconnexion du canal de retour de Keycloak https://matrix.example.org/_synapse/client/oidc/backchannel_logout. Synapse explique également comment activer l'option « session requise » dans Keycloak. Cette option gère les notifications de déconnexion initiées par le fournisseur ; elle n'est pas nécessaire pour la connexion SSO initiale.
Avant le déploiement : déterminez si l’authentification unique (SSO) doit créer de nouveaux utilisateurs Matrix ou authentifier uniquement les comptes provisionnés séparément, puis consultez les options OIDC de Synapse pour votre version installée. Les libellés de configuration et l’interface d’administration de Keycloak peuvent varier d’une version à l’autre. Les étapes décrites ici suivent la documentation OIDC de Synapse, disponible le 10 octobre 2026, et supposent un domaine Keycloak standard et un déploiement Synapse utilisant le format de fournisseur documenté. Consultez le guide Synapse OpenID Connect et Keycloak , le guide de configuration de Synapse et la documentation officielle de Keycloak avant d’appliquer les paramètres spécifiques à la version. Une fois que le compte de test se connecte correctement et que vous disposez d’une procédure de récupération, documentez le rappel final, l’émetteur et le mappage des revendications pour les administrateurs.