How Keycloak SAML SSO works for Mattermost sign-in
Keycloak can act as the SAML 2.0 identity provider for Mattermost, with Mattermost acting as the service provider. The integration is a SAML configuration, not a separate connector, and it follows the steps in Mattermost's guide for configuring SAML with Keycloak. This matters for a self-hosted Mattermost server that already sends staff to a central identity provider: Keycloak handles the sign-in step, and Mattermost trusts the identity it receives. Keycloak is open source under the Apache 2.0 license and supports SAML 2.0, OpenID Connect and OAuth 2.0 in one server, so the same identity service can serve Mattermost and other internal applications. The Mattermost guide was tested with Keycloak v26.4.0. Confirm the version your team plans to run against that guide, because the current Keycloak release is 26.8.1. Keycloak documents that breaking changes in minor releases are opt-in, but the SAML settings should still be retested after any upgrade.
The sign-in sequence is short, but each step depends on settings made on both sides. A user selects the SAML option on the Mattermost login page, and the browser is redirected to Keycloak with a SAML authentication request. Keycloak checks for an existing session or prompts for credentials, along with any additional authentication steps configured in the realm. It then returns a signed SAML response to Mattermost's assertion consumer service, containing an assertion about the user. Mattermost should validate the signature and the issuer, audience and time conditions before it matches or creates the account. In the documented setup the Name ID format is email, so an email address changed in Keycloak changes the identity Mattermost sees. Decide early how email changes, account matching and account deprovisioning will be handled.
Confirm the plan entitlement before scoping. Mattermost's pricing page lists SSO (SAML, OIDC, OAuth) and AD/LDAP user sync as included from the Professional plan, and it does not publish prices, directing buyers to contact sales. Mattermost sells its plans as prepaid annual subscriptions based on seat licenses, so ask the vendor to confirm in writing which plan covers the number of users you expect. Keycloak's open source project carries no license fee of its own, but the costs are the servers and database it runs on, the people who operate and upgrade it, and the time to test SAML changes. If you choose a supported distribution such as the Red Hat build of Keycloak, that is a separate subscription. A quote for this work should show the Keycloak build, the Mattermost configuration, testing and handover as separate lines.
Three checks protect the rollout. First, sign in with an ordinary staff account and an administrator account, and confirm that the email address, given name and surname reach Mattermost as expected. Second, record the SAML signing certificate, its expiry date and the person responsible for renewing it, because a lapsed certificate can stop all SAML sign-ins at once. Third, keep a documented way for a local administrator to sign in if the identity provider is unavailable, and decide who may change the Keycloak SAML client. Also plan the order of Mattermost server and Keycloak upgrades, since either change can affect SAML behavior, and retest both in staging before production.
Prerequisites for Keycloak SAML SSO with Mattermost
Six items need a decision or a check before you change any SAML settings. Each one affects the next step, from the client configuration in Keycloak to the certificates and URLs that Mattermost trusts. Confirm them with your Mattermost account contact and your Keycloak platform owner first.
Mattermost server version and plan
Record the Mattermost server version you run and the plan your organization holds. The Mattermost guide lists this SAML setup as available from the Entry plan, but the pricing page places SSO, including SAML, from the Professional plan. Confirm with Mattermost which applies to your contract before you state a plan in the project scope. Check the server version against the release you intend to run, since monthly releases and Extended Support Releases have different support windows.
Keycloak version compatibility
The Mattermost guide was tested with Keycloak v26.4.0, and the current Keycloak release is 26.8.1, published October 13, 2026. Confirm that the version you deploy works with the steps in the guide before you copy any client settings. Keycloak plans four minor releases a year and states that breaking changes in a minor release are opt-in, so pin the exact version and review the upgrading guide before you move it.
Production database for Keycloak
Keycloak's supported production databases include PostgreSQL 14 to 18, along with several other engines. The default dev-file database is meant for development only and should not hold the realm that Mattermost depends on. Confirm the database version, the backup method, and whether Keycloak will migrate its schema automatically at startup or through SQL that your team applies. If you plan a clustered design, confirm that the database replicates synchronously, as Keycloak's high availability designs require.
HTTPS hostnames for both systems
Mattermost and Keycloak each need a stable HTTPS hostname that users and the other system can reach. The SAML client in Keycloak and the SAML settings in Mattermost both reference these addresses, so a later change means reconfiguring both sides. Confirm the public names, the certificates issued for them, and whether internal DNS resolves the same names for the Mattermost server. Decide these names before you build the client, not during testing.
Test realm and test users
Create a separate test realm in Keycloak so you can validate the Mattermost sign-in flow without changing production users or clients. Add test accounts with an email address, a given name and a surname populated, because the guide's attribute mappers read those values. Confirm that the test users sit in the same group or role model you plan to use in production. Disable or remove the test realm once the review is complete.
Certificate and key material
The guide configures encrypted assertions with the AES_256_GCM algorithm, so the key material must exist before you save the SAML client. Decide who generates the keys, where the private keys are stored, and who may export them from the Keycloak admin console. Confirm the validity period and the rotation process, because an expired certificate stops sign-in for every user. Record the owner of the certificates on both the Mattermost and Keycloak sides.
Choosing the SAML client settings Mattermost expects
The Mattermost Keycloak guide sets a small number of SAML client values, and Mattermost's SAML settings must use the same values. The client ID is mattermost, which is the identifier Keycloak uses for the SAML client and the name Mattermost expects in the assertion exchange. Before you configure anything, record the service provider details that your Mattermost site generates from its public URL. A mismatch in the site URL, the scheme or a trailing slash is enough to make Keycloak reject logins, so check these values in both systems before testing with users.
The Name ID format is set to email, which tells Keycloak to send each user's email address in the NameID element of the assertion. Whether Mattermost reads the NameID or a separate attribute depends on how its SAML settings are filled in, so confirm which field the Mattermost identifier setting reads. The X500 mappers for email, givenName and surname are separate from the identifier. They supply the profile values Mattermost uses to create accounts and show names, so an empty or misnamed mapper usually produces accounts with missing details rather than a failed login.
Matching users by email has a clear advantage. The address is familiar to administrators and users, it usually matches the accounts already created by email invitation, and it is often the same value held in the corporate directory. The cost appears when email changes. A name change, a domain consolidation or an alias update can cause Mattermost to create a second account or fail to match an existing one. A stable identifier, such as an employee number or a directory object ID, avoids that problem, but it requires Keycloak to hold that attribute for every user, a matching mapper, and Mattermost configured to match on it. Choose the identifier before go-live, because changing it later means reconciling existing accounts.
Encrypted assertions with the AES_256_GCM algorithm mean Keycloak encrypts the assertion so that only Mattermost can read its content. Mattermost must hold the matching private key and accept the chosen algorithm in the version you run. Confirm both before rollout, and check the Keycloak side and the Mattermost side against the same written values. The guide was tested with Keycloak 26.4.0, while the current Keycloak release is 26.8.1. Before upgrading Keycloak, run a test login with a non-administrator account, confirm that the algorithm and key settings still match, and record the final values in your change documentation.
Configuring Keycloak and Mattermost SAML SSO step by step
This sequence configures Keycloak as the SAML identity provider for Mattermost, from the SAML client and encrypted assertions through attribute mappers and the System Console settings. Each step closes with a check, and the sequence ends with a non-administrator sign-in that confirms the assertion, NameID and user profile arrive as expected.
Create or select the Keycloak realm
In the Keycloak admin console, either select the realm that holds your workforce accounts or create a dedicated realm for Mattermost. The Mattermost Keycloak guide was tested with Keycloak v26.4.0, so confirm your server version or check the guide for differences before you begin. Create or confirm a test user who is not an administrator and has an email address, because the email value becomes the sign-in identity. Done when the realm is enabled and the test user can sign in to the Keycloak account page.
Create the SAML client with ID mattermost
In the selected realm, create a SAML client with the client ID mattermost, as the Mattermost Keycloak guide specifies. Set the Name ID format to email so Keycloak sends the user's email address as the subject identifier in each assertion. Confirm in the Mattermost SAML documentation which attribute Mattermost uses to match accounts, and keep the email values in Keycloak consistent with your directory. Done when the client appears in the client list with the ID mattermost and the Name ID format shows email.
Set the Mattermost ACS and metadata URLs
Copy the Assertion Consumer Service URL and the metadata URL for your Mattermost server from the Mattermost SAML documentation, then enter them in the client settings as the guide directs. These values are built from your Mattermost site URL, so use the exact address users will open, including the scheme and any path prefix. A mismatch prevents the login response from being accepted, so compare the values character by character. Done when the client settings show the Mattermost ACS URL and the Mattermost server address loads in a browser.
Enable encrypted assertions with AES_256_GCM
On the client, turn on encrypted assertions and set the encryption algorithm to AES_256_GCM, as the Mattermost Keycloak guide specifies. Keycloak encrypts the assertion for the client, so confirm from the guide which certificate or key Mattermost must hold to decrypt it. Store any private key material in your secrets management system, not in a shared document. Done when the client saves with encryption enabled and you have recorded where the matching certificate or key is kept for the test step.
Add email, givenName and surname mappers
Add three attribute mappers to the client using the X500 email, givenName and surname attribute names, each mapped to the matching user property in Keycloak. These attributes let Mattermost populate the user profile at first login, so names shown in channels come from the identity provider. Use the attribute names exactly as the Mattermost guide lists them, because a typo can silently produce an empty profile field. Done when a test assertion or SAML tracing output shows all three attributes with values for the test user.
Export identity provider metadata for Mattermost
From the realm's SAML descriptor, export the identity provider metadata that Mattermost needs, following the steps in the Mattermost guide. Treat the file or URL as the single source for this configuration, and record the realm name and export date so you can reproduce it after any certificate rotation. Metadata includes signing certificate details, so store copies as configuration assets with controlled access. Done when you have a metadata file or URL that opens and contains the entity ID for your Keycloak realm.
Enter SAML settings in the System Console
In Mattermost, open the System Console and go to the SAML settings under the authentication or SSO area. Enable SAML, then enter the identity provider values from the metadata, along with the certificate and attribute settings that the Mattermost SAML documentation describes. Confirm that your plan includes SAML, since Mattermost's pricing page lists SSO as included from the Professional plan. Field labels can change between Mattermost releases, so check them against the current documentation. Done when the settings save without error and the sign-in page offers a SAML login option.
Test sign-in with a non-admin account
Sign in to Mattermost as the test user who is not a system administrator, starting from the SAML login option. Keycloak should redirect the user to its login page and then return them to Mattermost. Confirm the NameID in the assertion matches the user's email address, and check that Mattermost created the profile with the given and family names. If sign-in fails, review the Keycloak user events and the Mattermost server log before changing any settings. Done when the test user is signed in to Mattermost with a provisioned profile that matches the directory record.
Mapping Keycloak user attributes to Mattermost fields
This table lists each Keycloak mapper and NameID setting used in the Mattermost SAML guide, the SAML attribute or identifier it sends, the Mattermost field it populates and the check to run before go-live. Read each row as a pair: the Keycloak setting on the left must produce the value Mattermost expects on the right. The main takeaway is that the email address does double duty as the NameID and as an attribute, so a single mismatch between them is the most common cause of duplicate or unmatched accounts.
| Keycloak source | SAML attribute or NameID | Mattermost field | Check to confirm |
|---|---|---|---|
| Email mapper (X500 email) | X500 email attribute carrying the user's email address | Sign in as a test user and confirm the Mattermost profile email matches the Keycloak user record exactly, including case | |
| givenName mapper | X500 givenName attribute carrying the user's first name | First name | Confirm the first name appears on the Mattermost profile after a test login and updates when changed in Keycloak |
| Surname mapper | X500 surname attribute carrying the user's last name | Last name | Confirm the last name appears on the Mattermost profile after a test login and that users with no surname still sign in |
| NameID format set to email | NameID value in the SAML assertion, sent as the user's email address | Authentication identifier used to match the account | Confirm the NameID in a decrypted test assertion equals the email attribute value for the same user |
How certificate handling and encrypted assertions affect the rollout
Encrypted assertions change who must be able to read what. When Keycloak encrypts a SAML assertion with the Mattermost service provider's public key, only the holder of the matching private key can decrypt it. The Mattermost guide for Keycloak sets the encryption algorithm to AES_256_GCM with encrypted assertions, so the SAML client on the Keycloak side and the SAML settings on the Mattermost side must agree on the same certificate pair. If the private key on the Mattermost side is missing, rotated without a matching change, or pasted in a different form, sign-in fails at the assertion step even though the identity provider itself is healthy. Plan for this during the build, not after the first login test.
Keycloak signing and encryption certificates need a documented lifecycle before go-live. Decide where each certificate and key is stored, who can export them, how the export is recorded, and how a rotation is scheduled and approved. Keycloak keeps its realm keys in its own configuration, and the SAML client exposes the certificate that Mattermost must trust. Confirm with your Keycloak deployment method how those keys are created, exported and replaced. If you run the Keycloak Operator and manage SAML clients through KeycloakSAMLClient custom resources, the certificate handling may be expressed in the resource definitions and in the secrets they reference, so the rotation procedure belongs in your change process and in version control, not in a manual console session.
Certificate expiry is the most common silent outage in this setup. A certificate that expires on either side stops assertions from validating or decrypting, and users see a generic login failure. Put every expiry date on a calendar owned by a named person, alert before the date, and test the rotation in a non-production realm or environment first. Confirm with Mattermost how it reloads SAML certificates in your server version and whether a restart is required, because that determines the maintenance window. Also confirm the Mattermost SAML settings that reference the identity provider certificate and the service provider key, since these fields are the ones that must change together.
Any key change requires metadata updates on both sides. When Keycloak issues or rotates a signing or encryption certificate, the Mattermost configuration must receive the new public certificate, and when the Mattermost encryption certificate changes, the Keycloak SAML client must receive the new public key. Treat these as one change with a single owner, a written rollback path and a verification step that completes a test login with a non-administrator account. Keep the old certificate available until the new pair is confirmed, so a failed change can be reversed without rebuilding the client.
Private keys must stay out of shared chat, tickets and email. A key pasted into a Mattermost channel, a Jira issue or a support thread becomes readable by everyone with access to that location and is difficult to revoke completely. Use your secrets manager or the Kubernetes secret mechanism your platform team already governs, restrict read access to the people who run the rotation, and reference secrets by name in change records instead of copying their values. Ask your DeployOpen team and your Keycloak and Mattermost administrators to confirm the exact steps for your versions and deployment method before the first production change.
Hardening Keycloak SAML SSO for Mattermost
These controls span the Keycloak identity provider, the Mattermost service provider and the operating practices around them. Work through them before go-live and again after each Keycloak upgrade, certificate change or Mattermost SAML edit. They support your own control design, but an independent auditor decides any assessment result.
TLS on both hostnames
Keycloak and Mattermost each serve their own hostname, and both need valid TLS certificates from a certificate authority your browsers and servers trust. Check that the redirect and assertion consumer URLs use https, that the Mattermost site URL matches the hostname in the SAML client settings, and that the certificate chain is complete on every node behind a load balancer. Self-signed certificates or mismatched hostnames often cause login loops or rejected assertions that look like SAML faults. Confirm the exact URLs against the Mattermost Keycloak guide before go-live.
Assertion encryption and private keys
The Mattermost guide sets the encryption algorithm to AES_256_GCM with encrypted assertions, so Mattermost must hold the matching private key to read them. Store that key and any Keycloak keystore material in a secrets store, not in realm exports, Git repositories, container images or chat. Decide who can read the store, how keys reach the Keycloak container at startup, and how you would revoke a leaked key. Replacing a certificate without updating Mattermost stops all SAML logins at once, so schedule key rotation as a planned change and record which key generation is active.
Restricting the Keycloak admin console
The Keycloak admin console and its administrative endpoints should not be reachable from the internet path that serves user sign-in. Restrict them with a private network, a VPN or an allowlist at the reverse proxy, and keep administrative work in the master realm limited to a small group. Give administrators separate accounts from their everyday identities and require strong multi-factor authentication. Confirm which admin paths your Keycloak version exposes before writing proxy rules, then test that user sign-in still works after the rules take effect.
Limiting who changes SAML settings
In Mattermost, the SAML configuration sits in the System Console, and one wrong change can lock out every user. Limit the system administrator role to named people and confirm exactly who can open the SAML settings in your plan and version. Keycloak has its own admin roles, so the people who edit the SAML client should belong to a defined group with multi-factor authentication enforced. Route every SAML change through your change process, and review role membership on a schedule your team sets.
Break-glass administrator account
Keep one local Mattermost system administrator account that does not depend on SAML, and store its credentials in a sealed, audited location. It is the only path back if Keycloak is unavailable, a certificate expires or the SAML configuration is wrong. Test sign-in with it during setup and after each SAML change. Confirm in the Mattermost SAML documentation how local sign-in behaves when SAML is enforced for your version. Alert the security team whenever the account signs in, and record why it was used.
Logging authentication events in Keycloak
Enable Keycloak event logging for login, login errors, logouts and admin events, and forward them to the log platform your security team uses. Confirm which event types your Keycloak version records by default and how long they are kept in the database. Keycloak's metrics documentation explains how to expose observability data, so track login failures and token errors alongside the events. Use the Keycloak production configuration guide as the reference for logging and proxy settings, and check that logs can answer who signed in through SAML, from where, and which client rejected an assertion.
Keeping Keycloak and Mattermost upgrades from breaking SSO
The two products in this integration move on different schedules, and either upgrade can change the SAML login path. Mattermost releases a new server version in binary form on the 16th of each month. Version 12.0 was released on 2026-10-16. Version 11.7 is an Extended Support Release, released on 2026-05-15 with support ending 2027-05-15, so an organization that wants fewer changes may stay on it until that date. Keycloak plans four minor releases a year and a major release every two to three years. Mattermost's Keycloak guide was tested with Keycloak v26.4.0, while the current Keycloak release is 26.8.1. The version you run in production may therefore differ from the one Mattermost tested. Confirm in writing with your Mattermost and Keycloak contacts that the exact combination you plan to run has been validated.
Keycloak states that breaking changes in a minor release are opt-in, which lowers the risk that a minor upgrade changes behavior without action from your team. That protection depends on how the upgrade is delivered. The Keycloak Operator documentation strongly recommends manual approval mode for operator updates to avoid unintended automatic upgrades. Set that approval mode deliberately in the Operator Lifecycle Manager configuration, and treat each approval as a change request that names the Keycloak version, the Mattermost version and the test realm used for verification. If Keycloak runs outside the Operator, pin the image tag and change it only through the same review. Ask whoever operates the platform to show where the update setting lives, so the approval step is not left to default behavior.
Database schema migration is the step most likely to block SSO during an upgrade. Keycloak migrates its database schema automatically at startup by default, so the new version changes the database as soon as the new pod starts. The Keycloak upgrading guide also supports manual migration, where administrators apply the SQL themselves, and suggests this approach for large deployments. Choose the model before the upgrade window opens and take a tested database backup first. Check Mattermost's upgrade notes for the same question on the server side, because a server that applies database changes at startup can fail in the middle of a rollout. Decide the upgrade order for your versions in advance, and confirm it rather than assuming that either product can move first.
Test a SAML login after every upgrade in a non-production realm before changing production. Build the test realm from an export of the production realm so it carries the same SAML client, with client ID mattermost, Name ID format email, AES_256_GCM encryption with encrypted assertions, and the X500 email, givenName and surname mappers. After each upgrade, sign in through Mattermost with a test user and check that the email, first name and last name arrive correctly, that the encrypted assertion is accepted, and that the certificates in use match what Mattermost expects. Record the outcome with both version numbers. Only when the test passes should the same sequence run in production, with a rollback plan that restores the database backup and the previous image tag.
Why Keycloak SAML SSO fails for Mattermost users
This table maps common failures in Keycloak SAML sign-in for Mattermost to their likely causes and the checks that confirm each fix. Read it in order when a login fails, because the first rows cover the SAML handshake and the later rows cover attributes, accounts and time. Confirm log locations, SAML tracing tools and time synchronization methods in your own environment before you change any settings.
| Symptom | Likely cause | Check and fix |
|---|---|---|
| Keycloak returns an error after the redirect from Mattermost, or the SAML request is rejected | Client ID in Keycloak does not match the value the Mattermost SAML settings expect | Confirm the Keycloak SAML client ID is mattermost and that Mattermost uses the same entity ID. Compare both in the admin consoles. |
| Keycloak signs the user in, but Mattermost rejects the account or shows a generic sign-in error | Name ID format is not set to email, so Mattermost cannot match the identity to a user | Confirm Name ID format is email in the Keycloak client. In one captured SAML response, check that the NameID value matches the user's email. |
| Mattermost logs show assertion parsing or decryption errors | Encrypted assertions are enabled on one side only, or the algorithm differs from AES_256_GCM | Confirm encrypted assertions and AES_256_GCM in Keycloak, and that Mattermost holds the matching key. Check that both sides were saved after the change. |
| Sign-in worked before, then fails with signature or certificate validation errors | The Keycloak signing certificate was rotated or regenerated, and Mattermost still holds the older certificate | Compare the certificate in Keycloak's SAML descriptor with the one in Mattermost. Record the expiry date and schedule each rotation in both systems. |
| Users are created as new accounts, or the account has no email, first name or last name | The X500 email, givenName or surname mapper is missing or points to the wrong attribute | Confirm all three mappers exist on the Keycloak client. Sign in as a test user and inspect the attribute statement in a captured SAML response. |
| The same person has two Mattermost accounts | Email values differ in case or domain from existing accounts, or accounts were created before the mapper was corrected | Search the Mattermost user list for the email and compare it with the Keycloak user. Decide which account to keep before you deactivate or merge anything. |
| Assertions are rejected as expired or not yet valid, often for some users or after a server move | Clock skew between Keycloak, Mattermost and the load balancer or proxy | Check time synchronization on each server and compare timestamps in the logs. Confirm the clock tolerance in the current Mattermost and Keycloak documentation. |
| Metadata cannot be fetched, the callback loops, or the ACS URL points to http or a different host | The Mattermost site URL, ACS URL or metadata URL uses a different scheme or hostname from the public address users type | Confirm that the site URL, ACS URL and metadata URL in Keycloak all use https and the same public hostname. Fetch the metadata URL from a user network. |
| A user who changed their email cannot sign in, or signs in to the old account | The email in Keycloak changed, but the Mattermost account still holds the previous email | Confirm which attribute your Mattermost SSO setup matches on. Update the stored email in a test account first, then apply the change to other users. |
Questions buyers ask about Keycloak SAML SSO for Mattermost
How much does Keycloak SAML SSO for Mattermost cost to set up?
No price is published for this work. The cost follows from a written scope that DeployOpen agrees before work starts, and the quote reflects that scope. Main cost drivers:
- Number of environments, such as production, staging and test, each needing its own SAML client and testing
- Whether Keycloak already runs in production or must be installed and hardened first
- Certificate and key handling: creating the signing and encryption key pair, storing keys, and agreeing a renewal process
- Testing of login, logout, account provisioning and attribute mapping
- Whether your Mattermost plan includes SSO. Mattermost lists SAML from the Professional plan, so confirm your plan with Mattermost.
Most of the cost is one-time: configuration, testing and a runbook. Certificate renewal and upgrade retesting recur. Ask for a quote that lists each environment, who owns certificate renewal, the test cases covered and the handover documents.
How long does a Keycloak SAML integration with Mattermost take?
The duration depends on the scope agreed in writing, and no fixed timeline is published for this work. The biggest factors are the state of your Keycloak deployment, the number of environments, and how quickly approvals and change windows come through on both the identity and Mattermost sides.
Other factors that lengthen the work include designing how users map to Mattermost accounts, a large number of user groups or attributes, and identity-provider changes that need formal review. The Mattermost guide was tested with Keycloak v26.4.0, so a different Keycloak version adds a step to confirm the documented settings still apply.
Ask for a timeline that is tied to named milestones: environment access, test accounts, first login in staging, production cutover and handover. Confirm how many review cycles the quote assumes.
What does our team need to provide for a Mattermost SAML SSO project?
The project needs four things from your side, plus a named contact who can make decisions.
- Keycloak administrators with rights to create clients, mappers and keys in the target realm
- Mattermost System Console access with an administrator account, so SAML settings can be entered and tested
- Test accounts covering each user type and role you need to verify, in every environment
- A decision on identifiers: which attribute identifies the user, how the Name ID format is set (the Mattermost guide uses email), how email maps to the Mattermost username, and what happens when an existing Mattermost account has the same email
You should also confirm change windows for production, the owner of certificate renewal, and who signs off on the cutover. Missing identifier decisions are the most common reason login testing has to be repeated.
Can an internal team set up Mattermost SAML with Keycloak alone?
Yes, an internal team can follow Mattermost's documented Keycloak guide if it has Keycloak administrators who have worked with SAML and a non-production environment to test in. The guide sets the SAML client ID to mattermost, uses email as the Name ID format, enables encrypted assertions with AES_256_GCM, and adds X500 mappers for email, givenName and surname.
The risk sits in the details around those steps: generating and storing keys, matching the encryption settings exactly, handling certificate expiry, and testing edge cases such as users who already have accounts. An error in an attribute mapper can block sign-in for everyone or quietly create accounts with the wrong data.
If your team lacks this experience, DeployOpen can implement, test and document the integration under a fixed-scope agreement. Confirm the guide version that matches your Mattermost server and Keycloak release before starting.
Does Keycloak high availability change the effort for Mattermost SAML?
The SAML settings in Mattermost change little, but the surrounding Keycloak design adds work. Keycloak documents three high availability architectures: a single cluster optionally spread across availability zones, multi-cluster deployments (v2) without an external Infinispan cluster, and the deprecated multi-cluster v1 design. Both supported designs need a synchronously replicated database.
Effort increases in these areas:
- Stable, consistent public hostnames so the SAML endpoints and metadata do not change between nodes or sites
- Load balancer and session behavior tested during node failure
- Certificate and key distribution across all nodes
- Failover testing with real logins
If your design uses the deprecated v1 model, plan the migration as part of the scope. High availability for Mattermost itself is available on Enterprise and Enterprise Advanced plans, which is a separate decision from Keycloak's design.
Does the Keycloak database choice change the SAML work?
The SAML configuration is the same on any supported database, but the database choice changes operations and high availability work. Keycloak supports MariaDB, Microsoft SQL Server, MySQL, Oracle Database, PostgreSQL 14 to 18, EnterpriseDB Advanced, Amazon Aurora PostgreSQL and Azure SQL in production. The default file-based database is for development only.
The database affects:
- Synchronous replication, which both supported high availability designs require
- Backup and restore testing for the realm and client configuration
- Schema migration, which Keycloak runs automatically at startup by default. Large deployments can apply the SQL manually, as the upgrading guide suggests.
- Upgrade planning and support lifecycle for the database itself
Confirm which database you run and whether it meets Keycloak's replication requirement before the scope is written.
How do Keycloak upgrades affect Mattermost SAML SSO after go-live?
Each Keycloak upgrade can change login behavior, so plan to retest SSO after every upgrade. Keycloak plans four minor releases a year and a major release every two to three years. Breaking changes in minor releases are opt-in, which reduces surprise, but they still need review. The current release is 26.8.1, published October 13, 2026, and the Mattermost guide was tested with v26.4.0, so the gap between versions is a planning input.
If you use the Keycloak Operator, the documentation strongly recommends manual approval mode for operator updates to prevent unintended automatic upgrades. Include in your upgrade plan a staging test of sign-in, sign-out, attribute values and certificate handling, plus a rollback step.
Ask for upgrade support to be defined in the scope or in a separate retainer.
What happens to Mattermost sign-in if the Keycloak SAML certificate expires?
Sign-in through SAML fails once a certificate or key used in the trust relationship expires or no longer matches. Users see login errors, and administrators may not see a clear message in Mattermost about why. Plan certificate lifetimes, renewal dates and rotation steps before go-live, not after the first failure.
A workable process records which certificate Mattermost trusts, who owns renewal, the date of the next expiry and how the new certificate is installed in both Keycloak and Mattermost. Test the rotation in staging first, because encrypted assertions depend on matching key material on both sides.
The quote should state who handles rotation, whether it is included in ongoing support and how an emergency change is handled. Confirm the exact certificate settings with the current Mattermost and Keycloak documentation.
How DeployOpen scopes and delivers Keycloak SAML SSO for Mattermost
DeployOpen plans, builds and hands over Keycloak as the SAML identity provider for a self-hosted Mattermost server, inside your own infrastructure. Each engagement starts with a written, fixed scope that names the Keycloak and Mattermost versions, the SAML client settings, the attribute mappers and the certificate process before any configuration begins.
How we scope
- Confirm which Mattermost plan you hold, since SSO through SAML is included from the Professional plan.
- Record the Keycloak version, hosting model and database choice, and whether Keycloak will run as a single cluster or another high availability design.
- Agree in writing how the SAML client, Name ID format, encryption settings, mappers and signing certificates will be configured and tested.
How we build
- Create the SAML client with client ID mattermost, Name ID format email and encrypted assertions using AES_256_GCM, as the Mattermost guide describes.
- Map X500 email, givenName and surname attributes so that Mattermost receives the identity fields it needs at first login.
- Test sign-in, assertion encryption and attribute values in a non-production environment, then document the certificate rotation steps before go-live.
How we hand over
- Deliver written runbooks covering the Keycloak client, mappers, certificate locations and Mattermost SAML settings under your change control.
- Walk your administrators through a login test, failure symptoms and where SAML errors appear in the Keycloak and Mattermost logs.
- Document the upgrade approach for both products, including how Keycloak minor and major releases and Mattermost monthly or ESR releases will be checked against this configuration.
How we support
- Offer ongoing support, upgrades and reviews of the SAML configuration as a retainer, separate from the fixed-scope build.
- Re-test SSO after each Keycloak or Mattermost upgrade and after any certificate renewal before the change reaches users.
- Confirm with your team which support hours, response paths and retainer terms apply, using the written scope as the reference.
