Connect Element Web to Keycloak Through Synapse OIDC

To add Keycloak sign-in to Element Web, configure Keycloak as an OpenID Connect (OIDC) provider in Synapse, then make sure Element Web is using that Synapse homeserver. Synapse handles the authentication redirect and callback; Element Web does not need the Keycloak client secret.

Example scenario (hypothetical): a small organization runs Element Web at chat.example.org, Synapse at matrix.example.org, and Keycloak at login.example.org. The same sequence applies to other hostnames, but every URL must match your actual public configuration. This example is illustrative, not a report of a live setup.

What you need before changing settings

Use public HTTPS URLs for Keycloak and Synapse. Synapse’s OIDC documentation requires a secure origin for the identity provider, and its callback must be reachable through the public Synapse URL. Confirm the realm name in Keycloak, Synapse’s public_baseurl, and the homeserver URL served to Element Web. If a reverse proxy sits in front of either service, it must pass requests to the correct backend and preserve the external HTTPS host and scheme.

Synapse’s current configuration uses an oidc_providers list. The older single-provider oidc_config form is deprecated. Keep a working administrator login and a copy of the current configuration while testing. Do not disable password login or registration until you have verified the SSO flow and decided how accounts will be provisioned.

1. Register Synapse as a client in Keycloak

In the Keycloak realm where your organization’s users live, create an OpenID Connect client for Synapse. Synapse’s official Keycloak example uses a confidential client with client ID synapse. Set the valid redirect URI to this exact callback, substituting your Synapse hostname:

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

For the hypothetical setup, set the client access type to confidential and enable the client. On the Credentials tab, copy the generated client secret into your secrets-management system; do not put it in Element Web’s public config.json or publish it in a repository.

The redirect URI is a frequent source of failure. It must use the public Synapse URL, the exact /_synapse/client/oidc/callback path, and the same scheme and hostname Synapse sees from the browser. Avoid a broad wildcard callback when an exact URI will work. If you later enable back-channel logout, add Synapse’s documented back-channel endpoint in Keycloak as well; this is optional and separate from basic sign-in.

2. Add the Keycloak provider to Synapse

Edit the active homeserver.yaml. Replace the realm and secret below with your values, and confirm the issuer URL from the realm’s OpenID discovery document. The standard Keycloak realm issuer has this shape:

https://login.example.org/realms/your-realm

For a deployment using the standard discovery endpoint and claims shown in Synapse’s Keycloak example, the provider entry is:

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 }}"

The issuer must match Keycloak’s realm issuer, not just the Keycloak server root. Discovery lets Synapse obtain the authorization, token, and user-information endpoints from that issuer. The mapping uses Keycloak’s preferred_username to form a Matrix localpart and name as the display name; make sure these claims are present and stable for your users. A Matrix localpart is an account identifier, so changing the mapping later can make account matching confusing or produce a different Matrix ID.

Keep the existing oidc_providers list if other identity providers are configured; add this entry rather than replacing unrelated providers. Protect the client secret as a secret and set file permissions according to your deployment. Validate the YAML indentation, then restart Synapse using the service or container procedure for your installation. Packaged installations may already include OIDC dependencies; for a virtualenv installation, Synapse documents installing matrix-synapse[oidc]. Follow your package maintainer’s guidance for other install methods.

3. Point Element Web at the same homeserver

Element Web’s config.json should identify the Synapse server as its homeserver, for example through default_server_config.mHomeserver.base_url. Use the actual homeserver URL, not the Keycloak issuer. Element Web is a static client: redeploy or reload its configuration using your hosting method after changing the homeserver URL. Do not put Keycloak’s client secret in this file because browsers can read it.

For the hypothetical example, Element Web is hosted at https://chat.example.org and connects to https://matrix.example.org. When a user selects the SSO option on Element’s sign-in screen, the browser should move through Synapse’s login flow to the Keycloak realm and return to Synapse’s callback. Exact button wording and login-screen layout can vary by Element Web release and server configuration; test the behavior rather than relying on a particular label.

4. Test with one account before enforcing SSO

Open Element Web in a private browser window and select the SSO login option. Sign in with a test Keycloak user, approve the requested access if prompted, and confirm the browser returns to the intended homeserver and opens the expected Matrix account. Check that the resulting Matrix ID has the intended localpart. Review Synapse and Keycloak logs if the browser returns an error.

If the redirect fails, compare the callback URL in Keycloak character for character with Synapse’s public callback URL. An “issuer mismatch” points to a wrong realm issuer or reverse-proxy hostname. A missing username or mapping error means the configured claim is absent or unsuitable; inspect the test user’s claims and adjust the mapping deliberately. If the browser reaches Keycloak but does not return, check TLS certificates and proxy routing for the Synapse callback.

Optional logout: Synapse supports OIDC back-channel logout. To use it, set backchannel_logout_enabled: true under this provider and configure Keycloak’s back-channel logout URL as https://matrix.example.org/_synapse/client/oidc/backchannel_logout. Synapse also documents enabling the session-required option in Keycloak. This handles provider-initiated logout notifications; it is not required to make initial SSO login work.

Before rollout: decide whether SSO should create new Matrix users or only authenticate accounts you provision separately, then review Synapse’s OIDC options for your installed version. Configuration labels and Keycloak’s administration UI can change between releases. The steps here follow Synapse’s OIDC documentation available October 10, 2026, and assume a standard Keycloak realm and a Synapse deployment using the documented provider format. Consult the Synapse OpenID Connect and Keycloak guide, the Synapse configuration reference, and the official Keycloak documentation before applying version-specific settings. Once the test account signs in correctly and you have a recovery route, document the final callback, issuer, and claim mapping for administrators.

Leave a Comment

Connect Element Web to Keycloak Through Synapse OIDC

Configure a Keycloak OIDC client and Synapse provider so Element Web users can sign in through your identity server without exposing client secrets.

Set Up Element Key Backup and Cross-Signing Safely

Set Up Element Key Backup and Cross-Signing Safely

Save a recovery key, verify your Element sessions, and check that encrypted message keys can be restored without confusing backup with your account password.

Stop Matrix Synapse Memory Crashes During Client Sync

Diagnose Synapse out-of-memory failures during sync, adjust caching safely, identify request backlogs, and verify stable memory use.

Resolve Synapse Federation TLS Certificate Errors

Trace Matrix federation certificate failures to the correct server, repair the TLS chain or CA trust, and verify the fix without disabling security checks.

Put a Synapse Matrix Server Behind Cloudflare Safely

Put a Synapse Matrix Server Behind Cloudflare Safely

Route Matrix clients and federation through Cloudflare on HTTPS 443, preserve Synapse discovery, and avoid caching API traffic or breaking media uploads.

Restore Matrix Synapse Safely with a PostgreSQL Dump

Back up Synapse with pg_dump, protect its signing key and media, and restore into a clean PostgreSQL database without reusing stale one-time keys.

Run Mjölnir as a Matrix Room Moderation Bot with Docker

Run Mjölnir as a Matrix Room Moderation Bot with Docker

Set up Mjölnir with a dedicated Matrix account, encrypted management room, Docker Compose, policy list, and permission checks.

Enable Native Matrix Sliding Sync for Faster Mobile Loading

Enable Native Matrix Sliding Sync for Faster Mobile Loading

Skip the retired proxy and configure Synapse’s built-in Sliding Sync. Check client discovery, then measure room-list loading and reconnect behavior on a compatible phone.

Host Element Web on Nginx with a Custom Homeserver

Deploy Element Web as a static site, point it to your Matrix homeserver, add HTTPS, and configure Nginx to serve updates without stale files.

Run a Lightweight Matrix Homeserver on Raspberry Pi 4

Set up Conduit on a 64-bit Raspberry Pi 4 with persistent data, HTTPS federation, protected registration, and checks for a working homeserver.