Keycloak and Mattermost SAML SSO

Mattermost lists Keycloak as a custom identity provider rather than as one of its officially supported SAML providers. That is a statement about certification, not about whether the integration works. SAML 2.0 is a documented standard, Mattermost's SAML single sign-on feature is included from the Professional plan according to the Mattermost pricing page, and Keycloak implements SAML 2.0 as one of its supported protocols. Teams should treat the Keycloak setup as a documented SAML pattern that Mattermost does not certify for Keycloak specifically, and plan their support model with that distinction in mind.

In practice, the difference shows up in three places. First, support escalation: when a sign-in fault appears, Mattermost may ask you to reproduce it against a supported identity provider or to involve Keycloak's own community or vendor channels, so your runbook should record which party owns each layer of the chain, from the Keycloak client and its mappers to the Mattermost SAML settings and the assertion contents. Second, testing before production: because Mattermost does not certify the pairing, your team carries more of the proof that sign-in, attribute mapping, logout behavior and account provisioning work with your exact Keycloak and Mattermost versions. Third, vendor responsibility when Mattermost changes SAML behavior in a server release. Mattermost ships a new server version in binary form on the 16th of each month, so a SAML change can arrive on a schedule your team does not control.

Ask Mattermost directly what support covers for your plan and for a custom identity provider. Put the question in writing, ask whether any SAML problem is handled under your subscription regardless of the identity provider, and ask what evidence they need to open a case, such as the SAML settings, log lines or a sample assertion with sensitive values removed. Record the answer, the date, the name of the person who gave it and the plan level in the project decision log, next to the decision to use Keycloak. If the answer changes at renewal or after a plan change, the record shows what was agreed and when it was reviewed.

Use the same log to assign ownership. Name who watches Mattermost release notes for SAML changes before each upgrade, who runs the test sign-in in a staging environment after every Mattermost and Keycloak version change, and who holds the Keycloak client configuration in version control. Keycloak's own upgrade notes for the 26.8 line call out changes to login failure handling and token validation, so an identity provider upgrade can also need a retest of the Mattermost sign-in path. Confirm the current Mattermost support window for your server version on the Mattermost server releases page before you schedule that work.

The first decision is what Keycloak signs. In a SAML sign-in, the identity provider can sign the whole response, the assertion inside it, or both. Mattermost needs to verify whichever element it expects, so the choice has to match what the Mattermost SAML configuration accepts. Confirm this against the Mattermost SAML single sign-on documentation for your server version, then set the matching options on the Keycloak SAML client. Do not assume that a default in Keycloak matches what Mattermost validates. Test a single account after each change and inspect the SAML response in a browser tool to confirm which elements carry a signature before you widen the rollout.

Next, decide which certificate Mattermost trusts. Mattermost holds the public certificate used to verify Keycloak signatures, and that certificate comes from the Keycloak realm's signing key for the client. Record the realm, the key identifier and the certificate expiry date in your change log, so anyone reviewing a failed login can see which key is in use. Confirm with your Mattermost administrator where the certificate is loaded and whether it is held in the server configuration or in a file the server reads. Keep the identity provider and service provider settings under the same change control, since a mismatch on either side produces the same generic sign-in error.

Certificate rotation is the most common cause of a sudden sign-in outage for SAML integrations. A signing certificate expires on a fixed date, and the platform will reject every assertion once it does, even though nothing else has changed. Plan rotation as a scheduled task with a calendar reminder well before expiry, a named owner on each side, and a rollback path. Where the platform accepts more than one certificate during a transition, add the new certificate first, verify sign-in with a test account, and only then retire the old one. Ask both vendors and your own administrators which rotation steps the current versions support, and do not rely on memory of an earlier release.

Assertion encryption is a separate choice and adds value only for a specific threat model. Signing protects integrity: it lets Mattermost confirm that the assertion came from Keycloak and was not altered. Encryption protects confidentiality of the attribute values inside the assertion while the message passes through the browser and any intermediaries. If your attributes are low sensitivity and the connection uses TLS end to end, encryption adds key management work without a clear gain. If the assertion carries sensitive identifiers, or your security team requires confidentiality against browser-side inspection, encryption becomes worth the extra key lifecycle. Confirm that the Mattermost configuration accepts encrypted assertions before you design around them, and confirm the Keycloak client settings that produce the encryption key pair.

Treat certificate expiry as a recurring operational task rather than a one-time setup step. Before go-live, ask the team to document each certificate, its expiry date, the people who can rotate it and the test account used to verify sign-in. Keep at least one test account outside the general user population so a failed rotation can be diagnosed without locking out administrators. Run a rotation rehearsal in a non-production Mattermost environment where one exists, and make sure the rehearsal covers both the Keycloak change and the Mattermost reload. These steps cost little compared with an unplanned outage on the day a certificate expires.

Before any user signs in to Mattermost through Keycloak, run a defined test plan against the exact topology that will serve production traffic. Start with a dedicated test user in Keycloak, not a personal account, and assign it only the groups and attributes the Mattermost SAML client is meant to read. Sign in from a clean browser session each time, so cached Keycloak sessions or Mattermost cookies do not hide a broken assertion or a stale redirect. Record which SAML attributes arrive at Mattermost and confirm that the attribute mappers in the Keycloak client produce the email, username and name values Mattermost expects. Mattermost documents its own SAML settings, so check each setting against that page rather than against memory of an earlier environment.

Next, test the account lifecycle paths that real users will hit. Sign in as a user who has never existed in Mattermost to confirm first-login account creation, then check the resulting account's email, username and team membership. Create a Mattermost account with the same email address first, sign in through Keycloak, and observe whether the accounts match or whether a duplicate appears, because that behavior decides how you handle users who already exist. Test sign-out from both sides: signing out of Mattermost, and signing out of Keycloak and then opening Mattermost. Note whether the Keycloak session still allows silent sign-in. Then test a user whose assertion omits the email or username attribute, and a disabled Keycloak user, which should be refused at the Keycloak login step. Record the exact error text each user sees, because support staff will need it.

Test the production path itself. Mattermost high availability is available only on the Enterprise and Enterprise Advanced plans, so if your design uses more than one application server, run these tests through the same load balancer, TLS termination point and hostnames that production uses. A test against one node on a private address can pass while the SAML ACS URL, the entity ID or the forwarded protocol header fails behind the proxy. Confirm that the Keycloak client's valid redirect URIs and the Mattermost site URL match the public hostname exactly, and that the signing certificate and any encryption settings reach every node in the same way.

Rehearse certificate rotation before you need it. Generate a new signing certificate in a staging realm, update the Keycloak client and the Mattermost SAML configuration in the order your runbook specifies, and confirm that sign-in works with the new certificate and fails cleanly with the old one. Time the steps and note which ones required a restart or a maintenance window. Your rehearsal should also confirm who holds the Keycloak admin credentials and where the certificate and key are stored, since a rotation that only one engineer can perform is a delivery risk.

Finally, plan recovery. Keep at least one local Mattermost system administrator account that does not depend on SAML, store its credentials under your normal privileged access controls, and test that you can sign in with it during the same window as the SSO tests. Document how to disable SAML enforcement and fall back to local sign-in, and confirm which Mattermost and Keycloak settings must change to do so. Keycloak and Mattermost are both self-hosted, so the recovery path should not require a call to a vendor. Repeat the test plan after each Keycloak or Mattermost upgrade, since either can change how assertions, sessions or certificates behave.