Differences

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

--- en:2.0:single_sign_on:saml_mediawiki [2025/04/28 19:59] – created kainhofer
+++ en:2.0:single_sign_on:saml_mediawiki [2025/04/29 01:39] (current) – [Connecting MediaWiki to SimpleSAMLphp and mapping groups] kainhofer
@@ Line 4: / Line 4: @@
 The SAML Login functionality of MediaWiki is provided by the [[https://www.mediawiki.org/wiki/Extension:SimpleSAMLphp|SimpleSAMLphp extension for MediaWiki]], which in turn uses a local installation of [[https://simplesamlphp.org/|SimpleSAMLphp]].
+Setting up SAML login to MediaWiki thus means to first set up SimpleSAMLphp to login using Admidio's user accounts, and then in a second step connecting MediaWiki to SimpleSAMLphp.
 ===== Prerequisites =====
@@ Line 37: / Line 40: @@
   - Download   [[https://simplesamlphp.org/|SimpleSAMLphp]] from its website and place it somewhere on your harddisk. On Linux (or a Linux image running in Docker) one would typically use /var/simplesamlphp.
-  - If you use the Apache2 webserver, add an apache config file ''/etc/apache2/conf-enabled/simplesaml.conf'' to have the /simplesaml Alias point to /var/simplesamlphp/public directory:
+  - If you use the Apache2 webserver, add an apache config file ''/etc/apache2/conf-enabled/simplesaml.conf'' to have the /simplesaml Alias point to ''/var/simplesamlphp/public'' directory:<code>
-      <code>     SetEnv SIMPLESAMLPHP_CONFIG_DIR /var/simplesamlphp/config
+      SetEnv SIMPLESAMLPHP_CONFIG_DIR /var/simplesamlphp/config
       Alias /simplesaml /var/simplesamlphp/public
@@ Line 57: / Line 60: @@
           'baseurlpath' => 'https://mediawiki.local/simplesaml/',
           'store.type' => 'sql',  // IMPORTANT: don't use phpsession, that will NOT work
-          'store.sql.dsn' => 'sqlite:/var/simplesamlphp/config/sqlitedatabase.sq3',
+          'store.sql.dsn' => 'sqlite:/var/simplesamlphp/config/sqlitedatabase.sq3',</code>
-          </code>
+  - Once this basic setup of SimpleSAMLphp is done, one can log in to its web frontend and start configuring the SAML IdP. Go to ''https://[YOUR_INSTALLATION]/simplesaml/module.php/admin/'' and enter the admin password you assigned in config/config.php.
 ==== Connecting SimpleSAMLphp with Admidio ====
+Adding a SAML Identity Provider to SimpleSAMLphp is described at https://simplesamlphp.org/docs/2.4/simplesamlphp-sp.html and will be followed here to connect to Admidio.
+When SimpleSAMLphp is set up, log in to ''https://[YOUR_INSTALLATION]/simplesaml/module.php/admin/'' using the password you assigned in the config/config.php file. SimpleSAMLphp can parse Admidio's IdP metadata XML file and produce a ready configuration that can be stored in the file ''metadata/saml20-idp-remote.php''.
-===== MediaWiki-specific instructions =====
+  - Go to Admidio's SSO preferences at ''https://[YOUR_INSTALLATION]/modules/preferences.php?panel=sso'', download the SAML metadata file (direct URL is https://[YOUR_INSTALLATION]/modules/sso/index.php/saml/metadata) .
+  - Go to the "Federation" tab and use the "XML to SimpleSAMLphp metadata converter" link to convert Admidio's metadata xml to a SimpleSAMLphp config. You can either past the xml content from the metadata file or directly upload the file itself. After clicking "Parse", a config snippet for saml20-idp-remote.php will be shown, which can be copied to the clipboard with the "copy" icon on its top right. Simply paste the PHP structure into an empty file in a text editor and save it as ''metadata/saml20-idp-remote.php''.
+{{ :en:2.0:sso:sso_saml_simplesamlphp_01_metadata.png?direct&600 |}}
+  - The connection to Admidio's IdP is now defined. The next step is to define SimpleSAMLphp as a Service Provider (SP) that uses this IdP. Open the file ''config/authsources.php'' (if it does not exist, copy it from the ''config/authsources.php.dist'' template) and add this code at the end of the file:<code>
+    $config['admidio-sp'] = [
+        'saml:SP',
+        'entityID' => 'https://mediawiki.local/', // Your SP entityID
+        'idp' => 'https://admidio.local',         // Admidio entityID, as given in the metadata
+        'privatekey' => 'saml.pem',
+        'certificate' => 'saml.crt',
+    ];</code>
+  - Finally, you have to create the 'saml.pem' and 'saml.crt' private key and certificate. The simplest way is to follow the SimpleSAMLphp instructions and use openssl:<code bash>cd cert
+openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem</code>
-==== Configuring the Service Provider (Nextcloud) ====
-SAML 2.0 login in Nextcloud is provided by the app "SSO & SAML authentication".
+SimpleSAMLphp should now be set up to connect to Admidio. It provides metadata for automatic setup in the "Federation" tab in the "Hosted entities" section:
-{{ :en:2.0:sso:sso_saml_02-01_nc_install_saml_app.png?direct&600 |}}
+{{ :en:2.0:sso:sso_saml_simplesamlphp_02_metadatalink.png?direct&600 |}}
-After installation it can be configured in Nextcloud's "Administration settings" in the section "SSO & SAML authentication". First, one needs to choose the built-in SAML authentication (one-time setting after first installation).
+The link typically has the form ''https://[YOUR_INSTALLATION]/simplesaml/module.php/saml/sp/metadata/admidio-sp''. Copy that URL to later paste it into Admidio.
-{{ :en:2.0:sso:sso_saml_02-02_nc_saml_setup1.png?direct&600 |}}
-Nextcloud does not support automatic configuration from IdP metadata, so one has to copy the correct settings over from the Admidio preferences. It is 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 Nextcloud's configuration.
-This is a typical configuration of the Nextcloud SAML plugin for Admidio as an idP:
-{{ :en:2.0:sso:sso_saml_02-03_nc_saml_setup2.png?direct&600 |}}
-Once these basic SAML settings are done, I would recommend to set up the SP in Admidio, and do the remaining settings (transmitted fields and roles, as well as signing/encryption requirements) in parallel in Nextcloud and Admidio.
-If the basic settings are valid, Nextcloud should indicate "Metadata valid" at the bottom of the page next to a button to download the metadata XML. Copy the URL of the metadata XML button (right-click on the "Download metadata XML" button and choose "copy link address").
-{{ :en:2.0:sso:sso_saml_02-04_nc_saml_metadata_link.png?direct&400 |}}
-=== Setting up encryption ===
-If encryption is desired for all SAML messages sent by Admidio to Nextcloud, or if Nextcloud should sign all its requests, then Nextcloud needs a private/public key pair to decrypt or sign messages. These need to be entered into the Nextcloud SAML config in PEM format and can be generated by openssl's command line tools, by tools like https://www.samltool.com/self_signed_certs.php, or in Admidio's key administration. Simply create a new Key for Nextcloud (RSA 2048 bits). The certificate can be copied directly from the key's edit page, but the private key is not available in Admidio's GUI for security reason. Instead, it can be downloaded (secured with a password!) from the list of keys in Admidio:
-{{ :en:2.0:sso:sso_saml_02-03a_nc_saml_keysetup1.png?direct&400 |}}
-After downloading the .p12 file, Applications like [[https://keystore-explorer.org/|KeyStore Explorer]] can be used to read the private key and copy the private key and the certificate in PEM format to the clipboard and paste it into Nextcloud's SAML configuration.
-{{:en:2.0:sso:sso_saml_02-03b_nc_saml_keystoreexplorer1.png?direct&400|}}{{:en:2.0:sso:sso_saml_02-03c_nc_saml_keystoreexplorer2.png?direct&400|}}
-{{ :en:2.0:sso:sso_saml_02-03d_nc_saml_keyconfig.png?direct&400 |}}
 ==== Setting up the Client (SP) in Admidio ====
-Now, return to Admidio's SSO preferences page, go to the "Single-Sign-On Client Administration" (the button right above the "Save" button), and create a new client.
+Now, return to Admidio's "Single-Sign-On Client Administration" (linked in the SSO preferences page, the button right above the "Save" button), and create a new client.
 {{ :en:2.0:sso:sso_saml_03-00_admidio_saml_preferences.png?direct&400 |}}
+Paste the metadata URL copied from SimpleSAMLphp into the corresponding input field at the top and click "Load Client Metadata". This should load all settings from SimpleSAMLphp and pre-fill the following fields correctly. Only the Client Name needs to be entered. Choose any name to clearly identify the client in the list of SAML clients. There is no functionality depending on the name.
+{{ :en:2.0:sso:sso_saml_mediawiki_02_samlclient.png?direct&600 |}}
-Paste the metadata URL copied from Nextcloud into the corresponding input field at the top and click "Load Client Metadata". This should load all settings from Nextcloud and pre-fill the following fields correctly. Only the Client Name needs to be entered. Choose any name to clearly identify the client in the list of SAML clients. There is no functionality depending on the name.
-{{ :en:2.0:sso:sso_saml_02-05_nc_admidio_clientsetup1.png?direct&600 |}}
+In addition to the Entity ID and URLs to connect SP and IdP and the certificate, which are configured automatically, one also needs to define the attribute and role mapping. The username, email and the fullname are the most relevant (and the only attributes directly used by MediaWiki). To use Admidio's group memberships as MediaWiki groups, also make sure to include the "Roles" field and provide the correct field name later in MediaWiki. Typically one would use "groups".
+{{ :en:2.0:sso:sso_saml_mediawiki_03_fieldmapping.png?direct&600 |}}
-In addition to the Entity ID and URLs to connect SP and IdP and the certificate, which are configured automatically, one also needs to define the attribute and role mapping. The username is the most relevant. To use Admidio's group memberships as Nextcloud groups, make sure to include the "Roles" field and provide the correct field name in Nextcloud. Internally, Nextcloud will add a prefix to the role names, which makes it impossible to assign admin rights to SAML groups (Nextcloud uses the group with internal name "admin" for administrators). If you want to assign admin rights through SAML, too, then you must enter a single space into the prefix field. This causes Nextcloud to take the role names verbatim as Nextcloud group names, including "admin".
+To map Admidio groups/roles to MediaWiki groups, one can either use the group mapping of MediaWiki (which I have not been able to correctly set up), or provide the desired group names directly in Admidio. MediaWiki uses serveral internal group names to assign elevated permissions: 'sysop' for admin rights, 'suppress' for users that can block users and administrate page revisions, 'bureaucrat' to edit users, 'users' for normal users, 'bot' for bot processes, etc. One can assign admin or other elevated rights by mapping an Admidio role to one of those reserved role names (and later setting up the automatic group assignment in MediaWiki, see below):
+{{ :en:2.0:sso:sso_saml_mediawiki_04_rolemapping.png?direct&600 |}}
-{{ :en:2.0:sso:sso_saml_02-06_nc_admidio_clientsetup1.png?direct&900 |}}
+One can also check the box to include all Admidio groups in the SAML assetion. This will cause Admidio to send all groups to MediaWiki. Groups that have no particular rights assigned will be assigned to the user but will not have any effect.
-The Nextclout SAML configuration also provides settings to choose whether its requests sent to admidio should be signed (a crypto key needs to be set as described above!), and whether all received responses and asserts are expected to be signed or encrypted. You can choose the security level that you desire, but you need to make sure that the settings in Admidio and Nextcloud are consistent, otherwise login will not be possible (e.g. if Wordpress is configured to require signatures on all asserts and responses received, while Admidio is configured not to sign them).
+==== Setup completed, test Single-Sign-On ====
+Admidio and SimpleSAMLphp should now be set up to use Admidio for logging in to SimpleSAMLphp. Switch back to the SimpleSAMLphp admin screen and go to the "Test" tab. Click on "admidio-sp" (the array key used in ''config/authsources.php'' for the Admidio IdP). You will be redirected to Admidio's login form.
+{{ :en:2.0:sso:sso_saml_simplesamlphp_03_test.png?direct |}}{{ :en:2.0:sso:sso_saml_simplesamlphp_04_admidio_loginform.png?direct |}}
-{{ :en:2.0:sso:sso_saml_02-07_nc_admidio_clientsetup3.png?direct&900 |}}
+After logging in with a user from Admidio, you should be logged in to SimpleSAMLphp.
+{{ :en:2.0:sso:sso_saml_simplesamlphp_04_loggedin.png?direct |}}
-==== Setup completed, test Single-Sign-On ====
+==== Connecting MediaWiki to SimpleSAMLphp and mapping groups ====
-Admidio and Nextcloud should now be set up to use Admidio for logging in to Nextcloud. If you log out of Nextcloud, you should see the login screen with the choice of logging in with password or via SAML.
-{{ :en:2.0:sso:sso_saml_02-08_nc_saml_login.png?direct&400 |}}
-After choosing SAML login and loggin in with a user from Admidio, you should be logged in to Nextcloud.
-{{:en:2.0:sso:sso_saml_02-09_nc_saml_loggedin.png?direct&200|}}
-{{:en:2.0:sso:sso_saml_02-10_nc_saml_users.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:SimpleSAMLphp|SimpleSAMLphp]] extension by downloading or git-cloning the code to the ''extensions/'' directory.
+* Open the ''LocalSettings.php'' configuration file of MediaWiki and append the following lines to the end of the file:<code php>
+    wfLoadExtension( 'PluggableAuth' );
+    wfLoadExtension( 'SimpleSAMLphp' );
+    # 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; // Allow username/password login at MediaWiki
+    $wgPluggableAuth_EnableAutoLogin = false; //
+    $wgSimpleSAMLphp_InstallDir = '/var/simplesamlphp';
+    $wgPluggableAuth_Config["SAML with Admidio"] = [
+        'plugin' => 'SimpleSAMLphp',
+        'data' => [
+            'authSourceId' => 'admidio-sp',
+            'usernameAttribute' => 'username',
+            'realNameAttribute' => 'fullname',
+            'emailAttribute' => 'email'
+        ],
+        '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 SAML -> remove it!
+                'groupAttributeName' => 'groups',
+            ]
+        ]
+    ];</code>
-==== Caveats and Things to Consider ====
-  * For security reasons, Nextcloud will prepend **SAML_ prefix to the group names** obtained from the SAML IdP. This makes hybrid environments quite hard in practice, where some users authenticate via SAML, others via local accounts or other network accounts. In these hybrid cases, the SAML-generated groups will be different than the local groups and all group permissions need to be set twice! As a **workaround**, one can **enter a single space into the prefix input box**. This will cause Nextcloud's SAML extension to clear the prefix, but the input field will appear empty in the future, so it is not clarly visible whether the prefix was "cleared" or the default prefix will be applied!
+MediaWiki should now use the SAML login through the SimpleSAMLphp installation. Groups should be assigned as mapped in Admidio:
+{{:en:2.0:sso:sso_saml_mediawiki_05_loginform.png?direct&300|}}{{:en:2.0:sso:sso_saml_simplesamlphp_04_admidio_loginform.png?direct&500|}}{{:en:2.0:sso:sso_saml_mediawiki_06_loginsuccess.png?direct&250|}}{{:en:2.0:sso:sso_saml_mediawiki_06_loginsuccessgroups.png?direct&600|}}