Difference between revisions of "Cool Solution - Install Moodle/SAML authentication"

From Univention Wiki

Jump to: navigation, search
(Replaced content with "This page has been moved to the Knowledge Base Cool Solutions in the Forum. [https://help.univention.com/t/cool-solution-install-moodle-saml-authentication/12299/4 Cool S...")
Tag: Replaced
 
Line 1: Line 1:
{{Version|UCS=4.4}}
+
This page has been moved to the Knowledge Base Cool Solutions in the Forum.
{{Version|school=4.4}}
 
{{Cool Solutions Disclaimer|Repository=no}}
 
{{#seo:
 
|title={{#replace:{{#replace:{{#replace:{{#replace:{{FULLPAGENAME}}|'|'}}|&|&}}|"|"}}|Cool Solution - |}} - {{SITENAME}}
 
<!--|description=-->
 
}}
 
  
We will now connect Moodle with our UCS Identity Provider using Single-Sign-On (SSO) and the SAML (Security Assertion Markup Language) Protocol. Moodle will be able to create and map all it's users based on all the enabled ones inside our LDAP context(s).
+
[https://help.univention.com/t/cool-solution-install-moodle-saml-authentication/12299/4 Cool Solution - Install Moodle / SAML authentication]
 
 
This article is based on a successful installation of Moodle accomplished by following our [[Cool Solution - Install Moodle|Cool Solution "Install Moodle"]].
 
 
 
== Prerequisites ==
 
 
 
We will first have to download and extract the [https://moodle.org/plugins/auth_saml2 SAML2 Single-Sign-On plugin]. You can use the following script to download the last tested version ''2019022100''. You might find and use newer plugin versions on the linked Moodle website.
 
<syntaxhighlight lang="bash">
 
tmpdir=$(mktemp -d) # A temporary working directory
 
 
 
# Download Moodle and extract it
 
wget --show-progress -O $tmpdir/moodle-auth_saml2-2019022100.tgz https://github.com/catalyst/moodle-auth_saml2/archive/2019022100.tar.gz
 
tar -xvzf $tmpdir/moodle-auth_saml2-2019022100.tgz -C /var/www/moodle/auth/
 
 
 
# Set the correct folder and file permissions (This might take a few seconds)
 
mv /var/www/moodle/auth/moodle-auth_saml2-2019022100 /var/www/moodle/auth/saml2
 
chown -R www-data:www-data /var/www/moodle/auth/saml2
 
find /var/www/moodle/auth/saml2/ -type f -exec chmod 640 {} \;
 
find /var/www/moodle/auth/saml2/ -type d -exec chmod 750 {} \;
 
 
 
# Remove the temporary working directory again
 
rm -R $tmpdir
 
</syntaxhighlight>
 
 
 
Moodle will now require an upgrade of its database. This can quickly be done by opening the service in a webbrowser (might take a while):
 
<pre>
 
https://<server>/moodle
 
</pre>
 
 
 
As last prerequisite, the '''SAML2''' Plugin should be activated inside the web configuration site '''Site Administration''' -> '''Plugins''' -> '''Authentication''' -> '''Manage authentication'''. Please confirm that the '''LDAP server''' Plugin is disabled. We don't recommend having both authentication services enabled.<br>
 
Now the SAML connection can be configured. You can either use the webbrowser or use the command line as described below.
 
 
 
== SAML Single-Sign-On configuration from the Command Line ==
 
 
 
Use the following script to automatically configure the SAML2 Single-Sign-On plugin through the command line. You can optionally use your web browser further down:<br>
 
(Note: Don't forget to set the variables on the script top first)
 
 
 
This first part has to be executed on your '''UCS SAML server''' (usually your Master) to create a SAML service provider and additionally enable a few attributes, that can then be accessed by Moodle.
 
<syntaxhighlight lang="bash">
 
moodle_server_fqdn="slave1.cool-solutions.intranet" # The fully qualified domain name (FQDN) of your Moodle server
 
moodle_web_address="https://slave1.cool-solutions.intranet/moodle" # Please set the direct web address to moodle here. It should be the same address you used during the Moodle installation and should also start with the https protocol
 
 
 
# Enable a few attributes, that can later be accessed by Moodle
 
shopt -s nocasematch
 
eval "$(ucr --shell search saml/idp/ldap/get_attributes)"
 
temp_saml_idp_ldap_get_attributes="$saml_idp_ldap_get_attributes"
 
 
 
for attribute in 'uid' 'mailprimaryAddress' 'enabledServiceProviderIdentifier' 'c' 'departmentNumber' 'description' 'givenName' 'l' 'mobile' 'o' 'sn' 'street' 'telephoneNumber' 'uidNumber'; do
 
    if [[ ! $saml_idp_ldap_get_attributes =~ [\'\"]$attribute[\'\"] ]]; then
 
        temp_saml_idp_ldap_get_attributes+=" ,'$attribute'"
 
    fi
 
done
 
ucr set saml/idp/ldap/get_attributes="$temp_saml_idp_ldap_get_attributes"
 
 
 
# Create a SAML identity provider for Moodle. This will allow Moodle to send login requests and receive the set attributes to map them to the automatically created users
 
udm saml/serviceprovider create --position cn=saml-serviceprovider,cn=univention,$(ucr get ldap/base) \
 
--set Identifier="$moodle_web_address/auth/saml2/sp/metadata.php" \
 
--set AssertionConsumerService="$moodle_web_address/auth/saml2/sp/saml2-acs.php/$moodle_server_fqdn" \
 
--set singleLogoutService="$moodle_web_address/auth/saml2/sp/saml2-logout.php/$moodle_server_fqdn" \
 
--set isActivated=TRUE \
 
--set simplesamlAttributes=TRUE \
 
--set simplesamlNameIDAttribute=uid \
 
--set LDAPattributes=c \
 
--set LDAPattributes=departmentNumber \
 
--set LDAPattributes=description \
 
--set LDAPattributes=givenName \
 
--set LDAPattributes=l \
 
--set LDAPattributes=mailPrimaryAddress \
 
--set LDAPattributes=mobile \
 
--set LDAPattributes=o \
 
--set LDAPattributes=sn \
 
--set LDAPattributes=street \
 
--set LDAPattributes=telephoneNumber \
 
--set LDAPattributes=uid \
 
--set LDAPattributes=uidNumber
 
</syntaxhighlight>
 
 
 
This part now has to be executed on your '''UCS Moodle server''' to configure the SAML2 Single-Sign-On plugin. Please again, don't forget to set the variable on top of the script).
 
<syntaxhighlight lang="bash">
 
# The DNS record to the UCS identity provider. This is ''ucs-sso.domainname'' followed by the path ''/simplesamlphp/saml2/idp/metadata.php'' by default
 
sso_web_address="https://ucs-sso.cool-solutions.intranet/simplesamlphp/saml2/idp/metadata.php"
 
 
 
# Configure the SAML Plugin
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="anyauth" --set="1"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="autocreate" --set="1"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="duallogin" --set="0"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="idpattr" --set="uid"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="idpmetadata" --set="$sso_web_address"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="idpmetadatarefresh" --set="1"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="nameidpolicy" --set="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
 
 
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_lock_address" --set="locked"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_lock_city" --set="locked"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_lock_country" --set="locked"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_lock_department" --set="locked"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_lock_description" --set="locked"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_lock_email" --set="locked"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_lock_firstname" --set="locked"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_lock_idnumber" --set="locked"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_lock_institution" --set="locked"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_lock_lastname" --set="locked"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_lock_phone1" --set="locked"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_lock_phone2" --set="locked"
 
 
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_map_address" --set="street"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_map_city" --set="l"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_map_country" --set="c"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_map_department" --set="departmentNumber"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_map_description" --set="description"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_map_email" --set="mailPrimaryAddress"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_map_firstname" --set="givenName"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_map_idnumber" --set="uidNumber"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_map_institution" --set="o"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_map_lastname" --set="sn"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_map_phone1" --set="telephoneNumber"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_map_phone2" --set="mobile"
 
 
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updatelocal_address" --set="onlogin"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updatelocal_city" --set="onlogin"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updatelocal_country" --set="onlogin"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updatelocal_department" --set="onlogin"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updatelocal_description" --set="onlogin"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updatelocal_email" --set="onlogin"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updatelocal_firstname" --set="onlogin"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updatelocal_idnumber" --set="onlogin"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updatelocal_institution" --set="onlogin"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updatelocal_lastname" --set="onlogin"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updatelocal_phone1" --set="onlogin"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updatelocal_phone2" --set="onlogin"
 
 
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updateremote_address" --set="0"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updateremote_city" --set="0"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updateremote_country" --set="0"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updateremote_department" --set="0"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updateremote_description" --set="0"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updateremote_email" --set="0"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updateremote_firstname" --set="0"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updateremote_idnumber" --set="0"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updateremote_institution" --set="0"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updateremote_lastname" --set="0"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updateremote_phone1" --set="0"
 
php /var/www/moodle/admin/cli/cfg.php --component="auth_saml2" --name="field_updateremote_phone2" --set="0"
 
 
 
cd /var/www/moodle/admin/tool/task/cli/
 
php schedule_task.php --execute=\\auth_saml2\\task\\metadata_refresh
 
</syntaxhighlight>
 
 
 
We are almost finished. As last we will have to activate our registered SAML service provider for all wanted users. Please follow the Postrequisites to achieve this.
 
<br clear=all>
 
 
 
=== Alternative: SAML Single-Sign-On configuration using the web browser ===
 
[[File:Moodle_saml_service_provider_basic.png|400px|thumb|right|SAML service provider basic settings]]
 
[[File:Moodle_saml_service_provider_extended.png|400px|thumb=Moodle_saml_service_provider_extended_thumb.png|right|SAML service provider extended settings]]
 
 
 
As first part, we will have to create a new external service provider. We can follow the [http://docs.software-univention.de/manual-4.4.html#domain:saml:additionalserviceprovider official UCS Documentation] for this.
 
 
 
A few attributes have to be appended to an UCR variable on your '''UCS SAML server'''. This later allows Moodle to access the data when it automatically creates a new user. The Univention Management Console system module '''Univention Configuration Registry''' can be used for this.
 
 
 
Assure that the UCR variable ''"saml/idp/ldap/get_attributes"'' contains the following attributes:<br>
 
'' 'uid', 'mailPrimaryAddress', 'enabledServiceProviderIdentifier' ,'c' ,'departmentNumber' ,'description' ,'givenName' ,'l' ,'mobile' ,'o' ,'sn' ,'street' ,'telephoneNumber' ,'uidNumber' ''
 
 
 
 
After setting the UCR variable, use the following settings while using the Univention Management Console domain module '''SAML identity provider''' to create a new service provider:
 
{|class="wikitable"
 
!Key
 
!Value
 
|-
 
!colspan="2"| SAML service provider basic settings
 
|-
 
| Service provider activation status
 
| Activated
 
|-
 
| Service provider identifier
 
| https://<YOUR_MOODLE_SERVER_FQDN>/moodle/auth/saml2/sp/metadata.php
 
|-
 
| Respond to this service provider URL after login
 
| https://<YOUR_MOODLE_SERVER_FQDN>/moodle/auth/saml2/sp/saml2-acs.php/<YOUR_MOODLE_SERVER_FQDN>
 
|-
 
| Single logout URL for this service provider
 
| https://<YOUR_MOODLE_SERVER_FQDN>/moodle/auth/saml2/sp/saml2-logout.php/<YOUR_MOODLE_SERVER_FQDN>
 
|-
 
| Name of the attribute that is used as NameID
 
| uid
 
|-
 
| Name of the organization for this service provider
 
| Moodle
 
|-
 
| Description of this service provider
 
| Moodle on <YOUR_MOODLE_SERVER_FQDN>
 
|-
 
!colspan="2"| SAML service provider extended settings
 
|-
 
| Allow transmission of ldap attributes to the service provider
 
| Activated
 
|-
 
| Attribute
 
| telephoneNumber
 
|-
 
| Attribute
 
| departmentNumber
 
|-
 
| Attribute
 
| c
 
|-
 
| Attribute
 
| description
 
|-
 
| Attribute
 
| mobile
 
|-
 
| Attribute
 
| mailPrimaryAddress
 
|-
 
| Attribute
 
| uidNumber
 
|-
 
| Attribute
 
| l
 
|-
 
| Attribute
 
| o
 
|-
 
| Attribute
 
| street
 
|-
 
| Attribute
 
| sn
 
|-
 
| Attribute
 
| givenName
 
|-
 
| Attribute
 
| uid
 
|}
 
<br clear=all>
 
 
 
[[File:Moodle_saml_server_settings.png|400px|thumb|right|SAML server settings]]
 
[[File:Moodle_saml_data_mapping.png|400px|thumb=Moodle_saml_data_mapping_thumb.png|right|Data mapping]]
 
Moodle is now allowed to send authentication requests to our UCS server. Next, we will have to configure the Moodle SAML plugin.<br>
 
Change the values under the Moodle web page '''Site Administration''' -> '''Plugins''' -> '''Authentication''' -> '''Manage authentication''' -> '''SAML2''' -> '''Settings''' to successfully configure the SAML plugin:
 
{|class="wikitable"
 
!Key
 
!Value
 
|-
 
!colspan="2"| SAML server settings
 
|-
 
| IdP metadata xml OR public xml URL
 
| https://ucs-sso.<YOUR_DOMAIN_NAME>/simplesamlphp/saml2/idp/metadata.php
 
|-
 
| IdP metadata refresh
 
| Yes
 
|-
 
| Dual login
 
| No
 
|-
 
| Auto create users
 
| Yes
 
|-
 
!colspan="2"| Data mapping (for all entries)
 
|-
 
| Update local
 
| On Every Login
 
|-
 
| Update external
 
| Never
 
|-
 
| Lock value
 
| Locked
 
|-
 
!colspan="2"| Data mapping attributes
 
|-
 
| First name
 
| givenName
 
|-
 
| Surname
 
| sn
 
|-
 
| Email address
 
| mailPrimaryAddress
 
|-
 
| City/town
 
| l
 
|-
 
| Country
 
| c
 
|-
 
| Description
 
| description
 
|-
 
| ID number
 
| uidNumber
 
|-
 
| Institution
 
| o
 
|-
 
| Department
 
| departmentNumber
 
|-
 
| Phone
 
| telephoneNumber
 
|-
 
| Mobile phone
 
| mobile
 
|-
 
| Address
 
| street
 
|}
 
 
 
We are almost finished. As last we will have to activate our registered SAML service provider for all wanted users. Please follow the Postrequisites to achieve this.
 
<br clear=all>
 
 
 
== Postrequisites ==
 
 
 
We can now activate Moodle for all wanted users. For this, we need to enable users for the created Moodle service providers on the user's Account tab.
 
* Open the Univention Management Console module ''Users''
 
* Select all users you want to enable for Moodle
 
* Open the ''Account'' tab
 
* Add your created service provider inside the ''SAML settings'' section (It's entry schould look like: ''"https://<YOUR_MOODLE_SERVER_FQDN>/moodle/auth/saml2/sp/metadata.php"'')
 
* Save the changes
 
 
 
You should now be able to login as any user that is enabled for the registered SAML service provider. Note that some attributes like Email address are mandatory for moodle. Users without valid email addresses inside UCS won't be able to leave their profile settings page, so you should make sure that all moodle users own a valid email.
 
 
 
Note: You can always login locally on Moodle by using the following Link: https://<YOUR_MOODLE_SERVER_FQDN>/moodle/login/index.php?saml=off
 
 
 
== Restrictions ==
 
 
 
* '''Class mapping''': These articles do not handle mappings between UCS@School classes and Moodle groups at this moment. If you need assistance to create the respective mapping or would like to have the setup packaged, feel free to contact Univention for an offer to create either.
 
 
 
== References ==
 
 
 
* Moodle SAML Plugin - https://moodle.org/plugins/auth_saml2
 
* UCS SAML identity provider - https://docs.software-univention.de/manual-4.4.html#domain:saml
 
  
 
[[Category:EN]]
 
[[Category:EN]]
 +
[[Category:Howtos]]

Latest revision as of 11:39, 11 June 2019

This page has been moved to the Knowledge Base Cool Solutions in the Forum.

Cool Solution - Install Moodle / SAML authentication

Personal tools