Why Matrix SSO integration decides who can sign in and who can leave
This section helps you decide how staff will sign into Matrix with the identity they already use elsewhere, and how access is removed when someone leaves. The aim is an integration that controls both the sign-in path and the account lifecycle, so that disabling a person in your directory actually stops their access to the homeserver. Treat SSO as a design decision with several parts, not a single setting. Single sign-on in Matrix is not one switch. Synapse, the most widely documented Matrix homeserver, supports OpenID Connect through its oidc_providers setting, SAML2 through saml2_config, and CAS natively. Matrix Authentication Service (MAS) works differently: it sits in front of the homeserver as an OAuth 2.0 and OpenID provider and delegates authentication to upstream OpenID Connect providers such as Keycloak, Microsoft Entra ID, Google or Authentik. MAS does not speak SAML. If your identity provider only issues SAML assertions, you will need a bridge such as Dex, which the MAS documentation recommends, or you will choose a Synapse-native SAML path. Confirm which pattern your identity provider supports before choosing the homeserver architecture. Several things make this harder than it looks. The first is account lifecycle: a successful login proves a person can authenticate today, but says nothing about whether their account should exist next month. The second is identifier mapping. A Matrix user ID has the form @user:server_name, and the mapping from your directory's subject claim, email address or username to that localpart must be deterministic, documented and tested, because a mismatch creates duplicate accounts or locks people out. The third is the gap between login and provisioning. Logging in creates or matches an account, but it does not by itself apply group membership, room access or deactivation when a person leaves. Ask your team which system is the source of truth for each of these, and which events will trigger a deactivation. Before you commit, run a small test with a pilot group. Sign in with each account type you expect, including contractors and accounts with changed email addresses. Then disable a test identity in the upstream directory and confirm that the Matrix session ends and new logins fail. Record what you find. The results will shape the provisioning design, which is where the real offboarding control sits.
Which identity components are involved in a Matrix SSO build
In a Synapse-only build, the homeserver itself talks to the identity provider. Synapse's configuration manual documents three single sign-on paths: OpenID Connect through the oidc_providers setting, SAML2 through saml2_config (which uses the pysaml2 library), and CAS. When a user starts a login, the Element client redirects to Synapse, Synapse redirects to the chosen provider, and the provider returns an assertion or token that Synapse validates before it creates or maps the local Matrix account.
The settings you will touch most often are:
- oidc_providers: issuer, client ID and secret, scopes, and the attribute mapping that turns claims into a Matrix user ID and display name.
- saml2_config: the metadata source, the entity ID, and the attribute mapping for the user identifier.
- CAS: the CAS server URL and the mapping from the CAS user field to a localpart.
- Redirect and client URLs: the callback addresses registered at each identity provider must match your public homeserver name exactly.
- Registration behavior: whether first login creates an account automatically or only links to an existing one.
Before go-live, confirm with your identity team which attributes they release and whether the provider supports the SAML or OIDC version your Synapse release expects. Check the current Synapse configuration manual for the exact option names in your release.
Matrix Authentication Service (MAS) moves the login flow out of Synapse. It is an OAuth 2.0 and OpenID provider for Matrix that implements the OIDC-based authentication described in MSC3861. Clients authenticate against MAS, and MAS authenticates users against one or more upstream OpenID Connect providers. MAS then issues the tokens Synapse trusts, so the homeserver no longer handles passwords or SSO callbacks directly.
The upstream provider list in MAS documentation includes Keycloak, Microsoft Entra ID, Google and Authentik. Responsibilities split as follows:
- MAS owns the session, token issuance and the user-facing login and consent pages.
- The upstream OIDC provider owns the credentials, multi-factor policy and the source of identity claims.
- Synapse owns the Matrix account, room membership and message data, and trusts tokens issued by MAS.
- Upstream mapping rules decide which claim becomes the Matrix localpart and how display names are populated.
- Administrative accounts are managed through MAS and must be kept distinct from ordinary user accounts.
MAS does not support SAML. If your directory only speaks SAML or LDAP, you need a bridge component in front of MAS, covered in the next tab. Confirm with the MAS documentation that the release you deploy matches the Synapse release you run, because the two must be upgraded together.
When the corporate identity source is SAML or LDAP, MAS documentation recommends placing a bridge such as Dex between the two. Dex is an OpenID Connect provider that federates to upstream SAML, LDAP and other connectors. In this design, MAS sees Dex as a standard OIDC upstream, and Dex translates the directory's answer into OIDC claims. The directory remains the source of truth for passwords, group membership and deprovisioning.
The bridge adds one component to build, secure and monitor:
- SAML connector in Dex maps the SAML assertion attributes to the claims MAS expects.
- LDAP connector performs bind and search against the directory, so the bind account and search base need least-privilege design.
- Dex client registration is created for MAS, with the redirect URI matching the MAS callback.
- Certificate and signing keys for SAML and TLS for LDAP must be rotated under a documented process.
- Group claims pass through Dex and decide room or admin access only if your MAS configuration maps them.
Because Dex sits in the authentication path, an outage there blocks all new logins even though Synapse and MAS are healthy. Ask your team to define where Dex runs, how it is restarted, and who receives its logs.
Authentication and provisioning are separate concerns. Element Server Suite (ESS) is the packaged Element deployment on Kubernetes with Helm charts. Per Element's product description, ESS includes Synapse Pro, MAS, LDAP and SCIM integration, and auditing. The LDAP and SCIM integration is about who has an account and what state it is in, which is different from the login step itself. SCIM is a provisioning protocol that lets an identity source create, update and deactivate users, and LDAP integration lets the platform read directory entries.
For planning, separate the two jobs:
- Login happens through MAS and the upstream provider, once per session.
- Provisioning creates, updates and deactivates accounts ahead of or alongside login.
- Deprovisioning is the step most often missed. Confirm that removing a user in the directory deactivates the Matrix account and ends active sessions.
- Attribute ownership should be agreed between the identity team and the Matrix administrators before mapping is built.
- Edition scope: confirm which ESS edition includes the LDAP and SCIM features you need, since the suite is offered in several editions.
Ask Element and your identity team to confirm the supported SCIM version and the exact deactivation behavior in the release you plan to run, and test a leaver scenario before production.
Synapse native SSO or Matrix Authentication Service
This table compares five ways to connect Matrix sign-in to an identity source: Synapse OIDC, Synapse SAML2, Synapse CAS, Matrix Authentication Service with an upstream OIDC provider, and a Dex bridge for SAML or LDAP. Read each row against your identity provider, your protocol requirements and how much extra service your team is willing to run. No single option is the right default for every organization.
| Option | When it fits | Operational cost | Main trade-off |
|---|---|---|---|
| Synapse OIDC (oidc_providers) | Your identity provider speaks OpenID Connect and you want sign-in handled inside Synapse without another component. | Configure the provider block in the Synapse configuration and keep client secrets rotated. No additional service to patch or monitor. | Synapse remains responsible for authentication flows, so upgrades of Synapse must be tested against your provider settings. |
| Synapse SAML2 (saml2_config) | Your identity provider only offers SAML 2.0 and you need Synapse to validate assertions directly. | Maintain SAML metadata, certificates and attribute mappings inside Synapse. Certificate renewal becomes a recurring task tied to the homeserver. | Depends on pysaml2 as bundled with Synapse, so SAML-specific configuration changes must be verified after each Synapse release. |
| Synapse CAS | Your organization already runs a CAS server and users, applications and policies are managed there. | Point Synapse at the CAS server and test ticket validation. Operational effort is mainly tied to the CAS platform you already run. | CAS is a narrower protocol than OIDC, so confirm attribute release and logout behavior meet your requirements before committing. |
| Matrix Authentication Service with an upstream OIDC provider | You want a dedicated authentication service for Matrix that delegates login to an OIDC provider such as Keycloak, Microsoft Entra ID, Google or Authentik. | Run and patch MAS as an extra service, with its own database, TLS endpoints and upgrade cycle. Plan monitoring for both MAS and Synapse. | MAS does not support SAML, so SAML-only sources need a bridge. Adds one more component in the login path. |
| Dex bridge for SAML or LDAP sources | Your sources are SAML or LDAP only and you want MAS, which speaks OIDC, to still authenticate those users. | Run Dex as a further service with its own configuration, connectors and certificates, alongside MAS and Synapse. Connector changes need regression testing. | Two extra layers between users and Matrix increase troubleshooting paths. Confirm the connector and claim mapping for each source with your team. |
How to build Matrix SSO step by step
This sequence takes a Matrix deployment from a new homeserver to users signing in through the organization's identity provider, with access removed when people leave. Each step closes with a check you can run before users depend on the setup. Platform engineers, identity administrators and the security team each own part of the work.
Confirm the homeserver and server_name
The platform team confirms which homeserver implementation and release the organization will run, then fixes the server_name that appears in every user ID, such as @user:example.com. Treat server_name as permanent, because it is hard to change once accounts and rooms exist. Confirm the PostgreSQL and Python versions the chosen release requires, and decide whether federation is open, limited to listed domains or switched off. The step is done when the server_name is documented, the homeserver starts on a test host, and the identity team agrees on the domain used in user IDs.
Choose the login architecture
The identity lead chooses between two paths. Synapse can sign users in directly through its OpenID Connect, SAML2 or CAS settings. Matrix Authentication Service handles sign-in through an upstream OpenID Connect provider such as Keycloak, Microsoft Entra ID, Google or Authentik, and it does not support SAML itself, so a SAML estate needs a bridge such as Dex or a different path. LDAP needs its own design decision. Write a one-page architecture note naming the identity provider, protocol and component. The step is done when the security and identity owners sign off that note.
Register the client at the identity provider
The identity administrator creates an application or client record for Matrix in the identity provider, using the protocol chosen in the previous step. The redirect URI must match the callback path the chosen component expects, built from the public URL of the homeserver or Matrix Authentication Service, so check the component's documentation for the exact path. Limit the client to the users or groups who should reach Matrix, and store the client secret in the organization's secret manager. The step is done when a test sign-in reaches the identity provider and returns to Matrix without an error page.
Configure the chosen component
The platform engineer adds the identity provider details to the configuration of the chosen component, either the Synapse OpenID Connect or SAML2 settings or the upstream provider section of Matrix Authentication Service. Follow the configuration manual for the release in use, and keep the client secret out of plain configuration files where your deployment tooling allows. Restart or reload the service as its documentation directs. The step is done when the service starts cleanly, the logs show the provider loaded, and the login page offers the organization's sign-in option.
Map claims to Matrix user IDs and display names
The identity lead decides which claim becomes the localpart of the Matrix user ID and which claim fills the display name, then configures that mapping in the component. Prefer a stable identifier over an email address, because a user ID that has to change later is difficult to unwind. Test with several accounts, including one with unusual characters in the name, to see how each claim renders. The step is done when each test account receives the expected user ID and display name, and the mapping is recorded in the runbook.
Test a first login
Sign in with a dedicated test account through Element or another Matrix client, then check the session, the user ID, the display name and whether the account can join a test room. Repeat with a second account to confirm the mapping works for more than one identity. Review the homeserver logs for warnings about claims, redirects or token validation. The step is done when two test accounts log in, join a room and send a message with no errors in the logs. Failed logins often trace back to a redirect URI mismatch or a claim the mapping expects but the provider does not send.
Set deprovisioning and session expiry
Decide how a leaver loses access. Settle whether the identity provider disables the account and Matrix applies that change at the next login, whether sessions expire on a schedule, and how existing sessions and devices are revoked. Confirm which of these the chosen component and release support, and whether account and group provisioning needs a separate tool, such as the SCIM integration included in Element Server Suite. Disable a test account and confirm its sessions stop working in line with your policy. The step is done when the offboarding procedure is written, tested once and assigned to a named administrator.
How claim mapping and user IDs shape the rollout
The most consequential decisions in a Matrix SSO rollout are made before the first user signs in. In Synapse, each OIDC, SAML or CAS login is turned into a Matrix user ID, and the localpart and display name are populated from identity claims that your identity provider sends. Your team needs to decide which claim becomes the localpart, which claim becomes the display name, and what happens when a claim is missing or malformed. Confirm the exact claim names and attribute mappings in the Synapse configuration manual for the provider type you are using, and confirm them again if you are routing through Matrix Authentication Service with an upstream OpenID Connect provider.
Choose the stable identifier from the identity provider before anything else. A good candidate is an immutable subject value or employee number that does not change when someone marries, changes department or changes their email address. Email addresses and display names are usually poor localparts because people change them, and a localpart is much harder to change once accounts exist. Ask your directory team how the chosen attribute is populated for contractors, shared mailboxes and leavers, and whether it is ever reused. Write the decision down with the owner of the identity provider, because the rest of the rollout depends on it.
Duplicate emails need an explicit rule. Directories sometimes hold the same email address on two accounts after a rename, a merge or a service account, and a mapping that keys on email can then link two people to one Matrix account or fail for one of them. Decide whether the mapping is allowed to match an existing account by email at all, and if it is, who resolves the conflict. Identify these cases in the directory export before go-live rather than in a support queue afterward.
The server_name is the most permanent setting in the deployment. Synapse uses it to form every user ID and room identifier, so once real users exist, changing it means migrating identities rather than editing a file. Settle the domain, and whether delegation will serve user IDs such as @user:example.com from another host on port 443, before creating any account, including test accounts you plan to keep. The federation policy you choose elsewhere depends on the same value, so review the two decisions together.
Test the mapping with real directory data before go-live, not with a handful of hand-made accounts. Export a representative set of users from the directory, including leavers, contractors, accounts with missing attributes, renamed users and known duplicates, and run them through a staging homeserver with the same provider configuration. Check the resulting user IDs, display names and any account linking results against a written expected list. Repeat the test after any change to the provider's attribute release settings, since a silent change there can alter every new login. Ask your identity team to confirm who can change those settings and how they are reviewed.
What drives SSO effort and how to keep it down
This table lists the factors that most change the effort of an SSO and identity integration for Matrix, with the reason each one matters and the steps that keep it contained. Read each row as a question to settle before design starts, since most rework follows from answers left open. The main takeaway is that the number of identity sources and the choice between MAS and native Synapse login set the shape of the work, so settle them first.
| Driver | Why it changes effort | How to keep it down |
|---|---|---|
| User count and directory cleanliness | Stale accounts, duplicate identities and mismatched attributes add mapping and test work. | Remove inactive accounts, agree one unique identifier per person and confirm which attributes Matrix needs. |
| Number of identity sources | Each added source (directory, HR system, contractor store) brings another trust relationship, claim mapping and failure case. | Name the authoritative source for Matrix accounts and limit sign-in to that source where possible. |
| SAML or LDAP bridging | Synapse reads SAML2 directly, but MAS does not support SAML and its documentation recommends a bridge such as Dex for SAML or LDAP. | Confirm which protocol your identity provider offers and count any bridge as an extra component to run, patch and monitor. |
| MAS versus Synapse native login | MAS adds a separate service and needs an upstream OpenID Connect provider. Native Synapse SSO avoids that service but changes the homeserver config. | Choose one login architecture for production and avoid running two sign-in paths for the same users. |
| Number of environments | Each environment (test, staging, production) needs its own client registrations, redirect URIs and test identities. | Keep environment-specific values in configuration and automate registration so each environment is set up the same way. |
| Custom claim logic | Mapping roles, groups or departments into Matrix attributes or room permissions needs rules that must be tested again after upgrades. | Limit claim mapping to what access decisions need and document each rule with a named owner. |
| Compliance evidence for access reviews | Reviewers need to see who had access, when it was granted and removed, and which source approved it. Collecting this from several systems adds effort. | Agree the evidence list with your assessor early and export group membership and deprovisioning records on a fixed schedule. |
| Integration with existing clients | Clients and bots that rely on password login or older tokens need an updated sign-in path and retesting after each login change. | Inventory clients and bots before design and confirm each supports the chosen login flow in its build. |
How SSO differs on single node, workers, and Kubernetes
A single-node Synapse runs the main process, client traffic and federation traffic on one host, with PostgreSQL as the database. Synapse supports SSO through OpenID Connect providers (oidc_providers), SAML2 (saml2_config) and CAS, so the identity configuration lives in the homeserver config file alongside the server name and database settings. Because there is one process handling every request, the OIDC redirect and callback path resolves to the same host the user reaches directly, and there is no routing layer to reason about.
What to plan for on a single node:
- Callback URL: register the exact redirect URI Synapse expects with your identity provider, using the public hostname that clients use.
- Server name: the server_name setting fixes how user IDs are formed, so confirm it before any users are provisioned.
- PostgreSQL: the upstream documentation recommends PostgreSQL for production; confirm the minimum PostgreSQL version required by your Synapse release in the upgrade notes.
- Federation listener: if federation is restricted, the federation_domain_whitelist setting and host firewall rules still apply to the same host.
- Upgrade effects: a configuration change to SSO usually means a restart of the single process, so plan a maintenance window.
Before go-live, confirm the callback path, the provider's allowed redirect list and the behavior of login for an account that is disabled in the identity provider. Verify these against the Synapse version you run.
A worker-based Synapse splits work across the main process and several worker processes. Synapse documents that the main process and all workers connect to Redis, which relays replication between them, and that the generic worker handles client, federation and event traffic. The SSO question changes here: the OIDC callback is an ordinary HTTP request, and it must reach the process that handles client login, not an unrelated worker. A load balancer therefore needs routing rules that send the login and callback endpoints to the correct worker type.
What changes with workers:
- Routing rules: map the SSO login and callback paths on the load balancer to the worker that serves client traffic, as documented in the Synapse workers guide for your version.
- Session affinity: confirm how the login flow state is held between the redirect and the callback when more than one client-facing process is running.
- Redis: Redis carries replication between processes, so it must be reachable by every process that handles SSO traffic.
- Configuration consistency: every process must load the same identity provider settings and the same server_name.
- Test matrix: test login from each entry point the load balancer exposes, not only from one hostname.
Ask your implementer to show the routing table, the worker types assigned to each path and the test results for a login that crosses the load balancer. Confirm these details against the workers documentation for the release you deploy.
A Kubernetes deployment usually uses the Element Server Suite Helm charts, which deploy the homeserver and related components on Kubernetes. The SSO settings move from a hand-edited homeserver file into chart values, and the callback hostname becomes an ingress concern. Element Server Suite includes Matrix Authentication Service, LDAP and SCIM integration as part of the suite, so the design choice is which identity path your organization uses, not only how to set one config key.
What changes on Kubernetes:
- Chart values: confirm which SSO options your chart version exposes and where secrets such as client credentials are stored.
- Ingress: the public hostname, TLS certificate and path rules must match the redirect URI registered with the provider.
- Secret handling: store identity provider client secrets in the cluster's secret mechanism, and confirm how the chart reads them.
- Pod restarts: a configuration change rolls the pods, so check how that affects in-flight logins.
- Edition scope: confirm which components and identity integrations are included in the edition you license, since ESS Community and ESS Pro are offered separately.
Before deployment, ask the vendor or your implementer which chart version supports your chosen identity path and what the upgrade process does to SSO settings. Verify this against the Element Server Suite documentation for your edition.
Securing SSO credentials, sessions and admin access
Single sign-on turns the login page into the main control point for a Matrix deployment, so the settings that protect it deserve the same attention as the homeserver itself. The cards below cover the credentials, redirect targets, admin roles, token lifetimes, local login and network listeners that together decide who can get in and what they can do once inside.
Client secret storage
The OIDC or SAML client credentials that Synapse or Matrix Authentication Service presents to the upstream provider should live in a secrets store or an environment variable managed by your platform, not in a configuration file committed to version control. Check who can read the homeserver host, the configuration directory and the process environment, because a leaked client secret lets someone impersonate the Matrix client to your identity provider. Ask the team to document a rotation procedure and confirm that rotating the secret does not require a homeserver rebuild.
Restricting redirect URIs
Register only the exact callback URLs that your Synapse or MAS deployment uses with each upstream identity provider, including scheme, host and path. Wildcard or overly broad redirect URIs let an attacker who controls another page on the same domain receive authorization codes. Review the registration in the identity provider after every change to server_name, delegation or reverse proxy routing, since those changes often break the callback path and tempt teams to widen the allowed list.
Limiting identity groups to Synapse admins
Map admin rights only from a dedicated identity group that a small number of named operators belong to, and keep it separate from general staff groups. Synapse can make a user an admin based on claims from the upstream provider, so a broad group such as all employees would grant administrative rights to the whole company. Ask for a list of who holds the admin group, how membership is reviewed, and how removal takes effect for existing sessions.
Session and token lifetimes
Set access token and refresh behavior deliberately, because the upstream provider's session length and the homeserver's token policy both affect how long a lost or stolen device stays signed in. Confirm which lifetimes are enforced by Synapse or MAS and which are set by the identity provider, and test that deprovisioning a user in the directory ends their Matrix sessions. Document the values you choose and the reasons, since clients behave differently when tokens expire.
Disabling local password login
Where policy requires that all access goes through corporate identity, turn off local password registration and login so that the only entry point is the configured single sign-on flow. Test the setting with an existing local account, a newly provisioned user and an operator account, because some admin and recovery paths depend on local credentials. Record the break-glass procedure for the case when the identity provider is unavailable, and confirm who may use it and how that use is logged.
Keeping the admin API off public listeners
The Synapse admin API performs powerful user, room and media operations, so it should be reachable only from an internal network, a bastion or an admin host rather than through the public client listener. Confirm in the reverse proxy configuration that admin paths are blocked for external clients, and verify this with requests from outside the network. Include the admin path restrictions in your security test scope, because a proxy rule that works for the client API can still expose admin endpoints by mistake.
Federation and login exposure
Federation and single sign-on share the same homeserver, so a setting that opens federation also changes who can reach the server and which identities can interact with your users. Restricting federation to a domain allowlist, or disabling it, reduces the set of remote servers that can send events to your users, but it does not change how local users authenticate. Firewall the federation listener on port 8448 when federation is restricted, and review the login path and federation settings together before any change to delegation or public routing.
How to test that SSO works and fails safely
Before SSO goes live for Matrix, the team should be able to show, case by case, that sign-in succeeds for allowed users and fails closed for everyone else. Test the full path: the client, Synapse (or Matrix Authentication Service if you use it), and the upstream identity provider. Each test case needs a named tester, a test account, an expected result and a place to record what actually happened. Start with the happy paths. A first login by a new user should create the Matrix account with the expected user ID, display name and any mapped attributes, such as email or group membership, if your configuration maps them. A returning login should reuse that same account rather than create a duplicate. Check that the Matrix user ID matches the mapping you designed, because a mismatch here is hard to undo once people have joined rooms. Then test the cases that matter for access control. A user in an excluded group should be refused at sign-in and should not gain a session or an account, depending on how your provider and Synapse settings are configured. Confirm this with the identity provider's group claims, not just with the client's error message. Revoke a test user in the identity provider and confirm they lose access at the next authentication point. Also test an expired session and a wrong redirect URI, which should produce an error at the provider and never a token issued to an unregistered address. Finally, simulate an identity provider outage and confirm that existing logins behave as your continuity plan says and that new logins fail with a clear message rather than hanging. Testing must cover both Synapse and each client your organization uses, including the desktop, web, mobile and any third-party client that accepts Matrix logins. Clients handle redirects, token refresh and error screens differently, so a flow that works in one client may break in another. Record the client version tested, since client releases change this behavior. Ask your implementation partner or internal team to write the expected user-facing message for each failure, and check the Synapse and provider logs for the same event. Logs should show the attempt, the provider used, the outcome and a reason code, without recording passwords, tokens or full claim sets. Confirm with your provider and your Synapse version which log lines and fields are emitted, and keep the results as evidence for your change record.
What to monitor, back up and document after SSO goes live
This table sets out what operations teams should watch, protect, test and write down once single sign-on works for Matrix. Each row names the item, what to do with it and the evidence to keep, so the team can tell when the identity path is degrading before users are locked out. Treat the rows as the minimum operating baseline for a Synapse or Matrix Authentication Service deployment with an upstream identity provider.
| Area | What to do | Evidence to keep |
|---|---|---|
| Login failures | Track failed SSO callbacks, token exchange errors and account mapping rejections in homeserver logs and alert on sustained increases | Dashboard or log queries, alert definitions and the owner who responds |
| Identity provider certificates and secrets | Record the expiry date of each signing certificate and OIDC client secret, and schedule rotation before expiry in both the identity provider and the Matrix configuration | Rotation calendar, change tickets and a test login after each rotation |
| Identity configuration backup | Back up the Synapse or MAS configuration, OIDC client registrations and secret storage locations, stored separately from the running system | Backup inventory, restore test record and access list for the backup store |
| Secrets handling | Keep client secrets and signing keys in a managed secret store with restricted access, and confirm that backups of secrets are encrypted and tested for restore | Access review results and secret inventory with owners |
| Upgrade testing against the SSO path | Before each Synapse or MAS upgrade, run a staging login through the full SSO flow, including new user creation and existing user relinking | Staging test script, results per release and the release notes reviewed |
| Claim mappings | Document which identity provider claims map to Matrix user IDs, display names and any attributes, and the fallback behavior when a claim is missing | Mapping specification kept under version control with the change history |
| Group and access rules | Write down each group rule, the Matrix role or room it grants, and who approves changes to it | Rule register with owner, approval record and last review date |
| Offboarding procedure | Define how a departed user is disabled in the identity provider, how sessions are ended in Matrix and who handles room ownership and retained messages | Written runbook, periodic test of the procedure and a record of each execution |
Questions buyers ask before bringing in an SSO partner
What drives the cost of Matrix SSO and identity integration?
The main cost drivers are the login path you choose, the number of identity sources, and how much provisioning work sits behind the login. Signing users in through Synapse's native OIDC, SAML2 or CAS support is a different job from putting Matrix Authentication Service (MAS) in front of an upstream OpenID Connect provider, and an LDAP or SCIM requirement adds more. Other drivers include attribute and group mapping, the number of environments (development, staging and production), testing with each client, and documentation for your administrators. The build is mostly one-time work. Upgrades, identity provider changes and new clients recur. Ask any partner to split the quote into design, build, testing, handover and ongoing support, and to state which identity sources and environments the price covers.
How long does Matrix SSO integration take to complete?
No fixed duration applies to every environment, so treat any single number with caution. Timing depends on whether the work targets Synapse directly or MAS, how many upstream providers must be connected, how quickly directory and identity provider access is granted, and how many environments must pass testing before production. Organizations with a single modern identity provider and a clean test tenant usually move faster than those with several directories, legacy claims or change approval windows. Ask for a written plan with milestones and dependencies, and confirm which of your teams must approve each step, since those approvals often set the pace.
What does the client need to provide for SSO integration?
Plan for four groups of inputs before work starts. First, directory access: read access to the users, groups or attributes that the login flow will use. Second, identity provider administrator rights, or a named administrator who can register the Matrix client application, set redirect URIs and configure claims. Third, test accounts in every identity source, including accounts for users who should be denied access, disabled users and users in each group. Fourth, infrastructure details: the server name, DNS records, TLS certificates for the homeserver and MAS hostnames, and a staging environment that matches production closely enough to prove the flow. Agree on who owns each input and how quickly it will be provided.
Can an internal team set up Matrix SSO without an outside partner?
Yes, an experienced internal team can do this alone, provided it has skills in three areas: identity protocols (OIDC, SAML and claim design), Synapse or MAS operations, and testing across clients. The hardest parts are usually not the initial configuration but the edge cases: mismatched server names, redirect URI errors, missing claims, deprovisioning gaps and changes to the upstream provider. Synapse upgrade notes also warn that rolling back can be difficult because of database schema changes, so plan changes carefully in either case. If your team lacks one of these skills, a fixed-scope engagement can cover the gap. Ask for the scope in writing, including who handles upgrades after go-live.
Does Matrix Authentication Service support SAML?
No. Matrix Authentication Service does not support SAML. It is an OAuth 2.0 and OpenID provider that uses upstream OpenID Connect providers such as Keycloak, Microsoft Entra ID, Google and Authentik. For a SAML-only identity provider, the Matrix documentation recommends a bridge such as Dex, which accepts SAML and exposes OIDC to MAS. A second option is to keep authentication in Synapse, which supports SAML2 through its saml2_config setting using pysaml2. Confirm which path fits your identity provider, your Synapse version and your support model before choosing, because each path adds its own configuration and testing work.
Can Synapse authenticate users with SAML 2.0 directly?
Yes. The Synapse configuration manual describes SAML2 support through the saml2_config section, which uses pysaml2 as the underlying library. This keeps the login flow inside the homeserver, which can suit a smaller deployment with one identity provider. The trade-off is that you must maintain the SAML settings in the homeserver configuration, check them after each Synapse upgrade, and test attribute mapping and logout behavior with each client. Organizations that already plan to run MAS for OIDC may prefer to keep one login path. Confirm the current Synapse configuration options against the version you run, because the documentation is the authority for setting names and defaults.
What usually breaks in Matrix SSO integrations after go-live?
The most common failures involve configuration values that look correct but do not match exactly. Check that the server_name and the public hostnames match the redirect URIs registered with the identity provider, that certificates are valid and renewed, and that claim names and group mappings still exist after a directory change. Deprovisioning is another weak point: a user disabled in the directory may keep an active Matrix session unless the login path and session handling are tested. Upgrades also cause trouble when Python or PostgreSQL versions fall behind the minimums that Synapse requires. Build a test script that covers login, logout, a denied user and a disabled user, and run it after every change.
How DeployOpen works on this
DeployOpen plans, implements, integrates, documents and supports self-hosted open-source platforms inside the client's own infrastructure, including Matrix SSO and identity integration. Work follows a written scope agreed before it starts, so the choice of identity path, upstream provider and user provisioning is settled on paper before any configuration changes.
How we scope
- Confirm whether Synapse signs users in directly over OIDC, SAML or CAS, or whether Matrix Authentication Service fronts an upstream OIDC provider.
- Record the upstream identity provider, its version and claims, and who administers it on the client side.
- Agree in writing how users are provisioned, deprovisioned and mapped to Matrix roles, and which LDAP or SCIM paths are in scope.
How we build
- Configure the chosen identity path in a non-production environment, with server_name and login flows fixed before users arrive.
- Test sign-in, logout, account linking, expired sessions and deprovisioning against each identity source in scope.
- Keep identity configuration in version-controlled files so changes can be reviewed, repeated and rolled back cleanly.
How we hand over
- Deliver configuration, a runbook for the identity path and a record of the tests run against each sign-in flow.
- Document how to rotate client secrets, change upstream provider settings and onboard or remove users from the identity source.
- Walk the client's administrators through login troubleshooting, so they can diagnose common failures without escalation.
How we support
- Ongoing support and upgrades are available as a retainer, covering identity configuration through Synapse and MAS releases.
- Retesting of sign-in flows is repeated after upstream provider changes, certificate renewals and homeserver upgrades.
- Confirm with the client's identity team who owns each change, since support boundaries depend on the written scope.
