Set up single sign-on (SSO)

Updated on Sep 21, 2026 Feedback on this page

You can configure your Mattermost so users sign in via single sign-on (SSO) against your identity provider. It uses the OpenID Connect standard, so it works with Authentik, Keycloak, Authelia, Zitadel, Nextcloud, Google Workspace, Microsoft Entra ID and other OIDC-capable providers.

Mattermost restricts generic OpenID Connect to its enterprise edition. We ship our own open-source plugin that implements the full OIDC flow instead – no enterprise licence required, included on every plan. Configuration is self-service in the customer portal, and it covers the web, desktop and mobile clients.

Requirements

An active Mattermost subscription at server.camp
A reachable, OIDC-capable identity provider (e.g. managed Authentik at server.camp or a Nextcloud, see below)
Admin access to both systems

Step 1 – Create an application at your identity provider

Create a new OAuth2/OpenID application for Mattermost at your identity provider. The exact steps differ per provider; these values are the same everywhere:

Setting	Value
Client type	`Confidential`
Grant type	`Authorization Code`
Scopes	`openid`, `profile`, `email`
Redirect URI	`https://<your-mattermost-domain>/plugins/mattermost-oidc/oauth2/callback`

The path /plugins/mattermost-oidc/oauth2/callback is fixed. What counts is the domain your Mattermost is reachable under: if you have set up a custom domain, its address belongs in the redirect URI – the default address is no longer used.

Then note down the client ID, the client secret and the issuer URL. The issuer URL is the address that hosts the discovery document .well-known/openid-configuration – without that suffix, e.g.:

https://your-authentik.srv.camp/application/o/mattermost/

Restrict access to a group

At your IdP, restrict access to the application to a specific group (e.g. all-staff). Only members of that group can then sign in to Mattermost via SSO.

Example: Nextcloud as the identity provider

If you run a Nextcloud, you can use it as your identity provider without any additional service – a managed Nextcloud at server.camp, for instance:

Sign in to Nextcloud with an administrator account
Install and enable the OIDC Identity Provider app
In the administration settings, open the OpenID Connect Provider section, choose Add client and fill in:
- Name: anything you like, e.g. Mattermost
- Redirection URI: https://<your-mattermost-domain>/plugins/mattermost-oidc/oauth2/callback
Note down the new client’s client ID and client secret
For the issuer URL, your Nextcloud’s address is enough – important: without a trailing slash, so e.g. https://my-nextcloud.srv.camp

That is everything you need for step 2. You can leave the remaining fields at their defaults: Nextcloud sends preferred_username, email and first and last name (split out of the display name).

Users need an email address in Nextcloud

Nextcloud only passes on an email address if one is set in the user’s profile. Without it, the login fails with “Failed to read user information from identity provider” – the most common cause when SSO with Nextcloud fails for individual users.

Do not require verified email addresses with Nextcloud

By default, Nextcloud reports email addresses as not verified (email_verified: false) – including the ones you entered yourself in the admin area. So if you enable “Only allow verified email addresses” in the portal, every login fails. If you want the option anyway, set Email Verified Flag to Set to always verified in Nextcloud, in the Settings block on the same page – Nextcloud then reports email_verified: true.

Step 2 – Configure Mattermost in the server.camp portal

Open the configuration of your Mattermost subscription in the customer portal. Under Single Sign-On, enter:

Field	Value
Enable single sign-on	Checked
OpenID Connect issuer URL	Issuer URL from step 1 (must be `https://`)
OpenID Connect client ID	Copied from your IdP
OpenID Connect client secret	Copied from your IdP

Save and wait for provisioning to finish. The first time you enable it, this takes a few minutes longer than other changes, because the SSO plugin is installed and Mattermost is restarted. After that, the login page shows an additional button for signing in through your provider.

Before you start: hold back one local admin account

Once an account signs in via SSO, that account can no longer sign in with a password – permanently (see below). So never use your only admin account for an SSO login: create a second administrator account beforehand that only ever uses password login. That is your emergency access if the identity provider goes down or the configuration turns out wrong.

Step 3 – Put new users into a team

In Mattermost, a user without a team sees nothing. So set default team to the team that accounts created via SSO should join automatically. That is the name from the URL (https://<your-mattermost-domain>/my-team/channels/town-square → my-team), not the display name.

If you leave the field empty, new users end up in an instance without a team and have to be invited by hand.

What happens to accounts

The first SSO login decides how an account authenticates from then on, and it is a one-way street:

New users are created as SSO accounts on their first SSO login. They never have a password and always sign in through your identity provider.
Existing users linked by email (see the option below) are converted to SSO in the process. Their previous password stops working — even if you disable SSO again later. “Forgot password” does not help those accounts either.
Accounts that are not linked stay untouched and keep signing in with a password. The login form does not disappear; it sits next to the SSO button.

An account that has been converted can only be reverted on the server side. If you need that, contact our support and include the affected email address.

In practice: keep at least one administrator account that never signs in via SSO.

Signing in from the mobile app

SSO also works in the native Mattermost app for iOS and Android, with no extra setting. Your users enter the server address as usual and are offered the SSO button.

Optional fine-tuning

These fields have sensible defaults. Only change them if you deliberately want different behaviour:

Field	Default	Effect
Create accounts automatically	Checked	Creates an account on first SSO login. Without it, only users who already have an account can sign in.
Link existing accounts by email	Unchecked	Links an existing account with the same email address on first SSO login – permanently (see warning below).
Only allow verified email addresses	Unchecked	Only accepts logins whose email address the provider reports as verified. Requires the claim below (see warning below).
Login button text	`Log in with OIDC`	Label of the SSO button, e.g. `Sign in with company SSO`.
Login button colour	`#0058CC`	Colour of the SSO button as a hex value.
OAuth 2.0 scopes	`openid profile email`	Requested scopes. Must include `openid`.

The six claim fields decide which token fields Mattermost takes username, email, first and last name, position, and the email verification status from. The defaults match most providers:

Field	Default	Note
Username claim	`preferred_username`	Alternatively `sub` or `nickname`, for instance.
Email claim	`email`	Must be present – without an email address, Mattermost rejects the login.
First name claim	`given_name`
Last name claim	`family_name`	Authentik does not send this claim; the field then stays empty on the user.
Position claim	empty	E.g. `position` or `job_title`. Empty = not synced.
Email verification claim	empty	Usually `email_verified`. The value lands in Mattermost’s “email verified” field on every login. Empty = not read.

Requiring verified email addresses: lock-out risk

“Only allow verified email addresses” rejects every login where the claim is missing or reports “not verified” – without creating an account, linking one, or issuing a session. Many providers do not send email_verified at all, or only when the scope asks for it explicitly. So set the claim first, confirm with a test account that logins still work, and enable the option only afterwards – otherwise you lock out every user at once.

Linking accounts by email: be careful

“Link existing accounts by email” switches an existing account with the same email address over to SSO permanently – that account’s password stops working afterwards. And whoever controls the email address at the identity provider takes over the account. Only enable this if you genuinely trust your provider with those addresses and it verifies them.

With the option off, SSO login fails for addresses that already exist in Mattermost – which keeps those existing accounts protected.

Enforce two-factor authentication at the provider

SSO login creates the session right after the OIDC flow and does not evaluate Mattermost’s built-in MFA, so anyone signing in via SSO bypasses it. Enforce two-factor authentication at the identity provider instead – there it applies to every application and every client.

What signing in looks like for your users

Open Mattermost in the browser, the desktop app or the mobile app
Click the SSO button on the login page
Get redirected to the identity provider and sign in there (with 2FA if configured)
Back in Mattermost – the user is signed in

Test first, then roll out

Test the SSO login with a dedicated test account, not with your admin account – the first SSO login converts the account it is used with to SSO for good. That surfaces problems with the redirect URI, the claims or the default team early, without costing you your password login.

Troubleshooting

“redirect_uri mismatch” at the IdP: the redirect URI at the provider does not match. Check it character by character, including https:// and the path /plugins/mattermost-oidc/oauth2/callback. With a custom domain, the callback URL has to point to that domain, not to the default address.
No SSO button visible: is “Enable single sign-on” checked and provisioning finished? After that, reload the page with a cleared browser cache.
“issuer URL must use HTTPS”: the issuer URL has to start with https://; the plugin rejects http://.
The SSO button is there, but leads to “OIDC provider not initialized. Check plugin configuration.”: the plugin could not read the provider at startup. Usually there is one slash too many at the end of the issuer URL – it has to match, character for character, the address the provider reports as issuer in its discovery document. Also possible: the provider was unreachable, or its TLS certificate is invalid.
“Failed to read user information from identity provider” (server log: email claim 'email' is empty): the provider does not return an email address. Check that the email scope is assigned and the claim name matches. With Nextcloud as the provider: does the user have an email address set in their Nextcloud profile at all?
“Your email address is not verified by your identity provider”: “Only allow verified email addresses” is on, but the provider does not report the address as verified. Check the email verification claim and whether the provider sends email_verified at all – or turn the option off again.
Login fails with “session expired”: more than ten minutes passed between clicking the SSO button and returning from the identity provider, or the return page was loaded again. Simply start the login once more.
User is signed in but sees nothing: no team. Set a default team (step 3) or invite the user to a team manually.
“Account already exists” / login aborts although the user has an account: the email address belongs to an existing account and “Link existing accounts by email” is off. Either enable the option (the account is then converted to SSO permanently) or keep letting that user sign in with a password.
A user can suddenly no longer sign in with a password: that is by design – their account was converted to SSO on its first SSO login. Reverting is only possible server-side, through our support.

If you have further questions, reach our support through the customer portal.