Matrix and Keycloak SSO integration

For most teams the choice depends on where login and session decisions should live. Synapse's built-in OpenID Connect support lets the homeserver accept Keycloak logins directly. You add an entry under oidc_providers in the Synapse configuration, using the idp_id keycloak as in the Synapse Keycloak example, and Synapse handles the redirect, token validation and user mapping itself. Matrix Authentication Service (MAS) works differently. It is a separate service that acts as the OAuth 2.0 and OpenID provider for Matrix, and it uses Keycloak as an upstream OpenID Connect provider. Users sign in through MAS, which sends them to Keycloak, and the Matrix session model sits in MAS and is shared with Synapse.

Start with three questions. First, how many users and clients you expect. Both paths can serve a single homeserver, but the number of accounts, devices and other applications that will authenticate through Keycloak should shape your sizing and your Keycloak client layout. Confirm the sizing guidance for your expected load with your Synapse and MAS maintainers or your implementation partner before you commit. Second, whether you need the MAS session and device model, which manages Matrix sessions and devices in a dedicated service. If you have no requirement for that model, the Synapse path has fewer components. Third, whether your team can operate an extra service. MAS adds its own database, configuration, certificates, routing, upgrades and monitoring, and each of these needs a named owner before go-live.

Do not start new work on the removed path. Synapse v1.157.0 dropped the deprecated experimental MSC3861 auth delegation in favour of the stable Matrix Authentication Service integration. Older guides, sample configurations and community posts that describe MSC3861 settings may still circulate, so check any proposed configuration against the current Synapse upgrade notes and the MAS documentation before you copy it. If an existing deployment was built on the experimental delegation, treat the move to the stable integration as a planned migration. Read the upgrade notes for every Synapse version between your current release and your target, and test the change on a copy of your database first, because the upgrade notes warn that rolling back can be difficult after schema changes.

Before you choose, check two requirements that affect the design. Synapse's Keycloak documentation describes OIDC back-channel logout, enabled with backchannel_logout_enabled in Synapse and a back-channel logout URL configured in Keycloak, so that signing out of Keycloak also logs the user out of Synapse. Confirm that the same behavior works on the MAS path for the versions you plan to run before you rely on it. Also note that MAS does not support SAML. If your identity policy requires SAML or LDAP, the MAS documentation recommends a bridge such as Dex, and that route needs its own testing. Finally, record the decision with the Synapse, MAS and Keycloak versions you tested, so the choice can be reviewed at the next upgrade.

Back-channel logout is the mechanism that signs a Matrix user out of Synapse when that user logs out of Keycloak. Synapse's OpenID Connect configuration includes the backchannel_logout_enabled setting, and Keycloak needs a back-channel logout URL configured for the Matrix client. When both are in place, a logout at Keycloak triggers a request from Keycloak to Synapse, which then ends the matching Synapse session. Synapse's Keycloak documentation describes this pairing. Before you build anything around it, confirm the exact endpoint path and the logout behavior for the Synapse version you plan to run, using the Synapse documentation for that release. Record the version in your design notes, because the endpoint and its behavior are the parts most likely to change between releases.

The main trade-off is between front-channel and back-channel logout. Front-channel logout relies on the user's browser to carry logout requests to each relying application. If the browser is closed, blocked, or never loads the logout page, the Matrix session may stay active. Back-channel logout does not depend on the browser because Keycloak sends a server-to-server request. That benefit has a cost: Keycloak must be able to reach the Synapse endpoint over the network. In practice, this means checking firewall rules, reverse proxy routes, internal DNS, and the TLS trust chain between the two systems. If Keycloak cannot deliver the request, the user may be signed out of Keycloak while the Synapse session continues. Plan monitoring for failed logout deliveries so that gap is visible.

Test logout with an active Matrix client session, not only with a browser session. Sign in to Element or another client on desktop and on mobile, confirm the session works, then sign out of Keycloak from a separate browser. Check whether each client loses access, and whether the device appears as ended in the Synapse session list for that user. Review the Synapse logs for the incoming logout request and any errors. Then repeat the test with the network path between Keycloak and Synapse deliberately blocked, so you can see what the users and administrators would observe during an outage. Record the observed behavior for each client type you support, because client token handling differs and the results affect what you tell users about sign-out.

Assign ownership for the logout path before go-live. A named owner should maintain the Keycloak client configuration, the Synapse OIDC settings, and the network route between them, and should review both after every Synapse or Keycloak upgrade. If you plan to adopt Matrix Authentication Service later, do not assume this Synapse setting carries over unchanged. Confirm the logout behavior for that architecture in the MAS documentation and retest. Document what happens when a user is disabled in Keycloak, since that is a separate action from logging out, and confirm with your Synapse version whether it changes existing sessions. Agree on how quickly a user's Matrix access must end after an offboarding event, then test that timing against your real environment.

Adopting Matrix Authentication Service (MAS) adds a service you must run. With MAS in place, clients authenticate against MAS, which acts as the OAuth 2.0 and OpenID provider for Matrix, and MAS in turn signs users in through an upstream provider such as Keycloak. Your team will deploy, upgrade and back up MAS alongside Synapse, its database and its configuration. Before you commit, confirm which MAS and Synapse versions the project documents as compatible for your release, and plan the upgrade order for both. Synapse v1.157.0 removed the deprecated experimental MSC3861 auth delegation in favour of the stable MAS integration, so an installation still on the experimental setup needs a dated migration plan before any other change.

Configuration also splits across two services. Synapse keeps homeserver settings such as server_name, federation and media, while MAS holds the upstream provider definitions, client registrations and the secrets those depend on. Each Keycloak client must use the callback URLs that MAS expects, and each value must be kept in step on both sides during changes. Decide early which team owns each file and secret store, and record which setting lives where. Back-channel logout is the area most likely to need verification. Synapse's Keycloak guidance covers backchannel_logout_enabled, but confirm with the MAS documentation how logout from Keycloak reaches MAS sessions before you rely on it in production.

MAS does not support SAML. If your identity source is SAML-only, the simplest path depends on whether Keycloak already sits in front of it. If Keycloak already brokers the SAML source, MAS can keep using Keycloak as its single upstream and the SAML work stays where it already lives. If Keycloak does not broker it, you need a bridge. The MAS documentation recommends Dex for SAML or LDAP sources, which adds another service to deploy, monitor and upgrade. The sibling topic on LDAP and Active Directory covers the Dex route in more depth, so treat the bridge here as a scoping decision: who runs it, and where its logs and certificates are kept.

Migration raises three questions to answer before cutover. First, existing users and their external identities: map how current Matrix accounts link to the subject claims your upstream provider returns, then test the mapping with a copy of your data, since a mismatch can create duplicate accounts. Second, sessions: plan for active devices and clients to sign in again, and tell users in advance so support requests do not spike. Third, whether Keycloak is already the upstream. If it is, most of the change sits in MAS and Synapse configuration. If it is not, adding Keycloak or a new identity provider widens the scope to cover that provider's own administration and recovery.

Element Server Suite (ESS) includes MAS, and it is available as ESS Community and ESS Pro, with ESS TI-Messenger for German healthcare. ESS is deployed on Kubernetes with Helm charts, which changes the operating model if your team currently runs Synapse on virtual machines. Packaging, licensing and support terms, including whether Element supports a MAS deployment that uses your own Keycloak as upstream, should be confirmed directly with Element before you choose between a self-assembled setup and ESS. Ask Element to state in writing which components it supports, which versions it pairs, and where its support stops.

Run this test plan in a non-production environment before any user is moved to Keycloak sign-in. The first group of tests covers first login for two account types: people who have never had a Matrix account, who should be created on their first sign-in, and people who already hold a password-based account on the homeserver. For existing accounts, decide and test how the Keycloak identity maps to the current Matrix user ID, and what happens when the proposed localpart is already taken. If accounts will be linked, test the linking flow with copied accounts from production data and confirm the outcome in writing before cutover. Record the Matrix user ID, the Keycloak subject and the display name for each test case so results can be compared later.

Logout needs its own tests because a session can end in one place and survive in another. Open Element or another Matrix client, sign in through Keycloak, then end the Keycloak session from the account console or admin console. Confirm that Synapse ends the matching session when back-channel logout is enabled with backchannel_logout_enabled and the back-channel logout URL is set in the Keycloak client. Then test the reverse direction: log out inside the Matrix client and check whether the Keycloak browser session remains, since that determines whether the next person on a shared workstation can sign in silently. Confirm the network path from Keycloak to Synapse, because a blocked callback leaves a session that looks active until its token expires. Repeat these tests on each client platform your users run.

Inspect tokens and claims before you trust the mapping. Sign in with a test user and read the ID token Keycloak issues, checking the subject, the preferred username, the email and any claim used for display name. Confirm that the claim chosen for the Matrix localpart is stable and unique, because a changed username in Keycloak can create a second Matrix account beside the original. Remove a mapped attribute from a test user and check the resulting error message. Then run the failure path: disable a Keycloak user, attempt a new login, and check whether an existing Matrix session continues until its own expiry or ends through back-channel logout. Record each result, since the answers determine what the help desk tells users during the transition.

Rehearse the rollback before cutover, not after it. The Synapse upgrade notes warn that rolling back can be difficult because database schema changes between releases may not reverse cleanly, so the rehearsal should run against a fresh copy of the production PostgreSQL database. Keycloak also migrates its schema automatically at startup by default, so a Keycloak rollback needs its own database backup taken before the change. Define a decision point in writing: the last moment the team will revert configuration, and the point after which it will fix forward instead. Keep the Synapse configuration and the Keycloak client export under version control so the previous state can be rebuilt. Time the rehearsal, record each step, and ask your vendor or support provider to confirm which Synapse and Keycloak versions you can run together before you begin.