How to use Mattermost OAuth2 for free (with authentik)

Mattermost is an exceptional piece of open source software and I've come to love it as an great self-hosted alternative to Slack, MS Teams or other open source software such as Rocket.Chat. However, one disadvantage is the lack to use a centralized authentication server (such as authentik) with the free version of the software. Fortunately there is a workaround which can be easily deployed without too much of a hassle. Let me walk you through it 🤗

There are two ways we can configure Mattermost to use an OAuth2 server of our choice for free. Both ways require us to use the GitLab OAuth2 integration which is included in the community (free) version of Mattermost. Which method you should choose depends on the level of permission you have on the deployment on both Mattermost and authentik.

Create authentik Application and Provider

authentik and Mattermost can trade authorization and authentication via OAuth2 properties. But Mattermost won't accept the default properties shipped with authentik. Hence we have to create two custom properties in authentik.

To do this, navigate to the Property Mappings which can be found under the "Customization" submenu in the authentik administrator dashboard. Once loaded press "Create" and select "Scope Mapping". Now enter the following information:

Name: Mattermost ID
Scope Name: id
Description: optional own description
Expression: return { "id": request.user.id }

Afterwards create another "Scope Mapping" and fill in the following:

Name: Mattermost Username
Scope Name: username
Description: optional own description
Expression: return { "username": request.user.username }

Of course you can alter the name, enter your own description and even change the expression to your liking. However, this is out of scope for this article.

After you've successfully created the mappings let's create an application and provider with the new (version: ≥2024.2) authentik wizard. Therefore we'll need to navigate to the Applications page in the menu of the authentik administrator dashboard.

Next, open the wizard by clicking "Create With Wizard." You can now enter details that align with your organization's or personal preferences. For instance, entering "Mattermost" in the name field will automatically generate the corresponding slug. Optionally, you can specify a group and choose a policy method. Then, expand the "UI Settings" tab and input a URL similar to the following format: https://mattermost.company.tld/oauth/gitlab/login.

Press next to continue creating a provider for this application. In this case we will need to create an OAuth2/OIDC provider. Select this from the available providers and press Next once again.

Now, enter a name for the provider (e.g., "OAuth2: Mattermost"), and select both an authentication flow and an authorization flow. Before proceeding, be sure to record the Client ID and Client Secret in a safe place, or ensure you know how to retrieve them later, as you'll need these credentials in the upcoming steps.

Enter the following into the Redirect URIs/Origins (RegEx) field to allow users to both signup and login to Mattermost via authentik. Later on you can always decide to disable registration to Mattermost.

https://mattermost.company/login/gitlab/complete
https://mattermost.company/signup/gitlab/complete

Another very important step is the need for selecting the correct scopes (which we created earlier on). Therefore, open the dropdown which is labeled "Advanced protocol settings" and scroll down to "Scopes". In here move "Mattermost ID" and "Mattermost Username" to the "Selected Scopes" column (assuming you've used the same names as stated earlier in this article).

Once finished create the provider using the blue button in the footer of the popup. Success! We've configured authentik to handle Mattermost requests correctly after we've setup Mattermost 😉.

Right now you will have to decide which part of this article you'll use to configure Mattermost. If you have read and write permissions to the config.json file of Mattermost it is advised to continue with the next part. Otherwise, or if you don't want to modify this document, continue under the dedicated section.

Access to Mattermost' config.json

Mattermost provides administrators with a comprehensive "System Console" dashboard for configuring and monitoring their instance. However, some settings are not accessible through the graphical user interface (GUI). For configurations beyond the GUI, you can make changes directly via the config.json file, provided you have access to it. If you do not have access to the file, refer to the next section for alternative instructions.

Open the config.json file in a file editor of your choice and scroll down to the GitLabSettings array. In here, enable the module by modifying the Enable key from false to true. Then also enter your authentik provider client ID and client secret. The AuthEndpoint, TokenEndpoint and UserApiEndpoint should look something like the URLs in the following example.

"GitLabSettings": {
  "Enable": true,
  "Secret": "YOUR_AUTHENTIK_PROVIDER_CLIENT_SECRET",
  "Id": "YOUR_AUTHENTIK_PROVIDER_CLIENT_ID",
  "Scope": "",
  "AuthEndpoint": "https://authentik.company/application/o/authorize/",
  "TokenEndpoint": "https://authentik.company/application/o/token/",
  "UserAPIEndpoint": "https://authentik.company/application/o/userinfo/",
  "DiscoveryEndpoint": "",
  "ButtonText": "Login with SSO",
  "ButtonColor": ""
},

Optionally, edit the ButtonText, ButtonColor or other settings in the config.json file. After you've saved the file restart the Mattermost instance. For example using docker compose up -d assuming you use Docker Compose to deploy Mattermost.

You've completed the guide successfully. After Mattermost has restarted check whether the OAuth2 process works. Finally, in the System Console of Mattermost under Authentication, you can tweak some settings so that access to the server can only be provided via OAuth2.

No access to Mattermost' config.json

If you have no write access to the config.json file or if you have any other reason why you don't want to alter this file you can still use any self-hosted or GitLab compatible authentication server. To do this get into the System Console of Mattermost and navigate to Authentication->GitLab.

In here, enable the settings and enter your Application ID and Secret which you've previously saved from authentik. In the GitLab Site URL you can enter the following URL: https://authentik.company/application/o/gitlab where, of course, you need to change the domain to your actual authentik instance.

Now, there is one last step to allow Mattermost to communicate with authentik and that is to set-up three redirects in the (reverse) proxy of authentik. The pages that need to be redirected are the following:

• /application/o/gitlab/api/v4/user --> /application/o/userinfo/
• /application/o/gitlab/oauth/authorize --> /application/o/authorize/
• /application/o/gitlab/oauth/token --> /application/o/token/

If you're using NGINX for proxying the requests you can add these lines to your configuration file for authentik.

# GitLab emulation
rewrite ^/application/o/gitlab/api/v4/user$ /application/o/userinfo/ redirect;
rewrite ^/application/o/gitlab/oauth/authorize$ /application/o/authorize/ redirect;
rewrite ^/application/o/gitlab/oauth/token$ /application/o/token/ redirect;

You've completed the guide successfully. Restart Mattermost and the NGINX webserver and check whether the OAuth2 process works. Finally, in the System Console of Mattermost under Authentication, you can tweak some settings so that access to the server can only be provided via OAuth2.

Troubleshooting

Token request failed

If you have your authentik instance deployed on the same machine as Mattermost you might have connection issues and receive errors like "Token request failed". When checking your error logs you might encounter an error like the following.

{..."error":"AuthorizeOAuthUser: Token request failed., Post \"https://authentik.company/application/o/token/\": dial tcp AUTHENTIK_IP:443: i/o timeout"}

If this is the case, you might need to alter your TokenEndpoint and UserAPIEndpoint in your config.json to a local IP or hostname instead of the publicly available authentik URL. For example, when using Docker you can use the hostname of the authentik-server container. To illustrate this you can take a look at the following part of the config.json file.

"GitLabSettings: {
  ...,
  "AuthEndpoint": "https://authentik.company/application/o/authorize/",
  "TokenEndpoint": "http://authentik-server-1:9000/application/o/token/",
  "UserAPIEndpoint": "http://authentik-server-1:9000/application/o/userinfo/",
  ...
}

Notice the difference between the AuthEndpoint and the other endpoints; it is because the AuthEndpoint is the place where users will get redirected after pressing the Login with SSO button and therefore has to be a public URL. The other URLs are local hostnames and are only used for token and user information exchange between Mattermost and authentik. Since they won't leave the machine there is no TLS encryption.