AuthSaml

Überblick

AuthSaml macht Ihren Identity Provider zur einzigen Quelle der Wahrheit für Matomo: Anmeldung per SAML 2.0 Single Sign-on, Benutzer-Lebenszyklus per SCIM 2.0 und Site-Berechtigungen direkt aus den Gruppen Ihres IdP. Das Plugin funktioniert mit jedem SAML-2.0-Provider und ist mit Okta, Microsoft Entra ID und Keycloak getestet.

Login und Rechte aus einer Hand

Beim ersten SSO-Login legt AuthSaml das Matomo-Konto automatisch an (Just-in-Time-Provisionierung). Bei jedem Login synchronisiert es die Site-Berechtigungen aus den Gruppen-Claims: Im Admin-Bereich ordnen Sie IdP-Gruppen den Matomo-Sites und einer Rolle zu (Ansicht, Schreiben oder Administrator). Ab dann verwalten Sie Zugriffe nur noch im IdP. Alternativ oder zusätzlich liest AuthSaml Rechte aus einem direkten Attribut (z. B. matomo_access = "view:1,4;write:2").

Drei Sync-Modi bestimmen, wie streng der IdP führt: additiv (nur vergeben, nie entziehen), verwaltet (entzieht nur, was das Plugin selbst vergeben hat; manuell vergebene Rechte bleiben unangetastet) oder autoritativ (der IdP bestimmt die Rechte vollständig).

Offboarding, das sofort greift

Mit aktiviertem SCIM 2.0 überträgt Ihr IdP Benutzer und Gruppen aktiv nach Matomo: Neue Teammitglieder sind angelegt, bevor sie sich das erste Mal anmelden. Meldet der IdP eine Person als ausgeschieden, deaktiviert AuthSaml das Konto sofort: Der Login ist gesperrt, laufende Sitzungen enden und die vom Plugin vergebenen Rechte werden entzogen, ohne dass jemand daran denken muss. Gruppen-Änderungen im IdP wirken unmittelbar auf die Site-Rechte, ganz ohne Login-Vorgang.

Sicher ab Werk, ohne Aussperr-Risiko

Signierte Assertions, RSA-SHA256, Strict-Modus und Replay-Schutz sind Standard. Gleichzeitig ist AuthSaml so gebaut, dass Sie ein IdP-Ausfall nicht aussperrt: Hauptadministratoren erreichen über einen Break-Glass-Zugang das Passwort-Formular, auch wenn Force SSO aktiv ist. Login-Einschränkungen greifen erst, wenn SAML tatsächlich konfiguriert ist. Nur wenn Sie den Passwort-Login für alle abschalten, ist auch der Break-Glass-Zugang gesperrt.

Einrichtung per Metadata-Import

SP-Metadata-URL in den IdP kopieren, IdP-Metadata-URL im Plugin eintragen: Import und täglicher Abgleich sind inklusive, ein Zertifikatswechsel beim IdP (z. B. bei Entra ID) wird automatisch übernommen. Gruppen-Mapping anlegen, fertig. Die Admin-Seite zeigt die letzten SSO-Fehler, bei abgelehnten Logins mitsamt der tatsächlich empfangenen Gruppen und Attribute. Schluss mit Rätselraten, warum ein Login scheitert. Für automatisierte Abläufe gibt es Konsolen-Befehle, Schritt-für-Schritt-Anleitungen für Okta, Entra ID und Keycloak stehen in der Dokumentation.

Eine Lizenz, der ganze Lebenszyklus

AuthSaml ist bewusst als Komplettlösung angelegt: Eine Lizenz deckt den gesamten Benutzer-Lebenszyklus ab, von der SAML-Anmeldung über die Rechteverwaltung mit IdP-Gruppen bis zur SCIM-Provisionierung mit sofortigem Offboarding. Das ersetzt manuelle Benutzerpflege und separate Provisionierungs-Werkzeuge.

Einsatzszenarien

• Ein Login für alles: Ihre Nutzer melden sich mit dem Firmen-Login an, SP- oder IdP-initiiert, optional mit Single Logout und Force SSO. Konten entstehen automatisch beim ersten Login.
• Rechte aus IdP-Gruppen: Gruppe → Sites → Rolle: Das Mapping im Admin-Bereich macht Ihren IdP zur Rechteverwaltung. Synchronisiert wird bei jedem Login und jeder SCIM-Änderung, manuell vergebene Rechte bleiben auf Wunsch unangetastet.
• Offboarding in Echtzeit: Sobald Ihr IdP per SCIM 2.0 einen Austritt meldet, deaktiviert AuthSaml das Konto: Sitzungen enden, die vom Plugin vergebenen Rechte werden entzogen. Ohne Login-Vorgang und ohne manuelle Nacharbeit.
• Kein Aussperr-Risiko: Strict-Modus, signierte Assertions und Replay-Schutz sind Standard. Trotzdem behalten Hauptadministratoren in der Standardeinstellung einen Break-Glass-Zugang per Passwort, damit Sie ein IdP-Ausfall nicht aus Matomo aussperrt.
• Diagnose statt Support-Ticket: Die Admin-Seite zeigt die letzten SSO-Fehler, bei abgelehnten Logins inklusive der empfangenen Gruppen und Attribute. So sehen Sie schnell, warum ein Login scheitert und was im IdP zu tun ist.

Einrichtung Schritt für Schritt

Wie Sie das Plugin installieren, steht unter Plugins installieren. Für die Einrichtung brauchen Sie ein Matomo-Konto mit Hauptadministrator-Rechten, Admin-Zugang zu Ihrem Identity Provider (IdP) und eine per NTP synchronisierte Serveruhr, denn die SAML-Prüfung toleriert nur etwa drei Minuten Abweichung.

1. Daten für den IdP holen. Öffnen Sie in Matomo Administration → System → SAML SSO. Dort finden Sie die SP-Metadata-URL, die ACS-URL (Reply-URL) und die SSO-Login-URL. Die SP-Entity-ID ist standardmäßig die URL Ihrer Matomo-Instanz.
2. Anwendung im IdP anlegen. Legen Sie eine SAML-2.0-Anwendung an, tragen Sie ACS-URL und SP-Entity-ID ein und lassen Sie den IdP E-Mail, Anzeigename und Gruppen als Attribute senden. Die Klickpfade für Entra ID, Okta und Keycloak stehen unten bei den Praxisbeispielen.
3. IdP in Matomo eintragen. Unter Administration → System → Allgemeine Einstellungen → FeinwerkAuthSaml (oder über Einstellungen öffnen auf der Admin-Seite) tragen Sie die IdP-Metadata-URL ein. Entity-ID, SSO-URL und Zertifikate werden dann importiert und täglich aktualisiert. Ohne Metadata-URL pflegen Sie IdP-Entity-ID, IdP-Single-Sign-On-URL und IdP-X.509-Zertifikat (PEM) von Hand.
4. Attribute zuordnen. Im Abschnitt Attribut-Mapping passen die Standardwerte email, displayName und groups zu Okta und Keycloak. Optional liest das Direkt-Berechtigungs-Attribut (Standard matomo_access) Rechte wie view:1,4;write:2 oder view:* direkt aus dem IdP.
5. Gruppen zuordnen. Auf der Admin-Seite legen Sie unter Gruppen-Mappings mit Mapping hinzufügen fest, welche IdP-Gruppe welche Sites (oder ★ Alle Sites) mit welcher Rolle (Ansicht, Schreiben oder Administrator; in der Auswahl als view, write und admin angezeigt) bekommt, und klicken auf Mappings speichern.
6. Login-Verhalten festlegen. Auf der Login-Seite erscheint jetzt der Button Mit SSO anmelden. Erst wenn Ihr Test klappt, aktivieren Sie bei Bedarf Force SSO und wählen unter Passwort-Login erlaubt für, wer sich noch per Passwort anmelden darf (Standard: Nur Superuser).
7. Optional: SCIM. Aktivieren Sie SCIM-2.0-Endpoint aktivieren und erzeugen Sie auf der Admin-Seite mit Neuen Token generieren einen Bearer-Token. Er wird nur einmal angezeigt. Im IdP tragen Sie die SCIM-Basis-URL https://<matomo>/index.php/scim/v2 und den Token ein. Unter Offboarding-Verhalten wählen Sie Benutzer deaktivieren (empfohlen) oder Benutzer endgültig löschen.
8. Optional: Single Logout. Klicken Sie auf SP-Zertifikat generieren, laden Sie es mit Zertifikat herunterladen (PEM) herunter, hinterlegen Sie es beim IdP und aktivieren Sie Single Logout (SLO) aktivieren.

Erster Test: Melden Sie sich in einem privaten Browserfenster über Mit SSO anmelden an und prüfen Sie unter Administration → System → Benutzer, ob das Konto die erwarteten Rechte hat. Scheitert die Anmeldung, zeigt die Fehlerseite eine Fehlerreferenz. Den Eintrag dazu finden Sie auf der Admin-Seite unter Letzte SSO-Fehler, bei fehlenden Rechten zusammen mit den empfangenen Gruppen und Attributen.

Notfallzugang: Über https://<matomo>/index.php?module=Login&action=login&direct=1 erreichen Hauptadministratoren das Passwort-Formular auch bei aktivem Force SSO (Break-Glass-Login).

Praxisbeispiele

Microsoft Entra ID. Legen Sie unter Enterprise Applications → New application → Create your own eine Non-gallery-App an. In Single sign-on → SAML setzen Sie Identifier = SP-Entity-ID und Reply URL = ACS-URL. Die App Federation Metadata Url kommt als IdP-Metadata-URL ins Plugin, so läuft auch der Zertifikatswechsel automatisch. Den Gruppen-Claim fügen Sie unter Token configuration → Add groups claim hinzu. Im Plugin tragen Sie als Gruppen-Attribut http://schemas.microsoft.com/ws/2008/06/identity/claims/groups und als E-Mail-Attribut http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress ein. Entra sendet die Object-IDs der Gruppen, verwenden Sie diese IDs als Gruppennamen im Mapping. SCIM richten Sie unter Provisioning → Automatic ein.

Okta. Unter Applications → Create App Integration → SAML 2.0 setzen Sie Single Sign-On URL = ACS-URL und Audience URI = SP-Entity-ID. Attribute Statements: email → user.email und displayName → user.displayName, dazu ein Group Attribute Statement namens groups. Die Metadata-URL der Okta-App wird zur IdP-Metadata-URL, SCIM finden Sie unter Provisioning → SCIM. Für signierte Requests laden Sie das SP-Zertifikat unter SAML Settings → Advanced → Signature Certificate hoch.

Keycloak. Unter Clients → Create client → SAML setzen Sie Client-ID = SP-Entity-ID und als Valid redirect URI die ACS-URL. In den Client Scopes legen Sie Mapper für email, displayName und groups an (Full group path aus). Die IdP-Metadata-URL lautet https://<keycloak>/realms/<realm>/protocol/saml/descriptor.

Gut zu wissen

• Hauptadministratoren: Hauptadministrator-Rechte vergibt das Plugin nur, wenn Superuser über Claims erlauben aktiv und eine Superuser-Gruppe / Claim-Wert gesetzt ist. Bestehende Superuser nie herabstufen ist standardmäßig an, der letzte Hauptadministrator wird nie herabgestuft. Admin-Seite und Einstellungen sehen nur Hauptadministratoren.
• Ohne Rechte kein Login: Login verweigern, wenn Claims keine Rechte ergeben ist standardmäßig aktiv. Wer keiner zugeordneten Gruppe angehört, bekommt eine Fehlermeldung statt eines leeren Matomo.
• Kein Aussperren: Passwort-Login-Policy und Passwort-Reset-Sperre greifen erst, wenn SAML konfiguriert ist. Steht die Policy auf Niemand (nur SSO), ist auch der Break-Glass-Login gesperrt. Dann hilft die Kommandozeile: ./console feinwerkauthsaml:set-setting '{"passwordLoginPolicy":"superusers"}'
• Diagnose: ./console feinwerkauthsaml:diagnostics zeigt SAML- und SCIM-Status, Metadata-Fehler, die Zahl der Mappings und die letzten SSO-Fehler. Ab Version 2.2 meldet das Plugin außerdem unter Administration → Diagnose → Systemprüfung Konfigurationsprobleme und warnt 30 Tage vor Ablauf eines Zertifikats. Für mehr Details gibt es die Einstellung Debug-Logging.
• Reverse-Proxy: Läuft Matomo hinter einem TLS-terminierenden Proxy oder Load Balancer, aktivieren Sie ab Version 2.2 Hinter Reverse-Proxy betreiben (X-Forwarded-Header vertrauen).
• SCIM und nginx: Die SCIM-URLs nutzen PATH_INFO. Apache und IIS brauchen keine Anpassung, bei nginx müssen Pfade wie index.php/scim/v2/... an PHP weitergereicht werden. Die Admin-Seite zeigt, ob der Endpoint erreichbar ist.
• Gespeicherte Daten: Der SCIM-Token liegt nur als Hash vor. Für den Replay-Schutz merkt sich das Plugin verbrauchte Assertion-IDs und entfernt abgelaufene Einträge täglich.

Technische Referenz

Eigenschaft	Wert
Technischer Name	FeinwerkAuthSaml
Aktuelle Version	2.1.0
Matomo	≥ 5.0.0, < 6.0.0
PHP	≥ 8.1.0
Lizenz	kostenpflichtig
Datenbankänderungen	keine in der aktuellen Version

FAQ

Welche Identity Provider werden unterstützt?

Jeder SAML-2.0-konforme IdP. Getestet ist AuthSaml mit Okta, Microsoft Entra ID und Keycloak. GitHub bietet als IdP kein SAML an, dort hilft ein vermittelnder IdP wie Keycloak.

Brauche ich SCIM zwingend?

Nein. Kontoanlage und Rechte-Sync funktionieren komplett über den SAML-Login (Just-in-Time). SCIM lohnt sich, wenn Offboarding sofort wirken soll statt erst beim nächsten Login.

Kann ich Rechte weiterhin manuell in Matomo vergeben?

Ja. Im Standardmodus „verwaltet“ entzieht AuthSaml nur Rechte, die es selbst vergeben hat, alles manuell Vergebene bleibt unangetastet. Wer den IdP als alleinige Quelle möchte, wählt den autoritativen Modus.

Was passiert, wenn der Identity Provider ausfällt?

Hauptadministratoren erreichen über den Break-Glass-Zugang weiterhin das Passwort-Formular, auch bei aktivem Force SSO. Wer sich sonst noch per Passwort anmelden darf, legen Sie selbst fest: alle, nur Hauptadministratoren (Standard) oder niemand. Schalten Sie den Passwort-Login ganz ab, ist auch der Break-Glass-Zugang gesperrt. Die Einstellung lässt sich dann über die Kommandozeile zurücksetzen.

Wie aufwendig ist die Einrichtung?

Überschaubar: SP-Metadata-URL im IdP hinterlegen, IdP-Metadata-URL im Plugin eintragen (automatischer Import mit täglichem Abgleich), Gruppen-Mapping anlegen. Schritt-für-Schritt-Anleitungen für Okta, Entra ID und Keycloak stehen in der Dokumentation.

Werden Hauptadministrator-Rechte über SSO vergeben?

Nur wenn Sie es ausdrücklich aktivieren und eine eigene IdP-Gruppe dafür festlegen. Eine Schutzoption verhindert, dass bestehende Hauptadministratoren herabgestuft werden, und der letzte Hauptadministrator wird nie herabgestuft.

Was passiert mit bestehenden Matomo-Benutzern?

Sie werden übernommen, nicht dupliziert: Beim ersten SSO-Login ordnet AuthSaml das Konto über Login oder E-Mail-Adresse zu und verknüpft es dauerhaft mit dem IdP. Das Passwort bleibt bestehen, und manuell vergebene Site-Rechte bleiben im Standardmodus unangetastet, denn entzogen wird nur, was das Plugin selbst vergeben hat. Bestehende Hauptadministratoren werden nie herabgestuft. Die SCIM-Provisionierung übernimmt bestehende Konten genauso. SSO lässt sich so in einer laufenden Matomo-Installation einführen, ohne Benutzer neu anzulegen oder Rechte zu verlieren.

Warum ist AuthSaml teurer als einfache SSO-Plugins?

Weil es mehr abdeckt: Neben dem SAML-Login enthält AuthSaml die Rechteverwaltung über IdP-Gruppen und einen vollständigen SCIM-2.0-Server für automatisches On- und Offboarding. Eine Lizenz ersetzt damit die manuelle Benutzerpflege über den gesamten Lebenszyklus.