Single-Sign-On into DokuWiki using Admidio as an OpenID Provider [Admidio-Wiki]

Diese Seite ist nicht editierbar. Sie können den Quelltext sehen, jedoch nicht verändern. Kontaktieren Sie den Administrator, wenn Sie glauben, dass hier ein Fehler vorliegt.
====== Single-Sign-On into DokuWiki using Admidio as an OpenID 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 [[en:2.0:single_sign_on|general Single-Sign-On overview page]].

===== Prerequisites =====

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 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 |}}


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" = "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:
  * At the **Relying Party (RP)** - DokuWiki in our case - **install the extension** to support OpenID login.
    * Configure it either with Admidio's **discovery URL** (if supported), or enter the EntityID and the URL endpoints for authentication, token and userinfo. 
    * Also, choose which scopes (groups of profile fields) should be requested from Admidio ("openid" is required; If Admidio's groups/roles should be mapped to the client's groups, the "groups" scope is also required).
  * In **Admidio**, **create a new OpenID client**. 
    * 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 RP**, copy the created Client Secret (you will later need to paste it into DokuWiki's configuration), and enter the **Redirect URI** for the RP. Typically the latter can be found either on the RP's configuration page or in the documentation.
    * Many open source OIDC clients do not support encryption (PKCE, which is a security mechanism that prevents attackers from obtaining access unless their application started the initial login). By default, PKCE is required by Admidio, so in this case make sure that the requirement checkbox is turned off. Otherwise you will get an error. 
  * Optionally select (both in Admidio and the RP) which **profile fields should be mapped** to OpenID claims (attributes) and sent to the client, and configure which **group memberships** should be transmitted.


===== DokuWiki-specific instructions =====

==== Configuring the Service Provider (DokuWiki) ====

OpenID Connect login in DokuWiki is provided by the [[https://www.dokuwiki.org/plugin:oauth|"oauth plugin"]] and the connected [[https://www.dokuwiki.org/plugin:oauthgeneric|"oauth generic Service"]] extension.
{{ :en:2.0:sso:sso_oidc_04-01_dw_plugin_install.png?direct&600 |}}

After installation it can be configured in DokuWiki's Configuration Settings, near the bottom in the "Oauth" and "Oauthgeneric" sections.
{{ :en:2.0:sso:sso_oidc_01-01a_dw_settings.png?600 |}}

==== Setting up the Client (SP) in Admidio ====

It is now 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.

Now, return to Admidio's SSO preferences page, go to the "Single-Sign-On Client Administration" (the button right below the endpoint URLs and above the "Save" button), and create a new client.
{{ :en:2.0:sso:sso_oidc_01-07_clientadmin.png?direct&400 |}}

The first step is to copy over the endpoint URLs from Admidio into the DokuWiki configuration. DokuWiki does not support automatic discovery, so the individual URLs (hidden by default in a foldable section at the top) must be copied individually:
{{ :en:2.0:sso:sso_oidc_04-03a_dw_endpoints.png?800 |}}

The remaining settings are individual to the DokuWiki installation:
  - The **Client Name** is the label of the client in Admidio's client list, it can be anything you like.
  - The **"Client ID"** and **"Client Secret"** in Admidio have to match exactly the **"Application UID"** and **"Application Secret"** in DokuWiki's configuration. The ID is typically the client's URL, although some clients allow any unique identifier, while others (most notably MediaWiki) require it to be the base of the OpenID endpoint (up until the 'index.php/oidc/'). The Client Secret should a random string and will serve like a password. Admidio will create one and allow it to be copied to the client. Afterwards it is only stored as a hash in the database and not be recovered any more. However, one can create a new Client Secret in Admidio and copy that to the client's configuration.
  - DokuWiki will display its **Redirect URL**, which needs to be copied to Admidio.
  - The Dokuwiki OIDC plugin does not support encryption (PKCE, which is a security mechanism that prevents attackers from obtaining access unless their application started the initial login). By default, PKCE is required by Admidio, so make sure that the requirement checkbox is turned off. Otherwise you will get an error. 
  - Enter the **scopes** you desire in DokuWiki's config and make sure that Admidio's config matches it. At least **openid must be included** (Admidio will implicitly add it). If groups/roles are supposed to be used for access permissions, the **"groups" scope** also must be included in both DokuWiki's and Admidio's scope setting and the roles included as an OpenID claim. (The groups mapping that Admidio offers is optional, one can also send all groups verbatim without mapping. This can be achieved by checking the checkbox below the mapping table in Admidio).

This is a typical configuration of the DokuWiki Oauth extensions for Admidio as an OpenID provider:
{{ :en:2.0:sso:sso_oidc_04-04_dw_settings.png?direct&800 |}}


To use Admidio's group memberships as Dokuwiki groups, make sure to include the "Roles" field and provide the correct field name in Dokuwiki. DokuWiki even provides a setting to overwrite all groups with the groups received from Admidio.

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

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_oidc_04-07_dw_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'] = 'oauth';
$conf['superuser'] = '@admin';
$conf['plugin']['oauth']['register-on-auth'] = 1;
$conf['plugin']['oauth']['overwrite-groups'] = 1;
$conf['plugin']['oauthgeneric']['key'] = 'https://dokuwiki.local/';
$conf['plugin']['oauthgeneric']['secret'] = 'fE23/WbL...FEWHmg';
$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']['logouturl'] = 'https://admidio.local/modules/sso/index.php/oidc/logout';
$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 ====

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.

{{ :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 ====

  * DokuWiki allows **admin login** through OpenID by assigning the **group 'admin'** in the group mapping.
  * DokuWiki will convert all group names to lowercase. This is a general restriction in DokuWiki and not specific to OpenID.
  * DokuWiki 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, DokuWiki will treat these as two separate users (and modify the username of the newly created user to 'dale1')!
  * DokuWiki 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 |}}