Differences

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

--- en:2.0:single_sign_on:saml_moodle [2025/05/16 18:48] – created kainhofer
+++ en:2.0:single_sign_on:saml_moodle [2025/05/17 00:09] (current) – [Setup completed, test Single-Sign-On] kainhofer
@@ Line 36: / Line 36: @@
   * Install the "[[https://moodle.org/plugins/auth_saml2|SAML2 Single sign on]]" plugin from Moodle's plugin directory:
-{{ :en:2.0:sso:sso_saml_moodle_01_install_saml_plugin.png?direct |}}
+{{ :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_01_pluginadministration.png?nolink&400|}}{{:en:2.0:sso:sso_moodle_01_plugindirectory.png?nolink&400|}}
+{{ :en:2.0:sso:sso_moodle_saml_02_plugindirectory_search.png?direct&800 |}}
-{{ :en:2.0:sso:sso_moodle_02_plugindirectory_search.png?nolink&700 |}}
   * 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?nolink&600|}}
+{{ :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".
+  * 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 |}}
-{{ :en:2.0:sso:sso_moodle_saml_04_plugin_settings.png?nolink&800 |}}
+    * 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.
-  * 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.
+    * 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 "IdP label override" only governs the text displayed on the login button.
+    * 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 |}}
-  * 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.
+  * 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 |}}
-{{ :en:2.0:sso:sso_moodle_saml_05_plugin_idp_settings.png?nolink&400 |}}
+    * 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.**
-  * 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).
+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.
-{{ :en:2.0:sso:sso_moodle_saml_06_plugin_settings.png?nolink&400 |}}
+==== Setting up the Client (SP) in Admidio ====
-<WRAP center round todo 60%>
+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.
-todo box
+{{ :en:2.0:sso:sso_saml_03-00_admidio_saml_preferences.png?direct&400 |}}
-</WRAP>
-  *  "Settings" -> "Users & Companies" -> "SAML Providers" and create a new provider.
+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 |}}
-{{ :en:2.0:sso:sso_saml_moodle_02_moodle_setup_samlprovider.png?direct |}}
+  * 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.
-While the app supports IdP metadata import from Admidio, the corresponding metadata xml file is not automatically loaded, but the xml contents need to be pasted. Download the metadata xml file from the link given in Admidio's preferences (typically https://[YOUR_DOMAIN]/modules/sso/index.php/saml/metadata), open the file and copy the xml contents to Moodle's configuration:
-{{ :en:2.0:sso:sso_saml_moodle_03_moodle_setup_samlprovider_metadata.png?direct |}}
+==== Further configuration in Moodle: Fields Mapping====
-Once the metadata xml is pasted, Moodle will pre-fill most settings:
+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 |}}
-{{ :en:2.0:sso:sso_saml_moodle_04_moodle_setup_samlprovider_basics.png?direct |}}
+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 |}}
-One key setting is the SP entityID, which is pre-filled as "moodle". Since the entityID should be a unique identifier (but can be freely chosen), it is recommended to use a more specific ID like the URL of your installation. The entityID will be configured in Admidio, too, and must match exactly!
-Moodle also requires a private key / public certificate pair to sign messages sent to the Admidio IdP. These need to be uploaded into the Moodle SAML config as individual files in PEM format and can be generated by openssl's command line tools, by sites like https://www.samltool.com/self_signed_certs.php or in Admidio's key administration. Simply create a new Key for Moodle (RSA 2048 bits). The certificate can be copied directly from the key's edit page, but the private key is not available in Admidio's GUI for security reason. Instead, it can be downloaded (secured with a password!) from the list of keys in Admidio:
-{{ :en:2.0:sso:sso_saml_02-03a_nc_saml_keysetup1.png?direct&400 |}}
+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 |}}
-After downloading the .p12 file, Applications like [[https://keystore-explorer.org/|KeyStore Explorer]] can be used to read the private key and copy the private key and the certificate in PEM format into a file and upload them into Moodle's SAML configuration. As signature algorithm choose either SHA1 or the more modern SHA256.
-{{:en:2.0:sso:sso_saml_02-03b_nc_saml_keystoreexplorer1.png?direct&400|}}{{:en:2.0:sso:sso_saml_02-03c_nc_saml_keystoreexplorer2.png?direct&400|}}
+==== 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.
-Once these basic SAML settings are done, I would recommend to set up the SP in Admidio, and do the remaining settings (transmitted fields, as well as signing/encryption requirements) in parallel in Moodle and Admidio.
+{{: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 the basic settings are valid and saved, the Moodle plugin provides a link to the client (SP) metadata XML file right above the certificat upload field. Copy that URL, so it can be pasted into Admidio for auto-configuration  of the SAML access (right-click on the link and copy the link location to the clipboard).
+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|}}
-==== 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 Nextcloud 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.
-{{ :en:2.0:sso:sso_saml_moodle_06_admidio_client.png?direct |}}
-==== Further configuration in Moodle: Fields, Security / Signing ====
-The configuration of both Moodle and Admidio's SAML provides settings to want / require messages to be cryptographically signed to prevent security attacks. Choose your desired level of security, but make sure that the settings are consistent:
-{{ :en:2.0:sso:sso_saml_moodle_05_moodle_setup_samlprovider_crypto.png?direct |}}
-The plugin's configuration page also provides a mapping of SAML attributes to Moodle fields. Again, Admidio provides a similar mapping. Whatever information should be transferred from Admidio to Moodle should be configured. The actual SAML / IdP field name is not relevant, only the source Admidio field and the target Moodle field:
-{{ :en:2.0:sso:sso_saml_moodle_07_field_mapping.png?direct |}}
-==== Setup Users and Connect them to their Admidio Username ====
-Moodle's SAML app only allows connecting existing users to a SAML account from Admidio. It does not have any functionality to create new users when an unknown account successfully logs in via SAML.
-This means that one has to manually create all users that should have access to Moodle first, and then assign each one their proper SAML username. Only after that, single-sign-on via Admidio is possible.
-First, you have to configure Admidio to use the "Login name - usr_login_name" as the "User ID field".
-{{ :en:2.0:sso:sso_saml_moodle_11_admidio_useridfield.png?direct |}}
-Create each user, and in in the "Edit user" form, switch to the "SAML" tab, where you can create a new connection to a SAML account (click "Add a line", select the Admidio IdP on the left and enter the Admidio username on the right).
-{{ :en:2.0:sso:sso_saml_moodle_10_connect_user.png?direct |}}
-==== Setup completed, test Single-Sign-On ====
-Admidio and Moodle should now be set up to use Admidio for logging in to Moodle. 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_saml_moodle_08_moodle_loginform.png?direct |}}
-After choosing SAML login and loggin in with a user from Admidio, you should be logged in to Nextcloud.
+After choosing SAML login and loggin in with a user from Admidio, you should be logged in to Moodle.
-{{ :en:2.0:sso:sso_saml_moodle_09_admidio_loginform.png?direct |}}
+{{ :en:2.0:sso:sso_moodle_saml_16_loginsuccess.png?direct&600 |}}
@@ Line 141: / Line 110: @@
 ==== Caveats and Things to Consider ====
-  * Moodle does NOT automatically create a new user account if a successful login from an unknown Admidio account occurs. Instead, one first has to create a new user (or connect an existing user) and connect that user with the proper Admidio user account name. In Admidio's SAML client config, you can select whether to use the numeric user ID, the login name or the email as "User ID field". Whatever you choose determines which value must be entered in Moodle's user connection field.
+  * 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 |}}
-  * To install the SAML plugin, moodle needs the "pysaml2" library installed first. It can for example be installed from the shell with <code>php3 install pysaml2</code>
+  * 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 |}}
-  * If moodle is behind a reverse proxy (e.g. Nginx Proxy Manager), correct proxy settings both in Moodle and the proxy itself is vital to make sure that the SAML endpoints in the metadata file and the actually called endpoints actually use https. Otherwise, login will fail without a helpful error message.
-    * In `moodle.conf` set <code>proxy_mode = 1</code>
-    * Make sure the reverse proxy sends all proper proxy headers, including X-FORWARDED-HOST, which is used by moodle to detect a reverse proxy setup. Nginx Proxy Manager by default does not send this header. It is also not easily possible to add this header in the "Advanced" tab of the Proxy Host in NPM. Instead, one has to add Custom Location for "/" and set the X-Forwarded-Host header there via <code>proxy_set_header X-Forwarded-Host $host;</code> You need to duplicate the forwarding host information from the main host:{{ :en:2.0:sso:sso_saml_moodle_12_npm_x-forwarded-host.png?direct&400 |}}