Skip to main content
server.camp Docs server.camp Doku
Wechsel zwischen Dunkel/Hell/Auto Modus Wechsel zwischen Dunkel/Hell/Auto Modus Wechsel zwischen Dunkel/Hell/Auto Modus Zurück zur Startseite
  1. Dokumentation
  2. /
  3. Dienste
  4. /
  5. Mattermost
  6. /
  7. Single Sign-On (SSO) einrichten

Single Sign-On (SSO) einrichten

Feedback zu dieser Seite

Du kannst dein Mattermost so konfigurieren, dass sich Nutzer per Single Sign-On (SSO) gegen deinen Identity-Provider anmelden. Genutzt wird der Standard OpenID Connect – es funktioniert also mit Authentik, Keycloak, Authelia, Zitadel, Nextcloud, Google Workspace, Microsoft Entra ID und anderen OIDC-fähigen Providern.

Mattermost beschränkt generisches OpenID Connect auf die Enterprise-Edition. Wir liefern dafür ein eigenes, quelloffenes Plugin mit, das den kompletten OIDC-Flow abbildet – ohne Enterprise-Lizenz und in allen Tarifen inklusive. Die Konfiguration erfolgt self-service im Kundenportal, in Web-, Desktop- und Mobile-App.

Voraussetzungen

  • Ein aktives Mattermost-Abonnement bei server.camp
  • Eine erreichbare, OIDC-fähige Identity-Provider-Instanz (z. B. Managed Authentik bei server.camp oder eine Nextcloud, siehe unten)
  • Admin-Zugang zu beiden Systemen

Schritt 1 – Anwendung beim Identity-Provider anlegen

Lege bei deinem Identity-Provider eine neue OAuth2/OpenID-Anwendung für Mattermost an. Das genaue Vorgehen unterscheidet sich je nach Provider; diese Werte sind überall gleich:

Einstellung Wert
Client-Typ Confidential (vertraulich)
Grant-Type Authorization Code
Scopes openid, profile, email
Redirect-URI https://<deine-mattermost-domain>/plugins/mattermost-oidc/oauth2/callback

Der Pfad /plugins/mattermost-oidc/oauth2/callback ist fest vorgegeben. Maßgeblich ist die Domain, unter der dein Mattermost erreichbar ist: Hast du eine eigene Domain hinterlegt, gehört deren Adresse in die Redirect-URI – die Standard-Adresse wird dann nicht mehr verwendet.

Notiere dir anschließend Client ID, Client Secret und die Issuer-URL. Die Issuer-URL ist die Adresse, unter der die Discovery-Datei .well-known/openid-configuration liegt – ohne diesen Anhang, z. B.:

https://dein-authentik.srv.camp/application/o/mattermost/
Zugang auf Gruppen beschränken
Beschränke beim IdP den Zugriff auf die Anwendung auf eine bestimmte Gruppe (z. B. alle-mitarbeiter). So können sich nur Mitglieder dieser Gruppe über SSO in Mattermost anmelden.

Beispiel: Nextcloud als Identity-Provider

Hast du eine Nextcloud, kannst du sie ohne weiteren Dienst als Identity-Provider nutzen – zum Beispiel eine Managed Nextcloud bei server.camp:

  1. In Nextcloud mit einem Administrator-Konto anmelden
  2. Die App OIDC Identity Provider installieren und aktivieren
  3. In den Administrationseinstellungen den Bereich OpenID Connect-Anbieter öffnen, Client hinzufügen und ausfüllen:
    • Name: frei wählbar, z. B. Mattermost
    • Weiterleitungs-URI: https://<deine-mattermost-domain>/plugins/mattermost-oidc/oauth2/callback
  4. Client-ID und Client-Secret des neuen Clients notieren
  5. Als Issuer-URL genügt die Adresse deiner Nextcloud – wichtig: ohne abschließenden Schrägstrich, also z. B. https://meine-nextcloud.srv.camp

Damit hast du alles zusammen, was du für Schritt 2 brauchst. Die übrigen Felder kannst du auf den Standardwerten lassen: Nextcloud liefert preferred_username, email sowie Vor- und Nachname (aus dem Anzeigenamen aufgeteilt).

Nutzer brauchen eine E-Mail-Adresse in Nextcloud
Nextcloud gibt eine E-Mail-Adresse nur weiter, wenn sie im Profil des Nutzers hinterlegt ist. Fehlt sie, bricht die Anmeldung mit “Failed to read user information from identity provider” ab – das ist die häufigste Ursache, wenn der SSO-Login mit Nextcloud für einzelne Nutzer nicht klappt.
Mit Nextcloud keine bestätigten E-Mail-Adressen erzwingen
Nextcloud meldet E-Mail-Adressen standardmäßig als nicht bestätigt (email_verified: false) – auch die, die du selbst im Admin-Bereich eingetragen hast. Aktivierst du im Portal “Nur bestätigte E-Mail-Adressen zulassen”, schlägt damit jede Anmeldung fehl. Willst du die Option trotzdem nutzen, stelle in Nextcloud auf derselben Seite unter Einstellungen die Angabe der E-Mailadressverifizierung im Token auf Auf immer überprüft setzen – dann meldet Nextcloud email_verified: true.

Schritt 2 – Mattermost im server.camp-Portal konfigurieren

Öffne im Kundenportal die Konfiguration deines Mattermost-Abonnements. Unter Single Sign-On trägst du ein:

Feld Wert
Single Sign-on aktivieren Angehakt
OpenID Connect Issuer-URL Issuer-URL aus Schritt 1 (muss https:// sein)
OpenID Connect Client ID Aus deinem IdP kopiert
OpenID Connect Client Secret Aus deinem IdP kopiert

Speichern und warten, bis die Bereitstellung abgeschlossen ist. Beim erstmaligen Aktivieren dauert das ein paar Minuten länger als andere Änderungen, weil dabei das SSO-Plugin installiert und Mattermost neu gestartet wird. Danach erscheint auf der Login-Seite zusätzlich ein Button zur Anmeldung über deinen Provider.

Vorher: ein lokales Admin-Konto zurückhalten
Wer sich einmal per SSO anmeldet, kann sich mit diesem Konto danach nicht mehr per Passwort anmelden – dauerhaft (siehe unten). Melde dich deshalb nie mit deinem einzigen Admin-Konto per SSO an, sondern lege dir vorher ein zweites Administrator-Konto an, das ausschließlich das Passwort-Login nutzt. Das ist dein Notzugang, falls der Identity-Provider einmal ausfällt oder die Konfiguration nicht stimmt.

Schritt 3 – Neue Nutzer einem Team zuordnen

In Mattermost sieht ein Nutzer ohne Team nichts. Trage deshalb unter Standard-Team den Team-Namen ein, dem per SSO neu angelegte Konten automatisch beitreten. Gemeint ist der Name aus der URL (https://<deine-mattermost-domain>/mein-team/channels/town-square → mein-team), nicht der Anzeigename.

Bleibt das Feld leer, landen neue Nutzer nach dem ersten Login in einer Instanz ohne Team und müssen von Hand eingeladen werden.

Was mit den Konten passiert

Der erste SSO-Login legt fest, wie sich ein Konto künftig anmeldet – und das ist eine Einbahnstraße:

  • Neue Nutzer werden beim ersten SSO-Login als SSO-Konto angelegt. Sie haben nie ein Passwort und melden sich immer über deinen Identity-Provider an.
  • Bestehende Nutzer, die per E-Mail verknüpft werden (Option unten), werden dabei auf SSO umgestellt. Ihr bisheriges Passwort funktioniert danach nicht mehr – auch dann nicht, wenn du SSO später wieder abschaltest. „Passwort vergessen" hilft diesen Konten ebenfalls nicht.
  • Nicht verknüpfte Konten bleiben unangetastet und melden sich weiter mit Passwort an. Das Login-Formular verschwindet nicht; es steht neben dem SSO-Button.

Ein einmal umgestelltes Konto lässt sich nur serverseitig zurückstellen. Wenn du das brauchst, wende dich an unseren Support – bitte mit der betroffenen E-Mail-Adresse.

Praktisch heißt das: Behalte mindestens ein Administrator-Konto, das sich nie per SSO anmeldet.

Anmeldung in der Mobile-App

Die SSO-Anmeldung funktioniert auch in der nativen Mattermost-App für iOS und Android – ohne weitere Einstellung. Deine Nutzer tragen wie gewohnt die Server-Adresse ein und bekommen den SSO-Button angeboten.

Optionale Feineinstellungen

Diese Felder haben sinnvolle Standardwerte. Setze sie nur, wenn du bewusst abweichen willst:

Feld Standard Wirkung
Konten automatisch anlegen Angehakt Legt beim ersten SSO-Login automatisch ein Konto an. Ohne die Option kann sich nur anmelden, wer bereits ein Konto hat.
Bestehende Konten per E-Mail verknüpfen Nicht angehakt Verknüpft ein vorhandenes Konto mit gleicher E-Mail-Adresse beim ersten SSO-Login – dauerhaft (s. Warnung unten).
Nur bestätigte E-Mail-Adressen zulassen Nicht angehakt Lässt nur Anmeldungen zu, deren E-Mail-Adresse der Provider als bestätigt meldet. Setzt den Claim unten voraus (s. Warnung unten).
Text des Login-Buttons Log in with OIDC Beschriftung des SSO-Buttons, z. B. Mit Firmen-SSO anmelden.
Farbe des Login-Buttons #0058CC Farbe des SSO-Buttons als Hex-Wert.
OAuth 2.0 Scopes openid profile email Angefragte Scopes. Muss openid enthalten.

Die sechs Claim-Felder bestimmen, aus welchen Feldern des Tokens Mattermost Benutzername, E-Mail, Vor- und Nachname, Position sowie den Verifikationsstatus der E-Mail-Adresse übernimmt. Die Standardwerte passen zu den meisten Providern:

Feld Standard Hinweis
Claim für den Benutzernamen preferred_username Alternativ z. B. sub oder nickname.
Claim für die E-Mail-Adresse email Muss belegt sein – ohne E-Mail-Adresse lehnt Mattermost die Anmeldung ab.
Claim für den Vornamen given_name
Claim für den Nachnamen family_name Authentik liefert diesen Claim nicht; das Feld bleibt beim Nutzer dann leer.
Claim für die Position leer Etwa position oder job_title. Leer = keine Übernahme.
Claim für die E-Mail-Verifikation leer Üblich ist email_verified. Der Wert landet bei jeder Anmeldung im Mattermost-Feld “E-Mail bestätigt”. Leer = wird nicht gelesen.
Bestätigte E-Mail-Adressen erzwingen: Sperrgefahr
“Nur bestätigte E-Mail-Adressen zulassen” weist jede Anmeldung ab, bei der der Claim fehlt oder auf “nicht bestätigt” steht – ohne Konto anzulegen, zu verknüpfen oder eine Sitzung zu vergeben. Viele Provider senden email_verified gar nicht oder nur, wenn der Scope ihn ausdrücklich anfordert. Trage deshalb erst den Claim ein, prüfe mit einem Testkonto, dass die Anmeldung weiter klappt, und aktiviere die Option danach – sonst sperrst du alle Nutzer auf einmal aus.
Konten per E-Mail verknüpfen: Vorsicht

“Bestehende Konten per E-Mail verknüpfen” stellt ein vorhandenes Konto mit derselben E-Mail-Adresse dauerhaft auf SSO um – das Passwort dieses Kontos funktioniert danach nicht mehr. Und wer die E-Mail-Adresse beim Identity-Provider kontrolliert, übernimmt damit dieses Konto. Aktiviere die Option nur, wenn du deinem Provider die Adressen wirklich anvertraust und dort E-Mail-Adressen verifiziert werden.

Bleibt die Option aus, schlägt der SSO-Login für Adressen fehl, die es in Mattermost schon gibt – die bestehenden Konten sind damit geschützt.

Zwei-Faktor-Authentisierung beim Provider erzwingen
Die SSO-Anmeldung erzeugt die Sitzung direkt nach dem OIDC-Flow und wertet die Mattermost-eigene 2FA nicht aus. Wer sich per SSO anmeldet, umgeht sie also. Erzwinge Zwei-Faktor-Authentisierung deshalb beim Identity-Provider – dort greift sie für jede Anwendung und jeden Client.

Login-Ablauf für deine Nutzer

  1. Mattermost im Browser, in der Desktop- oder in der Mobile-App öffnen
  2. Auf der Login-Seite den SSO-Button anklicken
  3. Weiterleitung zum Identity-Provider, dort anmelden (und ggf. 2FA)
  4. Zurück in Mattermost – der Nutzer ist angemeldet
Erst testen, dann ausrollen
Teste den SSO-Login mit einem eigens dafür angelegten Testkonto, nicht mit deinem Admin-Konto – der erste SSO-Login stellt das verwendete Konto dauerhaft auf SSO um. So siehst du früh, ob Redirect-URI, Claims und Standard-Team stimmen, ohne dein Passwort-Login zu verlieren.

Fehlerbehebung

  • “redirect_uri mismatch” beim IdP: Die Redirect-URI beim Provider stimmt nicht. Prüfe sie zeichengenau, inklusive https:// und Pfad /plugins/mattermost-oidc/oauth2/callback. Bei eigener Domain muss die Callback-URL auf diese Domain zeigen, nicht auf die Standard-Adresse.
  • Kein SSO-Button sichtbar: Ist “Single Sign-on aktivieren” angehakt und die Bereitstellung abgeschlossen? Danach hilft ein Neuladen der Seite mit geleertem Browser-Cache.
  • “Issuer-URL muss HTTPS verwenden”: Die Issuer-URL muss mit https:// beginnen; http:// lehnt das Plugin ab.
  • Der SSO-Button ist da, führt aber zu “OIDC provider not initialized. Check plugin configuration.”: Das Plugin konnte den Provider beim Start nicht einlesen. Meist steht ein Schrägstrich zu viel am Ende der Issuer-URL – sie muss zeichengenau der Adresse entsprechen, die der Provider in seiner Discovery-Datei als issuer meldet. Ebenfalls möglich: Der Provider war nicht erreichbar oder sein TLS-Zertifikat ist ungültig.
  • “Failed to read user information from identity provider” (im Server-Log: email claim 'email' is empty): Der Provider liefert keine E-Mail-Adresse. Prüfe, ob der Scope email zugewiesen ist und der Claim-Name stimmt. Bei Nextcloud als Provider: Hat der Nutzer in seinem Nextcloud-Profil überhaupt eine E-Mail-Adresse hinterlegt?
  • “Your email address is not verified by your identity provider”: “Nur bestätigte E-Mail-Adressen zulassen” ist an, der Provider meldet die Adresse aber nicht als bestätigt. Prüfe den Claim für die E-Mail-Verifikation und ob der Provider email_verified überhaupt liefert – notfalls die Option wieder abschalten.
  • Anmeldung bricht mit “Sitzung abgelaufen” ab: Zwischen dem Klick auf den SSO-Button und der Rückkehr vom Identity-Provider sind mehr als zehn Minuten vergangen, oder die Rücksprung-Seite wurde erneut geladen. Melde dich einfach noch einmal an.
  • Nutzer ist angemeldet, sieht aber nichts: Kein Team. Trage ein Standard-Team ein (Schritt 3) oder lade den Nutzer manuell in ein Team ein.
  • “Konto existiert bereits” / Anmeldung bricht ab, obwohl der Nutzer ein Konto hat: Die E-Mail-Adresse gehört zu einem bestehenden Konto, und “Bestehende Konten per E-Mail verknüpfen” ist aus. Entweder die Option aktivieren (Konto wird dauerhaft auf SSO umgestellt) oder den Nutzer weiter per Passwort anmelden lassen.
  • Ein Nutzer kann sich plötzlich nicht mehr per Passwort anmelden: Das ist so gewollt – sein Konto ist beim ersten SSO-Login auf SSO umgestellt worden. Zurück geht es nur serverseitig, über unseren Support.

Bei weiteren Fragen erreichst du unseren Support über das Kundenportal.

Mattermost – Erste Schritte Mattermost – GitLab-Integration