Single-Sign-On into MediaWiki using Admidio as a SAML 2.0 Identity 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.

The SAML Login functionality of MediaWiki is provided by the SimpleSAMLphp extension for MediaWiki, which in turn uses a local installation of 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.

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 SAML 2.0 Identity Provider (IdP). This has to be done once and is not specific to Nextcloud. Please follow this guide: #a_basic_setup_for_admidio_as_a_saml_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 (SAML “Service Provider” - short SP) to use Admidio's user accounts for logging in consists of two steps. If both the IdP (Admidio in our case) and the SP (Nextcloud in this document) support metadata loading, the setup is very straightforward and easy. Otherwise, one has to copy URLs manually to the client, but Admidio already provides these in a single place, so this situation is not as bad, either.

• At the Service Provider (SP) - MediaWiki in our case - install the extension to support SAML login. This also requires a working installation of SimpleSAMLphp and the PluggableAuth MediaWiki extension
• SimpleSAMLphp supports reading the IdP metadata from Admidio and converting it into a working config that needs to be pasted into SimpleSAMLphp's metadata/saml20-idp-remote.php file to define an IdP connection.
• For SimpleSAMLphp one also has to add a minimal configuration entry to the file config/authsources.php to connect IdP connection and provide it as a SP for other apps.
• In Admidio, create a new SAML client. SimpleSAMLphp provides a metadata URL, which can be pasted into Admidio and to automatically load and configure the configuration from the SP. One can also manually paste these settings.
  • Choose an easily understood label for the client (only used in Admidio's list of clients, but has no technical use)
• In Admidio, also choose whether sent messages should be signed or encrypted. The crypto key generated in the general SAML setup will be used.
• Optionally select which profile fields should be mapped to SAML attributes and sent to the client, and configure which group memberships should be transmitted.
• Finally, in MediaWiki's config file LocalSettings.php one needs to enable the SAML extension, provide the path to SimpleSAMLphp, select the IdP and optionally define a groups mapping to use Admidio's roles as MediaWiki groups.

This section merely sets up a working SimpleSAMLphp instance that is ready to be set up for Admidio. We will closely follow the instructions on SimpleSAMLphp's homepage. If you already have SimpleSAMLphp up and running, please skip to the next section, where we will connect it to Admidio.

1. Download 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.
2. 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:

         SetEnv SIMPLESAMLPHP_CONFIG_DIR /var/simplesamlphp/config
         
         Alias /simplesaml /var/simplesamlphp/public
         
         <Directory /var/simplesamlphp/public>
             Options -Indexes +FollowSymLinks
             AllowOverride None
             Require all granted
         </Directory>

3. In SimpleSAMLphp's config directory, copy config/config.php.dist to config/config.php and append the following settings:

             'technicalcontact_name' => 'Your Name',
             'technicalcontact_email' => 'youremail@example.com',
             'admin.protectindexpage' => false,
             'admin.protectmetadata' => false,
             'enable.saml20-idp' => true,
             'auth.adminpassword' => 'password',  // set a password here
             'secretsalt' => 'admidio',    // choose any random salt!
             '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',

4. 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.

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.

1. 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) .
2. 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.

1. 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:

       $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',
       ];

2. 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:

   cd cert
   openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem

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:

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.

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.

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.

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”.

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):

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.

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.

After logging in with a user from Admidio, you should be logged in to SimpleSAMLphp.

* Install the PluggableAuth extension by downloading or git-cloning the code to the extensions/ directory. * Install the 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:

    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',
            ]
        ]
    ];

MediaWiki should now use the SAML login through the SimpleSAMLphp installation. Groups should be assigned as mapped in Admidio: