Single-Sign-On into Moodle using Admidio as a SAML 2.0 Identity Provider [Admidio-Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Single-Sign-On into Moodle 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 Moodle 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]].

There are several SAML plugins for Moodle. We will describe SAML login via the "[[https://moodle.org/plugins/auth_saml2|SAML2 Single sign on]]" plugin. Unfortunately, that app does not (yet) use rule mapping (i.e. using Admidio groups to grant permission in Moodle).

There is also the [[https://moodle.org/plugins/auth_saml2sso|SAML2 SSO Auth]] plugin, which depends on an separate installation of simpleSAMLphp. If you prefer this pugin, follow the instructions to set up [[en:2.0:single_sign_on:simplesamlphp|SimpleSAMLphp with Admidio]]. Once SimpleSAMLphp is working, connecting the Moodle installation to SimpleSAMLphp using the SAML2 SSO Auth is rather straightforward.


===== Prerequisites =====

Throughout the document we will assume you have both Admidio and Moodle already set up properly at https://admidio.local/ and https://moodle.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 any client. Please follow this guide: [[en:2.0:single_sign_on|#a_basic_setup_for_admidio_as_a_saml_id_provider]]
{{ :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**.
The page preferences https://admidio.local/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.

===== 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 (Moodle 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)** - Moodle in our case - **install the extension** to support SAML login.
  * Configure it either with Admidio's **XML 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.

===== Moodle-specific instructions =====

==== Configuring the Service Provider (Moodle) ====

  * Install the "[[https://moodle.org/plugins/auth_saml2|SAML2 Single sign on]]" plugin from Moodle's plugin directory:
{{ :en:2.0:sso:sso_moodle_01_pluginadministration.png?direct&600 |}}{{ :en:2.0:sso:sso_moodle_01_plugindirectory.png?direct&600 |}}
{{ :en:2.0:sso:sso_moodle_saml_02_plugindirectory_search.png?direct&800 |}}


  * After installing this plugin, go to the plugin list and scroll down to the "Authentication" section (or alternatively, use the URL https://[YOUR_MOODLE]/admin/settings.php?section=manageauths). The SAML plugin should be shown together with a link to the settings.
{{ :en:2.0:sso:sso_moodle_03_pluginlist.png?direct&800 |}}

  * Go to the plugin's settings (either via the link in the plugins page, or in the menu item "Plugins" -> "Authentication" -> "SAML2".{{ :en:2.0:sso:sso_moodle_saml_04_plugin_settings.png?direct&900 |}}
    * The plugin supports auto-loading of Admidio's IdP settings. In particular, one only needs to copy the Metadata URL from Admidio to Moodle's plugin configuration, and the plugin will retrieve all endpoint URLs, the key and the signing/encryption settings automatically.
    * The "IdP label override" only governs the text displayed on the login button.
    * If one wants more than one SAML IdP as user backend, it is possible to configure each IdP with an alias to provide direct login links or tweak the display. Typically, this is not needed, except for special cases.{{ :en:2.0:sso:sso_moodle_saml_05_plugin_idp_settings.png?direct&400 |}}
    * The plugin configuration allows the explicit generation of cryptographic certificates / keys for signing and encrypt. Usually the default is sufficient (a key is generated and used by moodle in any case).{{ :en:2.0:sso:sso_moodle_saml_06_plugin_settings.png?direct&400 |}}
  * The next section in the Moodle plugin configuration screen provides a link to the SP metadata, which (after the plugin config is saved) provides Admidio with all relevant information to configure its connection with Moodle as a SAML2.0 IdP.{{ :en:2.0:sso:sso_moodle_saml_07_plugin_settings.png?direct&600 |}}
    * The Entity ID is the most relevant identifier that needs to match in Moodle's and Admidio's configuration, otherwise login to Moodle with SAML using Admidio as login backend will not be possible. If the field is left blank, the plugin will generate a unique identifier. One can also choose any other unique string, typically the URL of the Moodle installation.
    * The link to the SP metadata can be copied from the link using the right mouse button. Typically it is of the form ''https://[YOUR_MOODLE]/auth/saml2/sp/metadata.php''. This URL will lalter be inserted into Admidio's configuration.
  * **SAVE the plugin configuration.**


Once these basic SAML settings are done, I would recommend saving the plugin configuration and to set up the SP in Admidio. The remaining settings (transmitted fields, as well as signing/encryption requirements) are best done in parallel in Moodle and Admidio. 


==== 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.
{{ :en:2.0:sso:sso_saml_03-00_admidio_saml_preferences.png?direct&400 |}}


Paste the metadata URL copied from Moodle into the corresponding input field at the top and click "Load Client Metadata". This should load all settings from Moodle 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, but it will be displayed to the end user in the login form.
{{ :en:2.0:sso:sso_moodle_saml_07a_admidio_metadata.png?direct&900 |}}

  * If the Moodle config does not override the "Entity ID", it will be the Metadata URL, which uniquely identifies the SAML client. 
  * The plugin config contains also several settings that tweak signing settings. Since the keys and certificates are automatically generated, one can choose whatever level of security is desired, but clearly the Moodle and Admidio settings need to be consistent for the login to work.
  * The "Allow create" setting determines whether new users should be generated in Moodle when an unknown user successfully logs in through SAML.


==== Further configuration in Moodle: Fields Mapping====

A seemingly large part of the plugin configuration is dedicated to mapping Admidio's (IdP) fields to profile data fields in Moodle. The first, important mapping is the field for the username. Make sure to map the Admidio username to a SAML field and use it in Moodle to map to the user ID.
{{ :en:2.0:sso:sso_moodle_saml_08_plugin_settings_mapping.png?direct&600 |}}

Towards the end of the configuration screen, a whole section "Data mapping" is dedicated to fields mapping. Each profile field has four settings: "Data mapping" (SAML attribute from Admidio), "Update local", "Update external" and "Lock value". None of these values is required, but if they are mapped, Admidio's profile data is properly imported into Moodle's profile.
{{ :en:2.0:sso:sso_moodle_saml_09_plugin_settings_mapping.png?direct&900 |}}



The last section would allow Moodle to act as a SAML IdP, which is not relevant in our case. Enabling IDP means that Moodle's user accounts can be used by other applications. This, however, is not our scope in this tutorial.
{{ :en:2.0:sso:sso_moodle_saml_10_plugin_idp.png?direct&600 |}}



==== Setup completed, test Single-Sign-On ====

Admidio and Moodle should now be set up to use Admidio for logging in to Moodle. The SAML plugin even provides a way to test the plugin configuration: Return to Moodle's plugin list (see above), which shows a "Test settings" next to the "Settings" link for the plugin:
{{ :en:2.0:sso:sso_moodle_03_pluginlist.png?direct&600 |}}

The test settings page allows a test login from Moodle to Admidio without influencing the current session Moodle. If login is successful, the profile data provided by Admidio is displayed.

{{:en:2.0:sso:sso_moodle_saml_11_plugin_test.png?direct&600|}}{{:en:2.0:sso:sso_moodle_saml_12_plugin_testresults.png?direct&400|}}

Once, this dry run is successful, one can attempt a real login through SAML.


If you log out of Moodle (or open Moodle in an incognito browser window) and go to the Moodle admin location, you should see the login screen with the choice of logging in with password or via SAML.

{{:en:2.0:sso:sso_moodle_13_moodle_loginform.png?direct&400|}}{{:en:2.0:sso:sso_moodle_saml_14_admidio_loginform.png?direct&400|}}


After choosing SAML login and loggin in with a user from Admidio, you should be logged in to Moodle.
{{ :en:2.0:sso:sso_moodle_saml_16_loginsuccess.png?direct&600 |}}



==== Caveats and Things to Consider ====

  * Transferring the country profile field from Admidio into Moodle's country field does not work, because Moodle appears to expect a particular format, which Admidio does not provide. The error message might look overwhelming, but it gives a good indication.{{ :en:2.0:sso:sso_moodle_saml_99_countrymapping.png?direct&600 |}}
  * If you have user accounts from different backends (e.g. local accounts, OpenID Connect login, SAML login) and an account for a user was already created, Moodle tries to match accounts by username (the field selected in the plugin config). However, if the other account has the same email address, but a different user ID through the OIDC or local backend, Moodle will try to create a new account with the SAML user ID, but fails since another account with the same email already exists.{{ :en:2.0:sso:sso_moodle_saml_15_login_duplicateemail.png?direct&600 |}}