Mattermost SAML Integration

This document explains how to implement Monosign with Mattermost, the open-source collaboration and messaging platform (a self-hosted alternative to Slack). It covers Single Sign-On using SAML 2.0, where Monosign acts as the Identity Provider (IdP) and Mattermost as the Service Provider (SP). Mattermost is configured in its own System Console (the administration web interface). Before you continue, it is better to read the Mattermost SAML 2.0 documentation.

This configuration is done with Mattermost Enterprise Edition 11.6.6 running on Docker (image mattermost/mattermost-enterprise-edition:11.6.6 and postgres:16-alpine). If your Mattermost version or deployment type is different, please check the Mattermost documentation.

Mattermost supports SAML 2.0 and OpenID Connect. This document covers SAML 2.0. The provider is configured in the System Console (Authentication > SAML 2.0). For the OpenID Connect integration, see the separate Mattermost OIDC Integration document.

Monofor has no responsibility to do Mattermost configurations. If you need support please contact the Mattermost community or your Mattermost support provider.

The Mattermost Enterprise Edition image automatically applies a free Entry license on first start, which unlocks SAML 2.0 and OpenID Connect single sign-on without any paid plan or manual trial. The free Team Edition (image mattermost/mattermost-team-edition) does not support SAML 2.0, so the Enterprise Edition image is used here.

In Mattermost a user account is bound to a single authentication method. A user created by the OpenID Connect integration cannot be reused for SAML (and the other way around): the second method tries to create a new account and fails with "An account with that username already exists". Use a dedicated user for the SAML test, or remove the old account first.

📑 Instructions

This documentation contains 5 main steps for integration.

Creating an application on Monosign
Configuring the SAML settings on Monosign
Assign a user to the Mattermost application
Configuration Single Sign-On for Mattermost
Sign In Test

1- Creating an Application on Monosign

Create your application on Monosign first. Open the Applications page from the left menu and click Add New.

Applications page in Monosign (1: Applications menu, 2: Add New)

Mattermost is not in the application catalog, so click Create from scratch.

Creating a new application from scratch (1: Create from scratch)

Fill in the application details on the Application tab and click Next.

New Application - Application tab (1: Name, 2: Logo (optional), 3: Next)

Property	Value	Description
Name	`Mattermost`	Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.
Type	`Web`	Mattermost is accessed through a web browser. Options: Web, Mobile, Desktop, API.
Url	Optional	Leave empty or enter the Mattermost address (for example `https://<app-address>`).
Logo	Optional	Browse and upload a logo; it is also shown on the Monosign sign-in page.
Users can see this application on their list	`Enabled`	Displays the application on the user portal.

On the Access tab define who can reach the application and click Create Application.

New Application - Access tab (1: Profile Access Type, 2: Create Application)

Property	Value	Description
User Access Type	`Only Assigned Users`	Defines which users can access this application. Options: Only Assigned Users, All Users, System Default. Mattermost creates an account for every user who signs in, so restrict it to assigned users.
User Group Access Type	`System Default`	Defines the application's user group access.
Source Using Type	`System Default`	Defines which user sources the application can use.
Profile Access Type	`All`	Defines which user profile attributes are available to the application (Options: Restricted, All). Mattermost needs the e-mail address and a user name, so the profile must be accessible.

After the application is created, click Keys and add a new Access Key for SAML access.

Keys tab of the Mattermost application (1: Keys, 2: Add New Access Key)

Select SAML as the key type and click Create. Monosign generates the Key value of the SAML application automatically; it is a part of the Monosign SAML addresses.

Property	Value	Options
Type	`SAML`	Rest API, OAuth 2.0, JWT, OIDC/OpenID, SAML, RADIUS, Access Gateway, LDAP, AuthN/Z Server
Key	Generated automatically	Unique identifier of the SAML application in the Monosign addresses.
Session	`System Default`	System Default, On-demand, Permanent
State	`Enabled`	Enabled, Disabled
Never Expires	`Yes`	Turn off to define a specific expiration date for the key.

The key page shows the Monosign values that are needed in the Mattermost configuration (step 4):

📸 Screenshot placeholder — add your own screenshot of the SAML Access Key details (Sign On Service, Entity Id, Certificate).

Monosign value	Example	Used in Mattermost as
Sign On Service	`https://<monosign-host>/saml/<key>/login`	`SAML SSO URL`
Entity Id	`https://<monosign-host>/saml/<key>`	`Identity Provider Issuer URL`
View Certificate / Download Certificate	X.509 certificate of Monosign	`Identity Provider Public Certificate` (uploaded as a `.crt` file)
Metadata, Download IdP Metadata	`https://<monosign-host>/saml/<key>/metadata`	Optional. Can be entered as the `Identity Provider Metadata URL` to auto-fill the three values above.

2- Configuring the SAML Settings on Monosign

Open the Edit screen of the SAML key and go to the SAML Settings → Configuration tab. Enter the address where Mattermost receives the SAML response in Assertion Consumer Url and set the Name Id to the e-mail address of the user.

SAML Settings → Configuration (1: Assertion Consumer Url, 2: Name Id)

Property	Value	Description
Assertion Consumer Url	`https://<app-address>/login/sso/saml`	The address where Mattermost receives the SAML response. The path `/login/sso/saml` is fixed by Mattermost. It is the same as the Service Provider Login URL of step 4.
ACS Validation Mode	`Warn Only`	Default. With `Enforce` Monosign accepts only the registered ACS address.
Audience / Entity Id / Idp Description	Empty (or the Mattermost SP Identifier)	Optional. If you set a Service Provider Identifier in Mattermost (step 4), you may enter the same value here as the Audience.
NameId Format	`System Default (unspecified)`	Default value.
Name Id	`Email`	Mattermost identifies the user by e-mail address, so the NameID of the SAML response is set to the e-mail address.

Open the Attribute Mapping tab, add the attributes that Mattermost needs and click Update to save. Mattermost requires an e-mail attribute and a user name attribute; the name attributes are optional.

SAML Settings → Attribute Mapping (email, username and the optional FirstName / LastName)

Attribute	Value	Description
email	`{{Email}}`	E-mail address of the user. Entered in Mattermost as the Email Attribute (step 4). Required.
username	`{{UserName}}`	User name. Entered in Mattermost as the Username Attribute (step 4). Required.
FirstName	`{{Profile.FirstName}}`	Optional. Entered in Mattermost as the First Name Attribute.
LastName	`{{Profile.LastName}}`	Optional. Entered in Mattermost as the Last Name Attribute.

3- Assign a User to the Mattermost Application

Open the Mattermost application in Monosign, click the Assignments tab and click Assign a User.

Assignments tab of the Mattermost application (1: Assignments, 2: Assign a User)

Search and select the users who can sign in to Mattermost, check the Expiration Date and save. You can select more than one user.

Assign a User window (select one or more users and set the expiration date)

Property	Value	Description
User(s)	Selected users	Users who can sign in to Mattermost with Monosign.
Expiration Date	Default one year	The assignment expires on this date.

4- Configuration Single Sign-On for Mattermost

As we mentioned at the start, please check out the Mattermost documentation first. Mattermost is configured in the System Console, the administration web interface. Open it from the product menu (the grid icon at the top left) > System Console. You must be signed in with a System Admin account.

First make sure the Site URL is correct (System Console > Environment > Web Server > Site URL, for example https://<app-address>); the Service Provider Login URL is built from it. Then go to System Console > Authentication > SAML 2.0, turn on Enable Login With SAML 2.0 and fill in the Monosign values from step 1, then Save.

System Console → Authentication → SAML 2.0 — Identity Provider settings (SSO URL, Issuer URL, Certificate, Verify Signature) and the Service Provider URLs

System Console → SAML 2.0 — the attribute fields (Email, Username and the optional name attributes)

Field	Value	Description
Enable Login With SAML 2.0	`true`	Turns on the SAML 2.0 single sign-on.
Identity Provider Metadata URL	Optional	`https://<monosign-host>/saml/<key>/metadata`. If set, the Get SAML Metadata from IdP button fills the next three fields automatically.
SAML SSO URL	`https://<monosign-host>/saml/<key>/login`	Sign On Service of the Monosign SAML key. Required.
Identity Provider Issuer URL	`https://<monosign-host>/saml/<key>`	Entity Id of the Monosign SAML key. Required.
Identity Provider Public Certificate	Monosign certificate `.crt`	Download the certificate from the Monosign key page and upload it here. Required.
Verify Signature	`true`	Verifies the SAML response signature with the IdP certificate.
Service Provider Login URL (ACS)	`https://<app-address>/login/sso/saml`	The Assertion Consumer Service URL of Mattermost. Enter the same address in Assertion Consumer Url of Monosign (step 2).
Service Provider Identifier	`mattermost` (or the Site URL)	The SP Entity ID that Mattermost sends. If you set it, you may enter the same value as the Audience in Monosign (step 2).
Email Attribute	`email`	The SAML attribute carrying the e-mail address. Must match the attribute name in Monosign (step 2). Required.
Username Attribute	`username`	The SAML attribute carrying the user name. Must match the attribute name in Monosign (step 2). Required.
First Name / Last Name Attribute	`FirstName` / `LastName`	Optional. Match the attribute names added in Monosign (step 2).
Login Button Text	`Monosign`	Text of the SAML sign-in button on the login page.

These fields map to the SamlSettings section of config.json, so the same configuration can also be applied by editing the config file and restarting the server (the certificate file is kept under config/saml-idp.crt). SAML 2.0 is only available on the Enterprise Edition image (with the free Entry license); on the Team Edition image this option is not shown.

Do not sign out of your own System Admin session before the sign-in test is successful. Keep a local System Admin account (e-mail and password) so you can still reach the System Console and correct the settings if the single sign-on fails.

Now try to log in to Mattermost using Monosign SSO.

Open a new browser window (or a private window) and type the Mattermost address. The sign-in page shows the standard login and, below it, the SAML button (its text is the Login Button Text set in step 4, for example Monosign).

Mattermost sign-in page with the Monosign (SAML) button

Click the Monosign button. Mattermost redirects the browser to the Monosign sign-in page of the application. Log in passwordless with your QR code (Monofor Identity), with a Passkey or with your user name and password (Sign in with Password). If you are already signed in to Monosign, the page is skipped.
After the sign-in Monosign sends the SAML response to the ACS URL of Mattermost (/login/sso/saml). At the first sign-in Mattermost creates the account with the e-mail address and user name from the SAML attributes and opens the team / channel view.

Signed in to Mattermost after Monosign SAML SSO

Troubleshooting

Symptom	Cause	Solution
The SAML 2.0 option is missing in the System Console	The server runs the Team Edition image, which does not support SAML.	Use the `mattermost/mattermost-enterprise-edition` image (it applies the free Entry license that unlocks SAML 2.0).
Mattermost shows "missing AttributeStatement element"	Monosign sends no attributes, usually because the Attribute Mapping is empty.	Add the `email` and `username` attributes in the Monosign Attribute Mapping and press Update (step 2).
"An account with that username already exists"	A Mattermost account with that user name already exists under another authentication method (for example from the OpenID Connect test).	Use a dedicated SAML test user, or remove the old account first (an account is bound to one auth method).
The Monosign (SAML) button is not shown on the login page	SAML is not enabled, or the settings were not saved.	Turn on Enable Login With SAML 2.0 and save (step 4).
Monosign shows an error about the ACS address	The Assertion Consumer Url of Monosign is different from the Service Provider Login URL of Mattermost.	Set both to `https://<app-address>/login/sso/saml` (steps 2 and 4).
Sign-in succeeds on Monosign but Mattermost shows a SAML error	The certificate or the Issuer URL is wrong, or the signature verification fails.	Download the certificate and copy the Issuer again from the Monosign key page (step 1); check Verify Signature and the Service Provider Login URL.
A user cannot sign in	The user is not assigned to the application.	Assign the user in step 3.
The single sign-on does not work and you cannot enter Mattermost	A wrong value was saved in the SAML settings.	Sign in with the local System Admin account (e-mail and password) and correct the settings.

After completing the configuration on Mattermost and Monosign, it is better to test in a new private browser window if the SAML SSO doesn't work, because old session cookies of the Mattermost address may cause errors.