Single-Sign-On into Matomo using Admidio as an OpenID Provider

Starting with version 5.0, Admidio can be used by other applications to authenticate users against Admidio's user base. These instructions will guide you through the process of connecting Matomo to Admidio to use Admidio's login. For general instructions, and other apps, please visit the general Single-Sign-On overview page.

Matomo provides OpenID Connect login through the Login OIDC or its fork RebelOIDC plugins. Both plugins are free and work similarly. RebelOIDC is a relatively recent fork to fix some long-standing issues in LoginOIDC. On the other hand, LoginOIDC has a longer history and a larger user base. Both of them are good choices, and the configuration is similar. The only difference so far is that in the redirect URL for RebelOIDC the string LoginOIDC must be replaced with RebelOIDC.

Throughout the document we will assume you have both Admidio and Matomo already set up properly at https://admidio.local/ and https://matomo.local/. Please modify these URLs to your actual installation.

As a first step, one needs to configure Admidio to act as an OpenID Provider (OP). This has to be done once and is not specific to Matomo. Please follow this guide: #a_basic_setup_for_admidio_as_an_oidc_id_provider

Basically, one (1) needs to create a cryptographic key to sign message and choose a unique EntityID. The page https://admidio.local/adm_program/modules/preferences.php?panel=sso also provides the link to the metadata xml, and the individual settings in case a client does not support auto-configuration via metadata.

Setting up Matomo (OpenID “Relying Party” - short RP) to use Admidio's user accounts for logging in consists of two steps: (1) Matomo needs to be set up with the data about the OpenID Provider (OP). One has to manually paste the Admidio endpoint URLs of the OpenID provider into the client's configuration. (2) Admidio needs to be told about the client. In particular, the entity ID and the redirect URL must be given, and a custom-generated (random) secret must be copied to the client configuration.

The concrete steps are:

• In Matomo (the Relying Party (RP)) install the extension to support OpenID login.
  • Configure it with Admidio's endpoint URLs for authentication, token and userinfo, and enter the EntityID. Auto-discover is currently not supported by the Matomo plugin.
  • Also, choose which scopes (groups of profile fields) should be requested from Admidio (“openid” is required; Since the OpenID Matomo plugin does not support groups mapping, the “groups” scope is not relevant and has no use, but other profile fields might be useful).
• In Admidio, create a new OpenID client.
  • Choose an easily understood label for the client (only used in Admidio's list of clients and in the login form, but has no technical use)
  • Enter the ClientID from the RP, Copy the created Client Secret (you will later need to paste it into the Matomo configuration), and enter the Redirect URI for the RP. The latter can be found on the plugin's documentation (https://[YOUR_MATOMO_URL]/index.php?module=LoginOIDC&action=callback&provider=oidc)
  • In Admidio, map the user ID, username, email and fullname to fields that are included in the OpenID login response (so-called “claims”) and enter the corresponding claim names in Matomo.

• First, install the Login OIDC or its fork RebelOIDC plugin in Matomo from the plugin directory:

• After installing this plugin, go to Matomo's settings screen. The top bar should show a link to “Login O I D C”, which will jump to the plugin settings.
• The first few settings configure the general Matomo login mechanism, e.g. whether superusers should be allowed to login through OIDC, whether user accounts for new logins should be created, etc.
• To configure the OpenID settings, it is a good idea to keep two browser windows open with Admidio and Matomo's configuration so one can easily select and copy the settings. Admidio even provides little “copy” buttons/icons to copy the various settings to the clipboard for easy pasting into the Matomo configuration.

• Return to Admidio's SSO preferences page, go to the “Single-Sign-On Client Administration” (the button right below the endpoint URLs and above the “Save” button), and create a new client.

• The settings in Matomo's and Admidio's OpenID setup need to match. Most of the settings can be copied over from Admidio to Matomo or vice versa:

• Copy over the various endpoint URLs from Admidio into Matomo (the green arrows in the screenshot above). Admidio provides little “copy” icons for this.
• The Userinfo ID should be set to sub, which is the standard field in OpenID to hold the unique user ID.
• The Client Name is the label of the client in Admidio's client list, it can be anything you like.
• The “Client ID” and “Client Secret” in Admidio and Matomo have to match exactly. The ID is typically the client's URL, although some clients allow any unique identifier. The Client Secret should be a random string and will serve like a password.¹⁾
• Enter the scopes you desire in the Matomo config and make sure that Admidio's config matches it. At least openid must be included (Admidio will implicitly add it), profile and email are recommended so that Matomo receives the username and email fields from Admidio.
• Matomo does not display its Redirect URL directly in the plugin config. Rather, the FAQ of the plugins lists it as: https://[YOUR_MATOMO_URL]/index.php?module=LoginOIDC&action=callback&provider=oidc (or for the RebelOIDC plugin: https://[YOUR_MATOMO_URL]/index.php?module=RebelOIDC&action=callback&provider=oidc). Enter this URL in Admidio.

After saving the changes (both in Matomo and Admidio), the apps should should now be set up for single-sign-on in Matomo.

Admidio and Matomo should now be set up to use Admidio for logging in to Matomo. If you log out of Matomo and try to log in again, you will be shown the Admidio login screen and then redirected back to Matomo after a successful login.

If a new user logs in, a new user account is created (if the corresponding config setting is selected), but the new user will not have any permissions and an error will be displayed. A Matomo admin must assign the correct permissions to the new user. This can be done in the Matomo user config section. Superuser permissions cannot be assigned in the list, but one can open the user for editing with the icon on the right:

Once the user has access permissions to a page, the successfull login will show the analytics page of Matomo: