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 with OpenID Connect (OIDC), which is built into Mattermost. Mattermost reads the Monosign addresses from the OIDC discovery document (the Discovery Document Endpoint), uses the Authorization Code flow and takes the user from the identity provider, so the OIDC/OpenID access key of Monosign is used. Unlike most applications, Mattermost is configured in its own System Console (the administration web interface), not with environment variables. Before you continue, it is better to read the Mattermost OpenID Connect documentation (opens in a new tab).
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 OpenID Connect, SAML 2.0 and the built-in GitLab, Google and Microsoft/Office 365 providers. This document covers generic OpenID Connect. The provider is configured in the System Console (Authentication > OpenID Connect), not with environment variables.
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 OpenID Connect and SAML single sign-on without any paid plan or manual trial. The free Team Edition (image mattermost/mattermost-team-edition) supports only GitLab OAuth, not generic OpenID Connect or SAML, so the Enterprise Edition image is used here.
Instructions
This documentation contains 5 main steps for integration.
Creating an application on Monosign
Configuring the OIDC/OpenID 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.
Mattermost is not in the application catalog, so click Create from scratch.
Fill in the application details on the Application tab and click Next.
Property | Value | Description |
|---|---|---|
Name |
| Name of the application shown to users on the Monosign portal and on the Monosign sign-in page. |
Type |
| Mattermost is accessed through a web browser. Options: Web, Mobile, Desktop, API. |
Url | Optional | Leave empty or enter the Mattermost address (for example |
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 |
| Displays the application on the user portal. |
On the Access tab define who can reach the application and click Create Application.
Property | Value | Description |
|---|---|---|
User Access Type |
| 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 (see the warning below). |
User Group Access Type |
| Defines the application's user group access. |
Source Using Type |
| Defines which user sources the application can use. |
Profile Access Type |
| Defines which user profile attributes are available to the application (Options: Restricted, All). Mattermost needs the e-mail address and the name of the user. |
Mattermost creates an account for every Monosign user who signs in for the first time. Make sure the effective User Access Type is Only Assigned Users and give access only to the users you assign in step 3.
After the application is created, click Keys and add a new Access Key for OIDC/OpenID access.
Select OIDC/OpenID as the key type and click Create. Monosign generates the Client Id and Client Secret automatically.
Property | Value | Options |
|---|---|---|
Type |
| Rest API, OAuth 2.0, JWT, OIDC/OpenID, SAML, RADIUS, Access Gateway, LDAP, AuthN/Z Server |
Client Id / Client Secret | Generated automatically | Use the eye icon next to the secret to reveal it. Both values are required in step 4. |
Session |
| System Default, On-demand, Permanent |
State |
| Enabled, Disabled |
Never Expires |
| Turn off to define a specific expiration date for the key. |
Configuration details for the Mattermost application are provided as follows:
Monosign value | Example | Used in Mattermost as |
|---|---|---|
Client Id |
|
|
Client Secret |
|
|
Configuration Url |
|
|
2- Configuring the OIDC/OpenID Settings on Monosign
Click the Configure button of the OpenID Connect (OIDC) key to open the OIDC/OpenID settings. Enter the scopes that Mattermost requests and add the callback address of Mattermost to Allowed Redirect URIs, then press Update.
Property | Value | Description |
|---|---|---|
Scope |
| The scopes that Mattermost sends in the authorization request. Add each scope separated by space. |
Allowed Redirect URIs |
| The address where Monosign sends the user back after sign-in. The path |
Signing Key / Key Id / Password, Issuer, Audience, Resource | Empty | Optional custom JWT settings. They are not needed. |
Token lifetimes, CORS | Empty | Default values are used. |
Mattermost reads the e-mail address and the name of the user from the claims email and name, which Monosign returns by default, so a claim mapping is not required. Mattermost matches or creates the account by its e-mail address and derives the Mattermost user name from it.
3- Assign a User to the Mattermost Application
Open the Mattermost application in Monosign, click the Assignments tab and click 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.
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; the first account that registers on a new Mattermost server becomes the System Admin.
First make sure the Site URL is correct. Go to System Console > Environment > Web Server > Site URL and set it to the public HTTPS address of Mattermost (for example https://<app-address>). The redirect address that is sent to Monosign is built from it, so it must match the Allowed Redirect URI of step 2.
Then go to System Console > Authentication > OpenID Connect, select OpenID Connect as the provider (not GitLab, Google or Office 365) and fill in the following fields, then Save.
Field | Value | Description |
|---|---|---|
Select service provider |
| The generic OpenID Connect provider (shown as "OpenID Connect (Other)"). Do not pick GitLab, Google or Office 365. |
Button Name / Button Color |
| Text and color of the sign-in button on the login page. Default: the provider name. |
Discovery Endpoint |
| Configuration Url of the Monosign access key. Mattermost reads the Auth, Token and UserInfo endpoints from it. Required. |
Client ID |
| The Client Id from the Monosign OIDC/OpenID access key (step 1). |
Client Secret |
| The Client Secret from the Monosign OIDC/OpenID access key (step 1). |
These fields map to the OpenIdSettings section of config.json (Enable, DiscoveryEndpoint, Id, Secret, Scope), so the same configuration can also be applied by editing the config file and restarting the server. Generic OpenID Connect is only available on the Enterprise Edition image (with the free Entry license); on the Team Edition image this option is not shown.
For reference, the Docker Compose file that was used for this document is below. Mattermost runs as a non-root user (UID 2000) and listens on port 8065. The Site URL is set with the MM_SERVICESETTINGS_SITEURL environment variable; the OpenID settings themselves are not environment variables, they are entered in the System Console as described above.
services:
postgres:
image: postgres:16-alpine
restart: unless-stopped
environment:
POSTGRES_USER: mmuser
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: mattermost
volumes:
- mm-postgres:/var/lib/postgresql/data
security_opt:
- no-new-privileges:true
mattermost:
image: mattermost/mattermost-enterprise-edition:11.6.6
restart: unless-stopped
depends_on:
postgres:
condition: service_healthy
user: "2000:2000"
ports:
- "8065:8065"
environment:
MM_SQLSETTINGS_DRIVERNAME: postgres
MM_SQLSETTINGS_DATASOURCE: "postgres://mmuser:${POSTGRES_PASSWORD}@postgres:5432/mattermost?sslmode=disable&connect_timeout=10"
MM_SERVICESETTINGS_SITEURL: "https://<app-address>"
volumes:
- mm-config:/mattermost/config:rw
- mm-data:/mattermost/data:rw
- mm-logs:/mattermost/logs:rw
- mm-plugins:/mattermost/plugins:rw
- mm-client-plugins:/mattermost/client/plugins:rw
- mm-bleve:/mattermost/bleve-indexes:rw
cap_drop:
- ALL
security_opt:
- no-new-privileges:true
volumes:
mm-postgres:
mm-config:
mm-data:
mm-logs:
mm-plugins:
mm-client-plugins:
mm-bleve:
The database password is kept in an .env file next to the Compose file (mode 600). When Mattermost is behind a reverse proxy, the proxy must send the header X-Forwarded-Proto: https and the Site URL must be the HTTPS address, otherwise the redirect back from Monosign fails.
The first account that registers on Mattermost becomes the System Admin. Create the local administrator account before enabling single sign-on, so you keep an admin login that does not depend on Monosign.
5- Sign In Test
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 OpenID button (its text is the Button Name set in step 4, for example Monosign).
Click the Monosign button. On the Monosign sign-in page 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 redirects the browser back to Mattermost (
/signup/openid/complete). At the first sign-in Mattermost creates the account with the name and the e-mail address from Monosign and opens the team / channel view.
Troubleshooting
Symptom | Cause | Solution |
|---|---|---|
The OpenID Connect option is missing in the System Console | The server runs the Team Edition image, which does not support generic OpenID Connect. | Use the |
The Monosign button is not shown on the login page | OpenID Connect is not enabled, or the settings were not saved. | Enable OpenID Connect in System Console > Authentication > OpenID Connect and save (step 4). |
Monosign shows a redirect URI error | The redirect address that Mattermost sends does not exactly match the Allowed Redirect URIs, usually because the Site URL is wrong. | Add |
Mattermost cannot reach Monosign (error about the discovery document, certificate or network) | The container cannot resolve or trust the address of Monosign. | Check the Discovery Endpoint, the DNS and firewall rules of the Mattermost host and that the certificate of Monosign is issued by a trusted CA. |
An error is shown after returning from Monosign | The Client ID or Client Secret is wrong. | Copy the values again from the Monosign access key (step 1) and read the Mattermost server log. |
Infinite redirect or an insecure/HTTP mismatch behind the reverse proxy | The proxy does not send | Set the Site URL to the HTTPS address and make the proxy send |
A user cannot sign in | The user is not assigned to the application. | Assign the user in step 3. |
SAML sign-in is required instead of OIDC | Mattermost also supports SAML 2.0 (with the same Entry license), but this document covers OpenID Connect. | Use the OpenID Connect integration in this document, or configure SAML 2.0 separately in System Console > Authentication > SAML 2.0. |
After completing the configuration on Mattermost and Monosign, it is better to test in a new private browser window if the OIDC SSO doesn't work, because old session cookies of the Mattermost address may cause errors.