Single-Sign-On into DokuWiki 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 DokuWiki 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 DokuWiki already set up properly at https://admidio.local/ and https://dokuwiki.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 DokuWiki. 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 (Dokuwiki 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) - DokuWiki in our case - install the extension to support SAML login.
• Configure it either with Admidio's link to the metadata file, or enter the EntityID, the Single-Sign-On Endpoint, the SLO Endpoint and the public certificate manually (Admidio provides a simple table to copy these values from).
• Choose whether sent messages should be signed and/or encrypted (these features require an additional private key and certificate for the SP!), and whether received messages are checked for signatures or encryption is expected.
• In Admidio, create a new SAML client. If the SP provides a metadata URL, paste it and let Admidio automatically load 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)
  • Enter the ClientID from the SP, as well as the ACS URL and the SLO response URL. These values must be provided by the client.
• 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.

SAML 2.0 login in DokuWiki is provided by the “SAML Plugin” extension.

After installation it can be configured in DokuWiki's Configuration Settings, near the bottom in the “Saml” section. The extension would also provide a configuration helper, but the information can also be copied over from Admidio's preferences directly.

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 DokuWiki's configuration.

This is a typical configuration of the DokuWiki SAML extension for Admidio as an idP:

Once these basic SAML settings are done, it's best to start setting up the client in Admidio, and do the remaining settings (transmitted fields and roles, as well as signing/encryption requirements) in parallel in Dokuwiki and 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.

DokuWiki provides its SAML SP client settings as a metadata XML. Unfortunately, there is no direct link to copy the URL from, but the URL is easy to construct:

  
  https://[URL_TO_YOUR_DOKUWIKI]/doku.php?do=saml
  

Paste that metadata URL into the corresponding input field at the top and click “Load Client Metadata”. This should load all settings from Dokuwiki 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 is the most relevant. To use Admidio's group memberships as Dokuwiki groups, make sure to include the “Roles” field and provide the correct field name in Dokuwiki.

Make sure to use the same SAML field names as the ones mapped in Dokuwiki's Saml configuration (circled red in the configuration screenshot above).

The plugin also provides settings to define whether signatures are expected or not. Choose whichever security level is desired, but make sure that the settings in DokuWiki and in Admiodio are consistent:

Once all settings are done, it is time to enable the saml plugin for login to DokuWiki in the “Configuration Settings”:

Admidio and DokuWiki should now be set up to use Admidio for logging in to Dokuwiki. If you log out of DokuWiki and try to log in again, you will be shown the Admidio login screen and then redirected back to Dokuwiki.

• Dokuwiki is picky about signatures. If a SAML response is not signed, login will not be possible, but no corresponding error message will be shown. After an apparent login, the user will arrive at dokuwiki with no user logged in (actually, DokuWiki even silently triggers a logout!). Make sure that in Admidio's client setting for the Dokuwiki SAML client the checkbox “Sign assertions sent to the client (SP)” is checked!