Note: You are currently viewing documentation for Moodle 3.9. Up-to-date documentation for the latest stable version of Moodle may be available here: Microsoft 365.

Microsoft 365: Difference between revisions

From MoodleDocs
No edit summary
(Highlight that the PowerShell script doesn't work on non-Windows operating systems.)
 
(4 intermediate revisions by 2 users not shown)
Line 19: Line 19:
* Automatic and manual user matching from Microsoft 365/Azure AD to Moodle
* Automatic and manual user matching from Microsoft 365/Azure AD to Moodle
* Calendar sync
* Calendar sync
* Course to Microsoft 365 group sync and shared file repositories
* Course to Microsoft 365 group/teams sync and shared file repositories
* OneNote assignment submission and feedback types
* OneNote assignment submission and feedback types
* Office document embedding using Office web apps
* Office document embedding using Office web apps
* Fully customizable sign-in experience
* Fully customisable sign-in experience
* Integration between Moodle courses and Microsoft Teams
* Integration with School Data Sync (SDS)
= Requirements =
= Requirements =
To use the Microsoft 365 plugins, you need the following:
To use the Microsoft 365 plugins, you need the following:
* A Microsoft 365 subscription.
* A Microsoft 365 subscription.
* A Microsoft Azure subscription.
* A Microsoft Azure subscription.
* Moodle version 3.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.
* Moodle version 3.5 or above. The plugins are available for Moodle versions 2.7 and above. Features available in each version, and the support status vary.
 
= Plugins & Features =
= Plugins & Features =
The Microsoft 365 set of plugins contains 5 core plugins, and 4 optional plugins, which provide a wide variety of features to enhance your Moodle instance.
The Microsoft 365 set of plugins contains 6 core plugins, and 3 optional plugins, which provide a wide variety of features to enhance your Moodle instance.
 
* '''Microsoft 365 Local Plugin''' (local_office365)
* '''Microsoft 365 Local Plugin''' (local_office365)
** This is a shell plugin which has dependencies on the current version of each of the 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
** This is a shell plugin which has dependencies on the current version of each of the 5 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''OpenID Connect Authentication Plugin''' (auth_oidc)
* '''OpenID Connect Authentication Plugin''' (auth_oidc)
** This plugin allows users to log in to Moodle using their Microsoft 365 accounts.
** This plugin allows users to log in to Moodle using their Microsoft 365 accounts.
** Users with existing Moodle accounts can switch to using this authentication plugin, and new users can log in with this plugin and have an account created for them.
** Users with existing Moodle accounts can switch to using this authentication type, and new users can log in with this plugin and have an account created for them.
** If the administrator allows, users can also choose to disconnect from OpenID Connect and revert their previous login method, or to a username/password.
** If the administrator allows, users can also choose to disconnect from OpenID Connect and revert their previous login method, or to a username/password.
** Features
** Features:
*** Standards-Compliant OpenID Connect Authentication
*** Standards-Compliant OpenID Connect Authentication.
*** Supports authorization code or resource-owner credentials grants
*** Supports authorization code or resource-owner credentials grants.
**** Users can log in to Moodle by clicking the identity provider on the login page, or by entering their OpenID Connect credentials.
**** Users can log in to Moodle by clicking the identity provider on the login page, or by entering their OpenID Connect credentials.
*** User profile field mapping
**** User profiles can be mapped and synced from IdP to Moodle.
*** Customizable Icon + Identity Provider name
*** Customizable Icon + Identity Provider name
**** The icon and identity provider name shown on the Moodle login page can be customized. A number of prechosen icons are available, as well as the ability to upload your own.
**** The icon and identity provider name shown on the Moodle login page can be customized. A number of prechosen icons are available, as well as the ability to upload your own.
Line 50: Line 52:
* '''Microsoft 365 support plugin''' (local_o365)
* '''Microsoft 365 support plugin''' (local_o365)
** This plugin provides most of the Microsoft 365 integration back-end. It provides shared code to communicate with Microsoft 365, and powers the calendar sync.
** This plugin provides most of the Microsoft 365 integration back-end. It provides shared code to communicate with Microsoft 365, and powers the calendar sync.
** Features
** Features:
*** Calendar sync from/to Outlook.
*** Calendar sync from/to Outlook.
**** Users can sync site events, course events, assignment due dates, and their personal Moodle calendar to their Outlook calendar.
**** Users can sync site events, course events, assignment due dates, and their personal Moodle calendar to their Outlook calendar.
*** User Sync and Matching
*** User Sync and Matching
**** Users can be synced from Azure AD, or matched with existing users.
**** Users can be synced from Azure AD, or matched with existing users.
*** Teams
*** Teams Integration
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
*** School Data Sync (SDS) Integration
**** You can connect your Moodle instance to a SharePoint subsite. Sites below this will be created for each course in your Moodle instance, and the document library from each course subsite is accessible through the OneDrive for Business repository. The course subsite document library is accessible by course teachers, serving as a place for teachers to share documents.
**** Moodle courses can be created from classes in SDS schools.
**** This feature is now deprecated. It is mainly used to provide shared document repositories for courses, which can now be accomplished by Teams.
Bidirectional sync between SDS class owners/members with Moodle course teachers/students.
* '''Microsoft Block''' (block_microsoft)
*'''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Microsoft 365 integration features, resources, and preferences.
** This block provides a user-facing menu to access various Microsoft 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Microsoft 365 integration user control panel.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Microsoft 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
*'''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
** Features:
*** Import files into Moodle from OneDrive for Business
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.
*** Embed documents into Moodle courses so users can view documents directly on the site.
 
*'''Microsoft 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
== Optional Plugins ==
== Optional Plugins ==
These 4 plugins provide support for OneNote assignment submission and feedback. While they are not required, they provide a powerful way to submit and review assignments.
These 3 plugins provide support for OneNote assignment submission and feedback. While they are not required, they provide a powerful way to submit and review assignments.
 
* '''Microsoft 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
Line 82: Line 82:
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.
** Allows students to submit assignments using OneNote.
== 3rd Party Plugins ==
== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [https://mix.office.com/ Office Mix] support for Moodle, allowing you to embed Office Mixes directly into any text within Moodle.
** Provides [https://mix.office.com/ Office Mix] support for Moodle, allowing you to embed Office Mixes directly into any text within Moodle.
= Resources =
= Resources =
Tooling and guidance on deploying Scalable Moodle Clusters on Azure
Tooling and guidance on deploying Scalable Moodle Clusters on Azure
* https://github.com/azure/moodle
* https://github.com/azure/moodle
= Setup =
= Setup =
== Installation ==
== Installation ==
The packages are available from:
The packages are available from:
* The [https://moodle.org/plugins/ Moodle Plugins directory]
* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Microsoft 365 Plugin Set]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Microsoft 365 Plugin Set]
* GitHub
* GitHub
** http://github.com/microsoft/o365-moodle
** http://github.com/microsoft/o365-moodle
When you log back in to your Moodle instance, you are presented with the all the plugin configuration options. Save the settings without configuring them for now, you will come back to them later.
When you log back in to your Moodle instance, you are presented with the all the plugin configuration options. Save the settings without configuring them for now, you will come back to them later.


For information on installing plugins in Moodle see [[Installing plugins]]
For information on installing plugins in Moodle see [[Installing plugins]]
 
== Configuration ==
== Configuration ==
After you have the code installed in your Moodle instance, you'll need to do a bit of setup before you can use the plugins.
After you have the code installed in your Moodle instance, you'll need to do a bit of setup before you can use the plugins.
=== Enable the OpenID Connect Authentication Plugin ===
=== Enable the OpenID Connect Authentication Plugin ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
# Verify the Authorization and Token endpoints.
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## These should be set by default to the following values:
## '''Token Endpoint:''' https://login.microsoftonline.com/common/oauth2/token
##* '''Authorization Endpoint''': <nowiki>https://login.microsoftonline.com/common/oauth2/authorize</nowiki>
# Note the Redirect URI. This should be the URI of your Moodle instance followed by /auth/oidc/. You will need to enter this value into Azure AD later, so note this value and put it aside.
##* '''Token Endpoint''': <nowiki>https://login.microsoftonline.com/common/oauth2/token</nowiki>
## For example, https://www.example.com/auth/oidc/
## It's also possible to replace the "common" part in the endpoints to be your tenant name or tenant GUID. By doing so, users who are redirected to Microsoft login pages (using the auth code login flow) will see the custom login page of your tenant if one is [https://docs.microsoft.com/en-us/microsoft-365/admin/setup/customize-sign-in-page?view=o365-worldwide configured following instructions]. e.g.
## Notes:
##* '''Authorization Endpoint''': <nowiki>https://login.microsoftonline.com/sample.onmicrosoft.com/oauth2/authorize</nowiki>
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any of the following reasons, you must change your Moodle site's configured domain name ($CFG->wwwroot).
##* '''Token Endpoint''': <nowiki>https://login.microsoftonline.com/sample.onmicrosoft.com/oauth2/token</nowiki>
### This URL must be a fully qualified domain name pointing to your Moodle instance.
## Note the endpoints may be in different format for B2C tenants. Please verify it in your Azure AD portal.
### If your Moodle installation is configured with an IP address pointing to your instance, you must change $CFG->wwwroot in your config.php to a fully-qualified domain name.
# Note the Redirect URI. This should be the URI of your Moodle instance followed by /auth/oidc/. You will need to enter this value into Azure portal later, so note this value and put it aside.
### This domain name does not need to be publicly accessible (i.e. internet-wide), but does need to be accessible to users of your Moodle instance. So, for example, you can use a intranet-only domain name.
#* For example, https://www.example.com/auth/oidc/
 
#* Notes:
#*# This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any reason, you must change your Moodle site's configured domain name ($CFG->wwwroot).
#*# This URI must be a fully qualified domain name pointing to your Moodle instance.
#*# The Moodle site's configured URL must use HTTPS, even with a self signed SSL cert. Redirect URI using HTTP will not be acceptable when creating Azure app for the integration.
#*# If your Moodle installation is configured with an IP address pointing to your instance, you must change $CFG->wwwroot in your config.php to a fully-qualified domain name.
#*# This domain name does not need to be publicly accessible (i.e. internet-wide), but does need to be accessible to users of your Moodle instance. So, for example, you can use a intranet-only domain name.
=== Prepare your Microsoft 365 account for single sign-on with your Moodle installation ===
=== Prepare your Microsoft 365 account for single sign-on with your Moodle installation ===
You will need an Azure subscription. If you do not have one, you can create one by visiting [http://azure.microsoft.com/en-us/pricing/free-trial/ Microsoft Azure Sign Up].
You will need an Azure subscription. If you do not have one, you can create one by visiting [http://azure.microsoft.com/en-us/pricing/free-trial/ Microsoft Azure Sign Up].
Line 131: Line 127:


'''Note''': During the setup, you are required to enter a credit card and phone number. If you do not setup virtual machines or use paid services on the subscription, and only use it to access the Azure Active Directory, you will not be charged for the subscription.
'''Note''': During the setup, you are required to enter a credit card and phone number. If you do not setup virtual machines or use paid services on the subscription, and only use it to access the Azure Active Directory, you will not be charged for the subscription.
=== Register Application in Azure (for auth_oidc and local_o365) ===
The easiest way to register application in Azure is to run the Windows PowerShell script downloaded from the plugin configuration page. Go to '''Site Administration > Plugins > Local plugins > Microsoft 365 Integration''', it's the '''Download PowerShell Script''' button in the '''Setup''' tab.


=== Register Application in Azure ===
Instructions on how to the PowerShell script to create Azure app using the downloaded file is available at https://github.com/microsoft/o365-moodle/blob/master/local/o365/scripts/README.md, or the /local/o365/scripts/README.md path of your Moodle installation.
The easiest way to register application in Azure is to run the PowerShell script downloaded from the plugin configuration page. Go to '''Site Administration > Plugins > Local plugins > Microsoft 365 Integration''', it's the '''Download PowerShell Script''' button in the '''Setup''' tab.


You should only follow the manual process if you are unable to setup the AzureAd app via PowerShell script, or you need to verify some specific settings.
You should only follow the manual process if you are unable to setup the AzureAd app via the Windows PowerShell script, or you need to verify some specific settings.


Note the PowerShell script doesn't work in PowerShell on non-Windows operating systems, because it uses features in .NET Framework but not in .NET Core. You will need to follow the manual steps.
==== Manual steps ====
==== Manual steps ====
The following steps are involved in the manual setup:
The following steps are involved in the manual setup:
Line 143: Line 141:
# Click '''New registration''' on the top menu.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# Choose option applicable to your organisation in '''Supported account types''' section.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.
===== Configure application =====
===== Configure application =====
# Locate the App.
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
#* If you followed steps above to create the Azure app, you should be redirected to the app settings page already.
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
#* Otherwise:
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
#*# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
#*# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the display name of the App to open its settings.
#*# Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
#*# Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
#*# Click on the display name of the App to open its settings.
# Enable implicit grant flow.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
Line 162: Line 161:
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Enter a description, and select a duration for "Expires".
## Click '''Add'''
## Click '''Add'''.
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need it later.
## A value will appear under '''Value''', note this value (write it down or copy it somewhere) and set it aside. You'll need it later.
# Expose an API - only required if Teams sync feature is used.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## Click the '''Set''' link next to '''Application ID URI'''.
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## This should open a '''Set the APP ID URI''' prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Replace this value with "api://'''URL.TO.MOODLE'''/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click '''Save''' to create the Application ID URI.
## Click "Add a scope".
## Click '''Add a scope'''.
## Enter "access_as_user" as scope name.
## Enter '''access_as_user''' as scope name.
## Set "Who can consent?" to "Admins and users".
## Set '''Who can consent?''' to '''Admins and users'''.
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set '''Admin consent title''' to '''Teams can access the user’s profile'''.
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set '''Admin consent description''' to '''Allows Teams to call the app’s web APIs as the current user'''.
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set '''User consent title''' to '''Teams can access the user profile and make requests on the user's behalf'''.
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Set '''User consent description''' to '''Enable Teams to call this app’s APIs with the same rights as the user'''.
## Ensure that "State" is set to "Enabled".
## Ensure that '''State''' is set to be '''Enabled'''.
## Select the "Add scope" button to save.
## Select the '''Add scope''' button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
## In the '''Authorized client applications''' section, identify the applications that you want to authorize for your app’s web application. Select '''Add a client application'''. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
##* '''<code>1fec8e78-bce4-4aaf-ab1b-5451cc387264</code>''' (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
##* '''<code>5e3ce6c0-2b1f-4285-8d4b-75ee78787346</code>''' (Teams web application)
# Configure App Permissions.
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose '''Microsoft Graph'''.
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## Click the checkbox for the following permissions in each of the '''Application''' and '''Delegated''' permissions sections according to the section below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
## After all the permissions are added, click the '''Grant admin consent for YOUR ORGANISATION NAME''' link.
{| class="nicetable"
## When you're done, click '''Add permissions''' at bottom of the page.
===== Azure app permissions =====
The integration uses various [https://docs.microsoft.com/en-us/graph/overview Microsoft Graph APIs] to communicate with Microsoft 365 to get and set data. Each Graph API would require a different set of permissions. The integration provides a list of recommended permissions to be given to ensure all features in the integration works, all of which are added automatically by the PowerShell script if it's used. Advanced users can customise the permissions according to the need of their own organisation, e.g. if group/team integration is not used, all permissions related to group can be removed, e.g. Group.ReadWrite.All.
====== Application permissions vs delegated permissions ======
The local_o365 supports two connection method - '''Application access''' and '''System API user'''. Application access connection method is recommended, and will be the only one supported in all new development from 2022.
 
The Azure app permissions required for the integration to work depend on the connection type. In general, if the Moodle site uses the '''Application access''' connection method, giving only application permissions would be enough; if the Moodle site uses the '''System API user''' connection method, only delegated permission are required.
 
Note the following exception when using '''Application access''' connection method.
*'''User.Read''' delegated permission is always required regardless of connection method.
*'''Notes.ReadWrite.All''' delegated permission is required for OneNote integration.
* '''Files.ReadWrite.All''' delegated permission is required for OneDrive integraiton.
* If teams integration feature is used, the following delegated permissions are required for teams SSO to work, regardless of connection method:
**'''openid'''
**'''offline_access'''
**'''email'''
**'''profile'''
====== Permissions ======
For a full list of Microsoft Graph API used, and the permissions required, please refer to [https://docs.google.com/spreadsheets/d/1XIFnnQ8RuFjlPGB8CiiMmK8x9Uta9XIR_icvAdx0G6k this spreadsheet]. Note that:
* This document is constantly updated.
* For each Graph API, a few permissions may be listed. Graph API can be called if permissions in any line is added, and the admin consent is granted for your organisation.
The recommended permissions to ensure all integration features work are listed below. These would be the same set of permissions that are applied when using the PowerShell script to set up the Azure app, with the exception of '''EduRoster.Read.All''' application permission, '''EduRoster.ReadWrite.All''' application permission, and '''EduRoster.ReadBasic''' delegated permissions that are used in the SDS sync feature, which need to be assigned manually.
{| class="wikitable"
|-
|-
! Type
! Type
! Permission
! Permission
! Display Name
! Display Name
!Connection Type
! Use
! Use
|-
|-
| rowspan="9" | Application Permissions
| rowspan="12" | Application Permissions
| '''Domain.ReadWrite.All'''
|'''Directory.ReadWrite.All'''
| '''Read and write domains'''
|'''Read and write directory data'''
| Required to automatically detect your Microsoft 365 tenant during setup.
|Application access
| A common permission used in both user syncs and group integration.
|-
|-
| '''User.ReadWrite.All'''
|'''Directory.Read.All'''
| '''Read and write all users' full profiles'''
|'''Read directory data'''
| Required to sync user information between Moodle and Microsoft 365.
|Application access
| A common permission used in both user syncs and group integration.
|-
|-
| '''Notes.ReadWrite.All'''
|'''Group.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
|'''Read and write all groups'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|Application access
| Required for course group/team integration.
|-
|-
| '''Group.ReadWrite.All'''
|'''User.Read.All'''
| '''Read and write all groups'''
|'''Read all users' full profiles'''
| Required for course group integration.
|Application access
| Required for SSO and to sync user information between Microsoft 365 and Moodle.
|-
|-
| '''Directory.Read.All'''
|'''Files.ReadWrite.All'''
| '''Read directory data'''
|'''Read and write files in all site collections'''
| Required for setup detection and verification.
|Application access
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
|-
| '''Calendars.ReadWrite'''
|'''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
|'''Read and write calendars in all mailboxes'''
|Application access
| Required for calendar event sync.
| Required for calendar event sync.
|-
|-
| '''Files.ReadWrite.All'''
|'''Sites.Read.All'''
| '''Read and write files in all site collections'''
|'''Read items in all site collections'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|Application access
|Required to detect OneDrive for Business URL setting.
|-
|'''Notes.ReadWrite.All'''
|'''Read and write all OneNote notebooks'''
|Application access
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
|-
|-
|-
| '''MailboxSettings.Read'''
|'''MailboxSettings.Read'''
| '''Read all user mailbox settings'''
|'''Read all user mailbox settings'''
|Application access
| Required for syncing Outlook default timezone settings of the user.
| Required for syncing Outlook default timezone settings of the user.
|-
|-
|-
|-
| '''MailboxSettings.ReadWrite'''
|'''AppRoleAssignment.ReadWrite.All'''
| '''Read and write all user mailbox settings'''
|'''Manage app permission grants and app role assignments'''
| Required for syncing Outlook default timezone settings of the user.
|Application access
| Required for assigning users to application during user sync if the option is enabled.
|-
|-
|'''EduRoster.Read.All'''
|'''Read the organization's roster'''
|Application access
|Required in the SDS sync feature to get information about schools, classes, and users.
|-
|-
|-
| rowspan="16" | Delegated Permissions
|'''Member.Read.Hidden'''
| '''Notes.ReadWrite.All'''
|'''Read all hidden memberships'''
| '''Read and write all OneNote notebooks that user can access'''
|Application access
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|Required in the SDS sync feature to get school class members.
|-
|-
| '''User.Read'''
| rowspan="17" |Delegated Permissions
| '''Sign-in and read user profile'''
|'''Directory.ReadWrite.All'''
| Required to sign users in using Microsoft 365, and to access Microsoft 365 APIs.
|'''Read and write directory data'''
|System API user
| A common permission used in both user syncs and group integration.
|-
|-
| '''User.ReadWrite.All'''
|'''Directory.Read.All'''
| '''Read and write all users' full profiles'''
|'''Read directory data'''
| Required to sync user information between Moodle and Microsoft 365.
|System API user
| A common permission used in both user syncs and group integration.
|-
|-
| '''Group.ReadWrite.All'''
|'''Group.ReadWrite.All'''
| '''Read and write all groups'''
|'''Read and write all groups'''
|System API user
| Required for course group integration.
| Required for course group integration.
|-
|-
| '''Directory.ReadWrite.All'''
|'''User.Read.All'''
| '''Read and write directory data'''
|'''Read all users' full profiles'''
| Required for setup detection and verification.
|System API user
|Required for SSO and to sync user information between Microsoft 365 and Moodle.
|-
|-
| '''Directory.AccessAsUser.All'''
|'''Files.ReadWrite.All'''
| '''Access directory as the signed in user'''
|'''Have full access to all files user can access'''
| Required to access Microsoft 365 APIs.
|Application access and system API user
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
|-
| '''Calendars.ReadWrite'''
|'''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
|'''Have full access to user calendars'''
|System API user
| Required for calendar event sync.
| Required for calendar event sync.
|-
|-
| '''Files.ReadWrite'''
|'''Sites.Read.All'''
| '''Have full access to user files'''
|'''Read items in all site collections'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|System API user
| Required for SharePoint integration (deprecated)
|-
|'''Notes.ReadWrite.All'''
|'''Read and write all OneNote notebooks that user can access'''
|Application access and system API user
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
|-
| '''Sites.Read.All'''
|'''AppRoleAssignment.ReadWrite.All'''
| '''Read items in all site collections'''
|'''Manage app permission grants and app role assignments'''
| Required for SharePoint integration (deprecated)
|System API user
|Required for assigning users to application during user sync if the option is enabled.
|-
|-
| '''MailboxSettings.Read'''
|'''MailboxSettings.Read'''
| '''Read user mailbox settings'''
|'''Read user mailbox settings'''
|System API user
| Required for syncing Outlook default timezone settings of the user.
| Required for syncing Outlook default timezone settings of the user.
|-
|-
| '''MailboxSettings.ReadWrite'''
|'''User.Read'''
| '''Read and write user mailbox settings'''
|'''Sign-in and read user profile'''
| Required for syncing Outlook default timezone settings of the user.
|Application access and system API user
| Required to sign users in using Microsoft 365, and to access Microsoft 365 APIs.
|-
|-
| '''openid'''
|'''openid'''
| '''Sign users in'''
|'''Sign users in'''
| Required to sign users in using Microsoft 365 (required for all integration).
|Application access and system API user
| Required for Teams SSO.
|-
|-
| '''offline_access'''
|'''offline_access'''
| '''Maintain access to data you have given it access to'''
|'''Maintain access to data you have given it access to'''
|Application access and system API user
| Required for Teams SSO.
| Required for Teams SSO.
|-
|-
| '''email'''
|'''email'''
| '''View users' email address'''
|'''View users' email address'''
|Application access and system API user
| Required for Teams SSO.
| Required for Teams SSO.
|-
|-
| '''profile'''
|'''profile'''
| '''View users' basic profile'''
|'''View users' basic profile'''
|Application access and system API user
| Required for Teams SSO.
| Required for Teams SSO.
|-
|'''EduRoster.ReadBasic'''
|'''Read a limited subset of users' view of the roster'''
|System API user
|Required in the SDS sync feature to get information about schools, classes and users.
|}
|}
When you're done, click '''Add permissions''' at bottom of the page.
=== Enter Azure application credentials into Moodle ===
=== Enter Azure application credentials into Moodle ===
# Navigate to the OpenID Connect authentication plugin's settings page (Site Administration > Plugins > Authentication > OpenID Connect)
# Navigate to the OpenID Connect authentication plugin's settings page (Site Administration > Plugins > Authentication > OpenID Connect)
Line 303: Line 369:
# Enter the '''Key''' value you noted earlier from Azure into the "Key" box on the screen.
# Enter the '''Key''' value you noted earlier from Azure into the "Key" box on the screen.
# Click "Save changes" at the bottom of the screen.
# Click "Save changes" at the bottom of the screen.
=== Configure the Microsoft 365 support plugin ===
=== Configure the Microsoft 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft 365 Integration'''
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft 365 Integration'''
Line 318: Line 383:
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.
== Connecting users to Microsoft 365 ==
== Connecting users to Microsoft 365 ==
To use any Microsoft 365 features, a Moodle user must be connected to a Microsoft 365 user that has an active Microsoft 365 subscription. There are two ways to connect a Moodle user to a Microsoft 365 user.
To use any Microsoft 365 features, a Moodle user must be connected to a Microsoft 365 user that has an active Microsoft 365 subscription. There are two ways to connect a Moodle user to a Microsoft 365 user.
 
=== Switch the user to use OpenID Connect authentication. ===
=== Switch the user to use OpenID Connect authentication ===
With this method, the user will log in to Moodle using their Microsoft 365 account credentials.
With this method, the user will log in to Moodle using their Microsoft 365 account credentials.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].
 
=== Link a Moodle user to a Microsoft 365 user. ===
=== Link a Moodle user to a Microsoft 365 user===
Users in Moodle can also be linked to Microsoft 365 users without changing the Moodle user's authentication method. Users will be able to log in as they always have, and still use all the Microsoft 365 features.
Users in Moodle can also be linked to Microsoft 365 users without changing the Moodle user's authentication method. Users will be able to log in as they always have, and still use all the Microsoft 365 features.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
Line 337: Line 399:
# If login was successful, you will be brought back to the '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# If login was successful, you will be brought back to the '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# This user is now connected to the Microsoft 365 user.
# This user is now connected to the Microsoft 365 user.
= Microsoft 365 Integration Local Plugin =
= Microsoft 365 Integration Local Plugin =
== Sync Settings ==
== Sync Settings ==
These features are accessible from the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft 365 Integration), on the '''Sync Settings''' tab.
These features are accessible from the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft 365 Integration), on the '''Sync Settings''' tab.
=== User Sync ===
=== User Sync ===
This option controls how users are synced from Azure AD to Moodle. If enabled, users from Azure AD can be automatically created in Moodle. This feature can also delete users in Moodle when they are deleted from Azure AD, or attempt to automatically match Moodle users with users in the connected Azure AD.
This option controls how users are synced from Azure AD to Moodle. If enabled, users from Azure AD can be automatically created in Moodle. This feature can also delete users in Moodle when they are deleted from Azure AD, or attempt to automatically match Moodle users with users in the connected Azure AD.
Line 351: Line 411:
* By default, this runs once per day at 1:00 AM in the time zone local to your server.
* By default, this runs once per day at 1:00 AM in the time zone local to your server.
* To sync large sets of users more quickly, you can increase the freqency of the Sync users with Azure AD task using the Scheduled tasks management page. See [[Scheduled_tasks]].
* To sync large sets of users more quickly, you can increase the freqency of the Sync users with Azure AD task using the Scheduled tasks management page. See [[Scheduled_tasks]].
There are several options that affect user sync:
There are several options that affect user sync:
* '''Create accounts in Moodle for users in Azure AD''': This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their Microsoft 365 credentials to log in to Moodle (using the OpenID Connect authentication plugin), and will be able to use all the features of the Microsoft 365 plugin set.
* '''Create accounts in Moodle for users in Azure AD''': This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their Microsoft 365 credentials to log in to Moodle (using the OpenID Connect authentication plugin), and will be able to use all the features of the Microsoft 365 plugin set.
Line 363: Line 422:
* '''Perform a full sync each run''': By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
* '''Perform a full sync each run''': By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
* '''Match Azure usernames to Moodle emails instead of Moodle usernames during the sync''': Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.
* '''Match Azure usernames to Moodle emails instead of Moodle usernames during the sync''': Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.
====User Creation Restriction====
====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".  
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".  
====User Field Mapping====
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.  
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
To create mappings:
# Click "Add Mapping"
# Click "Add Mapping"
Line 374: Line 432:
# In the third column on the same row, choose whether this only happens on user creation, on user login, or both.
# In the third column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.
# Click "Save Changes" at the bottom of the page.
To Delete A Mapping
To Delete A Mapping
# Click the "X" button at the end of the row you want to delete.  
# Click the "X" button at the end of the row you want to delete.  
# Click "Save changes" at the bottom of the page.
# Click "Save changes" at the bottom of the page.
# Note this will only prevent future information syncing, it will not undo past operations.
# Note this will only prevent future information syncing, it will not undo past operations.
=== Teams Sync ===
=== Teams Sync ===
The Teams sync setting creates teams in Microsoft Teams for courses in Moodle. Teams creation effectively results in team members being added to a Microsoft 365 group, enabling all group features to be usable.
The Teams sync setting creates teams in Microsoft Teams for courses in Moodle. Teams creation effectively results in team members being added to a Microsoft 365 group, enabling all group features to be usable.


Features:
Features:
Line 387: Line 443:
* Provides an easy way to address all users in a course from Microsoft 365. For example, a teacher can share a document from OneDrive with all of their students by choosing the user group, i.e. Teams members, for their course - they don't have to choose each student individually.
* Provides an easy way to address all users in a course from Microsoft 365. For example, a teacher can share a document from OneDrive with all of their students by choosing the user group, i.e. Teams members, for their course - they don't have to choose each student individually.
* Course group file stores are accessible from the Microsoft 365 Moodle file repository plugin, allowing users to access group files from Moodle.
* Course group file stores are accessible from the Microsoft 365 Moodle file repository plugin, allowing users to access group files from Moodle.
The Teams sync option allows a great deal of customization. An administrator can choose to create Teams for all courses, and enable all settings, or customize the implementation. If administrators choose the "Customize" option for this setting, administrators can choose which courses have Teams created, and choose which features are enabled for each course.
The Teams sync option allows a great deal of customization. An administrator can choose to create Teams for all courses, and enable all settings, or customize the implementation. If administrators choose the "Customize" option for this setting, administrators can choose which courses have Teams created, and choose which features are enabled for each course.


Once enabled, new Teams will be created every cron run for any enabled course that doesn't have a team set up. Once Teams are set up, membership will be maintained automatically whenever someone joins or leaves a Moodle course.
Once enabled, new Teams will be created every cron run for any enabled course that doesn't have a team set up. Once Teams are set up, membership will be maintained automatically whenever someone joins or leaves a Moodle course.
==== Teams vs Group ====
==== Teams vs Group ====
Microsoft Teams share the same base with Microsoft 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
Microsoft Teams share the same base with Microsoft 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to a Microsoft 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has at least one teacher who can be matched to a Microsoft 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Microsoft 365 user, only a group will be created.
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Microsoft 365 user, only a group will be created.
== Advanced settings ==
== Advanced settings ==
=== Administrator Tools ===
=== Administrator Tools ===
Line 404: Line 457:
* '''User Matching''': This tool allows administrators to manually match Moodle and Microsoft 365 users using a CSV file. Administrators can upload a CSV file containing, on each line, a Moodle username, and Microsoft 365 username, and a 1 or 0 indicating whether to enable Microsoft 365 login for that user. Once uploaded, the file is processed in batches during the Moodle cron. The tool page will display the progress of this process.
* '''User Matching''': This tool allows administrators to manually match Moodle and Microsoft 365 users using a CSV file. Administrators can upload a CSV file containing, on each line, a Moodle username, and Microsoft 365 username, and a 1 or 0 indicating whether to enable Microsoft 365 login for that user. Once uploaded, the file is processed in batches during the Moodle cron. The tool page will display the progress of this process.
* '''Maintenance Tools''': These tools perform maintenance tasks that can help solve problems which may crop up from time to time. Generally, users should not need these tools unless they encounter the specific situation these tools are designed to solve.
* '''Maintenance Tools''': These tools perform maintenance tasks that can help solve problems which may crop up from time to time. Generally, users should not need these tools unless they encounter the specific situation these tools are designed to solve.
** '''Resync users in groups for courses''': Course group membership is kept up-to-date as users are enrolled and un-enrolled from courses in Moodle. If this membership gets out-of-date for whatever reason, this tool will force a resync of group membership.
**'''Resync users in groups for courses''': Course group membership is kept up-to-date as users are enrolled and un-enrolled from courses in Moodle. If this membership gets out-of-date for whatever reason, this tool will force a resync of group membership.
** '''Recreate deleted Microsoft 365 groups''': Course groups are created from Moodle courses when using the course group feature. If a group is manually deleted from the Microsoft 365 administrator panel, this tool will recreate it.
** '''Recreate deleted Microsoft 365 groups''': Course groups are created from Moodle courses when using the course group feature. If a group is manually deleted from the Microsoft 365 administrator panel, this tool will recreate it.
** '''Generate debug data package''': This tool will generate a package of information that can be sent to the plugin suite maintainers to help debug problems in environment and setup. While no API keys are present, this information does contain a lot about your environment and setup, so please be careful about who you send this information to.
** '''Generate debug data package''': This tool will generate a package of information that can be sent to the plugin suite maintainers to help debug problems in environment and setup. While no API keys are present, this information does contain a lot about your environment and setup, so please be careful about who you send this information to.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Microsoft 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Microsoft 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.
===Other advanced settings===
===Other advanced settings===
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Microsoft 365 as well.
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Microsoft 365 as well.
Line 417: Line 469:
* '''Profile photo refresh time''': Profile photo syncing can be a resource-intensive process, so this setting allows you to set a minimum time between profile photo refresh runs.
* '''Profile photo refresh time''': Profile photo syncing can be a resource-intensive process, so this setting allows you to set a minimum time between profile photo refresh runs.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.
===Legacy settings===
===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''
'''These features are deprecated and is likely to be removed in a future version.'''
===Preview features===
===Preview features===
From time-to-time, we add features that use brand-new APIs or are slightly experimental in some way. These features often become part of our regular feature offering once they mature, but if you want to see the latest features we're working on, you can enable this setting to enable all preview features. Be careful though! These features do break from time to time.
From time-to-time, we add features that use brand-new APIs or are slightly experimental in some way. These features often become part of our regular feature offering once they mature, but if you want to see the latest features we're working on, you can enable this setting to enable all preview features. Be careful though! These features do break from time to time.
 
== School Data Sync (SDS) ==
The SDS feature of the plugin has the following functionalities:
* Sync teacher / student profile field from a selected SDS school.
* Sync classes from multiple SDS schools, and create Moodle courses from the classes.
* Sync class owners and members to Moodle courses as teachers and students according to the configured roles.
* Sync user enrolments and role changes in Moodle back to the connected SDS classes.
=== Settings ===
The settings applicable to the SDS feature are:
* '''Create Courses''': Allow selecting the schools available in the Azure tenant which need to be synced for course creation. Multiple schools can be selected. For each school selected, a new top level course category will be created, and each class in the school will be created as a course in the category.
* '''Teams creation enabled''': This controls if Moodle courses created from syncing SDS classes are automatically connected to the Microsoft Team of the SDS class. This should be enabled only if Teams are automatically created from the SDS classes.
* '''Enrol users''': Enrol SDS class teachers and members into Moodle courses created from the classes.
* '''Advanced enrolments sync with SDS classes''': Control whether to sync SDS class role changes to Moodle, and whether to sync Moodle course enrolment / role changes back to SDS class.
* '''Teacher role''' and '''Member role''': Control the default teacher and student roles to assign in Moodle courses for SDS class owners and members.
* '''Sync profile data from school''': Control the SDS school from which teacher and student profiles are synced from. If a school is selected, the teacher / student profile fields are available to match in auth_oidc profile field mapping settings.
=== Sync triggers ===
* Course and SDS user profile sync is triggered by the '''Sync with SDS''' (\local_o365\feature\sds\task\sync) scheduled task. Note this includes the sync of SDS teacher and student profile field, which is configured in auth_oidc.
* Sync from Moodle to SDS (e.g. course enrolments and role changes to SDS class) are triggered by Moodle observer functions, thus don't require scheduled task runs. Note there is normally a delay of up to 1 minute on Microsoft end to see such changes.
==Teams Settings==
==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
Line 433: Line 499:
* Forward all Moodle notifications to users to Teams.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.
Some features can be disabled if needed.
===Prerequisite===
===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''OpenID Connect Authentication''' plugin is enabled and configured.
Line 457: Line 522:
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.
## Save changes.
 
# Before you can test the messaging bot, you need to be sure that the MS Teams account has a user created in Moodle (user should have the same username as your teams user email address and Moodle user authentication type should be oidc) and you must have accessed Moodle at least once with that account.
=== Register Application in Azure ===
=== Register Application in Azure (for the bot) ===
Note this is different from the application registered above to allow user login integration.
Note this is different from the application registered above to allow user login integration and doesn't require any extra API permissions.  
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Enter a name for your application (can be anything you want, but should let you know this is for bot services).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Choose "Accounts in any organizational directory (Any Azure AD directory - Multitenant)" option in '''Supported account types''' section (multitenant application is required).
# Click '''Register''' button to finish registration.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
Line 471: Line 536:
# In '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# In '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.
# Save changes.
=== Update authentication application settings in Azure ===
=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
Line 484: Line 548:
## https://token.botframework.com/.auth/web/redirect
## https://token.botframework.com/.auth/web/redirect
# Save changes.
# Save changes.
=== Bot configuration ===
=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
Line 498: Line 561:
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## ''Moodle URL'''.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
Line 505: Line 568:
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.
==== Post deployment configuration====
==== Post deployment configuration====
After bot deployment is finished:
After bot deployment is finished:
Line 516: Line 578:
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Save changes.
# Save changes.
=== Add Moodle app to Teams ===
=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
Once all configured, you are ready to add Moodle app to Teams.
Line 523: Line 584:
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.
== Teams Moodle app settings==
== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
Line 529: Line 589:
* automatically create a Moodle tab in the '''General''' channel.
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.
To configure the field, follow these steps:
To configure the field, follow these steps:
# Log in Teams, and go to app catalog by clicking the '''Apps''' button from the navigation bar on the left.
# Log in Teams, and go to app catalog by clicking the '''Apps''' button from the navigation bar on the left.
Line 539: Line 598:
# Paste the app ID in the '''Moodle app ID''' setting on '''Teams Moodle app''' tab of '''Microsoft 365 Integration''' configuration page in Moodle.
# Paste the app ID in the '''Moodle app ID''' setting on '''Teams Moodle app''' tab of '''Microsoft 365 Integration''' configuration page in Moodle.
# Save changes.
# Save changes.
= OpenID Connect Authentication Plugin =
= OpenID Connect Authentication Plugin =
== Basic Usage ==
== Basic Usage ==
Line 545: Line 603:


Note: If the "Prevent account creation when authenticating" setting is enabled in Moodle, new accounts will not be created.
Note: If the "Prevent account creation when authenticating" setting is enabled in Moodle, new accounts will not be created.
== Settings ==
== Settings ==
There are a number of options you can use to customize how the plugin behaves. To configure the plugin, visit the plugin's settings page. (Site Administration > Plugins > Authentication > OpenID Connect)
There are a number of options you can use to customize how the plugin behaves. To configure the plugin, visit the plugin's settings page. (Site Administration > Plugins > Authentication > OpenID Connect)
====Provider Name====
====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the Microsoft 365 plugins to refer to the system used to log users in. For example, if your users are used to calling their Azure AD account their "School" account, you enter "School account" here, and all references to authentication will be "Log in with your School account".
The name entered here will be used through the OpenID Connect plugin and the Microsoft 365 plugins to refer to the system used to log users in. For example, if your users are used to calling their Azure AD account their "School" account, you enter "School account" here, and all references to authentication will be "Log in with your School account".
====Auto-Append====
====Auto-Append====
When using the "Username/Password" login flow, this setting with automatically append a given string to an entered username. This is useful in Azure AD usernames, where a single domain name is often used for every user - i.e. [user]@contoso.onmicrosoft.com. Users would normally have to enter this entire username to successfully log in to Moodle, but in this example, entering "@contoso.onmicrosoft.com" here means users would only have to enter their unique username, i.e. "bob.smith", instead of "bob.smith@contoso.onmicrosoft.com".
When using the "Username/Password" login flow, this setting with automatically append a given string to an entered username. This is useful in Azure AD usernames, where a single domain name is often used for every user - i.e. [user]@contoso.onmicrosoft.com. Users would normally have to enter this entire username to successfully log in to Moodle, but in this example, entering "@contoso.onmicrosoft.com" here means users would only have to enter their unique username, i.e. "bob.smith", instead of "bob.smith@contoso.onmicrosoft.com".
====Domain Hint====
====Domain Hint====
If users have several different Azure AD accounts with different tenants (i.e. @contoso.onmicrosoft.com, @example.onmicrosoft.com), but Moodle only uses one of these tenants, you can enter that tenant in this box to have the Azure AD login screen only ever suggest accounts from that tenant.
If users have several different Azure AD accounts with different tenants (i.e. @contoso.onmicrosoft.com, @example.onmicrosoft.com), but Moodle only uses one of these tenants, you can enter that tenant in this box to have the Azure AD login screen only ever suggest accounts from that tenant.
====Login Flow====
====Login Flow====
This setting changes how users log in to Moodle using the plugin. You can redirect users to the OpenID Connect provider's login page, or have users enter their credentials directly into Moodle. See the "Login Flows" section below for further information.
This setting changes how users log in to Moodle using the plugin. You can redirect users to the OpenID Connect provider's login page, or have users enter their credentials directly into Moodle. See the "Login Flows" section below for further information.
====User Restrictions====
====User Restrictions====
This setting allows you to restrict the users that can log in to Moodle using OpenID Connect (Azure AD).
This setting allows you to restrict the users that can log in to Moodle using OpenID Connect (Azure AD).
Line 573: Line 625:
# If you don't enter any restrictions above, all users that can log in to the OpenID Connect provider will be accepted by Moodle.
# If you don't enter any restrictions above, all users that can log in to the OpenID Connect provider will be accepted by Moodle.
# Any user that does not match any entered pattern(s) will be prevented from logging in using OpenID Connect.
# Any user that does not match any entered pattern(s) will be prevented from logging in using OpenID Connect.
====Record debug messages====
====Record debug messages====
If you experience problems using OpenID Connect, enable this setting. Once enabled, errors will be recorded to the Moodle log for review. These errors can help you or the plugin developers debug and fix the problem. The error log can be viewed by navigating to Site Administation > Reports > Logs, changing the "All activities" select box to "Site errors", and clicking "Get these logs".
If you experience problems using OpenID Connect, enable this setting. Once enabled, errors will be recorded to the Moodle log for review. These errors can help you or the plugin developers debug and fix the problem. The error log can be viewed by navigating to Site Administation > Reports > Logs, changing the "All activities" select box to "Site errors", and clicking "Get these logs".
====Custom Icon====
====Custom Icon====
This setting allows you to choose from a selection of predefined icons to appear next to the identity provider link on the login page. You can also upload your own icon.
This setting allows you to choose from a selection of predefined icons to appear next to the identity provider link on the login page. You can also upload your own icon.
# Visit the plugin settings page (Site Administration > Plugins > Authentication > OpenID Connect)
# Visit the plugin settings page (Site Administration > Plugins > Authentication > OpenID Connect)
# Locate the "Icon" section of the settings page.
# Locate the "Icon" section of the settings page.
Line 586: Line 635:
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.
== Login flows ==
== Login flows ==
This plugin supports two different methods for users to log in: Authorization Request and Username/Password Authentication
This plugin supports two different methods for users to log in: Authorization Request and Username/Password Authentication
=== Authorization Request ===
=== Authorization Request ===
This flow redirects the user to Microsoft 365 to log in and are then brought back to Moodle logged in.
This flow redirects the user to Microsoft 365 to log in and are then brought back to Moodle logged in.
Line 597: Line 644:
# The user is redirected to Microsoft 365 to log in.
# The user is redirected to Microsoft 365 to log in.
# Once successfully logged in, the user is redirected back to Moodle where the Moodle login takes place transparently.
# Once successfully logged in, the user is redirected back to Moodle where the Moodle login takes place transparently.
=== Username/Password Authentication ===
=== Username/Password Authentication ===
This login flow works like a classic username and password, except the user uses their Microsoft 365 account information.
This login flow works like a classic username and password, except the user uses their Microsoft 365 account information.
Line 605: Line 651:
# Their credentials are securely sent to Microsoft 365 for verification.
# Their credentials are securely sent to Microsoft 365 for verification.
# If the credentials are verified, the user is logged in to Moodle.
# If the credentials are verified, the user is logged in to Moodle.
== Switching existing Moodle users to use Microsoft 365 to log in ==
== Switching existing Moodle users to use Microsoft 365 to log in ==
If a user logs in to Moodle using OpenID Connect but does not have a Moodle account, one will be created for them. However, existing Moodle users can be migrated to use OpenID Connect and provide a connection to Microsoft 365.
If a user logs in to Moodle using OpenID Connect but does not have a Moodle account, one will be created for them. However, existing Moodle users can be migrated to use OpenID Connect and provide a connection to Microsoft 365.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
Line 619: Line 663:
# The Moodle account will now use Microsoft 365 to log in. '''The previous login method will not work.'''
# The Moodle account will now use Microsoft 365 to log in. '''The previous login method will not work.'''
# The Moodle user can now use any of the Microsoft 365 features in Moodle.
# The Moodle user can now use any of the Microsoft 365 features in Moodle.
== Connecting existing Moodle users to Microsoft 365 without changing login method ==
== Connecting existing Moodle users to Microsoft 365 without changing login method ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
Line 631: Line 674:
# The Moodle account is now linked to the Microsoft 365 account and can use Microsoft 365 features as that user.
# The Moodle account is now linked to the Microsoft 365 account and can use Microsoft 365 features as that user.
# The Moodle user's login method will not change, the user will log in to Moodle as they always have.
# The Moodle user's login method will not change, the user will log in to Moodle as they always have.
= OneDrive for Business Repository =
= OneDrive for Business Repository =
The OneDrive for Business repository allows users using the Microsoft 365 integration plugins to connect to their OneDrive for Business as a Moodle repository.
The OneDrive for Business repository allows users using the Microsoft 365 integration plugins to connect to their OneDrive for Business as a Moodle repository.
== Downloading and linking files ==
== Downloading and linking files ==
# When using a filepicker anywhere in Moodle, you'll see a list of repositories on the left side of the popup. Look for and click on "OneDrive for Business".
# When using a filepicker anywhere in Moodle, you'll see a list of repositories on the left side of the popup. Look for and click on "OneDrive for Business".
Line 647: Line 688:
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".
# Click "Select this file".
== Uploading files ==
== Uploading files ==
You can upload files into both your personal OneDrive for Business document library and a course SharePoint document library from the filepicker interface.
You can upload files into both your personal OneDrive for Business document library and a course SharePoint document library from the filepicker interface.
# When accessing a OneDrive document library from a file picker, you will see an "Upload New File" item in the list of files and folders.
# When accessing a OneDrive document library from a file picker, you will see an "Upload New File" item in the list of files and folders.
# Click the "Upload new file" item.
# Click the "Upload new file" item.
# Choose the file you want to upload and click "Upload this file".
# Choose the file you want to upload and click "Upload this file".
# The file will be uploaded to OneDrive and selected for the file picker.
# The file will be uploaded to OneDrive and selected for the file picker.
== Embedding Office documents ==
== Embedding Office documents ==
This repository allows users to embed Office documents from OneDrive into a course and have the live version viewable using Office web apps.
This repository allows users to embed Office documents from OneDrive into a course and have the live version viewable using Office web apps.
# Start as a user connected to Microsoft 365 and who has access to modify a course.
# Start as a user connected to Microsoft 365 and who has access to modify a course.
# Turn on editing for the course and choose "Add an activity or resource" for the section of the course you want to add the document.
# Turn on editing for the course and choose "Add an activity or resource" for the section of the course you want to add the document.
Line 668: Line 705:
# Click "Save and display"
# Click "Save and display"
# You should see the file embedded into the page.
# You should see the file embedded into the page.
= OneNote =
= OneNote =
OneNote is now available through Microsoft 365. If you have installed all the plugins (for example, by installing [https://moodle.org/plugins/view/local_office365]) then you already have the OneNote plugins installed. To access OneNote using your Microsoft 365 subscription, add OneNote to the list of applications in your Azure application. This is done the same way you configured Azure permissions, above. Note that OneNote is still in preview, and may not be available to everyone yet. If you don't see OneNote in the list of applications to add to your Azure application, you can try logging in to a desktop OneNote application using an administrator account in your Microsoft 365 tenant. This sometimes expedites to the process of adding the OneNote preview to your tenant.  
OneNote is now available through Microsoft 365. If you have installed all the plugins (for example, by installing [https://moodle.org/plugins/view/local_office365]) then you already have the OneNote plugins installed. To access OneNote using your Microsoft 365 subscription, add OneNote to the list of applications in your Azure application. This is done the same way you configured Azure permissions, above. Note that OneNote is still in preview, and may not be available to everyone yet. If you don't see OneNote in the list of applications to add to your Azure application, you can try logging in to a desktop OneNote application using an administrator account in your Microsoft 365 tenant. This sometimes expedites to the process of adding the OneNote preview to your tenant.  
= Notes on special release =
= Notes on special release =
== 3.8.0.4 and 3.9.1 release==
== 3.8.0.4 and 3.9.1 release==
3.8.0.4 and 3.9.1 release of the plugins on 29 September 2020 introduced improvements on SSO integration for Moodle in Teams as well as Single Sign Off support, but requires additional actions from Moodle and Azure admins.
3.8.0.4 and 3.9.1 release of the plugins on 29 September 2020 introduced improvements on SSO integration for Moodle in Teams as well as Single Sign Off support, but requires additional actions from Moodle and Azure admins.
=== Moodle and Teams SSO integration ===
=== Moodle and Teams SSO integration ===
The new releases is capable of getting a user token from either Teams desktop/mobile app or Teams web app, and attempt to log in as the user in the Moodle Teams tab. In order for it to work, changes in 3 sections are required.
The new releases is capable of getting a user token from either Teams desktop/mobile app or Teams web app, and attempt to log in as the user in the Moodle Teams tab. In order for it to work, changes in 3 sections are required.
==== Update Azure app settings ====
==== Update Azure app settings ====
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
Line 707: Line 740:
## ID Token
## ID Token
## Access Token.
## Access Token.
==== Download updated manifest file ====
==== Download updated manifest file ====
# Login to Moodle as site administrator.
# Login to Moodle as site administrator.
Line 723: Line 755:
# Select the new manifest file downloaded from Moodle.
# Select the new manifest file downloaded from Moodle.
Note that as long as the '''Microsoft app ID for the Moodle Teams app''' setting is not changed, this should be recognised as an app upgrade, rather than uploading a new app. This means that the app will be kept in all existing Teams that have it installed, and all existing Moodle tabs will keep working.
Note that as long as the '''Microsoft app ID for the Moodle Teams app''' setting is not changed, this should be recognised as an app upgrade, rather than uploading a new app. This means that the app will be kept in all existing Teams that have it installed, and all existing Moodle tabs will keep working.
==== Known limitations ====
It is a known issue that if a Microsoft 365 user has never login to Moodle either, her first attempt to SSO from Teams to Moodle will not work silently. Instead, the user will need to click a button from the prompt to login.
=== Single Sign Off ===
=== Single Sign Off ===
When a Microsoft 365 authenticated user clicks the Moodle log out button, it is possible to log the user out from Microsoft 365 at the same time.
When a Microsoft 365 authenticated user clicks the Moodle log out button, it is possible to log the user out from Microsoft 365 at the same time.


In order for this to work, configuration changes in two places are required:
In order for this to work, configuration changes in two places are required:
==== Moodle settings change ====  
==== Moodle settings change ====
# Sign in Moodle as site admin.
# Sign in Moodle as site admin.
# Go to "OpenID Connect" settings page under Plugins - Authentication:
# Go to "OpenID Connect" settings page under Plugins - Authentication:
# Go to "Advanced" tab.
# Enable "Single sign off".
# Enable "Single sign off".
# Save changes.
# Save changes.
Line 741: Line 770:
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the root URL of your Moodle site (wwwroot) as an entry.
# In the list of '''Redirect URIs''', add the root URL of your Moodle site (wwwroot) as an entry.
== 3.8.0.5 and 3.9.2 release==
== 3.8.0.5 and 3.9.2 release==
3.8.0.5 and 3.9.2 release of the plugins on 18 November 2020 added support for synching the default timezone preference of the user in Outlook to Moodle. This requires the following permission to be granted for the Azure app:
3.8.0.5 and 3.9.2 release of the plugins on 18 November 2020 added support for synching the default timezone preference of the user in Outlook to Moodle. This requires the following permissions to be granted for the Azure app.
# '''Delegated permissions'''
* If your Moodle site uses '''Application access''' connection method, you will need to add and grant '''MailboxSettings.Read application permission'''.
## '''MailboxSettings.Read'''
* If your Moodle site uses '''System API User''' connection method, you will need to add and grant '''MailboxSettings.Read delegated permission'''.
## '''MailboxSettings.ReadWrite'''
== 3.9.8, 3.10.5 and 3.11.2 release ==
# '''Application permissions'''
3.9.8, 3.10.5 and 3.11.2 release of the plugins on 07 December 2021 updated the implementation of SDS feature, and updated it to use Microsoft Graph APIs instead of legacy APIs. As a result, additional permissions are required for the feature to work properly.
## '''MailboxSettings.Read'''
* If your Moodle site uses '''Application access''' connection method, you will need to add and grant '''EduRoster.Read.All''' and '''Member.Read.Hidden application permissions'''.
## '''MailboxSettings.ReadWrite'''
* If your Moodle site uses '''System API User''' connection method, you will need to add and grant '''EduRoster.ReadBasic delegated permission'''.
= Teams integration known limitations =
* If the Moodle site is not publicly accessible, e.g. on a intranet, Moodle tabs will not work in Teams desktop and mobile apps. They will only work in web apps from browser.


* It is a known issue that if a Microsoft 365 user has never login to Moodle ever, the first attempt of the user to SSO from Teams to Moodle will not work silently. Instead, the user will need to click a button from the prompt to login.
=Any further questions?=
=Any further questions?=
For support, please open an issue on Github at [https://github.com/Microsoft/o365-moodle/issues]
For support, please open an issue on Github at [https://github.com/Microsoft/o365-moodle/issues]


For community discussion, please post in the [https://moodle.org/mod/forum/view.php?id=8273 Moodle office tool integrations forum] on moodle.org. Note: developers may or may not see questions in this forum thread.
For community discussion, please post in the [https://moodle.org/mod/forum/view.php?id=8273 Moodle office tool integrations forum] on moodle.org. Note: developers may or may not see questions in this forum thread.

Latest revision as of 15:20, 18 July 2022

Note: OAuth 2 authentication (enabling users to log in to Moodle with their Microsoft account) and the OneDrive repository are included in the standard Moodle, so require no additional plugins to be installed.

Introduction

Microsoft 365 services complement the Moodle learning platform to provide a more productive experience for teachers and students.

Differences from Moodle Core

Although Moodle core now provides Microsoft 365 authentication and basic OneDrive repository support, the Microsoft 365 plugin suite provides a much wider set of features.

A few key features only found in the Microsoft 365 plugin suite:

  • User sync from Microsoft 365/Azure AD to Moodle
  • Automatic and manual user matching from Microsoft 365/Azure AD to Moodle
  • Calendar sync
  • Course to Microsoft 365 group/teams sync and shared file repositories
  • OneNote assignment submission and feedback types
  • Office document embedding using Office web apps
  • Fully customisable sign-in experience
  • Integration between Moodle courses and Microsoft Teams
  • Integration with School Data Sync (SDS)

Requirements

To use the Microsoft 365 plugins, you need the following:

  • A Microsoft 365 subscription.
  • A Microsoft Azure subscription.
  • Moodle version 3.5 or above. The plugins are available for Moodle versions 2.7 and above. Features available in each version, and the support status vary.

Plugins & Features

The Microsoft 365 set of plugins contains 6 core plugins, and 3 optional plugins, which provide a wide variety of features to enhance your Moodle instance.

  • Microsoft 365 Local Plugin (local_office365)
    • This is a shell plugin which has dependencies on the current version of each of the 5 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
  • OpenID Connect Authentication Plugin (auth_oidc)
    • This plugin allows users to log in to Moodle using their Microsoft 365 accounts.
    • Users with existing Moodle accounts can switch to using this authentication type, and new users can log in with this plugin and have an account created for them.
    • If the administrator allows, users can also choose to disconnect from OpenID Connect and revert their previous login method, or to a username/password.
    • Features:
      • Standards-Compliant OpenID Connect Authentication.
      • Supports authorization code or resource-owner credentials grants.
        • Users can log in to Moodle by clicking the identity provider on the login page, or by entering their OpenID Connect credentials.
      • User profile field mapping
        • User profiles can be mapped and synced from IdP to Moodle.
      • Customizable Icon + Identity Provider name
        • The icon and identity provider name shown on the Moodle login page can be customized. A number of prechosen icons are available, as well as the ability to upload your own.
      • Provides hooks to link OpenID Connect accounts to Moodle accounts
        • If you do not want to change your users' login method, you can still connect to an OpenID Connect provider. The plugin provides code-level hooks to link a Moodle account to an OpenID Connect account without changing the Moodle user's authentication method. This means you can obtain tokens from an OpenID Connect service in the background.
      • Optional user-self-service connection and disconnection
        • A user-facing page is available for users to switch to and from OpenID Connect authentication. Access to this page and feature is controlled by a capability so administrators can disable it.
  • Microsoft 365 support plugin (local_o365)
    • This plugin provides most of the Microsoft 365 integration back-end. It provides shared code to communicate with Microsoft 365, and powers the calendar sync.
    • Features:
      • Calendar sync from/to Outlook.
        • Users can sync site events, course events, assignment due dates, and their personal Moodle calendar to their Outlook calendar.
      • User Sync and Matching
        • Users can be synced from Azure AD, or matched with existing users.
      • Teams Integration
        • Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
      • School Data Sync (SDS) Integration
        • Moodle courses can be created from classes in SDS schools.

Bidirectional sync between SDS class owners/members with Moodle course teachers/students.

  • Microsoft Block (block_microsoft)
    • This block provides a user-facing menu to access various Microsoft 365 integration features, resources, and preferences.
    • Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Microsoft 365 integration user control panel.
  • OneDrive for Business Repository (repository_office365)
    • This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
    • Features:
      • Import files into Moodle from OneDrive for Business
      • Upload files into OneDrive for Business from within Moodle
      • Link to files in OneDrive for Business so users always get the most up-to-date version.
      • Embed documents into Moodle courses so users can view documents directly on the site.
  • Microsoft 365 Teams Theme (theme_boost_o365teams)
    • This provides a theme to be used when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.

Optional Plugins

These 3 plugins provide support for OneNote assignment submission and feedback. While they are not required, they provide a powerful way to submit and review assignments.

  • OneNote support plugin (local_onenote)
    • This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
  • OneNote Assignment Feedback (assignfeedback_onenote)
    • Allows teachers to leave feedback for students using OneNote.
  • OneNote Assignment Submission (assignsubmission_onenote)
    • Allows students to submit assignments using OneNote.

3rd Party Plugins

  • oEmbed Filter (filter_oembed)
    • This filter converts links to a variety of sites into oembed-powered interactions.
    • Provides Office Mix support for Moodle, allowing you to embed Office Mixes directly into any text within Moodle.

Resources

Tooling and guidance on deploying Scalable Moodle Clusters on Azure

Setup

Installation

The packages are available from:

When you log back in to your Moodle instance, you are presented with the all the plugin configuration options. Save the settings without configuring them for now, you will come back to them later.

For information on installing plugins in Moodle see Installing plugins

Configuration

After you have the code installed in your Moodle instance, you'll need to do a bit of setup before you can use the plugins.

Enable the OpenID Connect Authentication Plugin

  1. Navigate to Site Administration > Plugins > Authentication and click Manage authentication
  2. Locate the OpenID Connect authentication plugin and click the eye icon to enable
  3. Click the Settings link for the plugin.
  4. Verify the Authorization and Token endpoints.
    1. These should be set by default to the following values:
      • Authorization Endpoint: https://login.microsoftonline.com/common/oauth2/authorize
      • Token Endpoint: https://login.microsoftonline.com/common/oauth2/token
    2. It's also possible to replace the "common" part in the endpoints to be your tenant name or tenant GUID. By doing so, users who are redirected to Microsoft login pages (using the auth code login flow) will see the custom login page of your tenant if one is configured following instructions. e.g.
      • Authorization Endpoint: https://login.microsoftonline.com/sample.onmicrosoft.com/oauth2/authorize
      • Token Endpoint: https://login.microsoftonline.com/sample.onmicrosoft.com/oauth2/token
    3. Note the endpoints may be in different format for B2C tenants. Please verify it in your Azure AD portal.
  5. Note the Redirect URI. This should be the URI of your Moodle instance followed by /auth/oidc/. You will need to enter this value into Azure portal later, so note this value and put it aside.
    • For example, https://www.example.com/auth/oidc/
    • Notes:
      1. This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any reason, you must change your Moodle site's configured domain name ($CFG->wwwroot).
      2. This URI must be a fully qualified domain name pointing to your Moodle instance.
      3. The Moodle site's configured URL must use HTTPS, even with a self signed SSL cert. Redirect URI using HTTP will not be acceptable when creating Azure app for the integration.
      4. If your Moodle installation is configured with an IP address pointing to your instance, you must change $CFG->wwwroot in your config.php to a fully-qualified domain name.
      5. This domain name does not need to be publicly accessible (i.e. internet-wide), but does need to be accessible to users of your Moodle instance. So, for example, you can use a intranet-only domain name.

Prepare your Microsoft 365 account for single sign-on with your Moodle installation

You will need an Azure subscription. If you do not have one, you can create one by visiting Microsoft Azure Sign Up.

To use Moodle with Microsoft 365 for SSO, you must configure Microsoft Azure to manage your Microsoft 365 Microsoft Azure Active Directory. A guide is available at this link.

Note: During the setup, you are required to enter a credit card and phone number. If you do not setup virtual machines or use paid services on the subscription, and only use it to access the Azure Active Directory, you will not be charged for the subscription.

Register Application in Azure (for auth_oidc and local_o365)

The easiest way to register application in Azure is to run the Windows PowerShell script downloaded from the plugin configuration page. Go to Site Administration > Plugins > Local plugins > Microsoft 365 Integration, it's the Download PowerShell Script button in the Setup tab.

Instructions on how to the PowerShell script to create Azure app using the downloaded file is available at https://github.com/microsoft/o365-moodle/blob/master/local/o365/scripts/README.md, or the /local/o365/scripts/README.md path of your Moodle installation.

You should only follow the manual process if you are unable to setup the AzureAd app via the Windows PowerShell script, or you need to verify some specific settings.

Note the PowerShell script doesn't work in PowerShell on non-Windows operating systems, because it uses features in .NET Framework but not in .NET Core. You will need to follow the manual steps.

Manual steps

The following steps are involved in the manual setup:

  1. Sign in to the Microsoft Azure Management Portal.
  2. Click on the Azure Active Directory link from Azure services section, then App Registrations from Manage section on the left.
  3. Click New registration on the top menu.
  4. Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
  5. Choose option applicable to your organisation in Supported account types section.
  6. In Redirect URI (optional) section, select Web and put the redirect URI from the OpenID Connect authentication plugin configuration. Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/
  7. Click Register.
  8. You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.
Configure application
  1. Locate the App.
    • If you followed steps above to create the Azure app, you should be redirected to the app settings page already.
    • Otherwise:
      1. Sign in to the Microsoft Azure Management Portal.
      2. Click on the Azure Active Directory link from Azure services section, then App Registrations from Manage section on the left.
      3. Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
      4. Locate the Application ID, note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
      5. Click on the display name of the App to open its settings.
  2. Enable implicit grant flow.
    1. From the menu on the left, go to Authentication link in the Manage section.
    2. In the Implicit grant section, check both "Access tokens" and "ID tokens".
    3. Save the changes.
  3. Create client secrets.
    1. From the menu on the left, go to Certificates & secrets link in the Manage section.
    2. Create a new client secret by clicking New client secret button.
    3. Enter a description, and select a duration for "Expires".
    4. Click Add.
    5. A value will appear under Value, note this value (write it down or copy it somewhere) and set it aside. You'll need it later.
  4. Expose an API - only required if Teams sync feature is used.
    1. From the menu on the left, go to Expose an API link in the Manage section.
    2. Click the Set link next to Application ID URI.
    3. This should open a Set the APP ID URI prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
    4. Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
    5. Click Save to create the Application ID URI.
    6. Click Add a scope.
    7. Enter access_as_user as scope name.
    8. Set Who can consent? to Admins and users.
    9. Set Admin consent title to Teams can access the user’s profile.
    10. Set Admin consent description to Allows Teams to call the app’s web APIs as the current user.
    11. Set User consent title to Teams can access the user profile and make requests on the user's behalf.
    12. Set User consent description to Enable Teams to call this app’s APIs with the same rights as the user.
    13. Ensure that State is set to be Enabled.
    14. Select the Add scope button to save.
    15. In the Authorized client applications section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
      • 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
      • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
  5. Configure App Permissions.
    1. Click the API permissions link in the Manage section.
    2. Click Add a permission button.
    3. In Select an API section, choose Microsoft APIs tab, then choose Microsoft Graph.
    4. Click the checkbox for the following permissions in each of the Application and Delegated permissions sections according to the section below.
    5. After all the permissions are added, click the Grant admin consent for YOUR ORGANISATION NAME link.
    6. When you're done, click Add permissions at bottom of the page.
Azure app permissions

The integration uses various Microsoft Graph APIs to communicate with Microsoft 365 to get and set data. Each Graph API would require a different set of permissions. The integration provides a list of recommended permissions to be given to ensure all features in the integration works, all of which are added automatically by the PowerShell script if it's used. Advanced users can customise the permissions according to the need of their own organisation, e.g. if group/team integration is not used, all permissions related to group can be removed, e.g. Group.ReadWrite.All.

Application permissions vs delegated permissions

The local_o365 supports two connection method - Application access and System API user. Application access connection method is recommended, and will be the only one supported in all new development from 2022.

The Azure app permissions required for the integration to work depend on the connection type. In general, if the Moodle site uses the Application access connection method, giving only application permissions would be enough; if the Moodle site uses the System API user connection method, only delegated permission are required.

Note the following exception when using Application access connection method.

  • User.Read delegated permission is always required regardless of connection method.
  • Notes.ReadWrite.All delegated permission is required for OneNote integration.
  • Files.ReadWrite.All delegated permission is required for OneDrive integraiton.
  • If teams integration feature is used, the following delegated permissions are required for teams SSO to work, regardless of connection method:
    • openid
    • offline_access
    • email
    • profile
Permissions

For a full list of Microsoft Graph API used, and the permissions required, please refer to this spreadsheet. Note that:

  • This document is constantly updated.
  • For each Graph API, a few permissions may be listed. Graph API can be called if permissions in any line is added, and the admin consent is granted for your organisation.

The recommended permissions to ensure all integration features work are listed below. These would be the same set of permissions that are applied when using the PowerShell script to set up the Azure app, with the exception of EduRoster.Read.All application permission, EduRoster.ReadWrite.All application permission, and EduRoster.ReadBasic delegated permissions that are used in the SDS sync feature, which need to be assigned manually.

Type Permission Display Name Connection Type Use
Application Permissions Directory.ReadWrite.All Read and write directory data Application access A common permission used in both user syncs and group integration.
Directory.Read.All Read directory data Application access A common permission used in both user syncs and group integration.
Group.ReadWrite.All Read and write all groups Application access Required for course group/team integration.
User.Read.All Read all users' full profiles Application access Required for SSO and to sync user information between Microsoft 365 and Moodle.
Files.ReadWrite.All Read and write files in all site collections Application access Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
Calendars.ReadWrite Read and write calendars in all mailboxes Application access Required for calendar event sync.
Sites.Read.All Read items in all site collections Application access Required to detect OneDrive for Business URL setting.
Notes.ReadWrite.All Read and write all OneNote notebooks Application access Required for the OneNote integration to create notebooks, sections, and pages for assignments.
MailboxSettings.Read Read all user mailbox settings Application access Required for syncing Outlook default timezone settings of the user.
AppRoleAssignment.ReadWrite.All Manage app permission grants and app role assignments Application access Required for assigning users to application during user sync if the option is enabled.
EduRoster.Read.All Read the organization's roster Application access Required in the SDS sync feature to get information about schools, classes, and users.
Member.Read.Hidden Read all hidden memberships Application access Required in the SDS sync feature to get school class members.
Delegated Permissions Directory.ReadWrite.All Read and write directory data System API user A common permission used in both user syncs and group integration.
Directory.Read.All Read directory data System API user A common permission used in both user syncs and group integration.
Group.ReadWrite.All Read and write all groups System API user Required for course group integration.
User.Read.All Read all users' full profiles System API user Required for SSO and to sync user information between Microsoft 365 and Moodle.
Files.ReadWrite.All Have full access to all files user can access Application access and system API user Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
Calendars.ReadWrite Have full access to user calendars System API user Required for calendar event sync.
Sites.Read.All Read items in all site collections System API user Required for SharePoint integration (deprecated)
Notes.ReadWrite.All Read and write all OneNote notebooks that user can access Application access and system API user Required for the OneNote integration to create notebooks, sections, and pages for assignments.
AppRoleAssignment.ReadWrite.All Manage app permission grants and app role assignments System API user Required for assigning users to application during user sync if the option is enabled.
MailboxSettings.Read Read user mailbox settings System API user Required for syncing Outlook default timezone settings of the user.
User.Read Sign-in and read user profile Application access and system API user Required to sign users in using Microsoft 365, and to access Microsoft 365 APIs.
openid Sign users in Application access and system API user Required for Teams SSO.
offline_access Maintain access to data you have given it access to Application access and system API user Required for Teams SSO.
email View users' email address Application access and system API user Required for Teams SSO.
profile View users' basic profile Application access and system API user Required for Teams SSO.
EduRoster.ReadBasic Read a limited subset of users' view of the roster System API user Required in the SDS sync feature to get information about schools, classes and users.

Enter Azure application credentials into Moodle

  1. Navigate to the OpenID Connect authentication plugin's settings page (Site Administration > Plugins > Authentication > OpenID Connect)
  2. Enter the Application ID value you noted earlier from Azure into the Application ID box on the screen.
  3. Enter the Key value you noted earlier from Azure into the "Key" box on the screen.
  4. Click "Save changes" at the bottom of the screen.

Configure the Microsoft 365 support plugin

  1. Navigate to Site Administration > Plugins > Local plugins and click Microsoft 365 Integration
  2. Complete each of the steps as follows:
  3. Choose connection method
    1. Choose the method you want to use to connect to Microsoft 365. Unless you have a special reason to use the System API user, choose Application access.
    2. Click Save changes
  4. Admin consent & additional information
    1. Admin consent: Every time you change a Requires admin permission in Azure, you will need an administrator to provide consent to use the permission. Clicking the Provide admin consent button will take you to a log in screen on Microsoft 365. An administrator will have to log in, and then will be given the option to approve the new permissions.
    2. Azure AD Tenant: This is the domain name that identifies your Microsoft 365 subscription, for example "contoso.onmicrosoft.com". If you know it, enter it in this box, if not, click the "Detect" button to attempt to detect the correct value.
    3. OneDrive for Business URL: This is the URL that your users use to access OneDrive for Business. This can usually be determined from your AzureAD tenant, for example, if your tenant is "contoso.onmicrosoft.com", your OneDrive for Business URL is "contoso-my.sharepoint.com." If you know the URL, enter it here, otherwise click "Detect" to attempt to detect the correct value. Only enter the domain name, do not include "http://", "www." or any trailing slashes. For example "contoso-my.sharepoint.com", not "https://contoso-my.sharepoint.com/"
    4. Click Save changes.
  5. Verify Setup
    1. This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
    2. If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

Connecting users to Microsoft 365

To use any Microsoft 365 features, a Moodle user must be connected to a Microsoft 365 user that has an active Microsoft 365 subscription. There are two ways to connect a Moodle user to a Microsoft 365 user.

Switch the user to use OpenID Connect authentication.

With this method, the user will log in to Moodle using their Microsoft 365 account credentials.

Link a Moodle user to a Microsoft 365 user.

Users in Moodle can also be linked to Microsoft 365 users without changing the Moodle user's authentication method. Users will be able to log in as they always have, and still use all the Microsoft 365 features.

  1. Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
  2. As the user to link to Microsoft 365, visit a page that has the Microsoft block visible.
  3. Click the Connect to Microsoft 365 link in the Microsoft block.
  4. You will be brought to the Microsoft 365 / Moodle Control Panel.
  5. There will be a "Connection Status" indicator box on the right side of the screen, click the "Click here to connect" link.
  6. You will be brought to the AzureAD authentication screen. Log in with the Microsoft 365 user's credentials you'd like to connect to the Moodle user you are logged in as.
  7. If login was successful, you will be brought back to the Microsoft 365 / Moodle Control Panel page, where the Microsoft 365 connection indicator should now read Active.
  8. This user is now connected to the Microsoft 365 user.

Microsoft 365 Integration Local Plugin

Sync Settings

These features are accessible from the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft 365 Integration), on the Sync Settings tab.

User Sync

This option controls how users are synced from Azure AD to Moodle. If enabled, users from Azure AD can be automatically created in Moodle. This feature can also delete users in Moodle when they are deleted from Azure AD, or attempt to automatically match Moodle users with users in the connected Azure AD.

The main benefit of using this option, compared to having accounts created as users log in using OpenID Connect, is that you can manage and enrol users before they first log in, so everything is ready to go the first time they access Moodle.

Notes:

  • The sync job runs in the Moodle cron, and syncs 1000 users at a time.
  • By default, this runs once per day at 1:00 AM in the time zone local to your server.
  • To sync large sets of users more quickly, you can increase the freqency of the Sync users with Azure AD task using the Scheduled tasks management page. See Scheduled_tasks.

There are several options that affect user sync:

  • Create accounts in Moodle for users in Azure AD: This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their Microsoft 365 credentials to log in to Moodle (using the OpenID Connect authentication plugin), and will be able to use all the features of the Microsoft 365 plugin set.
  • Update all accounts in Moodle for users in Azure AD: This will update all users in Moodle from each user in the linked Azure AD.
  • Delete previously synced accounts in Moodle when they are deleted from Azure AD: This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!
  • Match preexisting Moodle users with same-named accounts in Azure AD: This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are insensitive and ignore the Microsoft 365 tenant. For example, "BoB.SmiTh" in Moodle would match "bob.smith@example.onmicrosoft.com". Users who are matched will have their Moodle and Office accounts connected and will be able to use all Microsoft 365/Moodle integration features. The user's authentication method will not change unless the setting below is enabled.
  • Switch matched users to Microsoft 365 (OpenID Connect) authentication: This requires the "Match" setting above to be enabled. When a user is matched, enabling this setting will switch their authentication method to OpenID Connect. They will then log in to Moodle with their Microsoft 365 credentials. Note: Please ensure the OpenID Connect authentication plugin is enabled if you want to use this setting.
  • Assign users to application during sync: The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.
  • Sync Microsoft 365 profile photos to Moodle in cron job: User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.
  • Sync Microsoft 365 profile photos to Moodle on login: User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.
  • Perform a full sync each run: By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
  • Match Azure usernames to Moodle emails instead of Moodle usernames during the sync: Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

User Creation Restriction

During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".

User Field Mapping

This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced. To create mappings:

  1. Click "Add Mapping"
  2. In the row that appears, select an Azure field to bring into Moodle.
  3. In the second column on the same row, select a Moodle field to copy the value into.
  4. In the third column on the same row, choose whether this only happens on user creation, on user login, or both.
  5. Click "Save Changes" at the bottom of the page.

To Delete A Mapping

  1. Click the "X" button at the end of the row you want to delete.
  2. Click "Save changes" at the bottom of the page.
  3. Note this will only prevent future information syncing, it will not undo past operations.

Teams Sync

The Teams sync setting creates teams in Microsoft Teams for courses in Moodle. Teams creation effectively results in team members being added to a Microsoft 365 group, enabling all group features to be usable.

Features:

  • Teams (group) membership is kept up-to-date with enrolments in Moodle.
  • Provides an easy way to address all users in a course from Microsoft 365. For example, a teacher can share a document from OneDrive with all of their students by choosing the user group, i.e. Teams members, for their course - they don't have to choose each student individually.
  • Course group file stores are accessible from the Microsoft 365 Moodle file repository plugin, allowing users to access group files from Moodle.

The Teams sync option allows a great deal of customization. An administrator can choose to create Teams for all courses, and enable all settings, or customize the implementation. If administrators choose the "Customize" option for this setting, administrators can choose which courses have Teams created, and choose which features are enabled for each course.

Once enabled, new Teams will be created every cron run for any enabled course that doesn't have a team set up. Once Teams are set up, membership will be maintained automatically whenever someone joins or leaves a Moodle course.

Teams vs Group

Microsoft Teams share the same base with Microsoft 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:

  • If the course has at least one teacher who can be matched to a Microsoft 365 user enrolled, a Team will be created, with the teacher as Team owner,
  • If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Microsoft 365 user, only a group will be created.

Advanced settings

Administrator Tools

  • Tenants: This tool allows you to add additional Microsoft 365 tenants to be used with Moodle. Users from additional tenants can log-in to Moodle using their Microsoft 365 account, and use features like calendar sync and the OneDrive repository.
  • Health check: If you are experiencing problems with any Microsoft 365 / Moodle features, click the Health Check link to run tests on your system and look for potential problems.
  • Connections: This tool allows administrators to see and manage the connections between their Moodle users and Microsoft 365 accounts. Each user in the system is listed alongside the Microsoft 365 username the user is connected to, if any. Administrators can choose to manually connect or disconnect each user.
  • User Matching: This tool allows administrators to manually match Moodle and Microsoft 365 users using a CSV file. Administrators can upload a CSV file containing, on each line, a Moodle username, and Microsoft 365 username, and a 1 or 0 indicating whether to enable Microsoft 365 login for that user. Once uploaded, the file is processed in batches during the Moodle cron. The tool page will display the progress of this process.
  • Maintenance Tools: These tools perform maintenance tasks that can help solve problems which may crop up from time to time. Generally, users should not need these tools unless they encounter the specific situation these tools are designed to solve.
    • Resync users in groups for courses: Course group membership is kept up-to-date as users are enrolled and un-enrolled from courses in Moodle. If this membership gets out-of-date for whatever reason, this tool will force a resync of group membership.
    • Recreate deleted Microsoft 365 groups: Course groups are created from Moodle courses when using the course group feature. If a group is manually deleted from the Microsoft 365 administrator panel, this tool will recreate it.
    • Generate debug data package: This tool will generate a package of information that can be sent to the plugin suite maintainers to help debug problems in environment and setup. While no API keys are present, this information does contain a lot about your environment and setup, so please be careful about who you send this information to.
    • Cleanup OpenID Connect Tokens: If your users are experiencing problems logging in using their Microsoft 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
    • Cleanup User Sync Delta Tokens: If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.

Other advanced settings

  • Single sign off: If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Microsoft 365 as well.
  • Microsoft 365 for China: Microsoft 365 in China differs slightly in some technical aspects. If you are using Microsoft 365 for China, select this box to ensure everything will work properly.
  • Record debug messages: If you experience problems using any Microsoft 365 features in Moodle, enable this setting. Once enabled, errors will be recorded to the Moodle log for review. These errors can help you or the plugin developers debug and fix the problem. The error log can be viewed by navigating to Site Administration > Reports > Logs, changing the "All activities" select box to "Site errors", and clicking "Get these logs".
  • Minimum inexact username length to switch to Microsoft 365: When using automatic user matching, this setting can be used to exclude accounts with short names. The intended use of this is to avoid matching generic accounts like "admin". This setting is the minimum length of a username required for automatic matching to match users.
  • Profile photo refresh time: Profile photo syncing can be a resource-intensive process, so this setting allows you to set a minimum time between profile photo refresh runs.
  • Custom theme (Advanced): This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.

Legacy settings

These features are deprecated and is likely to be removed in a future version.

Preview features

From time-to-time, we add features that use brand-new APIs or are slightly experimental in some way. These features often become part of our regular feature offering once they mature, but if you want to see the latest features we're working on, you can enable this setting to enable all preview features. Be careful though! These features do break from time to time.

School Data Sync (SDS)

The SDS feature of the plugin has the following functionalities:

  • Sync teacher / student profile field from a selected SDS school.
  • Sync classes from multiple SDS schools, and create Moodle courses from the classes.
  • Sync class owners and members to Moodle courses as teachers and students according to the configured roles.
  • Sync user enrolments and role changes in Moodle back to the connected SDS classes.

Settings

The settings applicable to the SDS feature are:

  • Create Courses: Allow selecting the schools available in the Azure tenant which need to be synced for course creation. Multiple schools can be selected. For each school selected, a new top level course category will be created, and each class in the school will be created as a course in the category.
  • Teams creation enabled: This controls if Moodle courses created from syncing SDS classes are automatically connected to the Microsoft Team of the SDS class. This should be enabled only if Teams are automatically created from the SDS classes.
  • Enrol users: Enrol SDS class teachers and members into Moodle courses created from the classes.
  • Advanced enrolments sync with SDS classes: Control whether to sync SDS class role changes to Moodle, and whether to sync Moodle course enrolment / role changes back to SDS class.
  • Teacher role and Member role: Control the default teacher and student roles to assign in Moodle courses for SDS class owners and members.
  • Sync profile data from school: Control the SDS school from which teacher and student profiles are synced from. If a school is selected, the teacher / student profile fields are available to match in auth_oidc profile field mapping settings.

Sync triggers

  • Course and SDS user profile sync is triggered by the Sync with SDS (\local_o365\feature\sds\task\sync) scheduled task. Note this includes the sync of SDS teacher and student profile field, which is configured in auth_oidc.
  • Sync from Moodle to SDS (e.g. course enrolments and role changes to SDS class) are triggered by Moodle observer functions, thus don't require scheduled task runs. Note there is normally a delay of up to 1 minute on Microsoft end to see such changes.

Teams Settings

This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will

  • Automatically create Teams for Moodle courses configured to be synced.
  • Automatically sync Moodle course users to Teams.
  • Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
  • Allow users to use Moodle courses right from Teams.
  • Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
  • Forward all Moodle notifications to users to Teams.

Some features can be disabled if needed.

Prerequisite

  1. OpenID Connect Authentication plugin is enabled and configured.
  2. Allow frame embedding is enabled in HTTP security section of site configuration.
    1. Login to the site as site administrator.
    2. Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
    3. Find Allow frame embedding setting and make sure it's enabled.
    4. Save changes.
  3. Web services are enabled on the site.
    1. Login to the site as site administrator.
    2. Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
    3. Find Enable web services setting and make sure it's enabled.
    4. Save changes.
  4. Moodle Microsoft 365 Webservices are enabled.
    1. Login to the site as site administrator.
    2. Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
    3. From the list of web services in the "External service" part in "Built-in services" section, find Moodle Microsoft 365 Webservices.
    4. If the web services is disabled, i.e. greyed out, go to its settings and enable it.
  5. Give Authenticated user role permission to create web service token.
    1. Login to the site as site administrator.
    2. Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
    3. In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
    4. From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
    5. Save changes.
  6. Before you can test the messaging bot, you need to be sure that the MS Teams account has a user created in Moodle (user should have the same username as your teams user email address and Moodle user authentication type should be oidc) and you must have accessed Moodle at least once with that account.

Register Application in Azure (for the bot)

Note this is different from the application registered above to allow user login integration and doesn't require any extra API permissions.

  1. Sign in to the Microsoft Azure Management Portal.
  2. Click on the Azure Active Directory link from Azure services section, then App Registrations from the Manage section on the left.
  3. Click New application on the top menu.
  4. Enter a name for your application (can be anything you want, but should let you know this is for bot services).
  5. Choose "Accounts in any organizational directory (Any Azure AD directory - Multitenant)" option in Supported account types section (multitenant application is required).
  6. Click Register button to finish registration.
  7. You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
  8. Note the Application (client) ID of the app, which will be used in plugin configuration in Moodle.
  9. From the Manage section on the left of the page, go to Certificates & Secrets, and create a new client secret by clicking the New client secret button. Note the secret which will be used in plugin configuration in Moodle.
  10. In Teams Settings tab of Microsoft 365 Integration configuration in Moodle, fill in the Application (client) ID and the client secret in Application ID and Client Secret settings respectively.
  11. Save changes.

Update authentication application settings in Azure

When performing Step 1/3: Register Moodle with Azure AD in the Setup tab of Microsoft 365 Integration configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.

  1. Sign in to the Microsoft Azure Management Portal.
  2. Click on the Azure Active Directory link from Azure services section, then App Registrations from Manage section on the left.
  3. Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show All applications if the app wasn't created by your account.
  4. Go to the settings of the application by clicking its name.
  5. In the Manage section on the left of the page, go to Authentication.
  6. In the list of Redirect URIs, add the following entry, in type Web:
    1. https://your.moodle.url/local/o365/sso_end.php
  7. If bot feature is to be enabled, also add the following entry, in type Web:
    1. https://token.botframework.com/.auth/web/redirect
  8. Save changes.

Bot configuration

This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.

Bot deployment

  1. Go back to Teams Settings section of Microsoft 365 Integration configuration in Moodle as site administrator.
  2. Make sure Application ID and Client secret are configured and saved.
  3. Click Deploy to Azure button. This will start the process of bot deployment in Azure Portal in a popup window.
  4. Configure the following in the Custom deployment window:
    1. Choose your Subscription.
    2. Choose your Resource group. you may need to create a new one.
    3. Choose your Location.
    4. LUIS Pricing Tier - LUIS pricing tiers are explained here. The free tier should be able to get you started.
    5. LUIS Region - Region where the LUIS resource will be deployed.
    6. Bot Application ID - the application ID of the Moodle Teams integration application, which is the same as Application ID in Teams Settings tab of Microsoft 365 Integration configuration.
    7. Bot Application Password - the client secret of the Moodle Teams integration application, which is the same as Client Secret in Teams Settings tab of Microsoft 365 Integration configuration.
    8. Moodle URL'.
    9. Azure AD Application ID - The Application ID saved in the Setup tab of Microsoft 365 Integration configuration.
    10. Azure AD Application Key - The Application Key saved in the Setup tab of Microsoft 365 Integration configuration.
    11. Azure AD Tenant - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
    12. Shared Moodle Secret - Paste the Shared Moodle Secret setting of in the Teams Settings tab of Microsoft 365 Integration configuration.

Once all configured, agree the terms and conditions, and click Purchase. This will start the bot deployment, which can take a few minutes to finish.

Post deployment configuration

After bot deployment is finished:

  1. Sign in to the Microsoft Azure Management Portal.
  2. In the Navigation section of the page, go to Resource groups.
  3. From the list of resource groups, select the one in which the bot was created and deployed.
  4. One of the resources in the group should be in type Web App Bot. Click its name to go to settings.
  5. Copy the Messaging endpoint of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
  6. Paste this endpoint to the Bot webhook end point field in Teams Settings tab of Microsoft 365 Integration configuration page.
  7. Check Bot feature enabled box in Teams Settings tab of Microsoft 365 Integration configuration page.
  8. Save changes.

Add Moodle app to Teams

Once all configured, you are ready to add Moodle app to Teams.

  1. Go to Teams Settings tab of Microsoft 365 Integration configuration page.
  2. Click Download manifest file button. This will download a manifest file (in .zip format) which contains the Moodle app.
  3. Follow these instructions to upload the app to the app catalog of your tenant.
  4. Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

Teams Moodle app settings

After downloading the manifest file of Moodle app, a new tab Teams Moodle app will be made available in Microsoft 365 Integration configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:

  • automatically install the Moodle app,
  • automatically create a Moodle tab in the General channel.
  • automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

To configure the field, follow these steps:

  1. Log in Teams, and go to app catalog by clicking the Apps button from the navigation bar on the left.
  2. Find the Moodle app uploaded.
  3. Click the option icon of the app, which is located at the top right corner of the app image.
  4. Click Copy link.
  5. In a text editor, paste the copied content. It should contain an URL such as https://teams.microsoft.com/l/app/00112233-4455-6677-8899-aabbccddeeff.
  6. The last part of the URL, i.e. 00112233-4455-6677-8899-aabbccddeeff, is the app ID.
  7. Paste the app ID in the Moodle app ID setting on Teams Moodle app tab of Microsoft 365 Integration configuration page in Moodle.
  8. Save changes.

OpenID Connect Authentication Plugin

Basic Usage

Once configured, you should see a link named "OpenID Connect" on the Moodle login page. Clicking this link will redirect the browser to the identity provider. Users will log in there, and will be redirected back to Moodle. If they have logged in to Moodle using OpenID Connect before, they will be logged in to their existing Moodle account. If they have not logged in to Moodle with OpenID Connect before, an account will be created for them.

Note: If the "Prevent account creation when authenticating" setting is enabled in Moodle, new accounts will not be created.

Settings

There are a number of options you can use to customize how the plugin behaves. To configure the plugin, visit the plugin's settings page. (Site Administration > Plugins > Authentication > OpenID Connect)

Provider Name

The name entered here will be used through the OpenID Connect plugin and the Microsoft 365 plugins to refer to the system used to log users in. For example, if your users are used to calling their Azure AD account their "School" account, you enter "School account" here, and all references to authentication will be "Log in with your School account".

Auto-Append

When using the "Username/Password" login flow, this setting with automatically append a given string to an entered username. This is useful in Azure AD usernames, where a single domain name is often used for every user - i.e. [user]@contoso.onmicrosoft.com. Users would normally have to enter this entire username to successfully log in to Moodle, but in this example, entering "@contoso.onmicrosoft.com" here means users would only have to enter their unique username, i.e. "bob.smith", instead of "bob.smith@contoso.onmicrosoft.com".

Domain Hint

If users have several different Azure AD accounts with different tenants (i.e. @contoso.onmicrosoft.com, @example.onmicrosoft.com), but Moodle only uses one of these tenants, you can enter that tenant in this box to have the Azure AD login screen only ever suggest accounts from that tenant.

Login Flow

This setting changes how users log in to Moodle using the plugin. You can redirect users to the OpenID Connect provider's login page, or have users enter their credentials directly into Moodle. See the "Login Flows" section below for further information.

User Restrictions

This setting allows you to restrict the users that can log in to Moodle using OpenID Connect (Azure AD).

Once you've entered at least one user restriction, users logging in to Moodle must match at least one entered pattern.

How to use user restrictions:

  1. Enter a regular expression pattern that matches the usernames of users you want to allow.
  2. Enter one pattern per line
  3. If you enter multiple patterns a user will be allowed if they match ANY of the patterns.
  4. The character "/" should be escaped with "\".
  5. If you don't enter any restrictions above, all users that can log in to the OpenID Connect provider will be accepted by Moodle.
  6. Any user that does not match any entered pattern(s) will be prevented from logging in using OpenID Connect.

Record debug messages

If you experience problems using OpenID Connect, enable this setting. Once enabled, errors will be recorded to the Moodle log for review. These errors can help you or the plugin developers debug and fix the problem. The error log can be viewed by navigating to Site Administation > Reports > Logs, changing the "All activities" select box to "Site errors", and clicking "Get these logs".

Custom Icon

This setting allows you to choose from a selection of predefined icons to appear next to the identity provider link on the login page. You can also upload your own icon.

  1. Visit the plugin settings page (Site Administration > Plugins > Authentication > OpenID Connect)
  2. Locate the "Icon" section of the settings page.
  3. There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
  4. To use a custom icon, use the file picker below the "Icon" setting.
    1. This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
    2. If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

Login flows

This plugin supports two different methods for users to log in: Authorization Request and Username/Password Authentication

Authorization Request

This flow redirects the user to Microsoft 365 to log in and are then brought back to Moodle logged in.

Using this flow:

  1. The user clicks the name of the identity provider (What you entered in the "Provider Name" box at the top of the settings page.) on the Moodle login page.
  2. The user is redirected to Microsoft 365 to log in.
  3. Once successfully logged in, the user is redirected back to Moodle where the Moodle login takes place transparently.

Username/Password Authentication

This login flow works like a classic username and password, except the user uses their Microsoft 365 account information.

Using this flow:

  1. The user enters their Microsoft 365 username and password directly into the Moodle login form.
  2. Their credentials are securely sent to Microsoft 365 for verification.
  3. If the credentials are verified, the user is logged in to Moodle.

Switching existing Moodle users to use Microsoft 365 to log in

If a user logs in to Moodle using OpenID Connect but does not have a Moodle account, one will be created for them. However, existing Moodle users can be migrated to use OpenID Connect and provide a connection to Microsoft 365.

  1. Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
  2. Log in as the user to be migrated, visit a page that has the Microsoft block visible.
  3. Click the Connect to Microsoft 365 link in the Microsoft block.
  4. You will be brought to the Microsoft 365 / Moodle Control Panel.
  5. Click the Microsoft 365 Login link under Microsoft 365 Features'
  6. Click the "Start using Microsoft 365 to log in to Moodle." link.
  7. You will be redirected to Microsoft 365 to log in. Log in with the account you'd like to link to the Moodle account you're using.
    1. NOTE: If you're already logged in to Microsoft 365, you will not have to enter your credentials on the Microsoft 365 login page. This Microsoft 365 account will be linked to the Moodle account. Ensure you are logged in to the correct account, or log out of Microsoft 365 first to show the Microsoft 365 login screen.
  8. The Moodle account will now use Microsoft 365 to log in. The previous login method will not work.
  9. The Moodle user can now use any of the Microsoft 365 features in Moodle.

Connecting existing Moodle users to Microsoft 365 without changing login method

  1. Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
  2. Log in as the user to be migrated, visit a page that has the Microsoft block visible.
  3. Click the Connect to Microsoft 365 link in the Microsoft block.
  4. You will be brought to the Microsoft 365 / Moodle Control Panel.
  5. There will be a "Connection Status" indicator box on the right side of the screen, click the "Click here to connect" link.
  6. You will be brought to the AzureAD authentication screen. Log in with the Microsoft 365 user's credentials you'd like to connect to the Moodle user you are logged in as.
    1. NOTE: If you're already logged in to Microsoft 365, you will not have to enter your credentials on the Microsoft 365 login page. This Microsoft 365 account will be linked to the Moodle account. Ensure you are logged in to the correct account, or log out of Microsoft 365 first to show the Microsoft 365 login screen.
  7. If login was successful, you will be brought back to the Microsoft 365 / Moodle Control Panel page, where the Microsoft 365 connection indicator should now read Active.
  8. The Moodle account is now linked to the Microsoft 365 account and can use Microsoft 365 features as that user.
  9. The Moodle user's login method will not change, the user will log in to Moodle as they always have.

OneDrive for Business Repository

The OneDrive for Business repository allows users using the Microsoft 365 integration plugins to connect to their OneDrive for Business as a Moodle repository.

Downloading and linking files

  1. When using a filepicker anywhere in Moodle, you'll see a list of repositories on the left side of the popup. Look for and click on "OneDrive for Business".
  2. You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
    1. My Files contains all documents in your personal OneDrive for Business
    2. Courses will list all Moodle course shared document libraries that you have access to. If you want to download files from one of these, you'll click "Courses", then click the folder for the course you want to access.
  3. You will now see a list of all the files and folders in your OneDrive.
  4. Click the file you want to download into Moodle.
  5. Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
    1. If you want to download a copy of the file as it is now, choose "Make a cope of the file". This will copy the file into Moodle, and will then use the local Moodle copy when the file is accessed from within Moodle. Any changes to the file in OneDrive will not be seen in Moodle.
    2. If you want to link a file choose "Create an alias/shortcut to the file". This will create a link in Moodle to the file in OneDrive, and the file will be accessed from OneDrive directly. Any changes to the file in OneDrive will be seen when accessing the file from Moodle.
  6. You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
  7. Click "Select this file".

Uploading files

You can upload files into both your personal OneDrive for Business document library and a course SharePoint document library from the filepicker interface.

  1. When accessing a OneDrive document library from a file picker, you will see an "Upload New File" item in the list of files and folders.
  2. Click the "Upload new file" item.
  3. Choose the file you want to upload and click "Upload this file".
  4. The file will be uploaded to OneDrive and selected for the file picker.

Embedding Office documents

This repository allows users to embed Office documents from OneDrive into a course and have the live version viewable using Office web apps.

  1. Start as a user connected to Microsoft 365 and who has access to modify a course.
  2. Turn on editing for the course and choose "Add an activity or resource" for the section of the course you want to add the document.
  3. Choose the "File" resource to add to the course.
  4. In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
  5. Choose the "OneDrive for Business" repository and choose your Office document.
  6. When you select a file, make sure "Create an alias/shortcut to the file" is selected, the click "Select this file"
  7. Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
  8. Click "Save and display"
  9. You should see the file embedded into the page.

OneNote

OneNote is now available through Microsoft 365. If you have installed all the plugins (for example, by installing [1]) then you already have the OneNote plugins installed. To access OneNote using your Microsoft 365 subscription, add OneNote to the list of applications in your Azure application. This is done the same way you configured Azure permissions, above. Note that OneNote is still in preview, and may not be available to everyone yet. If you don't see OneNote in the list of applications to add to your Azure application, you can try logging in to a desktop OneNote application using an administrator account in your Microsoft 365 tenant. This sometimes expedites to the process of adding the OneNote preview to your tenant.

Notes on special release

3.8.0.4 and 3.9.1 release

3.8.0.4 and 3.9.1 release of the plugins on 29 September 2020 introduced improvements on SSO integration for Moodle in Teams as well as Single Sign Off support, but requires additional actions from Moodle and Azure admins.

Moodle and Teams SSO integration

The new releases is capable of getting a user token from either Teams desktop/mobile app or Teams web app, and attempt to log in as the user in the Moodle Teams tab. In order for it to work, changes in 3 sections are required.

Update Azure app settings

  1. Sign in to the Microsoft Azure Management Portal.
  2. Click on the Azure Active Directory link from Azure services section, then App Registrations from Manage section on the left.
  3. Locate the app used for Moodle and Microsoft 365 integration, and click its name.
  4. Under Manage, select Expose an API.
  5. Select the "Set" link to generate the Application ID URI in the form of api://{AppID}. Insert your fully qualified domain name (with a forward slash "/" appended to the end) between the double forward slashes and the GUID. The entire ID should have the form of: api://fully-qualified-domain-name.com/{AppID}. e.g. api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000.
  6. If you get errors when selecting the "Set" link, it may be because the Supported account types setting of your app is set to a value rather than the one with "single tenant". Try updating this value to get it working.
  7. Select the "Add a scope" button. In the panel that opens:
    1. enter "access_as_user" as the "Scope name".
    2. Set "Who can consent?" to "Admins and users".
    3. Set "Admin consent title" to be "Teams can access the user’s profile".
    4. Set "Admin consent description" to be "Allows Teams to call the app’s web APIs as the current user".
    5. Set "User consent title" to be "Teams can access the user profile and make requests on the user's behalf".
    6. Set "User consent description" to be "Enable Teams to call this app’s APIs with the same rights as the user".
    7. Ensure that "State" is set to "Enabled".
    8. Select the "Add scope" button to save.
  8. In the Authorized client applications section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
    1. 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
    2. 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
  9. Under Manage then API permissions, ensure the following permissions are added under "Microsoft Graph" > "Delegated permissions":
    1. User.Read (enabled by default)
    2. email
    3. offline_access
    4. OpenId
    5. profile
  10. Under Manage then Authentication, ensure the following boxes are checked for "implicit grant":
    1. ID Token
    2. Access Token.

Download updated manifest file

  1. Login to Moodle as site administrator.
  2. Go to "Microsoft 365 Integration" page in the site admin section.
  3. Go to "Teams Settings" tab.
  4. Verify settings on the page, note that two new settings are added in this release:
    1. Microsoft app ID for the Moodle Teams app: This is used in the "ID" field of Teams app manifest file, which is essentially a self generated app ID to identify itself. It should be set to the default value in most use cases, otherwise it may affect upgrading of the Teams app. The only scenario a custom value is to be set for this setting is when there are multiple Moodle sites in the organisation, and they all need to be integrated with Teams, thus each site will require a separate Teams app. If custom value is required, please use powershell or external tools to generate valid ones.
    2. Teams app name: This allows you to give a custom name, rather than the default "Moodle", to the Moodle Teams app created. It can be useful if you have multiple Moodle sites in your organisation, and each creating a separate Moodle app for Teams integration.
  5. Once settings are verified, save changes, go back to the tab, and click the "Download manifest file" button to download the new manifest file for the upgraded app.

Update Moodle app in Teams

  1. As a tenant admin, go to Teams.
  2. Go to "Apps" page to manage apps.
  3. From the menu on the left, click on the link "Built for YOUR ORGANISATION". This should list all custom apps uploaded for your tenant.
  4. Locate the previous Moodle app, click the options button on the card for more options, and click "update". This should open a file picker.
  5. Select the new manifest file downloaded from Moodle.

Note that as long as the Microsoft app ID for the Moodle Teams app setting is not changed, this should be recognised as an app upgrade, rather than uploading a new app. This means that the app will be kept in all existing Teams that have it installed, and all existing Moodle tabs will keep working.

Single Sign Off

When a Microsoft 365 authenticated user clicks the Moodle log out button, it is possible to log the user out from Microsoft 365 at the same time.

In order for this to work, configuration changes in two places are required:

Moodle settings change

  1. Sign in Moodle as site admin.
  2. Go to "OpenID Connect" settings page under Plugins - Authentication:
  3. Go to "Advanced" tab.
  4. Enable "Single sign off".
  5. Save changes.

Azure app settings change

  1. Click on the Azure Active Directory link from Azure services section, then App Registrations from Manage section on the left.
  2. Locate the app used for Moodle and Microsoft 365 integration, and click its name.
  3. In the Manage section on the left of the page, go to Authentication.
  4. In the list of Redirect URIs, add the root URL of your Moodle site (wwwroot) as an entry.

3.8.0.5 and 3.9.2 release

3.8.0.5 and 3.9.2 release of the plugins on 18 November 2020 added support for synching the default timezone preference of the user in Outlook to Moodle. This requires the following permissions to be granted for the Azure app.

  • If your Moodle site uses Application access connection method, you will need to add and grant MailboxSettings.Read application permission.
  • If your Moodle site uses System API User connection method, you will need to add and grant MailboxSettings.Read delegated permission.

3.9.8, 3.10.5 and 3.11.2 release

3.9.8, 3.10.5 and 3.11.2 release of the plugins on 07 December 2021 updated the implementation of SDS feature, and updated it to use Microsoft Graph APIs instead of legacy APIs. As a result, additional permissions are required for the feature to work properly.

  • If your Moodle site uses Application access connection method, you will need to add and grant EduRoster.Read.All and Member.Read.Hidden application permissions.
  • If your Moodle site uses System API User connection method, you will need to add and grant EduRoster.ReadBasic delegated permission.

Teams integration known limitations

  • If the Moodle site is not publicly accessible, e.g. on a intranet, Moodle tabs will not work in Teams desktop and mobile apps. They will only work in web apps from browser.
  • It is a known issue that if a Microsoft 365 user has never login to Moodle ever, the first attempt of the user to SSO from Teams to Moodle will not work silently. Instead, the user will need to click a button from the prompt to login.

Any further questions?

For support, please open an issue on Github at [2]

For community discussion, please post in the Moodle office tool integrations forum on moodle.org. Note: developers may or may not see questions in this forum thread.