Mattermost Self-Hosted: SSO mit Authentik als IDP in der Free-Version

Mattermost wird in vielen Unternehmen als zentrale Kommunikationsplattform verwendet. Es ist vergleichbar mit Microsoft Teams oder auch Slack. Was ist nun der Unterschied zwischen Mattermost und anderen Kommunikationsplattformen? Mattermost ist grundsätzlich kostenlos. Zudem kann man die Open-Source-Software auf eigenen Servern betreiben, was für einige Unternehmen ein wichtiges Kriterium sein wird, Stichwort: Compliance.

Ein großer Nachteil an der Free-Version von Mattermost ist die Limitierung sich nur via GitLab SSO authentifizieren zu können, sollte man mehr wollen als User in der Mattermost-internen DB. Sofern man GitLab als zentrale Nutzerverwaltung im Unternehmen verwendet stellt dies kein Problem dar. Meist verwenden Unternehmen jedoch dedizierte IDPs (Identity Provider) wie Keycloak, Authentik oder Auth0.

In diesem Blogeintrag möchten wir den Mittelsmann GitLab aus dieser Gleichung streichen und Mattermost direkt mit Authentik verknüpfen.

Wichtig: Um Datenverlust vorzubeugen sollten Datensicherungen vor Änderungen an laufenden Systemen angefertigt werden. Ebenfalls wichtig zu erwähnen ist, dass weitere individuelle Änderungen je nach Konfiguration der jeweiligen Instanzen notwendig sind.

Aktuelle Infrastruktur

Die aktuelle Infrastruktur besteht simpel dargestellt aus einer Mattermost-Instanz in der Free-Version, einer GitLab-Instanz in der CE-Edition und einer Authentik-Instanz. Alle diese Instanzen werden selbst betrieben.

Der Ablauf momentan sieht so aus, dass ein User die Mattermost-Instanz aufruft. Hier wird er über einen Klick auf den GitLab-SSO weitergeleitet. Am GitLab-SSO angekommen kann der User sich an dem IDP (Authentik) anmelden. Der User hüpft sozusagen über GitLab auf die Authentik-Instanz. Die eigentliche Authentifizierung an Mattermost geschieht dabei über die GitLab Session und die dort genutzte GitLab-User-Id.

Sofern eine komplett neue Infrastruktur erstellt wird ist der folgende Part nicht wichtig. Sollten bereits Benutzer in Mattermost vorhanden sein, sollten diese natürlich nicht gelöscht werden. Wie bereits erwähnt ist die GitLab-User-Id mit dem Mattermost-Account verknüpft. Dies ist wichtig um im späteren Verlauf dieser Migration das User-Mapping zu korrigieren.

Authentik

Erstellung Property Mappings

Mattermost erwartet bestimmte Rückgabewerte, welche von Authentik in der SSO-Response mitgegeben werden müssen. Diese können in Authentik in den Property Mappings definiert werden. Hierzu folgende, auf das Unternehmen angepasste, URL aufrufen: https://id.example.de/if/admin/#/core/property-mappings

Mit dem Klick auf “Create” > “Scope Mapping” müssen hier zwei neue Mappings erstellt werden.

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) }

Eine kurze Erläuterung zum Property Mapping mattermostId: Die Expression überprüft ob der User ein Attribut namens “mattermostId” gesetzt hat. Falls ja wird dieses zurückgegeben. Sollte das Attribut nicht gesetzt sein, so wird die User-Id zurückgegeben. Hierüber wird im späteren Verlauf das User-Mapping hergestellt.

Erstellung Application und Provider

Im Anschluss zu den Property Mappings muss ein Provider für Mattermost erstellt werden. Hier wird ein normaler OAuth2/OpenID Provider erstellt. Wichtig ist es die erstellten Property Mappings in dem Provider mitzugeben. Hierfür im Provider die Scopes editieren und folgende Scopes aktivieren:

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

Änderungen User Attribute

Dieser Abschnitt ist nur wichtig, sofern bereits eine Mattermost-Instanz verwendet wurde und diese vorher über GitLab authentifiziert hat. Hier muss nun das sogenannte User-Mapping angepasst werden. Ist dies eine komplett neue Installation, ohne vorher GitLab verwendet zu haben, kann dieser Abschnitt ignoriert werden. Hierzu wird die User-ID eines GitLab-Users auf den Authentik-User gemappt.

In einer selbstgehosteten GitLab-Instanz sind alle User unter folgendem Link abrufbar: https://gitlab.example.de/admin/users . Ein Klick auf den jeweiligen User öffnet eine userspezifische Ansicht mit verschiedensten Informationen. Wichtig ist hier die ID. Dies ist die Benutzer-ID mit welcher der Mattermost-Account (intern) erstellt wurden. Diese ID kopieren wir uns in die Zwischenablage.

Im nächsten Schritt öffnen wir unser Authentik-Admin-Panel. Unter “Directory” > “Users” finden wir alle angelegten Benutzer. Nun bearbeiten wir das Benutzer-Profil des o. g. Users. Unter “Attributes” wird nun folgende Zeile hinzugefügt:

mattermostId: <GITLAB_USER_ID>

Der Klick auf den Button “Update” speichert das Attribut und mappt den bereits vorhandenen Mattermost-Account auf den Authentik-User. Für neue Benutzer ist dieser Schritt nicht notwendig.

Mattermost

Konfiguration Mattermost

In Mattermost selbst, also der Admin-Konsole, sollte keine Änderung notwendig sein. Die benötigten Änderungen werden über die config.json mitgegeben. Hier muss der Part der GitLab-Settings editiert werden.

Wichtig: Die Konfiguration des IDP muss über den Key GitLabSettings definiert werden. Die Konfiguration in OpenIdSettings funktioniert nur in der kostenpflichtigen Version.

Die folgenden Einstellungen müssen in der config.json individuell angepasst werden. Theoretisch ist die Angabe von dem Discovery-Endpoint ausreichend und die Angabe der jeweiligen Endpoints überflüssig.

"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"
    }

Nach dem Ändern der Datei kann der Mattermost-Container neugestartet werden.

Sessions invalidieren

Damit jeder User sich mit der neuen Authentifizierungs-Methode einloggen muss, können in der Systemkonsole unter dem Tab “Benutzer” alle aktuellen Sessions invalidiert werden.

Fazit

Mit diesem Guide haben wir GitLab als Mittelsmann-IDP abgelöst. Es wurde ein neuer Provider und eine neue Application in Authentik erstellt. Zusätzlich dazu wurden Property Mappings angelegt. Über die Datei config.json wurde Authentik als primärer IDP konfiguriert. Ab nun wird Authentik verwendet um die User für Mattermost zu authentifzieren. Durch das Hinzufügen von GitLab-User-Ids zu bereits existierenden Authentik-Usern bleiben bereits in Mattermost bestehende Accounts und somit auch Chats erhalten.