Learning Stacks Moodle-IMIS Integration Components

Copyright (c) 2017: All Rights Reserved, Learning Stacks LLC

Introduction

Moodle-IMIS integration has three parts:

1. Moodle web services that IMIS can use to create Moodle user accounts and enrol Moodle users in courses.

2. A Moodle authentication plugin that provides Single Sign On (SSO) capabilities with IMIS.

3. A Moodle plugin that detects when an IMIS user completes a course in Moodle and sends that completion information back to IMIS.

Web Services

IMIS Bridge requires access to three standard Moodle web service functions:

1. core_user_get_users
2. core_user_create_users
3. enrol_manual_enrol_users

These services are made available by configuring a user, role and custom web service using standard Moodle capabilities.

Single Sign On

Single Sign On capabilities are provided by Learning Stacks AUTH_IMISBRIDGE Moodle authentication plugin.

This plugin provides the following features:

1. Attempts to log into Moodle directly are redirected to the IMIS Sign On page. Upon successful authentication the browser is redirected back to the originally requested Moodle page.

2. Users already authenticated in IMIS are allowed to directly access the requested page, assuming they have the required Moodle privileges.

3. Single Sign On can be bypassed and an authorized user can log directly into Moodle by accessing url <moodle wwwroot>/login/index.php?nosso and entering a valid username and password.

4. Each time a User logs into Moodle their User Profile is updated from IMIS. This feature can be disabled.

This plugin requires the LOCAL_IMISBRIDGE plugin (see next section).

Course Completion Reporting

Course completion reporting is provided bu Learning Stacks LOCAL_IMISBRIDGE plugin.

This plugin provides the following features:

1. When an IMIS User completes a Moodle course a Course Completion message is sent to IMIS. This feature can be disabled.

This plugin also provides the API for calling IMIS Bridge web services and is used by the AUTH_IMISBRIDGE plugin.

Setup

Web Service Setup

IMIS Bridge requires access to several Moodle web service methods.

• core_user_get_users
• core_user_create_users
• enrol_manual_enrol_users

For additional information on configuring Moodle Web Services (for Moodle 35) see https://docs.moodle.org/35/en/Using_web_services.

Within moodle you can navigate to Site administration > Plugins > Web services > Overview for a guided step-by-step procedure for setting up a web service.

The following recommended configuration creates a web service with the required functions and limits access to specified user that represents the IMIS Bridge system.

1. Enable Web Services

   1. Access Site Administration > Advanced features
   2. Check Enable web services
   3. Save changes

2. Enable Protocols

   • Access Site Administration > plugins > Web services > Manage protocols
   • Enable the REST protocol
   • You do not need to enable the Web services documentation
   • Save changes

3. Create a role that limits access to the required methods

   1. Access Site Administration > Users > Permissions > Define Roles

   2. Click Add a new role

   3. For Use role or archetype select No role then Continue

   4. Fill in the required fields

      Field	Value
      Short name	imisbridge
      Custom full name	imisbridge
      Role Archetype	None
      Context types where this role may be assigned	System
      Allow role assignments	None
      Allow role overrides	None
      Allow role switches	None
      Allow role to view	None

   5. Click Allow on the following Capabilities

      • enrol/manual:enrol
      • moodle/course:useremail
      • moodle/user:create
      • moodle/user:update
      • moodle/user:viewdetails
      • moodle/user:viewhiddendetails
      • webservice/rest:use

   6. Save changes

4. Create service User

   1. Access Site administration > Users > Add a new user

   2. Fill in required fields

      Field	Value
      Username	imisbridge (all lower case)
      Choose an authentication method	manual accounts
      Password	Any valid password
      First Name	imisbridge (or any desired value)
      Surname	service (or any desired value)
      Email address	Any string with valid email address syntax. e.g., imisbridge@nowhere.com

   3. Click Create user

5. Assign the imisbridge role to the imisbridge user in the system context

   1. Access Site Administration > Users > Permissions > Assign system roles
   2. Select role imisbridge
   3. In Potential users find and select imisbridge service
   4. Click Add

6. Create Service

   1. Access Site Administration > Plugins > Web Services > External services

   2. Click Add

   3. Fill in required fields

      Field	Value
      Name	imisbridge
      Enabled	Checked
      Authorised users only	Checked

   4. Click Add service

7. Add Functions

   1. Click Add functions
   2. Add the following functions
      • core_user_get_users
      • core_user_create_users
      • enrol_manual_enrol_users
   3. Click Add functions

8. Create Token for imisbridge user

   1. Access Site adminstration > Plugins > Web services > Manage Tokens

   2. Fill in required fields

      Field	Value
      User	Find and select imisbridge service
      Service	Select imisbridge
      IP restriction	Can leave blank or set to the IP address og the IMIS Bridge service
      Valid until	Leave disabled or set any desired expiration date

   3. Click Save changes

9. Assign the user to the service

   1. Access Site administration > Plugins > Web services > External Services
   2. Under Custom services > imisbridge click Authorised users
   3. In Not authorised users find and select imisbridge service
   4. Click Add
   5. Under Change settings for the authorised user > imisbridge service, if any missing capabilities are identified, allow these capabilities on the imisbridge role.

Plugin Installation and Configuration

Both components must be installed together.

1. Unzip auth_imisbridge.zip into folder <lms_root>\auth\imisbridge.
2. Unzip local_imisbridge.zip into folder <lms_root>\local\imisbridge.
3. Perform the Moodle upgrade process

AUTH_IMISBRIDGE Configuration

Setting	Description
SSO Login URL	Enter the full URL where the user should be redirected to login via IMIS
SSO Logout URL	Enter the URL where the user should be redirected after logging out.
Synch Profile	If checked, the User's Moodle profile will be updated each time they log in.

If Synch Profile is checked, the Moodle user profile will be updated with data from IMIS. The fields in this section define the fields to be update, their source, when they are updated, and what can be changed by the user.

Setting	Description
Text Field associated with the Moodle profile field	Enter the name of the field returned from the IMIS Bridge MoodleGetUserProfile service that contains the associated value. The spelling is case sensitive.
Update Local	Set to On every login
Update External	Set to Never
Lock Value	Set to Unlocked to allow user to change the value.

LOCAL_IMISBRIDGE Configuration

Setting	Values
Base API URL	The URL at which the IMIS Bridge web services are located

Testing the installation

Verify web service access

The testing feature built into Moodle does not allow testing of the custom web service or any of the functions used. Instead use a tool capable of submitting a GET or POST request. For example Postman, Curl, powershell Invoke-WebRequest, or even a browser can be used.

To view the documentation for a function access Site administration > Plugins > Web services > API Documentation. Clicking an a function shows the details of making that request.

For example, to test access to the core_user_get_users function using the browser enter the following URL into the browsers' address bar:

<moodle wwwroot>/webservice/rest/server.php?moodlewsrestformat=json&wsfunction=core_user_get_users&criteria[0][key]=username&criteria[0][value]=imisbridge&wstoken=<imisbridge user token>

The response should be a JSON string that should look like

{
    "users": [
        {
            "id": 3,
            "username": "imisbridge",
            "fullname": "imisbridge service",
            "email": "imisbridge@nowhere.com",
            "department": "",
            "firstaccess": 0,
            "lastaccess": 0,
            "auth": "none",
            "suspended": false,
            "confirmed": true,
            "lang": "en",
            "theme": "",
            "timezone": "99",
            "mailformat": 1,
            "description": "",
            "descriptionformat": 1,
            "profileimageurlsmall": "http://imisbridge.local.com/theme/image.php/boost/core/1574703494/u/f2",
            "profileimageurl": "http://imisbridge.local.com/theme/image.php/boost/core/1574703494/u/f1",
            "preferences": [
                {
                    "name": "auth_forcepasswordchange",
                    "value": "0"
                },
                {
                    "name": "email_bounce_count",
                    "value": "1"
                },
                {
                    "name": "email_send_count",
                    "value": "1"
                },
                {
                    "name": "_lastloaded",
                    "value": 1574715282
                }
            ]
        }
    ],
    "warnings": []
}

End to end tests

1. End to end test (verifies new user creation, SSO and completion reporting)

   1. Create a new user in IMIS that does not yet have a corresponding Moodle user account.
   2. Setup a course in IMIS and the corresponding course in Moodle
   3. Login into IMIS as the new user
   4. Register for the course in IMIS
   5. From IMIS open the course in Moodle.
   6. Complete the course in Moodle.
   7. Verify the course shows as completed in IMIS.
   8. As admin inspect the Moodle user account and verify profile details match IMIS.

2. SSO redirection

   1. Log out of Moodle and IMIS.
   2. Attempt to access the LMS home page.
   3. Verify you are redirected to the IMIS SSO login page.
   4. Log into IMIS.
   5. Verify you are redirected to the LMS home page.

3. Logout redirection (if set)

   1. Login into IMIS.
   2. Access the LMS home page.
   3. Click the Moodle logout link.
   4. Verify you are redirected to the SSO Logout URL configured in AUTH_IMISBRIDGE. If this is not set verify redirection to IMIS Login.

4. Profile update

   1. Log out of Moodle.
   2. Change the user's surname in IMIS.
   3. Login into IMIS and navigate to the LMS.
   4. Verify the surname has been updated in Moodle.

5. SSO Bypass

   1. Log out of Moodle and IMIS.
   2. Access <wwwroot>/login/index.php?nosso and and verify you can log in as the Moodle admin with username and password, without being redirected to IMIS.