Differences

This shows you the differences between two versions of the page.

--- en:2.0:single_sign_on:oidc_mediawiki [2025/05/06 19:19] – [TL;DR; - Quick Overview] kainhofer
+++ en:2.0:single_sign_on:oidc_mediawiki [2025/05/06 23:44] (current) – kainhofer
@@ Line 34: / Line 34: @@
 ==== Configuring the Service Provider (MediaWiki) ====
-OpenID Connect login in MediaWiki is provided by the [[https://www.mediawiki.org/plugin:oauth|"oauth plugin"]] and the connected [[https://www.mediawiki.org/plugin:oauthgeneric|"oauth generic Service"]] extension.
+OpenID Connect login in MediaWiki is provided by the OpenID Connect extension. To install it, the following steps are required:
-{{ :en:2.0:sso:sso_oidc_04-01_dw_plugin_install.png?direct&600 |}}
+  * Install the [[https://www.mediawiki.org/wiki/Extension:PluggableAuth|PluggableAuth]] extension by downloading or git-cloning the code to the ''extensions/'' directory.
+  * Install the [[https://www.mediawiki.org/wiki/Extension:OpenID_Connect|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 [[https://www.mediawiki.org/wiki/Extension:OpenID_Connect|OpenID Connect]] extension page, and then run ''composer update''
+  * Run the maintenance script (''php maintenance/run.php update'') to create the required database tables.
-After installation it can be configured in MediaWiki's Configuration Settings, near the bottom in the "Oauth" and "Oauthgeneric" sections.
+On a linux server, these would be the corresponding commands:
+<code bash>
+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
+</code>
-First, 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:
-{{ :en:2.0:sso:sso_oidc_01-01_setup_admidio_endpoints.png?direct&600 |}}
+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: {{ :en:2.0:sso:sso_oidc_01-01_setup_admidio_endpoints.png?direct&600 |}}
+    * 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.
+<code php>
+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;
+</code>
 ==== Setting up the Client (SP) in Admidio ====
@@ Line 51: / Line 108: @@
   - 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 have to match exactly the **"Application UID"** and **"Application Secret"** in MediaWiki's configuration. The ID is typically the client's URL, although some clients allow any unique identifier, while others (most notably MediaWiki) require it to be the base of the OpenID endpoint (up until the 'index.php/oidc/'). The Client Secret should 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 not be recovered any more. However, one can create a new Client Secret in Admidio and copy that to the client's configuration.
+  - 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.
-  - MediaWiki will display its **Redirect URL**, which needs to be copied to Admidio.
+  - 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.
-  - Enter the **scopes** you desire 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).
+  - 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 Oauth extensions for Admidio as an OpenID provider:
-{{ :en:2.0:sso:sso_oidc_04-04_dw_settings.png?direct&800 |}}
+This is a typical configuration of the MediaWiki OpenID client in Admidio:
+{{ :en:2.0:sso:sso_oidc_mediawiki_02_client.png?direct&600 |}}
-To use Admidio's group memberships as MediaWiki groups, make sure to include the "Roles" field and provide the correct field name in MediaWiki. MediaWiki even provides a setting to overwrite all groups with the groups received from 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.
-Make sure to use the same OpenID claim names as the ones mapped in MediaWiki's OpenID configuration (circled red in the configuration screenshot above).
-Once all settings are done, it is time to enable the saml plugin for login to MediaWiki in the "Configuration Settings":
+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.
-{{ :en:2.0:sso:sso_oidc_04-07_dw_enable.png?direct&400 |}}
-==== MediaWiki configuration as text ====
-The settings done above in the graphical interface could also be done in the ''conf/local.php'' config file of MediaWiki. The corresponding settings would look like this:
-<code php>
-$conf['authtype'] = 'oauth';
-$conf['superuser'] = '@admin';
-$conf['plugin']['oauth']['register-on-auth'] = 1;
-$conf['plugin']['oauth']['overwrite-groups'] = 1;
-$conf['plugin']['oauthgeneric']['key'] = 'https://mediawiki.local/';
-$conf['plugin']['oauthgeneric']['secret'] = 'lWDQ......gU';
-$conf['plugin']['oauthgeneric']['authurl'] = 'https://admidio.local/modules/sso/index.php/oidc/authorize';
-$conf['plugin']['oauthgeneric']['tokenurl'] = 'https://admidio.local/modules/sso/index.php/oidc/token';
-$conf['plugin']['oauthgeneric']['userurl'] = 'https://admidio.local/modules/sso/index.php/oidc/userinfo';
-$conf['plugin']['oauthgeneric']['scopes'] = array('openid', 'profile', 'address', 'phone', 'email', 'custom', 'groups', 'roles');
-$conf['plugin']['oauthgeneric']['json-user'] = 'username';
-$conf['plugin']['oauthgeneric']['json-name'] = 'fullname';
-$conf['plugin']['oauthgeneric']['json-mail'] = 'email';
-$conf['plugin']['oauthgeneric']['json-grps'] = 'roles';
-$conf['plugin']['oauthgeneric']['label'] = 'OIDC Login with Admidio';
-</code>
 ==== Setup completed, test Single-Sign-On ====
-Admidio and MediaWiki should now be set up to use Admidio for logging in to MediaWiki. If you log out of MediaWiki and try to log in again, you will be shown the Admidio login screen and then redirected back to MediaWiki.
+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'.
+{{:en:2.0:sso:sso_oidc_mediawiki_03_loginform.png?direct&200|}} {{:en:2.0:sso:sso_oidc_mediawiki_04_admidio_loginform.png?direct&400|}} {{:en:2.0:sso:sso_oidc_mediawiki_05_loginsuccess.png?direct&300|}} {{:en:2.0:sso:sso_oidc_mediawiki_06_loginsuccess_profile.png?direct&600|}}
-{{ :en:2.0:sso:sso_oidc_04-08_dw_login.png?direct&400 |}}
-{{ :en:2.0:sso:sso_oidc_04-09_dw_admidio_login.png?direct&400 |}}
-{{ :en:2.0:sso:sso_oidc_04-10_dw_login_success.png?direct&400 |}}
 ==== Caveats and Things to Consider ====
-  * MediaWiki allows **admin login** through OpenID by assigning the **group 'admin'** in the group mapping.
+  * 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.
-  * MediaWiki will convert all group names to lowercase. This is a general restriction in MediaWiki and not specific to OpenID.
+  * 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).
-  * MediaWiki will match its accounts using the email provided in the OpenID token, even when a different user id field is selected. E.g. if a local user 'dale' with email 'dale@example.com' already exists, and a new OpenID login from user 'dale' with email 'dale.baade@example.com' occurs, MediaWiki will treat these as two separate users (and modify the username of the newly created user to 'dale1')!
-  * MediaWiki controls **login permissions for OpenID** with a **group 'generic' assigned to a user**. If local accounts already exist, one needs to add them to the 'generic' group, otherwise login with OpenID is not possible and the following error message will be shown:{{ :en:2.0:sso:sso_oidc_04-10_dw_error_group.png?direct |}} To fix this, add the user to the 'generic' group: {{ :en:2.0:sso:sso_oidc_04-11_dw_generic_group.png?direct&600 |}}