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

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

Throughout the document we will assume you have both Admidio and MediaWiki already set up properly at https://admidio.local/ and https://mediawiki.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 MediaWiki. 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 a client (OpenID “Relying Party” - short RP) to use Admidio's user accounts for logging in consists of two steps: (1) The client (RP, MediaWiki in our case) needs to be set up with the data about the OpenID Provider (OP). Typically this is done via the metadata provided in the discovery URL of the provider. Otherwise one has to manually paste the endpoint URLs of the OpenID provider. Since Admidio provides those URLs with copy buttons in the preferences screen, even the manual configuration is rather straigtforward. (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:

• At the Relying Party (RP) - MediaWiki in our case - install the extension to support OpenID login.
• MediaWiki needs to be configured in the LocalSettings.phpconfig file.
  • Copy the discovery URL into the 'providerURL' setting
  • Choose which scopes (groups of profile fields) should be requested from Admidio (“openid” is required; If Admidio's groups/roles should be mapped to the client's groups, the “groups” scope is also required).
• In Admidio, create a new OpenID client.
  • Choose an easily understood label for the client (only used in Admidio's list of clients, but has no technical use)
  • Choose a good ClientID to uniquely identify the MediaWiki client (typically, use the base URL of your installation).
  • Copy both the ClientID and the Client Secret from Admidios client config to the MediaWiki config file.
  • Enter the redirect URL of Mediawiki in Admidio: 'https://[[YOUR_MEDIAWIKI]]/index.php/Special:PluggableAuthLogin'.
• Optionally select (both in Admidio and the RP) which profile fields should be mapped to OpenID claims (attributes) and sent to the client, and configure which group memberships should be transmitted.

OpenID Connect login in MediaWiki is provided by the OpenID Connect extension. To install it, the following steps are required:

• Install the PluggableAuth extension by downloading or git-cloning the code to the extensions/ directory.
• Install the OpenID Connect extension by downloading or git-cloning the code to the extensions/ directory.
• If installation is done via git, one must add “extensions/OpenIDConnect/composer.json” in the composer.local.json as described in the OpenID Connect extension page, and then run composer update
• Run the maintenance script (php maintenance/run.php update) to create the required database tables.

On a linux server, these would be the corresponding commands:

cd /var/www/html/extensions
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/PluggableAuth
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/OpenIDConnect
# Add the "extensions/OpenIDConnect/composer.json" include to composer.local.json 
# as described on the OpenID Connect extension documentation.
composer update
php maintenance/run.php update

After installing the extensions, its configuration is done entirely in the LocalSettings.php config file in the root directory of the MediaWiki installation.

• Open the LocalSettings.php configuration file of MediaWiki and append the following lines to the end of the file:
  • One has to copy over the OpenID endpoint URLs from Admidio's OpenID preferences (each URL has a copy button). You can find them here:
  • The 'providerURL' is the base URL of your admidio installation, i.e. the path to any of the endpoints shown in Admidio without the final authorize, token or userinfo
  • The Client ID and Client Secret will later come from Admidio's client configuration.
  • The default authMethod is 'client_secret_basic', which uses basic HTTP authentication headers. This prevents special characters in the authentication name (the client ID). So if one wants to the use installation URL as client ID, one must switch to the 'client_secret_post' authMethod.

wfLoadExtension( 'PluggableAuth' );
wfLoadExtension( 'OpenIDConnect' );
 
# https://www.mediawiki.org/wiki/Extension:PluggableAuth
# "The createaccount or autocreateaccount user rights must be granted to all users. "
$wgGroupPermissions['*']['autocreateaccount'] = true;
$wgGroupPermissions['*']['createaccount'] = true;
 
$wgPluggableAuth_EnableLocalLogin = true;
// $wgPluggableAuth_EnableAutoCreate = true;
$wgPluggableAuth_EnableAutoLogin = false;
 
 
$wgPluggableAuth_Config["OpenID with Admidio"] = [
    'plugin' => 'OpenIDConnect',
    'data' => [
        'providerURL' => 'https://admidio.local/modules/sso/index.php/oidc',
        'clientID' => 'https://mediawiki.local',
        'clientsecret' => 'RkMS+6tlpQQ5yow5PlQQTFRcOMC0XCU/',
        'scope' => ['openid', 'email', 'profile', 'address', 'phone', 'groups', 'custom'],
        'authMethods' => ['client_secret_post']
     ],
     'groupsyncs' => [
         [
             // There is also the 'mapped' type, but I have not been able to configure it!
             'type' => 'syncall',
             // 'locallyManaged' => ['sysop'],
             'locallyManaged' => [], // Default includes 'sysop' -> would never sync from OpenID -> need to clear it explicitly!
             'groupAttributeName' => 'groups',
         ]
     ]
];
$wgOpenIDConnect_SingleLogout = true;
$wgOpenIDConnect_MigrateUsersByUserName = true;

It is now a good idea to keep two browser windows open 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 MediaWiki's configuration.

Now, 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.

1. The Client Name is the label of the client in Admidio's client list, it can be anything you like.
2. The “Client ID” and “Client Secret” in Admidio have to match exactly the “clientID” and “clientsecret” entries in MediaWiki's configuration. The ID is typically the client's URL. The client secret is randomly generated and must be copied exactly to the MediaWiki configuration. The Client Secret should be a random string and will serve like a password. Admidio will create one and allow it to be copied to the client. Afterwards it is only stored as a hash in the database and can not be recovered any more. However, one can create a new Client Secret in Admidio and copy that to the client's configuration.
3. MediaWiki's redirect URL is the Special:PluggableAuthLogin page, i.e. https://[YOUR_INSTALLATION]/index.php/Special:PluggableAuthLogin. Enter that URL in Admidio's client config.
4. Enter the scopes you used in MediaWiki's config and make sure that Admidio's config matches it. At least openid must be included (Admidio will implicitly add it). If groups/roles are supposed to be used for access permissions, the “groups” scope also must be included in both MediaWiki's and Admidio's scope setting and the roles included as an OpenID claim. (The groups mapping that Admidio offers is optional, one can also send all groups verbatim without mapping. This can be achieved by checking the checkbox below the mapping table in Admidio).

This is a typical configuration of the MediaWiki OpenID client in Admidio:

The clientID and the client secret in the Admidio client page and MediaWiki's LocalSettings.php have to match exactly. Similarly, the scopes should coincide, otherwise not all desired profile fields will be transmitted. To make use of the group mapping in MediaWiki, make sure to include the 'groups' scope in Admidio and Mediawiki, and map the 'Roles - roles' Profile Field to an OIDC claim.

To assign admin (sysop) rights to an OpenID account, the group 'sysop' should be assigned in Admidio's client config and MediaWiki's groupsyncs must exclude 'sysop' from the locally managed groups.

Admidio and MediaWiki should now be set up to use Admidio for logging in to MediaWiki. If you log out of MediaWiki (or open a new incognito browser window) and try to log in again, you will be shown the Admidio login screen and then redirected back to MediaWiki after successful login. If groups are properly set up and mapped, MediaWiki groups will also be assigned, even admin rights through the OIDC group 'sysop'.

• MediaWiki allows admin login through OpenID by assigning the group 'sysop' in the group mapping. The 'groups' scope must be included in both Admidio's as well as MediaWiki's config, and Admidio's role must be included as an OIDC claim.
• By default, MediaWiki will use basic http authentication for its calls to the authorization and token endpoints, which means that no special characters (in particular colons) are allowed. Unfortunately, the client ID will be used as username, which typically contains a colon in 'https://...'. The OpenID specification states that the colon is the separator between username and passphrase (client secret), so Admidio will incorrectly assume 'https' to be the username and everything else is the client secret… The two possible solutions are to (1) either not use the full URL, but any other unique identifier without a colon as clientID, or (2) switch MediaWiki to the 'client_secret_post' authMethod in the MediaWiki's LocalSettings.php configuration file (see the example above, which already contains this fix).