Sign in to Moodle with OpenAthens

This will show you how to configure Moodle to accept OpenAthens logins using the SAML2 Single sing on plugin from their plugins directory. Other plugins may be available and should work in similar ways - this is the one we used on vle.openathens.net.

Prerequisites

• Administration access to Moodle
• Access to the OpenAthens administration area at the domain level

Method

Install and configure the plugin in Moodle

Install

The plugin will use the URL you are accessing Moodle at during setup for various things, so make sure you sign into Moodle using the externally facing URL it has (or will have if it isn't yet live) before installing the plugin.

1. Go to the Moodle plugins directory (Site administration > Plugins > Install plugins > Instal plugins from the plugins directory)
   
   
2. Find the 'SAML2 Single sign on' plugin and install it (e.g. download the zip file and then drop it in the box on the install plugins page)
   
   
3. Wait - this will take a few minutes to install and self-configure

Configure

This assumes you are using OpenAthens accounts or that local accounts map data to standard fields.  

1. Site administration > Plugins > Authentication
   
   
2. Find the SAML2 authentication plugin in the list and click on settings
   
   
3. Settings - Most can be left as their defaults except:
   
   
   1. IdP metadata: enter your login.openathens.net metadata address - e.g. https://login.openathens.net/saml/2/metadata-idp/yourapiname. 
      1. See: How to access your login.openathens.net metadata
   2. IdP label override: e.g. OpenAthens
      
      
   3. SP Metadata: Use the link to download the SP metadata - you will use that when you configure the OpenAthens end.
      
      
   4. Dual login: Leave this as Yes for now - you can change it to No or Passive when you are ready to go live
      
      
   5. Allowed any auth type: Yes if you have users that won't be signing in with OpenAthens - e.g. if you are migrating users in batches
      
      
   6. Mapping IdP: enter username
      
      
   7. Autocreate users: Often set to Yes for initial testing
      
      
4. Data mapping (you can map more, but these three will stop Moodle presenting a screen to capture them on first login)
   
   
   1. First name: forenames
      
      
   2. Surname: surname
      
      
   3. Email address: emailAddress
      
      
5. Save

If you are mapping additional data fields, it is the target name of the OpenAthens attribute that you need to copy over.

Set up a custom SAML resource in OpenAthens

1. Access the administration area as the domain administrator and navigate to the catalogue (Resources > Catalogue).
   
   
2. Switch to the custom tab and click on the Add button
   
   

   

   
   
   
3. Select the SAML option 
   
   

4. Upload the metadata file you downloaded from the SAML2 plugin's settings page
   
   

5. Click the create button

This will create the basic custom resource using the values in the metadata. If it doesn't have a suitable name, you can edit the details to change it, and add a description or logo.

Add the application to your release policy

1. Still in the administration area navigate to the release policy page (Preferences > Attribute release). 
   
   

   

   
   
   
2. Add a resource policy via the button
   
   
   1. Start typing the name of the SAML resource.
   2. Select it from the list of any options to add a policy
      
      
3. Click on the first name, last name and email address attributes so that they go green. 
   
   
4. Click done and then save changes

This will now release the attributes that Moodle is expecting, but only to your Moodle.

Testing and going live

Until you click the eye icon to enable the plugin (on Moodle's Site administration > Plugins > Authentication page) you will only be able to test using the test button on that page. Both IdP login functions should pass wiht a cheerful 'Authed!' and a list of attributes.

When you're ready to go live, review your plugin settings for things such as dual login and auto-create users, and then click on the eye icon to enable it.   

Customise

Once the basic resource exists, that is all the system need to work unless you are using restrictive mode (see below). You can edit the details of the custom SAML resource in any way you need to.  

All types of custom resources can be made available to sub-organisations by opening the detail view and changing the setting on the visibility tab:

Restrictive mode

If you are running in restrictive mode, the custom resource MUST be included in at least one of the permission sets used by anyone who should gain access or OpenAthens will block access at the authentication point.

If you have sub-organisations you MUST ALSO set the visibility setting described above and allocate it to permission sets under those sub-organisations. The cascade option may be useful.

Whilst our service desk will always try to be helpful, they can only support the OpenAthens end of this kind of connection.