Mattermost Self-Hosted: SSO with Authentik as IDP in the Free Version

Mattermost is used in many companies as a central communication platform. It is comparable to Microsoft Teams or Slack. So, what sets Mattermost apart from other communication platforms? Mattermost is fundamentally free. Additionally, you can run the open-source software on your own servers, which is a crucial criterion for some companies, keyword: Compliance.

A major drawback of the free version of Mattermost is the limitation to authenticate only via GitLab SSO if you want more than users in the Mattermost internal DB. If your company uses GitLab as the central user management, this poses no problem. However, most companies use dedicated IDPs (Identity Providers) like Keycloak, Authentik, or Auth0.

In this blog post, we want to remove the intermediary GitLab from this equation and connect Mattermost directly with Authentik.

Important: To prevent data loss, backups should be made before making changes to running systems. It is also important to mention that further individual changes may be necessary depending on the configuration of the respective instances.

Current Infrastructure

The current infrastructure consists simply of a Mattermost instance in the free version, a GitLab instance in the CE edition, and an Authentik instance. All these instances are self-hosted.

Currently, the process is that a user accesses the Mattermost instance. Here, they are redirected by clicking on the GitLab SSO. Upon reaching the GitLab SSO, the user can log in to the IDP (Authentik). The user essentially hops over GitLab to the Authentik instance. The actual authentication to Mattermost happens via the GitLab session and the GitLab user ID used there.

If a completely new infrastructure is being created, the following part is not important. If users already exist in Mattermost, they should not be deleted. As mentioned, the GitLab user ID is linked to the Mattermost account. This is important to correct the user mapping later in this migration.

Authentik

Creating Property Mappings

Mattermost expects certain return values, which must be included by Authentik in the SSO response. These can be defined in Authentik in the Property Mappings. To do this, call the following URL adapted to the company: https://id.example.de/if/admin/#/core/property-mappings

By clicking “Create” > “Scope Mapping,” two new mappings must be created here.

Name: username
Scope name: username
Expression: return { "username": request.user.username }

Name: mattermostId
Scope name: id
Expression: return { "id": request.user.attributes.get("mattermostId", request.user.id) }

A brief explanation of the Property Mapping mattermostId: The expression checks if the user has an attribute named “mattermostId” set. If so, this is returned. If the attribute is not set, the user ID is returned. This is how the user mapping is established later.

Creating Application and Provider

Following the Property Mappings, a provider for Mattermost must be created. Here, a standard OAuth2/OpenID provider is created. It is important to include the created Property Mappings in the provider. To do this, edit the scopes in the provider and activate the following scopes:

• authentik default OAuth Mapping: OpenID ’email'
• authentik default OAuth Mapping: OpenID ‘openid’
• authentik default OAuth Mapping: OpenID ‘profile’
• mattermostId
• username

Changing User Attributes

This section is only important if a Mattermost instance has already been used and was previously authenticated via GitLab. Here, the so-called user mapping must now be adjusted. If this is a completely new installation without having used GitLab before, this section can be ignored. Here, the user ID of a GitLab user is mapped to the Authentik user.

In a self-hosted GitLab instance, all users can be accessed via the following link: https://gitlab.example.de/admin/users. Clicking on the respective user opens a user-specific view with various information. The ID is important here. This is the user ID with which the Mattermost account (internally) was created. We copy this ID to the clipboard.

In the next step, we open our Authentik admin panel. Under “Directory” > “Users,” we find all created users. Now we edit the user profile of the aforementioned user. Under “Attributes,” the following line is added:

mattermostId: <GITLAB_USER_ID>

Clicking the “Update” button saves the attribute and maps the already existing Mattermost account to the Authentik user. For new users, this step is not necessary.

Mattermost

Configuring Mattermost

In Mattermost itself, that is, the admin console, no change should be necessary. The required changes are provided via the config.json. Here, the part of the GitLab settings must be edited.

Important: The IDP configuration must be defined via the key GitLabSettings. The configuration in OpenIdSettings only works in the paid version.

The following settings must be individually adjusted in the config.json. Theoretically, specifying the discovery endpoint is sufficient, and specifying the respective endpoints is unnecessary.

"GitLabSettings": {
        "Enable": true,
        "Secret": "CLIENT_SECRET_HERE",
        "Id": "CLIENT_ID_HERE",
        "Scope": "",
        "AuthEndpoint": "https://id.example.de/application/o/authorize/",
        "TokenEndpoint": "https://id.example.de/application/o/token/",
        "UserAPIEndpoint": "https://id.example.de/application/o/userinfo/",
        "DiscoveryEndpoint": "https://id.example.de/application/o/<AUTHENTIK_APPLICATION_ID_SLUG_HERE>/.well-known/openid-configuration",
        "ButtonText": "Login with Example",
        "ButtonColor": "#ADD015"
    }

After changing the file, the Mattermost container can be restarted.

Invalidating Sessions

To ensure that every user must log in with the new authentication method, all current sessions can be invalidated under the “Users” tab in the system console.

Conclusion

With this guide, we have replaced GitLab as the intermediary IDP. A new provider and a new application were created in Authentik. Additionally, Property Mappings were set up. Authentik was configured as the primary IDP via the config.json file. From now on, Authentik is used to authenticate users for Mattermost. By adding GitLab user IDs to already existing Authentik users, existing accounts and thus also chats in Mattermost are retained.