AuthSaml

Overview

AuthSaml turns your identity provider into the single source of truth for Matomo: sign-in via SAML 2.0 single sign-on, user lifecycle via SCIM 2.0, and site permissions driven by your IdP groups. It works with any SAML 2.0 provider and is tested with Okta, Microsoft Entra ID and Keycloak.

Sign-in and permissions from one source

On the first SSO login, AuthSaml creates the Matomo account automatically (just-in-time provisioning). On every login it synchronizes site permissions from the group claims: in the admin area you map IdP groups to Matomo sites and a role (view, write or admin). From then on, access is managed in your IdP alone. Alternatively or additionally, AuthSaml reads permissions from a direct attribute (e.g. matomo_access = "view:1,4;write:2").

Three sync modes control how strictly the IdP leads: additive (only grants, never revokes), managed (revokes only what the plugin granted itself; manually assigned permissions stay untouched) or authoritative (the IdP fully defines permissions).

Offboarding that takes effect immediately

With SCIM 2.0 enabled, your IdP actively pushes users and groups to Matomo: new team members exist before their first sign-in. When the IdP reports that someone has left, AuthSaml deactivates the account right away: login is blocked, running sessions end and the permissions the plugin granted are revoked, with no one having to remember anything. Group changes in the IdP affect site permissions immediately, without any login involved.

Secure by default, with no lockout risk

Signed assertions, RSA-SHA256, strict mode and replay protection are the defaults. At the same time, AuthSaml is built so an IdP outage does not lock you out: super users reach the password form through a break-glass login, even when Force SSO is on. Login restrictions only apply once SAML is actually configured. Only if you switch off password login for everyone is the break-glass login blocked as well.

Setup via metadata import

Copy the SP metadata URL into your IdP, paste the IdP metadata URL into the plugin: import and daily refresh are included, and certificate rollover at the IdP (e.g. Entra ID) is picked up automatically. Create your group mappings, done. The admin page shows the most recent SSO errors, for denied logins together with the groups and attributes actually received. No more guessing why a login fails. Console commands support automated rollouts, and step-by-step guides for Okta, Entra ID and Keycloak are in the documentation.

One license, the full lifecycle

AuthSaml is deliberately built as a complete solution: one license covers the entire user lifecycle, from SAML sign-in and permission management through IdP groups to SCIM provisioning with immediate offboarding. It replaces manual user administration and separate provisioning tools.

Use cases

• One login for everything: Your users sign in with their company account, SP- or IdP-initiated, optionally with single logout and Force SSO. Accounts are created automatically on first login.
• Permissions from IdP groups: Group → sites → role: the mapping in the admin area turns your IdP into your access management. Permissions sync on every login and every SCIM change, and manually assigned permissions stay untouched if you want.
• Real-time offboarding: As soon as your IdP reports a leaver via SCIM 2.0, AuthSaml deactivates the account: sessions end and the permissions the plugin granted are revoked. No login involved, no manual cleanup.
• No lockout risk: Strict mode, signed assertions and replay protection are the defaults. Yet by default, super users keep a break-glass password login, so an IdP outage does not lock you out of Matomo.
• Diagnostics instead of support tickets: The admin page shows recent SSO errors, for denied logins including the groups and attributes actually received. You quickly see why a login fails and what to fix in the IdP.

Step-by-step setup

Installation is covered in Installing plugins. You need super user access in Matomo, admin access to your identity provider (IdP) and a server clock synced via NTP (SAML tolerates only about three minutes of drift).

1. Collect the data for your IdP. Open Administration → System → SAML SSO. It shows the SP metadata URL, the ACS URL (reply URL) and the SSO login URL. By default, the SP entity ID is your Matomo URL.
2. Create the application in your IdP. Create a SAML 2.0 application with the ACS URL and SP entity ID, and let the IdP send email, display name and groups as attributes.
3. Add your IdP in Matomo. Under Administration → System → General settings → FeinwerkAuthSaml (or via Open settings on the admin page), enter the IdP metadata URL. Entity ID, SSO URL and certificates are imported and refreshed daily. Alternatively, fill in IdP entity ID, IdP single sign-on URL and IdP X.509 certificate (PEM) by hand.
4. Map the attributes. In Attribute mapping, the defaults email, displayName and groups fit Okta and Keycloak. Optionally, the Direct access claim attribute (default matomo_access) reads permissions such as view:1,4;write:2 or view:* straight from the IdP.
5. Map your groups. On the admin page under Group mappings, use Add mapping to define which IdP group gets which sites (or ★ All sites) with which role (view, write or admin), then click Save mappings.
6. Decide on login behaviour. The login page now shows a Sign in with SSO button. After a successful test, optionally enable Force SSO and set who may still use a password under Password login allowed for (default: Super users only).
7. Optional: SCIM. Turn on Enable SCIM 2.0 endpoint and create a bearer token on the admin page with Generate new token (shown only once). In your IdP, enter the SCIM base URL https://<matomo>/index.php/scim/v2 and the token. Under Offboarding behaviour, choose Deactivate user (recommended) or Delete user permanently.
8. Optional: single logout. Click Generate SP certificate, download it with Download certificate (PEM), upload it to your IdP and turn on Enable single logout (SLO).

First test: sign in with Sign in with SSO in a private browser window, then check under Administration → System → Users that the account has the expected permissions. If sign-in fails, look up the error reference from the error page under Last SSO errors on the admin page. For missing permissions, it also lists the groups and attributes received.

Emergency access: https://<matomo>/index.php?module=Login&action=login&direct=1 takes super users to the password form even when Force SSO is on (break-glass login).

Practical examples

Microsoft Entra ID. Under Enterprise Applications → New application → Create your own, create a non-gallery app. In Single sign-on → SAML, set Identifier = SP entity ID and Reply URL = ACS URL. Use the App Federation Metadata Url as IdP metadata URL, so certificate rollover is handled automatically. Add the groups claim under Token configuration → Add groups claim. In the plugin, set Groups attribute to http://schemas.microsoft.com/ws/2008/06/identity/claims/groups and E-mail attribute to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress. Entra sends group object IDs, so use those IDs as group names in your mappings. SCIM is set up under Provisioning → Automatic.

Okta. Under Applications → Create App Integration → SAML 2.0, set Single Sign-On URL = ACS URL and Audience URI = SP entity ID. Attribute statements: email → user.email and displayName → user.displayName, plus a group attribute statement named groups. The app's metadata URL becomes your IdP metadata URL, SCIM lives under Provisioning → SCIM. For signed requests, upload the SP certificate under SAML Settings → Advanced → Signature Certificate.

Keycloak. Under Clients → Create client → SAML, set Client ID = SP entity ID and the ACS URL as valid redirect URI. Add client scope mappers for email, displayName and groups (full group path off). The IdP metadata URL is https://<keycloak>/realms/<realm>/protocol/saml/descriptor.

Good to know

• Super users: super user access is only granted if Allow super user via claims is on and a Super user group / claim value is set. Never demote existing super users is on by default, and the last super user is never demoted. Only super users see the admin page and settings.
• No permissions, no login: Deny login when claims grant no permissions is on by default, so people outside your mapped groups see an error instead of an empty Matomo.
• No lockout: the password login policy and password reset block only apply once SAML is configured. With the policy Nobody (SSO only), the break-glass login is blocked too. Then use the command line: ./console feinwerkauthsaml:set-setting '{"passwordLoginPolicy":"superusers"}'
• Diagnostics: ./console feinwerkauthsaml:diagnostics shows SAML and SCIM status, metadata errors and the latest SSO errors. From version 2.2, the plugin also reports problems under Administration → Diagnostic → System Check and warns 30 days before a certificate expires. For more detail, turn on Debug logging.
• Reverse proxy: behind a TLS-terminating proxy or load balancer, turn on Running behind a reverse proxy (trust X-Forwarded headers) (from version 2.2).
• SCIM and nginx: SCIM URLs use PATH_INFO. Apache and IIS need no changes, nginx must pass paths like index.php/scim/v2/... on to PHP. The admin page shows whether the endpoint is reachable.
• Stored data: the SCIM token is kept only as a hash. For replay protection, the plugin remembers used assertion IDs and removes expired ones daily.

Technical reference

Property	Value
Technical name	FeinwerkAuthSaml
Current version	2.1.0
Matomo	≥ 5.0.0, < 6.0.0
PHP	≥ 8.1.0
License	paid
Database changes	none in the current version

FAQ

Which identity providers are supported?

Any SAML 2.0 compliant IdP. AuthSaml is tested with Okta, Microsoft Entra ID and Keycloak. GitHub does not offer SAML as an IdP, so use a brokering IdP such as Keycloak there.

Do I need SCIM?

No. Account creation and permission sync work entirely through the SAML login (just-in-time). SCIM is worth it when offboarding must take effect immediately instead of at the next login.

Can I still assign permissions manually in Matomo?

Yes. In the default "managed" mode, AuthSaml only revokes permissions it granted itself, and everything assigned manually stays untouched. If you want the IdP as the single source of truth, choose the authoritative mode.

What happens if the identity provider goes down?

Super users still reach the password form through the break-glass login, even when Force SSO is on. You decide who else may sign in with a password: everyone, super users only (the default) or nobody. If you switch password login off completely, the break-glass login is blocked too. The setting can then be reset on the command line.

How much effort is the setup?

Manageable: register the SP metadata URL in your IdP, paste the IdP metadata URL into the plugin (automatic import with daily refresh), create your group mappings. Step-by-step guides for Okta, Entra ID and Keycloak are in the documentation.

Are super user rights granted via SSO?

Only if you explicitly enable it and define a dedicated IdP group. A safeguard option prevents demoting existing super users, and the last super user is never demoted.

What happens to existing Matomo users?

They are adopted, not duplicated: on the first SSO login, AuthSaml matches the account by login or email address and links it to the IdP permanently. The password is kept, and manually assigned site permissions stay untouched in the default mode, because the plugin only ever revokes what it granted itself. Existing super users are never demoted. SCIM provisioning adopts existing accounts the same way, so you can introduce SSO on a running Matomo installation without recreating users or losing permissions.

Why is AuthSaml priced above simple SSO plugins?

Because it covers more: beyond SAML sign-in, AuthSaml includes permission management through IdP groups and a full SCIM 2.0 server for automatic on- and offboarding. One license replaces manual user administration across the entire lifecycle.