Differences

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

--- en:2.0:single_sign_on:saml_dokuwiki [2025/04/25 10:51] – kainhofer
+++ en:2.0:single_sign_on:saml_dokuwiki [2026/09/09 19:19] (current) – [Prerequisites] kainhofer
@@ Line 7: / Line 7: @@
 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: [[en:2.0:single_sign_on|#a_basic_setup_for_admidio_as_a_saml_id_provider]]
+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  [[en:2.0:single_sign_on#a_basic_setup_for_admidio_as_a_saml_id_provider|follow this guide]].
 {{ :en:2.0:sso:sso_saml_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**.
+Basically, one needs to enable SAML 2.0 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.
+The page https://admidio.local/adm_program/modules/preferences.php?panel=sso 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 =====
+===== Quick Overview =====
-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.
+Setting up a client (SAML "Service Provider" = "SP") to use Admidio's user accounts for log-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 case is also straightforward.
-  * At the **Service Provider (SP)** - DokuWiki in our case - **install the extension** to support SAML login.
+  * 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)
+    * Choose an easily understood **label for the client** (only used in Admidio's list of clients as visual identifier, 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.
 ===== DokuWiki-specific instructions =====
@@ Line 56: / Line 60: @@
 {{ :en:2.0:sso:sso_saml_04-05_dw_admidio_clientsetup1.png?direct&400 |}}
+{{ :en:2.0:sso:sso_saml_04-05_dw_admidio_clientsetup1b.png?direct&400 |}}
-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.
+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. Both Admidio and Dokuwiki allow configuring the attribute used as login name and groups, so the actual attribute name is not important, but Dokuwiki and Admidio must be configured to use the same name (circled in the image). To use Admidio's group memberships as Dokuwiki groups, make sure to include the "Roles" profile field and map the included groups to SAML (=Dokuwiki) roles.
-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).
 {{ :en:2.0:sso:sso_saml_04-06_dw_admidio_clientsetup2.png?direct&400 |}}
-TODO: Describe signing and encryption settings (synced)
+Dokuwiki does not support signing its messages to admidio, so the corresponding settings in Admidio are not applicable.
-{{ :en:2.0:sso:sso_saml_02-07_nc_admidio_clientsetup3.png?direct&600 |}}
 Once all settings are done, it is time to enable the saml plugin for login to DokuWiki in the "Configuration Settings":
 {{ :en:2.0:sso:sso_saml_04-07_dw_saml_enable.png?direct&400 |}}
+==== DokuWiki configuration as text ====
+The settings done above in the graphical interface could also be done in the ''conf/local.php'' config file of DokuWiki. The corresponding settings would look like this:
+<code php>
+$conf['authtype'] = 'saml';
+$conf['superuser'] = '@admin';
+$conf['plugin']['saml']['idPEntityID'] = 'https://admidio.local';
+$conf['plugin']['saml']['endpoint'] = 'https://admidio.local/modules/sso/index.php/saml/sso';
+$conf['plugin']['saml']['slo_endpoint'] = 'https://admidio.local/modules/sso/index.php/saml/slo';
+$conf['plugin']['saml']['certificate'] = '-----BEGIN CERTIFICATE-----
+MIID4DCCAsigAwIBAgIBADANBg...nS+ViEoHuI2FSMyLpVB5
+-----END CERTIFICATE-----';
+$conf['plugin']['saml']['use_slo'] = 1;
+</code>
 ==== Setup completed, test Single-Sign-On ====
@@ Line 83: / Line 101: @@
 ==== Caveats and Things to Consider ====
-  * 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!
+  * 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 "Also sign SAML responses" is checked!
+  * DokuWiki's **single log out mechanism for SAML is broken**:
+    * Instead of the logged-in user, DokuWiki sends its own client ID, so Admidio never knows, which user is supposed to be logged out. Only the browser session ID is available. As a workaround, Admidio looks up all logged-in users attached to that browser session and performs a single-log-out on them.
+    * Single-Log initiated from another SAML client does not log out DokuWiki. Dokuwiki's SAML plugin just clears its login, but misses the relevant cookie, so the next reload will appear logged-in in dokuwiki again locally.
+    * Bug reports have been filed for DokuWiki's SAML plugin, including the necessary fixes: Issue [[https://github.com/takuy/dokuwiki-plugin-saml/issues/8|#8]], [[https://github.com/takuy/dokuwiki-plugin-saml/issues/9|#9]] and [[https://github.com/takuy/dokuwiki-plugin-saml/issues/10|#10]]
+    * With the three simple patches proposed in the bug reports, single-log-out works properly.