How to Set Up SAML2 SSO for Moodle or Totara

Assumptions

This SOP makes the following assumptions:

• The customer has an AD (Active Directory) based system.

• They want their users to be able to access Moodle or Totara without logging in (or at the very least they should be able to use their ‘current’ username and password).

• Their AD system supports SAML2

Make sure to check these assumptions with the customer!

Terminology

• Service Provider (SP): In our scenario, Moodle (or Totara) is the service provider – the application that provides the service the user wants to get access to.

• Identity Provider (IdP): The customer’s system where the user is authenticated

• Claims (or ClaimTypes): user attributes (properties of the user, i.e. information about the user)

Install SAML2 Plugin

Moodle does not support SAML2 out of the box (and neither does Totara). You have to install an authentication plugin: SAML2 Single sign on. If you don’t have access to the web server, try to install the plugin through the upload form for plugins: Site administration > Plugins > Install plugins. That should land you on this url: /admin/tool/installaddon/index.php.

Activate the SAML2 Authentication Plugin

Go to Site Administration > Plugins > Manage Authentication. You should end up on this page: /admin/settings.php?section=manageauths.

‘Enable’ the plugin by clicking on the eye icon (or something similar).

From this screen, you can also directly access the SAML2 plugin’s configuration settings by clicking on the Settings link.

Exchange Metadata with the Customer

Get IdP metadata xml or a public xml URL from the Customer

In order to configure the plugin, you need to exchange metadata with the customer. Ask them for the IdP metadata xml or a public xml URL. This should be filled out here:

Sometimes the customer will tell you what claims they’re providing (user attributes). In my experience, this information may or may not be accurate. Keep in mind that the customer’s IdP metadata is authoritative. If a ClaimType isn’t mentioned there, it means it won’t be made available in Moodle either, through SAML2.

Please note that the reverse is sometimes also true: not all claim types that are mentioned in the IdP metadata are always automatically available. Apparently, the administrator of the IdP system has to ‘turn on’ the claim types or something like that.

Provide the Customer with the SP metadata

After you have done that, you should provide them with the SP (Service Provider) metadata, which can be obtained here:

Copy the url from the ‘View Service Provider Metadata’ link and give it to the customer. They should know what to do with it, but just in case they ask you for it:

• The Identifier (Entity ID) can be found in the attribute entityID of the SP Metadata.

For instance, in the following snippet, I have highlighted the entityID attribute:

<md:EntityDescriptor xmlns:md=”urn:oasis:names:tc:SAML:2.0:metadata” xmlns:ds=”http://www.w3.org/2000/09/xmldsig#” entityID=”lms.example.com/auth/saml2/sp/metadata.php”>

• The Reply URL (Assertion Consumer Service URL) can be found in the Location attribute of an AssertionConsumerService node.

Here’s another example where I have highlighted the Location attribute:

<md:AssertionConsumerService Binding=”urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST” Location=”lms.example.com/auth/saml2/sp/saml2-acs.php/vivel.thelearninghub.be” index=”0″/>

N.B.: if you have trouble generating (accessing) the SP Metadata, wait till you have completed the remaining configuration (see the next section), then try again.

Configure the SAML2 Plugin

To configure the SAML2 plugin, take a close look at the customer’s IdP metadata xml. What you need to extract from it, are the fields you need to map in Moodle.

These are the fields that you need at minimum: uid, email address, first name, and last name.

In my experience, these are typically called:

• uid: uid, upn or objectidentifier (see subsection below)

• email address: emailaddress

• first name: givenname

• last name: surname

Officially, the names are much longer, e.g.:

lms.example.com/ws/2005/05/identity/claims/surname

But if you set ‘Simplify attributes’ to ‘Yes’ (the default), then you can use the much shorter names:

The defaults for the remaining configuration options are pretty sensible, although you might want to set ‘Auto create users’ to ‘Yes’, depending on whether the users already exist in Moodle or Totara. For testing purposes, set it to ‘Yes’.

Mapping IdP: uid, upn or objectidentifier

If you link accounts in two different systems (which is basically what SSO comes down to), then you need a way to uniquely identify a user in both systems. In SAML2, this typically done with one of the following attributes:

• uid

• upn (which stands for User Principal Name)

• objectidentifier

The default in Moodle (and Totara) is to use uid, but this won’t work if the attribute (claimtype) is not actually present in the customer’s IdP metadata xml.

So, find the appropriate attribute, and fill it in here, in Mapping IdP:

Typically, the claimtype is a complete url, but usually it is sufficient to only fill in the last part. So, instead of lms.example.com/ws/2005/05/identity/claims/emailaddress, it is sufficient to put in emailaddress.

Attention: the claim types seem to be case sensitive. For instance, the DisplayName may contain capital letters which are missing in the actual ClaimType value. You should always use the actual ClaimType value.

Mapping to Custom Profile Fields

SAML2 fully supports mapping claim types to custom profile fields. In fact, if you have custom profile fields, they will automatically show up in the configuration screen of the plugin: /admin/settings.php?section=authsettingsaml2 (Site Administration > Plugins > Authentication > SAML2). The resulting field name will be something like: auth_saml2 | field_map_profile_field_isDocentTrainer.

Test the SAML2 Based SSO

All the SAML2 configuration is done and tested on staging. Ask the customer for a test AD account, and try to login through SAML2.

If necessary, visit the /auth/saml2/test.php once you’ve got a saml2 based session going. You should see the details of the info the IdP is sending over.

For instance, visiting lms.example.com/auth/saml2/test.php with my Microsoft test account (provided to me by the client’s IT staff) yields:

{

]
}

This is useful information, especially if the Claim Types the client is giving you are not actually working. The screen above shows the right names to use for mapping the IdP fields to Moodle fields.

From Staging to Production

Once the SAML2 configuration has been successfully tested, we have to move it to production. There are two procedures here: one for a new customer and one for an existing customer.

New Customer

In case of a new customer, after testing we then copy the staging environment to production. Because the domain for will be different, we have to provide the customer with the new SP metadata url.

Existing Customer

For an existing customer, the procedure is:

• Test the SAML2 configuration on staging.

• Copy the settings from staging to production.

• Provide the customer with the SP metadata url for production.

Troubleshooting

Turn on the development and debugging mode. If you’ve reached a point where you can’t realistically test with the customer’s AD system (e.g. because you’re not allowed to go in there), use this testing system:

SAMLtest.id

Please keep in mind that your test site needs to be https (it must have an ssl certificate) .

Connecting to Test IDP SAMLtest.id

To test your Moodle or Totara system against SAMLtest.id, use the following settings in the auth Saml2 plugin:

• IdP metadata xml OR public xml URL: https://samltest.id/saml/idp

• Dual login: Yes

• Mapping IdP: uid – Which IdP attribute should be matched against a Moodle user field

• Mapping Moodle: Username

• Data mapping (First name): givenName

• Data mapping (Surname): sn

• Data mapping (Email address): mail

(See also https://samltest.id/download/#Attributes_Sent)

Please note: the selected IdP attribute will always be used to create a Moodle username, no matter what you choose for the Mapping Moodle field.

Special Case: Mapping the IdP attribute to Something Other than Username

In the auth Saml2 plugin settings screen:

• IdP metadata xml OR public xml URL: https://samltest.id/saml/idp

• Dual login: Yes

• Mapping IdP: uid – Which IdP attribute should be matched against a Moodle user field

• Mapping Moodle: ID number (this is the mdl_user.idnumber attribute)

• Data mapping (First name): givenName

• Data mapping (Surname): sn

• Data mapping (Email address): mail

• Data mapping (ID number): uid

Please keep in mind that the IdP attribute will also be used to create the username. In the example above, the uid will be used as the username, and it will be used as the ID number.

You can test this by having a SAMLtest.id test user login, and then change their Moodle username afterwards – they will still be able to login through SAMLtest.id (because the SAMLtest.id login matches with the ID number, given the settings above).

In most scenarios, it’s superfluous to set the ‘Mapping Moodle’ to anything other than username, since the ‘Mapping IdP’ will be stored there anyway.

However, if you want to link existing Moodle accounts to external accounts, it may be easier to set ‘Mapping Moodle’ to idnumber. That way you only need to supply the external value of Mapping IdP to idnumber. You don’t need to change the existing Moodle username – which can be confusing to users.

‘Common’ Errors

Error: “Exception – Call to a member function export_for_template() on string”

If you encounter this message on the login screen (/login/index.php):

– then ask a developer to go to line 731 of /lib/authlib.php and comment out this part:

$idp[‘icon’] = [

‘context’ => $icon->export_for_template($output),

‘template’ => $icon->get_template($output)

];

– and change:

$idp[‘icon’] = array_merge($idp[‘icon’], $icon->export_for_pix($output;

– to:

$idp[‘icon’] = ”;

The reason behind this bug: when the IdP provides an icon, the variable $idp[‘icon’] is set to a string. But Moodle (or Totara) expects an instance of pix_icon there.

TO DO

What is Sign on URL & Relay state?

wwwroot: lms.example.com

• Entity ID: lms.example.com/auth/saml2/sp/metadata.php

• Reply URL: lms.example.com/auth/saml2/sp/saml2-acs.php/opleidingen.sensoa.be

• Sign on URL: not sure. Login url of application is: lms.example.com//login/index.php

• Relay state: application allows deep linking, but most likely url is this one: lms.example.com/totara/dashboard/index.php

• Logout URL: lms.example.com/login/logout.php

This source, lms.example.com/hc/en-us/articles/360000146235-Configuring-SAML-for-Office-365-Azure-Active-Directory, says:

Apply the information collected from your JobReady Site:

• Identifier – Service Provider URL

• Reply URL – Service Provider Login URL

• Sign-on URL – Service Provider Login URL

• Relay State – https://domainname.lms.example.com/user/dashboard

• User Identifier – user.mail

Troubleshooting

You can use an IdP service like lms.example.com/ to test saml2. But please keep in mind that you should only do that if you think the saml2 plugin is somehow not working properly (e.g. you just installed a new version of the plugin).