How to Configure Single Sign-On (SSO) with Keycloak in Element Web

Element Web does not authenticate directly against Keycloak. Element asks its Matrix homeserver for supported login methods; the homeserver completes OpenID Connect (OIDC) with Keycloak and returns the user to Element. For a Synapse deployment using its built-in OIDC support, configure a confidential OIDC client in Keycloak, add that provider to Synapse, and optionally adjust Element Web’s config.json to show or automatically start SSO.

This guide uses Synapse’s built-in OIDC provider, which is a common deployment path. If your homeserver delegates authentication to Matrix Authentication Service (MAS), use the MAS callback and provider configuration described below instead. The two callback URLs are different. Instructions were checked against the Element Web configuration documentation, Synapse v1.144 OIDC guide, current MAS upstream SSO guide, and Keycloak 26.8.0 administration guide on October 6, 2026; deployment packaging and UI labels can vary by version.

First, identify which authentication path you use

Check your Synapse configuration and deployment documentation before creating a client. The callback must belong to the component that talks to Keycloak; do not register Element’s website URL as the callback.

What you need

• A public HTTPS URL for Synapse, such as https://matrix.example.com, and a reachable Keycloak realm issuer, such as https://sso.example.com/realms/company.
• Administrative access to the Keycloak realm and the Synapse configuration and service.
• A backup of the current configuration and a way to use Synapse logs or a server console if sign-in fails.
• A decision about account provisioning: which Keycloak users may sign in, which claim identifies them, and whether existing Matrix accounts must be retained.

Configure Keycloak for Synapse OIDC

1. Create a confidential OIDC client

In the realm used for Matrix accounts, create a client for Synapse using the OpenID Connect protocol. Enable the authorization code or standard flow and client authentication so Synapse can use a client secret at the token endpoint. Set the client ID to a value you will also use in Synapse, for example synapse.

Set the valid redirect URI to the exact Synapse callback:

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

Replace the example hostname with the public base URL actually configured for Synapse. Do not use a broad wildcard such as * in production. Keycloak validates redirect URIs, so a host, scheme, path, or trailing-slash mismatch can cause a “redirect URI is not allowed” error.

Save the client, copy its generated secret, and store it as a server-side secret. Keep it out of Element Web’s public config.json, source control, screenshots, and client-side JavaScript. The Keycloak admin console may label client authentication or credentials differently across releases; verify the resulting client is confidential and can use the standard authorization code flow.

2. Confirm the issuer and claims

The issuer identifies the realm, not the Keycloak server root. For this example, use https://sso.example.com/realms/company. Confirm that the realm’s OpenID configuration is reachable at <issuer>/.well-known/openid-configuration and that its advertised issuer matches the value you will give Synapse exactly.

Synapse needs a stable identity claim to associate the Keycloak account with a Matrix user. Its OIDC provider normally identifies the external subject using the OIDC subject claim; the username mapping below uses preferred_username as the Matrix localpart. Ensure Keycloak actually returns that claim and that usernames are unique and stable under your account policy. If your organization permits username changes, choose and test a mapping strategy before production; an unexpected mapping change can affect which Matrix account a person reaches.

Configure Synapse

3. Add the OIDC provider

Add a provider entry to Synapse’s main configuration, commonly homeserver.yaml. Merge it with existing YAML instead of replacing other settings. Substitute your realm issuer and the real client secret:

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

The requested scopes control which user information Keycloak may return; they do not guarantee that every claim is populated. If you do not need email or display-name import, reduce the scopes and mapping accordingly. Keep the configuration file readable only by the service administrator and Synapse process as appropriate for your deployment. If you manage Synapse through containers or a chart, put the provider settings in the supported configuration source rather than editing a generated file that will be overwritten.

4. Optionally configure back-channel logout

By default, logging out of one service does not necessarily end every other service’s browser session. If you want Keycloak logout notifications to end the Synapse session, enable backchannel_logout_enabled: true under the Keycloak provider in Synapse and set Keycloak’s Backchannel Logout URL to:

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

This is optional and depends on your logout policy and client setup. Test both logout directions: Synapse logout and Keycloak logout. Do not assume that logging out of Element alone terminates the Keycloak session.

5. Restart and test Synapse

Validate the YAML with your deployment’s configuration checks, then restart or reload Synapse using the method supported by your package or container setup. Review Synapse logs for OIDC discovery, client authentication, callback, or claim-mapping errors. Use a test account first and confirm that its Matrix ID and display name are the expected values.

Configure Element Web

6. Keep SSO optional or redirect automatically

Once Synapse advertises OIDC login, Element Web can present its SSO login option. Element’s sso_redirect_options setting controls the browser experience; it does not configure Keycloak or store the client secret. Add a setting like this to Element Web’s served config.json if you want unauthenticated visitors arriving at the welcome or login page to be sent to the available SSO flow:

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

For a deployment that truly requires SSO-only sign-in, set "immediate": true to start SSO for all unauthenticated users. That can make password or other login choices harder to reach, so test recovery and admin access before enforcing it. If users should choose between SSO and another method, leave automatic redirection disabled and test that the SSO option appears in the login flow.

If Synapse uses Matrix Authentication Service

MAS is a separate authentication service and can act as the OIDC client to Keycloak. In that architecture, configure Keycloak’s redirect URI as https://auth.example.com/upstream/callback/<provider-id>, where the provider ID matches the MAS configuration. Configure the provider under MAS’s upstream_oauth2.providers; Element then uses the homeserver’s MAS-based authentication flow. Do not use Synapse’s /_synapse/client/oidc/callback for this upstream connection. MAS requires an OIDC provider supporting the authorization code flow. Its configuration format, required provider ID, and migration steps are distinct from Synapse’s built-in oidc_providers.

Common misunderstandings and fixes

• “I only need to change Element’s config.” Element controls the browser flow, while Synapse or MAS handles OIDC. Configure the correct homeserver-side provider first.
• “A successful Keycloak login proves account mapping is correct.” Authentication can succeed while the wrong localpart or profile claim is selected. Test with a non-production user and verify the resulting Matrix ID.
• “SSO automatically disables passwords and registration.” Those policies are controlled by the homeserver and deployment. Review Synapse’s login and registration settings separately and confirm the approved policy.
• “Logging out of Element logs me out everywhere.” Browser sessions can remain active at Keycloak. Configure and test back-channel logout if centralized session termination is required.

Verification checklist

• The Keycloak client uses the authorization code flow, client authentication, and the exact callback for Synapse or MAS.
• The issuer URL matches the realm’s discovery metadata, and the client secret is stored server-side.
• Synapse or MAS starts without OIDC configuration errors and exposes the intended login method.
• A test user can sign in from a fresh browser session, lands in the expected Matrix account, and can complete a normal Element session.
• Logout behavior, existing accounts, registration restrictions, and any fallback administrator access match your policy.

Official references

• Synapse v1.144 OpenID Connect guide, including Keycloak client and callback settings
• Element Web configuration: SSO redirect options
• Matrix Authentication Service: configuring an upstream SSO provider
• Keycloak 26.8.0 Server Administration Guide