Integrations · OIDC

Mattermost SSO

Configure Mattermost Team or Enterprise Edition to authenticate via Clavex using OpenID Connect. Supports automatic account creation, display name sync, and team/channel assignment from Clavex group claims.

OpenID Connect vs GitLab OAuth: Mattermost supports "GitLab" as an OAuth provider which is actually a generic OIDC flow. Use the OpenID Connect option available in Mattermost ≥ 5.33 (Enterprise) or the GitLab option for Team Edition with the correct endpoint URLs.

Prerequisites

Mattermost ≥ 5.33 Enterprise Edition or Team Edition (with GitLab SSO method)
Mattermost System Admin access
Clavex at https://id.acme.eu, org slug acme

Step 1 — Register OIDC Client in Clavex

Admin API (curl)

$ curl -X POST https://id.acme.eu/api/v1/organizations/acme/clients \ -H 'Authorization: Bearer $ADMIN_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "client_id": "mattermost", "client_name": "Mattermost", "grant_types": ["authorization_code", "refresh_token"], "redirect_uris": [ "https://chat.acme.eu/signup/openid/complete", "https://chat.acme.eu/login/openid/complete" ], "scopes": ["openid", "profile", "email"], "token_endpoint_auth_method": "client_secret_post" }'

Step 2a — Configure via System Console (Enterprise)

System Console → Authentication → OpenID Connect
Set Select service provider to Other

Fill in:

Field	Value
Button name	`Sign in with Clavex`
Button color	`#5DCAA5`
Discovery endpoint	`https://id.acme.eu/acme/.well-known/openid-configuration`
Client ID	`mattermost`
Client secret	`cs_xxxxxxxxxxxxxxxx`

Click Save

Step 2b — config.json (Team Edition)

Use the GitLab SSO method with Clavex endpoints as a workaround for Team Edition:

config.json

"GitLabSettings": { "Enable": true, "Secret": "cs_xxxxxxxxxxxxxxxx", "Id": "mattermost", "Scope": "openid profile email", "AuthEndpoint": "https://id.acme.eu/acme/authorize", "TokenEndpoint": "https://id.acme.eu/acme/token", "UserApiEndpoint": "https://id.acme.eu/acme/userinfo", "DiscoveryEndpoint": "https://id.acme.eu/acme/.well-known/openid-configuration" }

bash

$ sudo systemctl restart mattermost

Attribute Mapping

Mattermost reads the following claims from the ID token / UserInfo response:

Mattermost attribute	Clavex claim	Notes
Auth data (user ID)	`sub`	Stable identifier
Username	`preferred_username`	Must be unique
Email	`email`	Required
First name	`given_name`
Last name	`family_name`
Picture	`picture`	Avatar URL

Troubleshooting

Symptom	Cause	Fix
SSO button not visible	Feature not enabled or license required	Verify Enterprise license; check System Console → Authentication → OpenID Connect
`An account with that username already exists`	`preferred_username` conflicts with existing local user	Convert existing user to SSO via `mmctl user convert`
Login fails after successful redirect	Redirect URI not registered in Clavex	Add both `/signup/openid/complete` and `/login/openid/complete` to allowed redirect URIs
`claim email_verified is false`	Clavex returns unverified email	Mark users' emails as verified in Clavex Admin; or disable email verification requirement