## Authentication: SAML2 Single sign on

auth_saml2
Maintained by Catalyst IT, Brendan Heywood, Adam Riddell
SAML done 100% in moodle, fast, simple, secure
484 sites
20 fans

## What is this?

This plugin does authentication, user auto creation with field mapping.

## Why is it better?

• 100% configured in the Moodle GUI - no installation of a whole separate app, and no touching of config files or generating certificates.
• Minimal configuration needed, in most cases just copy the IdP metadata in and then give the SP metadata to your IdP admin and that's it.
• Fast! - 3 redirects instead of 7
• Supports back channel Single Logout which most big organisations require (unlike OneLogin)

## How does it work?

It completely embeds a SimpleSamlPHP instance as an internal dependancy which is dynamically configured the way it should be and inherits almost all of it's configuration from Moodle configuration. In the future we should be able to swap to a different internal SAML implementation and the plugin GUI shouldn't need to change at all.

## Features

• Dual login VS forced login for all as an option, with ?saml=off on the login page for manual accounts, and ?saml=on supported everywhere to deep link and force login via saml if dual auth is on.
• SAML attributes to Moodle user field mapping
• Automatic certificate creation
• Optionally auto create users

Features not yet implemented:

• Enrolment - this should be an enrol plugin and not in an auth plugin
• Role mapping - not yet implemented

## Installation

1) Install the plugin the same as any standard moodle plugin either via the Moodle plugin directory, or you can use git to clone it into your source:

git clone git@github.com:CatalystIT-AU/moodle-auth_saml2.git auth/saml2

2) Then run the Moodle upgrade 3) If your IdP has a publicly available XML descriptor, copy this url into the SAML2 auth config settings page 4) If your IdP requires whitelisting each SP then in the settings page is links to download the XML, or you can provide that url to your IdP administrator.

For most simple setups this is enough to get authentication working, there are many more settings to define how to handle new accounts, dual authentication, and to easily debug the plugin if things are not working.

If you have issues please log them in github here:

https://github.com/CatalystIT-AU/moodle-auth_saml2/issues

https://www.catalyst-au.net/contact-us

## Testing

This plugin has been tested against:

• SimpleSamlPHP set up as an IdP
• openidp.feide.no
• testshib.org
• An AAF instance of Shibboleth

## Other SAML plugins

The diversity and variable quality and features of SAML Moodle plugins is a reflection of a great need for a solid SAML plugin, but the neglect to do it properly in core. SAML2 is by far the most robust and supported protocol across the internet and should be fully integrated into moodle core as both a Service Provider and as an Identity Provider, and without any external dependencies to manage.

Here is a quick run down of the alternatives:

Core:

• /auth/shibboleth - This requires a separately installed and configured Shibbolleth install

One big issue with this, and the category below, is as there is a whole extra application between moodle and the IdP, so the login and logout processes have more latency due to extra redirects. Latency on potentially slow mobile networks is by far the biggest bottle neck for login speed and the biggest complaint by end users in our experience.

Plugins that require SimpleSamlPHP

These are all forks of each other, and unfortunately have diverged quite early or have no common git history making it difficult to cross port features or fixes between them.

Plugins which embed a SAML client lib:

These are generally much easier to manage and configure as they are standalone.

• https://moodle.org/plugins/view/auth_onelogin_saml - This one uses it's own embedded saml library which is great and promising, however it doesn't support 'back channel logout' which is critical for security in any large organisation.

• This plugin, with an embedded and dynamically configured SimpleSamlPHP instance under the hood

## Warm thanks

Thanks to the various authors and contributors to the other plugins above.

Thanks to LaTrobe university in Melbourne for sponsoring the initial creation of this plugin:

http://www.latrobe.edu.au

Thanks to Centre de gestion informatique de l’éducation in Luxembourg for sponsoring the user autocreation and field mapping work:

http://www.cgie.lu

This plugin was developed by Catalyst IT Australia:

https://www.catalyst-au.net/

### Awards

• Mon, 6 Nov 2017, 10:53 PM
I've been using an old version(2016041300) of this SSO software with Moodle 3.0. We recently set up a dev box and upgrade to moodle 3.3 and I've downloaded the latest moodle_33PLUS branch from github and install it. However, now I'm having a problem with the "single sign on" with my IdP provider. Keep getting the error message "message did not meet security requirements". The only difference I find is in my metadata that I normally provide to my IdP provider. It no longer have the signature element. Is there a way to turn this on so it is included in my metadata when I download it? I've look into the log and notice that it does pass the signature in the auth request. Sorry but my previous post drop my xml tags.
• Tue, 7 Nov 2017, 7:22 AM
hi Sunil,

In the saml admin GUI there is a setting called 'SP Metadata signature', set this to yes. If that doesn't work please open an issue in github as it's easier to sort details like xml over there.
• Wed, 8 Nov 2017, 12:56 AM
Hi Brendan,

Thank you for your prompt response. That fix my problem. feeling a bit stupid for that oversight on the GUI option. Thanks
• Thu, 16 Nov 2017, 4:44 AM
I've been trying to check that the user has already been authenticated on the IDP (in a IDP-initiated process)? I tried isAuthenticated() but that didn't work. Specifically I need dual authentication turned on. It is. The SSO works when the user clicks on the SAML2 button. However, I need to only show this if a user has a valid session/login when they land on the login page to avoid showing it and just let them in. Or show the dual login page if they don't have a session when landing on the page. So I'm confused. It appears that a SP-initiated process flow works with this plugin.
• Thu, 16 Nov 2017, 4:51 AM
Per my last question. You guys do that in saml_login $auth = new SimpleSAML_Auth_Simple($this->spname);
$auth->requireAuth();$attributes = \$auth->getAttributes();

but I am trying to circumvent by check for isAuthenticated() in pre_loginpage_hook and/or should_login_redirect(). But the function always returns FALSE. The only way is if I preface it with requireAuth() to for a SP-to-IDP check. I cannot get access to the IDP assertion that was pushed/posted to the SP. How do I do this?
• Thu, 16 Nov 2017, 10:56 AM
hi A Guy,

https://www.catalyst-au.net/content/contact-us

If you can provide a patch, please make an issue / PR in github and we'll continue the conversation there.
• Thu, 16 Nov 2017, 11:03 AM
I don't see how this is actually even possible. In order for an IDP to post anything for the SP to receive I would think it would have to be wrapped in a session. So wouldn't the the SP have to be reached first and then the IDP log in for authentication show up next and redirect back to the SP? To me that sounds like SP initiated but without a session to track this I don't know how that would work. I don't much about isPassive. I will look into that.
• Thu, 16 Nov 2017, 2:15 PM
IdP initiated SSO is fairly mature protocol and it is already supported in the underlying saml library this plugin is using, it's just that we haven't tested it and it probably needs some moodle specific wiring to make it all work. But I have no doubt it is possible, it's just not a very common requirement. There isn't much upside to using Idp init, it's easier to just use clean deep links to resources with no knowledge of the IdP and let each SP do what it needs to transparently. isPassive is conceptually simpler but has a cost of a couple extra http redirect roundtrips. It is also supported in the saml library but just needs a bit of config and wiring.
• Fri, 17 Nov 2017, 5:30 AM
Sorry. Let me clarify. I know that simplesamlphp references idp first flow I think it is called. I have installed simplesamlphp manually for idp and sp and used it for SSO. What I mean by not being sure it if is possible I am specifically talking about how the IDP group wants this. Anyway the simplesamlphp folks say it is and it is a simple matter of posting to the acs.php protocol. They ahve and I do see the assertion/claims/attributes in the log file. I just cannot get to them with your plugin. I have tried using the auth.php and edited it to test for authentication. I cannot get it. I cannot get the attributes. I did try isPassive like you suggested but all that does is what I got your plugin to do anyway with a little modification--initiated the log in with IDP, IDP posts to SP, the SP sends back a request to check if there is a session, there is one of course, so it returns to the SP, we get logged in. isPassive just submits the login again. This is not what I need. When the user lands on the sp/lms/moodle page (internally) they are logged in via saml. I just need to be able to process that successfully decrypted assert/parameters that is in the sp/lms/moodle log file. I just don't know why I cannot. the simplesamlphp folks say it is not matter of a session. So I'm stumped. The only thing to do is yank out this out and install simplesamlphp myself manually. I thought I would ask you again before I do all of that to see if you can think of a reason I cannot just drop code in the loginpage_hook function after your check for whether the plugin is configure or not and check if the user is authenticated. By this point the user's decrypted data is in the saml log. I've tried most things I can think of at this point.
• Mon, 20 Nov 2017, 6:18 AM
Ok so you aren't just using this plugin, you are actively hacking on the code and trying to implement this feature? The flow for idp init would be quite different as they would hit the acs file first, rather than some arbitrary moodle page deeplink which would then trigger loginpage_hook etc. The sp/saml2-acs.php file may need tweaks, off the top of my head I don't know exactly whats involved but if the SSP sp itself is authenticating fine then it's just a matter of wiring up the moodle parts in the right way. While this should be fairly straight forward it's also not trivial and not something I can help with quickly here. If you want commercial support then please contact us
• Wed, 29 Nov 2017, 8:36 AM
I don't think it should matter which direction the SSO is initiated is what I was saying . . .a nd asking. The plugin implements simplesamlphp as a SSO for Moodle. Whether it is IDP-initiated or SP-initiated shouldn't matter I would think. It really is all the same API. The metadata is exchanged. The assertions are sent/received. THey are decrypted. They can be signed/checked. Etc. Moodle's authentication is moodle's authentication. But I have found something that maybe the problem. I noticed that you have sha1 on the sp side. And I saw a note in the code that said you needed "TODO" sha356 for ADFS. simplesamlphp out of the box allows you flip this algorithm in the configuration with signature.algorithm. But it doesn't seem to work when I delete the sp xml file in the moodledata/saml2 directory to regenerate it. The simplesamlphp docs say "http://www.w3.org/2000/09/xmldsig#rsa-sha1 Note: the use of SHA1 is deprecated and will be disallowed in the future." That is what continually appears. So I am wondering if this is the problem. Of course it isn't a problem today with SP-initiated. But with IDP-initiated I am wondering if this plugin can handle the sha356 algorithm being posted to it? Your thoughts?
• Wed, 29 Nov 2017, 9:33 AM
sp vs idp init are different and need to be handled differently - yes SSP itself can handle this but we are using it as an internal library. There probably needs to be a layer around it to translate this back to moodle.

The algorithm is currently 256 and it's easy to change manually here in the absence of a gui:

https://github.com/catalyst/moodle-auth_saml2/blob/MOODLE_33PLUS/config/authsources.php#L56

I've also logged adding the gui as a new feature here:

https://github.com/catalyst/moodle-auth_saml2/issues/162

I'm not sure where you are seeing sha1? The only place we use it directly is in the local key store, but this isn't a sensitive area and is only used to reduce the key size. For simplicity we could make this leverage the same hash used for the signature.
• Sat, 2 Dec 2017, 2:55 AM
sha1 is what shows up from this module when it builds the sp's metadata. so if you go to moodle site admin-> authentication->saml2 and click on the sp mooodledata link or the link to download it or even go to the moodledata->saml2->[sp xml file] it is sha1 by default.
• Sat, 2 Dec 2017, 2:57 AM
but I can say that the problem around 256 was irrelevant as far as I can tell. the idp in question was sending me a bad key in their metadata for signing. as I said above I have always been able to decrypt it their assertion as seen in my log file. but I found one error in the saml log that pointed me to a bad signing key. the IDP folks fixed it,t he error went away, so I am waiting on them to try another idp-initiated log in to see if that fixes the issue
• Fri, 8 Dec 2017, 8:51 PM
Is the version in the MOODLE_33_PLUS branch stable? I am wondering, because it has not been published in this repository as of yet, but seems to have fixed some problems we have with force-login and permissions after saml-login in Moodle. The only problem remaining for us is that the SLO does not work.