Setting up GitLab OAuth for Mattermost using Authentik

Currently, we (MMLAB) use Mattermost as a collaboration tool.
Recently, we’ve introduced Authentik to unify accounts across our website, webmail, wiki, and Mattermost.

We successfully configured the website, webmail, and wiki using Authentik’s OIDC provider. However, Mattermost’s OIDC integration requires a paid license.

The only SSO provider supported by Mattermost’s free Team Edition is GitLab OAuth (see: https://docs.mattermost.com/onboard/sso-gitlab.html).

Thus, we configured Authentik’s OIDC provider to mimic GitLab OAuth for integration with Mattermost.
Although some online resources existed, differences in Mattermost and Authentik versions made the setup challenging.

This tutorial is based on Mattermost version 10.9.1 and Authentik version 2025.6.3.
Also, you must use a reverse proxy in front of Authentik (in order to configure path rewrites).
We use Caddy v2 as our reverse proxy; instructions in this tutorial assume that.
If you use another proxy like Traefik or Nginx, adjust your configuration accordingly.

Note: This tutorial uses Authentik OAuth2 provider’s GitHub-compatible endpoint.

1. Authentik Configuration

Create Application

In the admin interface, select “Applications” from the sidebar, then click “Create,” and fill in:

• Name: Mattermost
• Slug: mattermost

Click “Create” at the bottom to finish.

Create Provider

Next, go to “Providers” in the sidebar, click “Create,” and select “OAuth2/OpenID Provider.” Click “Finish.”

On the next screen, enter and save the following:

• Name: Provider for Mattermost (or any descriptive name)
• Authorization Flow: Choose freely; I used default-provider-authorization-explicit-consent (Authorize Application)
• Redirect URI/Origin (Regex):
  • https://mattermost.my.domain/signup/gitlab/complete
  • https://mattermost.my.domain/login/gitlab/complete
  • Replace mattermost.my.domain with your actual Mattermost server domain.
• Advanced Protocol Settings > Scopes: You may remove all scopes (including openid, profile, email) because we’ll use Authentik’s GitHub-compatible endpoint, which uses special scopes.
• Note down Client ID and Client Secret for the next steps.

Link Provider to Application

Again, go to Applications -> select Mattermost -> edit -> select “Provider for Mattermost.”

2. Configure GitLab Auth in Mattermost

In Mattermost’s admin UI, navigate to Authentication -> GitLab.

• Enable authentication with GitLab: True
• Application ID: Client ID noted in step 1
• Application Secret Key: Client Secret noted in step 1
• GitLab Site URL: Authentik URL (e.g., https://sso.my.domain)

Save.

3. Configure Reverse Proxy

Modify your Authentik reverse proxy config file, adding path rewrite rules.

Here’s an example Caddyfile for Caddy reverse proxy:

sso.my.domain {
    uri replace /api/v4/user /user  1                         # User API Endpoint
    uri replace /oauth/authorize /login/oauth/authorize 1     # Auth Endpoint
    uri replace /oauth/token /login/oauth/access_token 1      # Token Endpoint
    uri replace /login/login/oauth /oauth 1
    reverse_proxy localhost:9000
}

4. Logging into Mattermost via GitLab OAuth

Login procedure differs based on whether the user is new or existing in Mattermost.

New Mattermost Users

Click “Log in with GitLab” on Mattermost’s login page. Authentik will prompt for login (or registration), after which you’ll be redirected to Mattermost. A Mattermost account is automatically created.

Existing Mattermost Users

Mattermost doesn’t provide an admin feature to bulk switch existing users to SSO, unlike most SSO-compatible apps. Each user must individually switch their accounts.

Below are instructions I shared with our lab members:

1. Log in to your Mattermost account in the browser. (Not mobile, not the desktop app.)
2. Click your profile image (top-right) -> Profile.
3. Click “Security.”
4. At bottom, click “Edit” next to “Sign-in Method.”
5. Click “Switch to Using GitLab SSO.”
6. Enter your current Mattermost password, then click “Switch Account to Gitlab SSO.”
7. Upon redirect, log in with your Authentik SSO credentials.
8. After switching, always log into Mattermost using the “Log In with SSO” option. (Previous username/password will no longer work.)

Tips

Changing GitLab Button Text or Hiding the Icon in Login Page

To modify the GitLab button text in the Mattermost login page, edit Mattermost’s config.json:
Change GitLabSettings.ButtonText to your preferred text.

There’s no direct setting to hide the GitLab icon, but I hid it with custom CSS. Because Mattermost lacks custom CSS support, I created a plugin following instructions in this repository.

The CSS I used:

svg[aria-label="Gitlab Icon"] {
    display: none !important;
}

Disable ID/Password Login

Once all users have switched to SSO, disable standard login methods via Mattermost admin UI -> Authentication -> Email:

• Enable account creation with email: False
• Enable sign-in with email: False
• Enable sign-in with username: False

Wrapping Up

I’m unsure how best to conclude this post.
In the future, I’ll continue to share lab server administration logs and other tips that seem too useful to keep to myself.
Thanks!