How authentik signs users in to Matrix Synapse
If you run or plan a self-hosted Synapse homeserver and want staff to log in with their company identity, the supported route is OpenID Connect, with authentik acting as the OAuth2/OIDC provider and Synapse acting as the relying party through its oidc_providers setting. The authentik integration guide for Matrix Synapse follows this pattern: you configure an OAuth2/OpenID Connect provider in authentik, then point Synapse at it. Synapse also supports SAML2 (through saml2_config) and CAS, but this page covers only the OIDC path.
The authentik side is an OAuth2/OIDC provider bound to a Synapse application, with a redirect URI that matches the callback Synapse expects on your public homeserver hostname. The Synapse side is a block under oidc_providers that holds the issuer, client ID, client secret and the claim mapping. Confirm the exact redirect URI, scopes and claim names against the current guide and the Synapse configuration manual before you copy values, because these are the settings most often mistyped. Keep the client secret out of the main configuration file and load it from a secured source your deployment tooling controls.
Decide early which claim becomes the Matrix user ID localpart, since that choice is hard to reverse once accounts exist. Also decide what happens to accounts that already exist locally. Synapse will not automatically link an OIDC login to a password-based account with the same name unless your configuration allows it, so test with a staff account that already has a local login and record what the user sees. Have a rollback plan that keeps password login available until the mapping has been checked, and note that Synapse's upgrade notes warn that rolling back after schema changes can be difficult.
What you need in place before configuring Matrix Synapse SSO
Single sign-on for Synapse depends on four things being settled first: where authentik runs, which Synapse release you operate, how the homeserver name and endpoints are reached, and how authentik is named in DNS. Each card below covers one of these decisions so the OIDC settings you configure later point at stable, correct addresses.
authentik deployment model
Docker Compose suits a test setup or small-scale production, and the authentik Compose guide calls for at least 2 CPU cores and 2 GB of RAM. For production, the Kubernetes guide installs with Helm and states that the bundled PostgreSQL is for demonstration and testing, so plan a separately managed PostgreSQL instance before you begin. Confirm which model your organization will run, because it determines where the OIDC issuer URL lives.
Supported authentik release line
Choose a version from a release line that still receives security fixes. The authentik security policy lists 2026.5.x and 2026.8.x as supported, and security releases are announced at least 24 hours in advance. Confirm the latest release on the authentik releases page before you install, and check the upgrade notes for your target version so the OIDC provider configuration you build carries forward.
Synapse version and runtime requirements
Synapse 1.143.0 and later require PostgreSQL 14 or newer, and 1.142.0 and later require Python 3.10 or newer. Synapse drops support for runtimes once they reach upstream end of life, and the upgrade notes warn that rolling back can be difficult because of schema changes. Confirm the current release on the Synapse releases page and pin the version you test against.
Public server name and endpoints
The server_name value fixes how user IDs such as @user:example.com are formed, and it cannot be changed casually once accounts exist. Plan the client endpoint behind a reverse proxy with valid TLS, and decide whether federation on port 8448 or delegation on port 443 will serve it. Your OIDC redirect URI is built from this hostname, so settle it before you register the provider.
DNS name and TLS for authentik
Give authentik its own DNS name and a TLS certificate that clients trust, because Synapse fetches the OIDC discovery document and token endpoints from that address during login. Confirm that the Synapse host can resolve and reach the authentik issuer over HTTPS, including any internal DNS or certificate authority your network uses. Test this path before changing Synapse configuration.
Configuration sequence for authentik and Synapse OIDC
This sequence connects a self-hosted Matrix Synapse homeserver to authentik over OpenID Connect, so users sign in through authentik and Synapse accepts the resulting identity. It ends with a homeserver that offers an SSO login option backed by your authentik instance.
Confirm the homeserver name and public URLs
Before touching authentik, decide the server_name your Synapse homeserver will use, because it fixes how user IDs such as @user:example.com and room identifiers are formed. Confirm the public base URL that users and browsers will reach, and the host where authentik will run. Changing server_name after accounts exist is a migration exercise, so record the value in your change ticket and have the platform owner approve it. Done when the server_name and both public URLs are written down and agreed by the team that owns DNS and TLS.
Create the OAuth2/OIDC provider in authentik
In the authentik admin interface, create an OAuth2/OpenID Connect provider for Synapse, set the client type to confidential, and add the redirect URI that Synapse will call back to, using the path format from the authentik Matrix Synapse integration guide. Select the signing key and the scopes Synapse needs, including openid, profile and email. Bind the provider to an application so that only the intended user groups can sign in. Done when the provider saves and shows a client ID and client secret.
Record the client ID, secret and issuer URL
Copy the client ID and client secret from the provider page into your secrets store, not into a shared document or a chat thread. Record the issuer URL that authentik shows for the application, which identifies the OpenID Connect issuer Synapse will trust. Note which claim will supply the localpart of the Matrix user ID, typically a stable username field, and confirm this with the identity owner. Done when the three values are stored, access to the secret is limited to the people who deploy Synapse, and the claim choice is written down.
Verify the authentik discovery document
Before configuring Synapse, request the OpenID Connect discovery document from the issuer URL with a browser or curl from the Synapse host. The response should be a JSON document that lists the authorization, token and userinfo endpoints. If it does not load, fix the issuer URL, DNS or TLS trust on the Synapse host first, because Synapse cannot use an issuer it cannot reach or verify. Done when the discovery document loads over HTTPS from the machine that will run Synapse.
Add the oidc_providers block to Synapse
Edit the Synapse homeserver configuration file and add an oidc_providers entry that points to the authentik issuer, uses the client ID and client secret from your secrets store, and sets the same redirect URI you entered in authentik. Map the claim you chose to the Matrix localpart, and decide whether to allow account creation through SSO. Keep the client secret in an environment variable or a secrets mechanism instead of plain text where your deployment supports it. Validate YAML indentation before continuing. Done when the file parses and the redirect URI matches the authentik provider exactly.
Restart Synapse and check the logs
Restart the Synapse process or container so it loads the new configuration, then read the startup logs for errors about the OIDC provider, the issuer or the client secret. Keep a backup of the previous configuration and a database backup taken before the change, because the upgrade notes warn that rolling back can be difficult after schema changes. Confirm that Synapse listens on its client port and responds to its versions endpoint. Done when Synapse starts cleanly without OIDC errors in the logs.
Confirm the SSO option on the login page
Open the Synapse login page in a browser or a Matrix client that supports SSO. The page should offer a single sign-on option labeled for your authentik provider. Start a test sign-in with a non-administrative account from an authorized group, complete the authentik login, and confirm that Synapse creates or matches the expected Matrix user ID. Check that a user outside the authorized group is refused. Done when a test user signs in through authentik and lands on a Matrix account with the expected identifier.
Review existing local accounts before rollout
Before you announce the change, compare the Matrix user IDs that Synapse generates from authentik claims with the accounts that already exist as local password users. Synapse does not merge an existing local account into an SSO identity automatically, so decide with the identity owner how each existing user will be moved, whether password logins will be disabled, and how the mapping will be reported. Confirm this plan in a staging homeserver if you have one. Done when the team has a written decision for every existing account type and has tested at least one case.
How authentik claims map to Synapse user IDs and profile fields
This table traces each identity value authentik sends over OpenID Connect to the Synapse setting that consumes it, and shows which choices are fixed once users exist. Read the rows in order, because the subject claim and server_name decide identifiers that are hard to change later. Confirm the exact claim names and template behavior against your authentik and Synapse versions before you go live.
| Value | authentik side | Synapse side | Decision before go-live |
|---|---|---|---|
| Subject (sub) | Provider subject mode, which can derive it from a hashed user ID, user ID, UUID, username or email | subject_claim in the oidc_providers user mapping | Pick a stable value that will not change for a person, since Synapse links each login to it |
| Preferred username | preferred_username claim, normally the authentik username | localpart_template renders the Matrix localpart, such as @localpart:server_name | Confirm allowed characters and how duplicate or renamed usernames are handled |
| email claim, released through the email scope | email_template, or attribute requirements that limit who may log in | Decide whether email is only a profile field or also a login gate | |
| Display name | name claim, released through the profile scope | display_name_template sets the profile display name | Choose the format users and admins expect in room member lists |
| server_name | Not sent by authentik | Set in homeserver.yaml and used in every user ID and room ID | Fix the final domain before any user is created, because changing it creates new identities |
| Existing local accounts | Users already exist in authentik with their own identifiers | A new OIDC login maps to a local account only when the rendered localpart matches it | Plan a reconciliation step for accounts created before SSO, and test the match with a non-production user |
What happens to existing local Synapse accounts
A local Synapse account keeps its password unless the OIDC mapping produces the same localpart. Synapse identifies a user by a full Matrix ID such as @alice:example.com, and the localpart (the part before the colon) is what the OIDC mapping generates from the authentik claim you choose. If the mapping yields the localpart of an existing account, the SSO login attaches to that account and the local password still works. If the mapping yields a different localpart, for example because the claim is an email address or a display name, authentik signs the person in to a new, empty Matrix user. Their history, rooms and devices remain under the old ID, and nothing in Synapse merges the two. Before you go live, list the existing localparts, then confirm that your authentik mapping reproduces them for each account. Treat any mismatch as a separate account to plan for, not as a bug to fix later.
Decide whether password login stays enabled alongside SSO. Keeping it open gives administrators and users a fallback if authentik is down, but it also means a second credential store must be protected, monitored and removed when staff leave. Closing it removes that path entirely, so confirm first that every active user can complete an SSO login and that you have a separate administrative route for emergencies. Plan the cutover in stages: map and test with a small group of accounts, announce the new login path with a date, then disable password login for the remaining users once the mapping has been confirmed against real accounts. Confirm with your own environment whether your Synapse version and clients handle the transition as you expect, since the authentik integration guide for Matrix Synapse describes the configuration but not your user population.
Test every mapping change against a copy of the Synapse PostgreSQL database before touching the live server. The Synapse upgrade notes warn that rolling back can be difficult because schemas change between releases, and a mapping error can create duplicate accounts that are hard to reverse cleanly. Restore a recent backup into a staging instance, point it at a test authentik application, and log in with representative accounts, including one whose email address differs from its username. Check the resulting Matrix IDs, room membership and admin rights. Only after those checks pass should you apply the same change to production, during a window you have announced to users.
Securing the authentik to Synapse trust relationship
Signing users in with authentik gives it authority over every Synapse account that logs in through OIDC, so the connection needs the same care as the homeserver itself. The cards below cover the credentials, transport, redirect targets, access scope and network exposure that together define that trust.
Protect the client secret
The OIDC client secret lets Synapse exchange authorization codes with authentik, so anyone holding it can impersonate the relying party. Keep it out of version control, load it from a secrets store or a file readable only by the Synapse service user, and rotate it in both authentik and homeserver.yaml in the same change window. Confirm that backups and logs do not capture it.
Require HTTPS on both sides
Synapse should be reached over HTTPS at its public name, and the authentik issuer and endpoints Synapse calls should also use HTTPS with certificates Synapse trusts. Check that the discovery URL and token endpoints in your provider configuration match the certificate names, and that no plain HTTP path exists for the authorization redirect. Mixed transport lets tokens and codes be read on the wire.
Restrict redirect URIs to the Synapse callback
In the authentik provider, list only the exact callback URL that your Synapse homeserver serves for OIDC, including scheme, host and path. Wildcards or extra entries let an attacker redirect an authorization response to a host they control. Review this list after any change to server_name, reverse proxy paths or the Synapse public base URL.
Limit who can sign in
Bind the authentik application to the groups or policies that should reach Synapse, so that authentik refuses the login before Synapse sees it. Confirm that disabled, deactivated or service accounts cannot complete the flow. Remember that Synapse creates a local account on first successful login, so the authentik access policy is the main gate for new Matrix users.
Firewall the federation listener
Synapse federates on port 8448 by default. The Synapse docs recommend firewalling the federation listener in addition to configuration, so only the peers you intend to serve can reach it. Use federation_domain_whitelist to limit federation to listed domains, or set it to an empty list to disable federation entirely. Decide this policy before users are onboarded, because it changes who can join rooms with your users.
Common Synapse SSO failures and how to fix them
This table pairs common failures when signing Synapse users in through authentik with their likely cause and fix. Read each row against the symptom you see, then check the Synapse configuration manual and authentik logs before changing settings.
| Failure | Likely cause | Fix and first checks |
|---|---|---|
| Redirect URI mismatch at login | The redirect URI registered in the authentik provider does not match the callback Synapse sends, often because the public base URL or path differs from server_name or a reverse proxy rewrite. | Set the redirect URI in the authentik provider to the exact callback path Synapse uses, with matching scheme and host. Check the authentik logs for the rejected redirect and compare it with the oidc_providers settings in the Synapse configuration manual. |
| Wrong issuer URL | The issuer in oidc_providers points to the wrong application slug, a trailing slash difference, or an authentik host that Synapse cannot reach over HTTPS. | Copy the issuer from the authentik provider's OpenID configuration for this application and paste it exactly into the Synapse issuer field. Confirm Synapse can fetch the discovery document from the server running it. |
| Unexpected user IDs after a server_name change | Synapse builds MXIDs from server_name, so changing it makes new logins create different user IDs from those already stored, and existing rooms and memberships stay tied to the old identifiers. | Treat server_name as fixed once users exist. If it must change, plan the identity migration first, because the Synapse upgrade notes and federation docs describe how server_name shapes identifiers. Confirm the mapping with the team before any change. |
| User mapping fails because email is unverified | The user_mapping_provider or localpart template relies on an email claim that authentik does not mark as verified, so Synapse rejects or mismaps the account. | Check which claims the authentik scope mapping sends and whether the email is verified for the user. Adjust the Synapse attribute mapping to use a stable claim such as a username, and review the mapping in the authentik logs for the login attempt. |
| Login loop behind a reverse proxy | The proxy terminates TLS but Synapse or authentik builds URLs with the internal HTTP address, or forwarded headers are not passed, so the callback never completes. | Pass X-Forwarded-Proto and Host headers, and set public_baseurl in Synapse to the external address. Confirm the proxy forwards the callback path and check both proxy and authentik logs for repeated redirects. |
| Existing local accounts conflict with SSO | A local password account already holds the localpart that the OIDC mapping would assign, so the SSO login cannot create or link the expected user. | Decide before rollout whether existing accounts are linked or kept separate. Review the Synapse user list and the mapping rules, and test with a non-production account first, since the mapping choice affects who can sign in later. |
| Federation or port errors after changes | Federation listener settings, port 8448 delegation or federation_domain_whitelist changes block remote servers, which can look like an SSO fault during testing. | Test SSO separately from federation. Review federation_domain_whitelist and delegation in the Synapse federation docs, and restrict the federation listener with a firewall rule as the configuration manual recommends. |
Questions teams ask before connecting Synapse to authentik
Does the free Open Source authentik edition support OIDC for Synapse?
Yes. The authentik pricing page lists the Open Source edition as free, and OpenID Connect is one of the standard provider types authentik documents, so an OAuth2/OIDC provider for Synapse is not an Enterprise-only feature. The Enterprise-only items on the pricing page are Google Workspace and Microsoft Entra ID integrations, mTLS client certificate authentication, privileged access management, password history, enhanced audit logging and ticket-based support. None of these is needed for the Synapse login flow itself. Confirm the edition you plan to run against the current pricing page before you commit, because feature placement can change between releases.
What drives the cost of connecting Synapse to authentik?
Cost follows the written scope, and the main drivers are the number of user populations, the state of existing accounts, the number of homeservers and the federation policy. Each additional population (staff, contractors, external partners) adds group and attribute mapping work. Existing local Synapse accounts need a decision on how their localparts map to authentik identities, which is often the largest single item. Each homeserver needs its own provider configuration and testing. Federation policy changes how much verification is needed around server_name and the federation listener. Ask any partner for a quote that lists these items separately, and ask which items are one-time work and which recur, such as upgrades and retained support.
How long does a Synapse and authentik SSO project take?
Duration depends on scope, and no fixed figure applies to every deployment. A single homeserver with one user population and no existing accounts to reconcile is a much smaller job than several homeservers with legacy local accounts and a federation policy to review. Timing is also shaped by the environment: access to the authentik and Synapse hosts, change windows, DNS and TLS certificates, and sign-off from the people who own the user directory. Ask for a timeline that breaks the work into design, build, test and cutover, and check which dependencies sit with your team.
What do we need to provide before the work starts?
The work needs a few concrete inputs from your side. Confirm the final server_name, because it fixes how user IDs such as @user:example.com are formed and is difficult to change later. Provide a running authentik instance with administrator access, the public URL where authentik is reachable, and a Synapse host you control with PostgreSQL, since the Synapse documentation recommends PostgreSQL for production. You will also need a decision on who owns the identity source of truth, the list of user populations, an export of existing local accounts, and a test group of users who can sign in before cutover. Agree these in writing so the scope matches what is delivered.
Can a competent internal team set this up without an outside partner?
Yes, a team with experience running Synapse and an OpenID Connect provider can build this alone, and the authentik integration guide for Matrix Synapse covers the provider side. The harder parts are the ones that are rarely in a quick start: planning user ID mapping for existing accounts, testing the behavior of already-registered users, reviewing federation and listener settings, and writing a rollback plan. Teams that lack recent Synapse operations experience, or that must show a documented change record for an audit, often bring in a partner for those parts. Decide which parts you will own before you start, and keep a named person accountable for the cutover.
What breaks most often when Synapse and authentik are first connected?
The most common failures are mismatched redirect URIs, issuer URLs that do not match the provider's discovery document, and user ID claims that do not map to the localpart Synapse expects. Existing local accounts can conflict with new SSO identities, so test with accounts that already exist and not only with new ones. Synapse upgrades can also change configuration expectations, and the upgrade notes warn that rolling back can be difficult because of database schema changes. Take a database backup before any version change and test the sign-in path again after each Synapse upgrade.
Does connecting SSO change how Synapse federation is secured?
Connecting SSO does not by itself change federation, but it affects how you should review it. Synapse federates on port 8448 by default, and the federation_domain_whitelist setting limits federation to listed domains, while an empty list disables it. The Synapse documentation recommends also firewalling the federation listener. Review these settings as part of the same change so that the login path and the federation path are signed off together. Confirm the policy with your security owner, because the right setting depends on whether your homeserver should talk to the wider Matrix network.
Keeping authentik and Synapse upgrades from breaking sign-in
Treat every authentik and Synapse upgrade as a change to the sign-in path, and test SSO on a staging homeserver before each one reaches production. Both products release often, so the question is not whether to upgrade but how to confirm that the OIDC flow still works afterward. On the authentik side, the security policy lists 2026.5.x and 2026.8.x as the supported lines receiving security fixes, and the project announces security releases at least 24 hours in advance. That notice window is short, so your staging environment should already mirror production's oidc_providers block, the authentik provider's redirect URI and the client secret handling before a security release arrives. Confirm with your own change calendar how quickly your team can run this check.
Synapse adds a constraint that changes the rollback plan. Its upgrade notes warn that rolling back can be difficult because of database schema changes between releases, so a bad upgrade may not be reversible by swapping images back. Before upgrading Synapse, take a PostgreSQL backup and record the exact Synapse version, the server_name value and the current oidc_providers settings. Also check the Synapse upgrade notes for the release you are moving to, since they flag Python and PostgreSQL minimum versions that can force a separate infrastructure change in the same window. Keep the two upgrades separate where possible so a failure has one cause.
Your staging test should cover the full sign-in cycle, not just the login page. Sign in with an existing local account and a new federated account, confirm that the user ID mapping still resolves to the same @user:example.com identity, and verify that a logout and a fresh login both succeed. Record the authentik and Synapse versions tested, then promote only when the results match. Ask your authentik and Synapse support channels, or your own vendor contacts, to confirm any breaking change that applies to your configuration before you schedule the production window.
