Comment configurer l'authentification unique (SSO) avec Keycloak dans Element Web

Element Web ne s'authentifie pas directement auprès de Keycloak. Element interroge son serveur Matrix pour connaître les méthodes de connexion prises en charge ; le serveur effectue l'authentification OpenID Connect (OIDC) auprès de Keycloak et redirige l'utilisateur vers Element. Pour un déploiement Synapse utilisant sa prise en charge OIDC intégrée, configurez un client OIDC confidentiel dans Keycloak, ajoutez ce fournisseur à Synapse et, si vous le souhaitez, configurez Element Web config.jsonpour afficher ou démarrer automatiquement l'authentification unique (SSO).

Ce guide utilise le fournisseur OIDC intégré de Synapse, une méthode de déploiement courante. Si votre serveur délègue l'authentification à Matrix Authentication Service (MAS), utilisez plutôt la configuration de rappel et de fournisseur MAS décrite ci-dessous. Les deux URL de rappel sont différentes. Les instructions ont été vérifiées le 6 octobre 2026 par rapport à la documentation de configuration d'Element Web, au guide OIDC de Synapse v1.144, au guide SSO MAS en amont (version actuelle) et au guide d'administration de Keycloak 26.8.0 ; le packaging de déploiement et les libellés de l'interface utilisateur peuvent varier selon la version.

Tout d'abord, identifiez le chemin d'authentification que vous utilisez.

Avant de créer un client, veuillez consulter la documentation relative à la configuration et au déploiement de Synapse. La fonction de rappel doit appartenir au composant qui communique avec Keycloak ; n’utilisez pas l’URL du site web d’Element comme fonction de rappel.

Ce dont vous avez besoin

• Une URL HTTPS publique pour Synapse, telle que https://matrix.example.com, et un émetteur de domaine Keycloak accessible, tel que https://sso.example.com/realms/company.
• Accès administratif au domaine Keycloak et à la configuration et au service Synapse.
• Une sauvegarde de la configuration actuelle et une solution pour utiliser les journaux Synapse ou une console serveur en cas d'échec de connexion.
• Une décision concernant la gestion des comptes : quels utilisateurs Keycloak peuvent se connecter, quelle revendication les identifie et si les comptes Matrix existants doivent être conservés.

Configurer Keycloak pour Synapse OIDC

1. Créer un client OIDC confidentiel

Dans le domaine utilisé pour les comptes Matrix, créez un client Synapse utilisant le protocole OpenID Connect. Activez le code d'autorisation ou le flux standard et l'authentification client afin que Synapse puisse utiliser un secret client au niveau du point de terminaison du jeton. Définissez l'ID client sur une valeur que vous utiliserez également dans Synapse, par exemplesynapse : .

Définissez l'URI de redirection valide sur l'URL de rappel Synapse exacte :

https://matrix.example.com/_synapse/client/oidc/callback

Remplacez le nom d'hôte d'exemple par l'URL de base publique réellement configurée pour Synapse. N'utilisez pas de caractère générique trop large, comme *en production. Keycloak valide les URI de redirection ; une incohérence au niveau de l'hôte, du schéma, du chemin ou de la barre oblique finale peut donc entraîner une erreur « URI de redirection non autorisée ».

Enregistrez le client, copiez son secret généré et stockez-le comme secret côté serveur. Ne le rendez pas public dans Element Web config.json, son système de contrôle de version, ses captures d'écran ni son code JavaScript côté client. La console d'administration Keycloak peut utiliser des libellés différents pour l'authentification ou les identifiants du client selon les versions ; assurez-vous que le client résultant est confidentiel et qu'il peut utiliser le flux d'autorisation standard.

2. Confirmer l'émetteur et les réclamations

L'émetteur identifie le domaine, et non la racine du serveur Keycloak. Dans cet exemple, utilisez `<domain>` https://sso.example.com/realms/company. Vérifiez que la configuration OpenID du domaine est accessible à l'adresse ` <issuer>/.well-known/openid-configuration<domain>` et que l'émetteur annoncé correspond exactement à la valeur que vous fournirez à Synapse.

Synapse a besoin d'une identité stable pour associer le compte Keycloak à un utilisateur Matrix. Son fournisseur OIDC identifie généralement le sujet externe à l'aide de l'identité OIDC correspondante ; le mappage de noms d'utilisateur ci-dessous utilise preferred_usernamecette identité comme partie locale Matrix. Assurez-vous que Keycloak renvoie bien cette identité et que les noms d'utilisateur sont uniques et stables conformément à votre politique de compte. Si votre organisation autorise les modifications de noms d'utilisateur, choisissez et testez une stratégie de mappage avant la mise en production ; une modification inattendue du mappage peut affecter le compte Matrix auquel un utilisateur accède.

Configurer Synapse

3. Ajouter le fournisseur OIDC

Ajoutez une entrée de fournisseur à la configuration principale de Synapse, généralement `<provider>` homeserver.yaml. Fusionnez-la avec le fichier YAML existant au lieu de remplacer d'autres paramètres. Remplacez l'émetteur de votre domaine et le secret client réel :

oidc_providers:
  - idp_id: keycloak
    idp_name: "Keycloak"
    issuer: "https://sso.example.com/realms/company"
    client_id: "synapse"
    client_secret: "REPLACE_WITH_THE_CLIENT_SECRET"
    scopes: ["openid", "profile", "email"]
    user_mapping_provider:
      config:
        localpart_template: "{{ user.preferred_username }}"
        display_name_template: "{{ user.name }}"

Les étendues demandées déterminent les informations utilisateur que Keycloak peut renvoyer ; elles ne garantissent pas que toutes les revendications soient renseignées. Si vous n'avez pas besoin d'importer l'adresse e-mail ou le nom d'affichage, réduisez les étendues et le mappage en conséquence. Limitez l'accès au fichier de configuration à l'administrateur du service et au processus Synapse, selon les besoins de votre déploiement. Si vous gérez Synapse via des conteneurs ou un graphique, placez les paramètres du fournisseur dans la source de configuration prévue à cet effet plutôt que de modifier un fichier généré qui sera écrasé.

4. Configurer éventuellement la déconnexion par canal secondaire

Par défaut, la déconnexion d'un service n'entraîne pas nécessairement la fermeture de toutes les sessions de navigateur des autres services. Si vous souhaitez que les notifications de déconnexion Keycloak mettent fin à la session Synapse, activez l' backchannel_logout_enabled: trueoption correspondante dans les paramètres du fournisseur Keycloak de Synapse et définissez l'URL de déconnexion du canal de retour Keycloak sur :

https://matrix.example.com/_synapse/client/oidc/backchannel_logout

Cette étape est facultative et dépend de votre politique de déconnexion et de la configuration de votre client. Testez les deux méthodes de déconnexion : Synapse et Keycloak. Ne présumez pas que la déconnexion d’Element seule met fin à la session Keycloak.

5. Redémarrez et testez Synapse

Validez le fichier YAML à l'aide des contrôles de configuration de votre déploiement, puis redémarrez ou rechargez Synapse selon la méthode prise en charge par votre package ou conteneur. Consultez les journaux Synapse pour détecter les erreurs de découverte OIDC, d'authentification client, de rappel ou de mappage de revendications. Commencez par utiliser un compte de test et vérifiez que son ID Matrix et son nom d'affichage correspondent aux valeurs attendues.

Configurer Element Web

6. Laissez l'authentification unique (SSO) optionnelle ou redirigez automatiquement.

Une fois que Synapse annonce la connexion OIDC, Element Web peut proposer son option de connexion SSO. sso_redirect_optionsLe paramètre d'Element contrôle l'expérience du navigateur ; il ne configure pas Keycloak et ne stocke pas le secret client. Ajoutez un paramètre comme celui-ci à la configuration d'Element Web config.jsonsi vous souhaitez que les visiteurs non authentifiés arrivant sur la page d'accueil ou de connexion soient redirigés vers le flux SSO disponible :

{
  "sso_redirect_options": {
    "immediate": false,
    "on_welcome_page": true,
    "on_login_page": true
  }
}

Pour un déploiement exigeant une authentification unique (SSO), activez "immediate": truel'authentification unique pour tous les utilisateurs non authentifiés. Cela peut rendre la saisie du mot de passe ou d'autres options de connexion plus difficile ; testez donc la récupération et l'accès administrateur avant de l'appliquer. Si les utilisateurs doivent choisir entre l'authentification unique et une autre méthode, désactivez la redirection automatique et vérifiez que l'option d'authentification unique apparaît bien dans le processus de connexion.

Si Synapse utilise le service d'authentification Matrix

MAS est un service d'authentification distinct et peut servir de client OIDC pour Keycloak. Dans cette architecture, configurez l'URI de redirection de Keycloak comme suit : `<URL_de_redirection>` https://auth.example.com/upstream/callback/<provider-id>, où l'ID du fournisseur correspond à la configuration MAS. Configurez le fournisseur dans les paramètres MASupstream_oauth2.providers ; Element utilise alors le flux d'authentification basé sur MAS du serveur d'accueil. N'utilisez pas Synapse /_synapse/client/oidc/callbackpour cette connexion en amont. MAS requiert un fournisseur OIDC prenant en charge le flux de code d'autorisation. Son format de configuration, l'ID du fournisseur requis et les étapes de migration sont différents de ceux de Synapse oidc_providers.

Malentendus courants et solutions

• « Il me suffit de modifier la configuration d'Element. » Element gère le flux du navigateur, tandis que Synapse ou MAS gère OIDC. Configurez d'abord le fournisseur côté serveur approprié.
• « Une connexion Keycloak réussie confirme que le mappage des comptes est correct. » L’authentification peut réussir même si la partie locale ou la revendication de profil sélectionnée est incorrecte. Effectuez un test avec un compte utilisateur hors production et vérifiez l’ID Matrix obtenu.
• L’authentification unique (SSO) désactive automatiquement les mots de passe et l’inscription. Ces règles sont gérées par le serveur d’accueil et le déploiement. Veuillez vérifier séparément les paramètres de connexion et d’inscription de Synapse et confirmer la règle approuvée.
• « Se déconnecter d’Element me déconnecte de tout. » Les sessions de navigateur peuvent rester actives sur Keycloak. Configurez et testez la déconnexion par canal secondaire si une fermeture centralisée des sessions est nécessaire.

Liste de vérification

• Le client Keycloak utilise le flux de code d'autorisation, l'authentification du client et le rappel exact pour Synapse ou MAS.
• L'URL de l'émetteur correspond aux métadonnées de découverte du domaine, et le secret client est stocké côté serveur.
• Synapse ou MAS démarre sans erreurs de configuration OIDC et expose la méthode de connexion prévue.
• Un utilisateur de test peut se connecter depuis une nouvelle session de navigateur, accéder au compte Matrix attendu et effectuer une session Element normale.
• Le comportement de déconnexion, les comptes existants, les restrictions d'inscription et tout accès administrateur de secours doivent être conformes à votre politique.

Références officielles

• Guide Synapse v1.144 OpenID Connect, incluant le client Keycloak et les paramètres de rappel
• Configuration d'Element Web : options de redirection SSO
• Service d'authentification Matrix : configuration d'un fournisseur SSO en amont
• Guide d'administration du serveur Keycloak 26.8.0