authentik and Mattermost SSO integration guide

How authentik signs users into Mattermost

If your team runs a self-hosted Mattermost server and wants one login for every employee, the first decision is which edition you run, because that decision sets the protocol. The authentik integrations catalog documents a Mattermost guide that offers OAuth 2.0 for Team Edition, while SAML is available only in Mattermost Enterprise Edition. Confirm your edition and licence entitlement before you create anything in authentik, since switching protocols later means reconfiguring both sides. Mattermost's pricing page states that SSO through SAML, OIDC and OAuth is included from the Professional plan, so the plan you buy should be checked against the protocol your team needs. The guide is published by authentik and is the natural starting point for the configuration itself: authentik integrations: Mattermost.

The integration has two halves that you configure separately. In authentik, you create an OAuth2/OIDC or SAML provider and an application that points to your Mattermost URL. In Mattermost, you enter the matching client settings or SAML metadata in the system console, and the login page then redirects users to authentik. No custom code is involved. The records that must agree on both sides are the redirect or assertion consumer URL, the client identifier and secret for OAuth, and the issuer or entity identifiers for SAML. A mismatch in any one of them produces a login loop or a rejected token, so write these values down in one place before you start. Keep the Mattermost site URL stable, because changing it later changes the callback addresses you must update in authentik.

Keep your existing Mattermost login methods available until you have tested single sign-on with a few named accounts. Mattermost stores accounts locally, so users who already have email and password accounts may be matched to SSO identities differently than you expect. Ask your Mattermost contact or review the official Mattermost SAML single sign-on documentation for the account matching behaviour of your edition, and record the answer in your rollout plan. Decide early which group or role data, if any, must flow from authentik, because the sync capabilities differ by edition and are covered in the sections that follow.

Choosing OAuth 2.0 or SAML by Mattermost edition

The authentik Mattermost guide documents OAuth 2.0 for Mattermost Team Edition, and this is the only SSO path the guide describes for that edition. On the authentik side, you create an OAuth2/OIDC provider and an application that points to it, then register the client ID and secret in Mattermost. The provider's redirect URI must match the Mattermost site URL exactly, including scheme and path, so confirm the public URL before you start.

Provider type: Create an OAuth2/OIDC provider in authentik, not a SAML provider, and bind it to an application for Mattermost.
Redirect URI: Match the Mattermost site URL exactly, including the scheme, host and callback path shown in the integration guide.
Mattermost console: Enter the client ID, client secret and the authentik endpoints in the OAuth settings of the System Console.
Scopes and claims: Confirm which claims authentik returns for username and email, because Mattermost uses them to match or create accounts.
Edition check: Confirm the server edition in your build before you rely on this path, since a SAML option is not available in Team Edition.

Before go-live, sign in with a test account, confirm the username and email land correctly, and check that a user who is removed in authentik cannot sign in again.

What you need before configuring Mattermost SSO

Single sign-on between authentik and Mattermost depends on four things lining up: the authentik release you run, the Mattermost edition and version you run, the hostname users reach Mattermost on, and the certificate and DNS work behind it. Check each one before you create a provider, because the protocol you can use depends on the Mattermost edition.

authentik release line

Run an authentik release that still receives security fixes. The security policy lists 2026.5.x and 2026.8.x as the supported lines, and the project announces security releases at least 24 hours in advance. Confirm which line your deployment is on, and plan an upgrade path if you are behind it, because the upgrade rules apply before you touch the Mattermost provider.

Mattermost edition decision

The protocol follows the edition. The authentik Mattermost guide documents OAuth 2.0 for Team Edition and SAML for Enterprise Edition, so decide which edition you run before you choose a provider type. Ask Mattermost which edition and plan your organization is licensed for, since SSO is included from the Professional plan on the pricing page.

Supported Mattermost version

Choose a server version still inside its support window. v12.0 (released 2026-10-16, support ending 2027-01-15) and v11.11 (released 2026-09-16, support ending 2026-12-15) are listed, and v11.7 is the Extended Support Release, supported until 2027-05-15. Note that v10.11 has reached end of life, so an older server must be upgraded before SSO work starts.

Public HTTPS hostname

Pick the external URL users will type into a browser, such as a dedicated chat. hostname, and use it consistently for the Mattermost SiteURL and the authentik provider. Browser redirects must reach that exact address over HTTPS. Avoid changing the hostname after users are enrolled, because identity redirect URIs and bookmarks are tied to it.

Certificate and DNS work

Issue a certificate that covers the hostname and make sure the chain is trusted by every browser and by the Mattermost server when it calls the identity provider. Create the DNS record before testing, and confirm that the authentik hostname is reachable on the same network path. Verify the exact redirect URI and certificate handling against the Mattermost SSO documentation, since the callback path differs by protocol.

License and tier fit

Confirm the license you hold before the build, not after. Mattermost sells prepaid annual subscriptions by seat licenses and publishes no public prices, so ask sales which plan includes the SSO and group features you need. The authentik side also has an edition boundary: authentik's enterprise directory carries its own license, so confirm which features your authentik tier provides.

Configuring the authentik provider and Mattermost in sequence

This sequence produces a working single sign-on path from authentik into Mattermost, with the protocol chosen by edition and the redirect or ACS and issuer values matched to your Mattermost site URL. Each step ends with a check so you can confirm the connection before you move on.

Confirm the edition and protocol
Before you touch either system, confirm which Mattermost edition you run, because that decides the protocol. Team Edition uses OAuth 2.0, and SAML is available only in Enterprise Edition, as the authentik Mattermost guide documents. Confirm your Mattermost site URL exactly as users type it, including scheme and any subpath, since every redirect and ACS value in later steps is built from it. Done when the edition, protocol and site URL are written down and agreed by the people who will own the integration.
Create the authentik provider and application
In authentik, create a provider for the protocol you chose, either an OAuth2/OIDC provider or a SAML provider, then create an application that uses it. Set the redirect URI for OAuth or the ACS URL and issuer for SAML so they match the Mattermost site URL confirmed in the previous step. Use the exact values from the authentik Mattermost guide for your protocol rather than a guessed path. Done when the provider and application save without errors and the provider shows the client ID and secret (OAuth) or the metadata and issuer (SAML) you will copy into Mattermost.
Set property mappings and scopes
Attach the property mappings Mattermost needs so that the attributes it expects, such as a username, email and name, arrive in the token or assertion. For OAuth, confirm the scopes requested include the identity claims Mattermost reads. For SAML, confirm the NameID and attribute names match what Mattermost maps to its user fields. Keep a note of each attribute name so you can compare it with what Mattermost receives during testing. Done when you can list the claims or attributes the provider will send and each one has a named Mattermost field it fills.
Enter the authentik values in Mattermost
In the Mattermost System Console, open the SSO settings for your edition and enter the values from authentik: the client ID and secret with the authorization, token and user endpoints for OAuth, or the identity provider metadata, login URL and certificate for SAML. Use the Mattermost SAML single sign-on documentation for the exact field names in your version. Save the configuration and leave the SSO option disabled for users until the test in the final step passes. Done when Mattermost saves the settings and the SAML metadata or OAuth endpoints resolve without errors from the server.
Check the callback or metadata exchange
Verify the connection before you open login to users. For SAML, fetch the authentik metadata from the URL shown on the provider and confirm Mattermost accepts it and that the ACS and entity IDs match on both sides. For OAuth, start a login from Mattermost and confirm authentik returns to the Mattermost redirect URI and that the token exchange completes. A mismatch in the site URL is the most common cause of failure here, so compare the values character by character. Done when a metadata fetch or OAuth callback completes and Mattermost shows the account it expects.
Test a login with a non-admin account
Sign in as a standard user who is not a System Admin in Mattermost, using a test account that exists in authentik and has access to the application. Confirm the user lands in Mattermost with the expected username, email and team membership, and that the login does not create a duplicate account if one already exists under the same email. Repeat the test with a second account if your authentik policies differ between groups. Done when the non-admin test account signs in through authentik, reaches Mattermost, and the attributes on the Mattermost profile match the authentik user.
Record the group and role limits
Before you enable SSO for all users, record what the integration does and does not sync in your edition. Group and role mapping depends on the edition and the protocol, and the sync capabilities described in the Mattermost pricing and SSO documentation differ by plan, so confirm with Mattermost which group and role behavior applies to your deployment. Note any manual steps that remain, such as assigning teams or roles inside Mattermost. Done when the team has a written list of what authentik controls, what Mattermost controls, and what you must confirm with the vendor before go-live.

Which authentik attributes Mattermost needs

This table lists the authentik user fields Mattermost reads at sign-in and the Mattermost fields they fill. Use it to confirm attribute names on both sides before testing, because a mismatch can show up as a blank name or a duplicate account. The main takeaway is that identity fields are set by the integration guide, while group data is only useful if the guide and your Mattermost edition support using it.

Mattermost field	authentik source	Notes for setup
Username	authentik username	Confirm which claim or attribute the guide sends as the username field.
Email address	User email attribute	Used to match existing Mattermost accounts. Confirm whether the guide requires the email claim or attribute.
First name	Name value on the authentik user	authentik keeps a single name value, so split it with a property mapping if the guide expects a first name.
Last name	Name value on the authentik user	Same source as first name. Test a user with a multi-part name before rollout to confirm the split.
Group membership	Groups claim or attribute, if configured	Sent only when the guide sets it. Group data does not assign Mattermost roles unless the guide documents that mapping.
Account identifier	Subject (OIDC) or NameID (SAML)	Links the login to a Mattermost account. Changing this value later can create a second account for the same person.
Claim or attribute names	Set in the authentik provider and the guide	Names must match exactly on both sides. Copy them from the guide instead of retyping them.
Protocol by edition	OAuth 2.0 for Team, SAML for Enterprise	Team Edition uses the OAuth 2.0 attribute path. SAML attributes apply only on Enterprise Edition.

How group and role sync differs between editions

Group and role sync between authentik and Mattermost depends on what each Mattermost edition supports and on what the authentik Mattermost guide documents, so confirm both before you design team membership. The guide covers OAuth 2.0 for Mattermost Team Edition and SAML for Mattermost Enterprise Edition. Those two paths do not necessarily carry the same group or role attributes into Mattermost, so the claims you map in authentik may behave differently depending on the edition you run. Ask DeployOpen or your own administrators to confirm, in writing, which group or role claims each edition reads and where they are applied in the Mattermost System Console.

Mattermost lists SSO (SAML, OIDC, OAuth) and AD/LDAP user sync as included from the Professional plan, so a Professional or higher subscription is the point at which directory user sync becomes available alongside SSO. Directory sync covers user accounts and, depending on configuration, group membership. Confirm with Mattermost whether group membership from the directory maps to team or channel membership in your chosen plan, and whether any group-based role assignment is limited to specific plans. Do not assume that a group attribute present in the authentik token will translate into a Mattermost role without a test in a staging instance.

Before you design team membership, decide whether channel membership stays manual. Automated group mapping can add users to teams and some channels at sign-in, but it can also remove access when an upstream group changes, which may disrupt active conversations. Many organizations keep teams synced from authentik groups and leave private or sensitive channels under manual control by channel administrators. Document that decision, the owner of each group in authentik, and the process for removing access, and test a user moving between groups in a non-production workspace before rollout.

Hardening the authentik to Mattermost login path

The login path between authentik and Mattermost carries identity assertions, client secrets and signing material, so a weak point at any hop can grant access to the wrong people. The cards below cover transport, access scoping, a local fallback, secret and certificate handling, and audit logging, in the order most teams review them during rollout.

HTTPS on both sides

Serve authentik and Mattermost only over HTTPS, and make sure the redirect URI registered in authentik matches the exact Mattermost site URL, including scheme and port. A mismatch often leads teams to relax settings to make login work, which weakens the path. Confirm that Mattermost's site URL and the authentik provider's redirect or ACS URL are both HTTPS, and that the certificates are valid for the hostnames users actually type.

Scoping application access

Bind the authentik application for Mattermost to a policy or group binding so that only the intended users and groups can start an SSO login. Without a binding, any authentik user who can reach the application may be able to create a Mattermost account through sign-up, depending on how Mattermost is configured. Test with one user outside the allowed group and confirm the denial is logged on both sides.

Documented local password fallback

Keep at least one break-glass administrator who can sign in with a local Mattermost password while SSO is enforced. Record where that credential is stored, who can retrieve it, and how it is tested. Confirm the setting that controls whether password login stays available in the Mattermost version you run, because an SSO-only configuration without a tested fallback can lock every administrator out during an authentik outage.

Protecting the client secret and signing material

For OAuth 2.0 on Team Edition, the client secret lives in the Mattermost configuration, so restrict read access to the server config and to backups that contain it. For SAML on Enterprise Edition, protect the authentik signing key and any certificate copied into Mattermost, and plan rotation with a dated cutover. Store both values in a secrets manager, not in shared documents or chat, and record who holds them.

Enhanced audit logging on eligible plans

authentik lists enhanced audit logging as an Enterprise-only feature, so do not plan around it unless your subscription includes it. On Open Source, rely on authentik's standard event records and forward them to your log platform, and confirm which login, failed sign-in and provider change events you can retain. Pair this with Mattermost's own audit output so a failed or unexpected login can be traced across both systems.

Common Mattermost SSO failures and fixes

This table lists the failures teams most often hit when connecting Mattermost to authentik, with the likely cause and the check to run for each. Work through the rows in order, since a license tier problem or a redirect mismatch can look like a login failure further down the chain. Confirm exact error messages and settings names against the authentik integration guide and the Mattermost SSO documentation for your version.

Failure	Likely cause	Check to run
Redirect URI mismatch (OAuth 2.0)	The redirect URI registered in the authentik provider does not match the callback URL Mattermost sends, often because of the site URL, http versus https, or a trailing path difference.	Compare the redirect URI in the authentik provider with the Mattermost site URL and OAuth callback path character by character, then retry from a clean browser session.
ACS or entity ID mismatch (SAML)	The Assertion Consumer Service URL or SP entity ID in authentik does not match what the Mattermost SAML settings expect, usually after a change to the site URL.	Confirm the ACS URL and entity ID in the authentik SAML provider against the Mattermost SAML configuration, and check that the site URL in Mattermost matches the public hostname.
Issuer or signing certificate mismatch	The issuer value, metadata, or signing certificate in Mattermost was copied from a different provider, or the certificate was rotated in authentik without updating Mattermost.	Re-download the IdP metadata from authentik, verify the issuer string and certificate fingerprint, and update Mattermost before testing again.
Email claim missing or mismatched	authentik does not send the email attribute Mattermost uses to match accounts, so Mattermost creates a new user instead of linking the existing one.	Inspect a test login's returned claims or assertion, confirm the email attribute mapping, and check whether existing Mattermost accounts use the same email address.
Duplicate accounts after first SSO login	Users already existed locally with a different username or email format, so the SSO identity was created as a second account.	List accounts sharing an email address, agree on a single identifier before cutover, and decide how existing local accounts will be linked or deactivated.
Users blocked by authentik policies	A binding, group membership, or policy on the authentik application denies access before the assertion reaches Mattermost, or a flow requires an unmet step.	Review the application's policy and group bindings and run authentik's test or access evaluation for a affected user to see which policy denied the request.
SSO option not visible in Mattermost	The running edition or plan does not include SSO for the chosen protocol, so the setting is absent from the admin console. Team Edition supports OAuth 2.0 only, and SAML requires Enterprise Edition.	Check the installed edition and license in the System Console, confirm the protocol against the Mattermost pricing and SSO documentation, and upgrade the license before configuring SAML.
Group or role sync not working	Group sync depends on the edition and on the claims or group membership being passed, and some group behavior is limited on lower tiers.	Confirm the edition supports the group feature you need, verify the group claim appears in the token or assertion, and test with one non-admin account first.

Questions buyers ask before configuring Mattermost SSO

Can I set up SSO with Mattermost without an Enterprise license?

Yes, for OAuth 2.0 on Team Edition. The authentik integration guide for Mattermost documents OAuth 2.0 as the option for Team Edition, while SAML is available only in Mattermost Enterprise Edition. If your organization needs SAML, the Enterprise tier is the deciding factor, not authentik. Check the current feature split on the Mattermost pricing page before you commit, because the pricing page is where Mattermost lists which plan includes SSO and AD/LDAP user sync. Mattermost does not publish plan prices there, so ask sales for a quote tied to your seat count.

What makes a Mattermost SSO project take more effort?

Four factors drive most of the effort: the Mattermost edition, how your groups map to teams and roles, whether existing local accounts must be kept, and how many applications share the same authentik instance.

Edition decides whether you configure OAuth 2.0 or SAML, and whether group or role sync is available at all.
Group model determines how many authentik groups you must map and how often membership changes.
Local accounts add work on matching emails and usernames so people keep their history.
Application count affects how much you reuse provider and mapping patterns across services.

Each factor adds design and testing time, so ask for them to be listed separately in any scope.

How long does a Mattermost SSO configuration usually take?

The supplied sources do not give a duration for this work, so any number you hear should be tested against your own scope. The time depends on the edition, the group model, the state of your existing accounts, and how many people must test sign-in before cutover. Your team's familiarity with authentik providers and property mappings also matters, as does access to a staging Mattermost server. Ask the partner or your internal team for a written plan that lists the test cases, the cutover window and who signs off on each step.

What do we need to provide before SSO work starts?

You need to supply access and decisions, not just a server. Plan to provide:

A Mattermost test server and a production server, with admin access and the edition you have licensed.
An authentik instance you control, with an administrator who can create providers, applications and property mappings.
The group list and role rules that decide who can join which teams.
A decision on existing local accounts and how their emails and usernames should match.
A named owner for DNS, TLS certificates and the redirect URLs Mattermost will use.

Confirm the exact settings against the authentik integration guide for Mattermost, since the fields and their names come from that source.

Can our own administrators run Mattermost SSO after handover?

Yes, if the people who will run it have authentik and Mattermost administration skills and a documented procedure. Day-to-day tasks include adding applications, updating mappings when group names change, rotating OAuth client secrets, and checking sign-in after each Mattermost release. Mattermost publishes server releases monthly in binary form, so plan a regular review of the support window for your version. Ask for a runbook that covers rollback, test accounts and who approves a configuration change. DeployOpen can plan, implement and document this work in infrastructure you control, and support can be added through a retainer.

Does Mattermost SSO sync groups and roles the same way on every edition?

No. Group and role handling depends on the edition and on the connection method you choose, so confirm it before you design the mappings. The authentik integration guide describes the OAuth 2.0 path for Team Edition and the SAML path that exists only in Enterprise Edition. Mattermost's SAML single sign-on documentation describes how attributes are read, and the pricing page indicates that AD/LDAP user sync is included from the Professional plan. Do not assume that a group claim available in one path works in the other. Test a user from each group in a staging environment before you rely on it.

What breaks most often in Mattermost SSO setups?

The most common failures come from mismatched redirect URLs, incorrect client secrets, and attributes that do not match the names Mattermost expects. Accounts can also fail to merge when local usernames or emails differ from the identity provider. Upgrades can change behavior, so test sign-in after every Mattermost and authentik upgrade. Keep a test user for each group and a documented local admin path, so a broken SSO setting does not lock out every administrator. Review the Mattermost SAML single sign-on documentation when a SAML attribute fails.

How DeployOpen scopes and delivers this integration

DeployOpen treats the authentik and Mattermost SSO integration as a fixed-scope piece of work inside your own infrastructure. We agree the edition, protocol, claim mapping and test cases in writing first, then build, verify and document the connection so your team can operate it after handover.

How we scope

Confirm the Mattermost edition and whether it is Team Edition with OAuth 2.0 or Enterprise Edition with SAML.
Record the authentik version, the provider and application objects, and the claims Mattermost must receive.
Agree in writing which group or role sync behavior is in scope for your edition, and which is excluded.

How we build

Configure the authentik provider, application and property mappings, then the matching Mattermost SSO settings in a non-production environment.
Test first sign-in, returning sign-in, deprovisioned user handling and login for users who already have Mattermost accounts.
Run the sign-in path through the reverse proxy and TLS endpoints used in your environment before changing production settings.

How we hand over

Document the configuration values, mappings, secrets locations and the steps to rotate client credentials or certificates.
Walk your identity and platform teams through the sign-in flow, the test cases and the known limits for your edition.
Provide a runbook for lockouts, failed sign-ins and the checks to repeat after each authentik or Mattermost upgrade.

How we support

Keep the integration current through authentik and Mattermost release changes, using the supported versions listed in each vendor's policy.
Offer ongoing support, upgrades and testing as a retainer if your team wants DeployOpen to stay engaged after handover.
Re-run the agreed test cases whenever the identity provider, the Mattermost plan or the network path changes.

authentik and Mattermost SSO integration