| Both sides previous revision Previous revision Next revision | Previous revision |
| en:2.0:single_sign_on:oidc_mediawiki [2025/05/06 21:34] – [Setting up the Client (SP) in Admidio] kainhofer | en:2.0:single_sign_on:oidc_mediawiki [2026/09/08 17:58] (current) – [Caveats and Things to Consider] kainhofer |
|---|
| |
| 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. | 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: [[en:2.0:single_sign_on|#a_basic_setup_for_admidio_as_an_oidc_id_provider]] | 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 any particular client. Please [[en:2.0:single_sign_on#a_basic_setup_for_admidio_as_an_oidc_id_provider|folow this guide]]: |
| {{ :en:2.0:sso:sso_oidc_01-05_setup_admidio_preferences.png?direct&600 |}} | {{ :en:2.0:sso:sso_oidc_01-05_setup_admidio_preferences.png?direct&600 |}} |
| |
| 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. | |
| |
| ===== TL;DR; - Quick Overview ===== | Basically, one needs to enable OpenID Connect (OIDC). The Issuer URL should in most cases be left blank, which means Admidio's public URL will be used as issuer URL. |
| | |
| | The page https://admidio.local/adm_program/modules/preferences.php?panel=sso also provides the link to the automatic discovery URL, and the individual settings for clients that do not support auto-configuration via metadata. |
| | |
| | ===== Quick Overview ===== |
| |
| 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. | Setting up a client (OpenID "Relying Party" = "RP") to use Admidio's user accounts for log-in consists of two steps: |
| | - The client (RP, DokuWiki 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 straightforward. |
| | - 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: | The concrete steps are: |
| 'providerURL' => 'https://admidio.local/modules/sso/index.php/oidc', | 'providerURL' => 'https://admidio.local/modules/sso/index.php/oidc', |
| 'clientID' => 'https://mediawiki.local', | 'clientID' => 'https://mediawiki.local', |
| 'clientsecret' => 'LOcPD...WLaZ', | 'clientsecret' => 'RkMS+6tlpQQ5yow5PlQQTFRcOMC0XCU/', |
| 'scope' => ['openid', 'email', 'profile', 'address', 'phone', 'groups', 'custom'], | 'scope' => ['openid', 'email', 'profile', 'address', 'phone', 'groups', 'custom'], |
| 'authMethods' => ['client_secret_post'] | 'authMethods' => ['client_secret_post'], |
| | 'codeChallengeMethod' => 'S256' |
| ], | ], |
| 'groupsyncs' => [ | 'groupsyncs' => [ |
| This is a typical configuration of the MediaWiki OpenID client in Admidio: | This is a typical configuration of the MediaWiki OpenID client in Admidio: |
| {{ :en:2.0:sso:sso_oidc_mediawiki_02_client.png?direct&600 |}} | {{ :en:2.0:sso:sso_oidc_mediawiki_02_client.png?direct&600 |}} |
| | {{ :en:2.0:sso:sso_oidc_mediawiki_02_client2.png?direct&600 |}} |
| |
| 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. | 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. |
| |
| |
| ==== MediaWiki configuration as text ==== | 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. |
| |
| 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: | ==== Setup completed, test Single-Sign-On ==== |
| |
| <code php> | 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'. |
| $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 ==== | {{: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|}} |
| |
| 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. | |
| |
| {{ :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 ==== |
| |
| ==== Caveats and Things to Consider ==== | * 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.<code php>[..., |
| | 'groupsyncs' => [ |
| | [ |
| | 'type' => 'syncall', |
| | // List of locally managed groups by default contain 'sysop', |
| | // so administrators would never sync from Admidio -> clear it! |
| | 'locallyManaged' => [], |
| | 'groupAttributeName' => 'groups', |
| | ]] |
| | </code>{{ :en:2.0:sso:sso_oidc_mediawiki_02_client3_sysop.png?400 |}} |
| | |
| | * 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 allows **admin login** through OpenID by assigning the **group 'admin'** in the group mapping. | |
| * MediaWiki will convert all group names to lowercase. This is a general restriction in MediaWiki and not specific to OpenID. | |
| * 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 |}} | |
