Difference between revisions of "Office365"

Jump to: navigation, search
(Created page with "= Introduction = Office 365 services complement the Moodle learning platform to provide a more productive experience for teachers and students. = Requirements = To use the O...")
 
 
(36 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
{{Infobox plugin
 +
|type = set
 +
|set=https://moodle.org/plugins/browse.php?list=set&id=72
 +
|entry =
 +
https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/filter_oembed https://moodle.org/plugins/block_microsoft
 +
|tracker = https://github.com/Microsoft/o365-moodle/issues
 +
|discussion = https://moodle.org/mod/forum/view.php?id=8273
 +
|maintainer = See plugins directory entries
 +
|float = right
 +
}}
 +
{{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  =
 
= Introduction  =
 
Office 365 services complement the Moodle learning platform to provide a more productive experience for teachers and students.
 
Office 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 Office 365 authentication and basic OneDrive repository support, the Office 365 plugin suite provides a much wider set of features.
  
 +
A few key features only found in the Office 365 plugin suite:
 +
* User sync from Office 365/Azure AD to Moodle
 +
* Automatic and manual user matching from Office 365/Azure AD to Moodle
 +
* Calendar sync
 +
* Course to Office 365 group sync and shared file repositories
 +
* OneNote assignment submission and feedback types
 +
* Office document embedding using Office web apps
 +
* Fully customizable sign-in experience
 
= Requirements =
 
= Requirements =
 
To use the Office 365 plugins, you need the following:
 
To use the Office 365 plugins, you need the following:
 
* An Office 365 subscription.
 
* An Office 365 subscription.
 
* A Microsoft Azure subscription.
 
* A Microsoft Azure subscription.
* Moodle version 2.7 or above.
+
* Moodle version 3.1 or above.
  
 
= Plugins & Features =
 
= Plugins & Features =
The Office 365 set of plugins contains 7 different plugins which provide a wide variety of features to enhance your Moodle instance.
+
The Office 365 set of plugins contains 5 core plugins, and 3 optional plugins, which provide a wide variety of features to enhance your Moodle instance.
  
 
* '''Office 365 Local Plugin''' (local_office365)
 
* '''Office 365 Local Plugin''' (local_office365)
** This is a shell plugin which has dependencies on the current version of each of the other 6 plugins. 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 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 Office 365 accounts.
 
** This plugin allows users to log in to Moodle using their Office 365 accounts.
Line 27: Line 49:
 
*** Optional user-self-service connection and disconnection
 
*** 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.
 
**** 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.
* '''o365 local plugin''' (local_o365)
+
 
 +
* '''Office 365 support plugin''' (local_o365)
 
** This plugin provides most of the Office 365 integration back-end. This provides shared code to communicate with Office 365, and powers the calendar sync.
 
** This plugin provides most of the Office 365 integration back-end. This provides shared code to communicate with Office 365, and powers the calendar sync.
 
** Features
 
** Features
 
*** Calendar sync from/to Office 365 Outlook.
 
*** Calendar sync from/to Office 365 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.
*** SharePoint sites for each Moodle course.
+
*** User Sync and Matching
 +
**** Users can be synced from Azure AD, or matched with existing users.
 +
*** Course Groups
 +
**** Office 365 groups can be automatically created for each course in Moodle (or you can select which courses are used), and group membership is kept up-to-date with Moodle enrolments.
 +
*** SharePoint sites for each Moodle course (Deprecated)
 
**** 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.
 
**** 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.
 +
**** This feature is now deprecated. It is mainly used to provide shared document repositories for courses, which can now be accomplished by course groups.
 +
 +
* '''Microsoft Block''' (block_microsoft)
 +
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
 +
** Links to: Course SharePoint sites, Azure AD login preferences, Calendar sync preferences, OneNote notebooks, and the Office 365 integration user control panel.
 +
 
* '''OneDrive for Business Repository''' (repository_office 365)
 
* '''OneDrive for Business Repository''' (repository_office 365)
 
** 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.
Line 41: Line 74:
 
*** 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.
* '''o365 Profile Field''' (profilefield_o365)
+
 
** This profile field provides status information on a user's Office 365 connection and a link for users to manage their Office 365-related preferences.
+
== Optional Plugins ==
* '''OIDC Profile Field''' (profilefield_oidc)
+
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.
** This profile field provides status information on a user's OpenID Connect connection and a link for users to manage it.
+
 
 +
* '''OneNote support plugin''' (local_onenote)
 +
** This provides supporting and shared code used by all other OneNote plugins. Does not have an 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)
 
* '''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 =
 +
 +
Tooling and guidance on deploying Scalable Moodle Clusters on Azure
 +
* https://github.com/azure/moodle
  
 
= Setup =
 
= Setup =
Line 57: Line 106:
 
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
 
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
 
* GitHub
 
* GitHub
** https://github.com/MSOpenTech/moodle-local_office365
+
** http://github.com/microsoft/o365-moodle
** https://github.com/MSOpenTech/moodle-auth_oidc
 
** https://github.com/MSOpenTech/moodle-local_o365
 
** https://github.com/MSOpenTech/moodle-repository_office365
 
** https://github.com/MSOpenTech/moodle-profilefield_o365
 
** https://github.com/MSOpenTech/moodle-profilefield_oidc
 
** https://github.com/MSOpenTech/moodle-filter_oembed
 
  
When you log back in to your Moodle instance, you are presented with the all the plugin configuration options. Since you are installing the plugins as a package there are dependencies that have not yet been enabled. Save the settings without configuring them. 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]]
Line 72: Line 115:
 
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 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.
# In the Provider Name field type an end user-facing label that will inform a user of the type credentials her or she must use to login. This can be anything you choose.
+
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
# Verify the auth and token endpoints. These should be set by default but if not, set the endpoints to the following:
+
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Auth Endpoint:''' https://login.windows.net/common/oauth2/authorize
+
## '''Token Endpoint:''' https://login.microsoftonline.com/common/oauth2/token
## '''Token Endpoint:''' https://login.windows.net/common/oauth2/token
+
# 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.
# Note the Redirect URI. This should be the URI of the Moodle instance followed by /auth/oidc.
+
## For example, https://www.example.com/auth/oidc/
## For example, https:// www.bellowscollege.com/auth/oidc/
+
## Notes:
## '''Note:''' The Microsoft application redirect URL can only be the fully qualified domain name pointing to your Moodle instance.
+
### 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).
 +
### This URL must be a fully qualified domain name pointing to your Moodle instance.
 
### 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.
 
### 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.
### The redirect URL '''must use the same domain name''' as the domain used to access your Moodle instance.
 
 
### 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.
 
### 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.
  
Line 93: Line 136:
 
# Create a new Active Directory.
 
# Create a new Active Directory.
 
# Select Use existing directory.
 
# Select Use existing directory.
[[image:AddDirectory1.png|border|none|550px|Add directory dialog with creation options.]]
 
 
# Select '''I am ready to be signed out now''' and click the check mark.
 
# Select '''I am ready to be signed out now''' and click the check mark.
[[image:AddDirectory2.png|border|none|550px|Add directory dialog log out option.]]
 
 
# Sign in with your Office 365 subscription credentials.
 
# Sign in with your Office 365 subscription credentials.
 
# Click '''Continue'''.
 
# Click '''Continue'''.
Line 103: Line 144:
  
 
=== Register Application in Azure ===
 
=== Register Application in Azure ===
# Sign in to the [https://manage.windowsazure.com Microsoft Azure Management Portal].
+
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Active Directory''' icon on the left menu, and then click on the desired Office 365 connected Azure AD.
+
# Click on the '''Azure Active Directory''' link on the left menu, then '''App Registrations'''.
# On the top menu, click '''Applications'''. If no apps have been added to your directory, this page will only show the '''Add an App''' link. Click on the link, or alternatively you can click on the '''Add''' button on the command bar.
+
# Click '''New application registration''' on the top menu.
# On the '''What do you want to do''' page, click on the link to '''Add an application my organization is developing'''.
+
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# On the '''Tell us about your application''' page, you must specify a name for your application and indicate the type of application you are registering with Azure AD. Click '''web application and/or web API''' (default) and then click the arrow icon on the bottom-right corner of the page.
+
# Choose '''Web app/ API''' for the Application Type.
# On the App properties page, provide the '''Sign-on URL''' and '''App ID URI''' for your Moodle instance.
+
# The '''Sign-on URI''' is the Redirect URI you from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URL - i.e. https://example.com/auth/oidc/'''
## The Sign-on URI is the Redirect URI you from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URL - i.e. https://example.com/auth/oidc/'''
+
# Click '''Create'''.
## The APP ID URI is the main URI of the Moodle instance.
+
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.
# Click the checkbox in the bottom-right hand corner of the page and then click Ok to add your app to Azure Active Directory.
 
# There are a couple more values and changes you need to make and write down some values which you will need in the next section.
 
  
 
=== Configure application ===
 
=== Configure application ===
# Click on the '''Active Directory''' icon on the left menu, and then click on the desired Azure AD.
+
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click the Applications tab at the top of the screen.
+
# Click on the '''Azure Active Directory''' link on the left menu, then '''App Registrations'''.
# Select your app.
+
# Click on the App you created for Moodle.
# Click Configure at the top of the screen.
+
## You may need to change the dropdown from "My apps" to "All apps"
# Locate the '''Client ID''' and copy it to the '''Client ID''' field in your OpenID connect configuration screen.
+
# Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
# To create a Client Secret, locate the '''keys''' section and select a duration for the validity of the key. Save the new key and copy it to the '''Client Secret''' field in your OpenID connect configuration screen.
+
# Click on "Settings"
## [[image:SettingOpenIDConnect.png|border|none|550px|OpenID Connect Settings]]
+
# Create a client secret key.
# Locate the '''Permissions to other applications''' section.
+
## Click the '''Keys''' link, under "API Access".
# Click '''Add application''' click the plus sign to the right of Office 365 Exchange Online and Office 365 SharePoint Online. Note, the plus will appear when you hover over each of the items.
+
## Enter a description, and select a duration for "Expires"
# Click the check mark at the bottom right of the dialog.
+
## Click '''Save'''
# In the Delegated Permissions dropdown for Office 365 Exchange Online select the following permissions:
+
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
## Read users’ calendars
+
# Configure Permissions
## Read and write users' calendars
+
## Click the '''Required Permissions''' link under '''API Access'''.
# In the Delegated Permissions dropdown for Office 365 SharePoint Online select the following permissions:
+
## Click '''Add''' at the top of the pane.
## Read items in all site collections
+
## Click '''Select an API''', choose "Microsoft Graph", then click '''Select'''.
## Read and write items in all site collections
+
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections:  
## Create or delete items and lists in all site collections
+
{| class="nicetable"
## Have full control of all site collections
+
|-
## Read users' files
+
! Type
## Read and write users' files
+
! Name
# In the Application Permissions dropdown for Windows Azure Active Directory select the following permissions:
+
! Use
## Read directory data
+
|-
# In the Delegated Permissions dropdown for Windows Azure Active Directory select the following permissions:
+
| rowspan="7" | Application Permissions
## Read directory data
+
| '''Read and write domains'''
## Enable sign-on and read users' profiles
+
| Required to automatically detect your Office 365 tenant during setup.
# Click save at the bottom of the screen.
+
|-
 +
| '''Read and write all users' full profiles'''
 +
| Required to sync user information between Moodle and Office 365.
 +
|-
 +
| '''Read and write all OneNote notebooks'''
 +
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
 +
|-
 +
| '''Read and write all groups'''
 +
| Required for course group integration.
 +
|-
 +
| '''Read directory data'''
 +
| Required for setup detection and verification.
 +
|-
 +
| '''Read and write calendars in all mailboxes'''
 +
| Required for calendar event sync.
 +
|-
 +
| '''Read and write files in all site collections'''
 +
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
 +
|-
 +
| rowspan="10" | Delegated Permissions
 +
| '''Read and write all OneNote notebooks that user can access'''
 +
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
 +
|-
 +
| '''Sign in and read user profile'''
 +
| Required to sign users in using Office 365, and to access Office 365 APIs.
 +
|-
 +
| '''Read and write all users' full profiles'''
 +
| Required to sync user information between Moodle and Office 365.
 +
|-
 +
| '''Read and write all groups'''
 +
| Required for course group integration.
 +
|-
 +
| '''Read and write directory data'''
 +
| Required for setup detection and verification.
 +
|-
 +
| '''Access directory as the signed in user'''
 +
| Required to access Office 365 APIs.
 +
|-
 +
| '''Have full access to user calendars'''
 +
| Required for calendar event sync.
 +
|-
 +
| '''Have full access to user files'''
 +
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
 +
|-
 +
| '''Read items in all site collections'''
 +
| Required for SharePoint integration (deprecated)
 +
|-
 +
| '''Sign users in'''
 +
| Required to sign users in using Office 365 (required for all integration).
 +
|}
 +
'''When you're done, click save at the top of the screen.'''
  
 
=== Add a user to the app ===
 
=== Add a user to the app ===
# Click on the '''Active Directory''' icon on the left menu, and then click on the desired Azure AD.
+
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click the Applications tab at the top of the screen.
+
# Click on the '''Azure Active Directory''' link on the left menu, then '''App Registrations'''.
# Select your app.
+
# Click on the App you created for Moodle.
# Click the Users tab at the top of the screen.
+
## You may need to change the dropdown from "My apps" to "All apps"
# Select an Office 365 User to assign to assign to the App.
+
# Click the name of the app under '''Managed application in local directory'''
# Click Assign at the bottom of the screen.
+
# Click '''Users and groups''' under the '''Manage''' section.
# When prompted whether you are sure you want to enable access, click Yes.
+
# Add users to your application using the '''Add user''' button.
 +
 
 +
The application will appear in the [https://portal.office.com/myapps My apps] page of the application launcher on the o365 portal for the users which have been assigned.
 +
 
 +
=== Enter Azure application credentials into Moodle ===
 +
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
 +
# Navigate to the OpenID Connect authentication plugin's settings page (Site Administration > Plugins > Authentication > OpenID Connect)
 +
# Enter the '''Application ID''' value you noted earlier from Azure into the '''Application ID''' 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.
  
=== Configure the O365 plugin ===
+
=== Configure the Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins'''.
+
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Click '''Microsoft Office 365 Integration'''.
+
# Complete each of the steps as follows:
# In the '''AzureAD Tenant''' field type the subdomain of your Office 365 subscription.
+
# '''Choose connection method'''
## For example "contoso.onmicrosoft.com"
+
## Choose the method you want to use to connect to Office 365. Unless you have a special reason to use the System API user, choose '''Application access'''.
# In the '''OneDrive for Business''' field type the url you use to access OneDrive for Business. This can usually be determined from your AzureAD tenant.
+
## Click '''Save changes'''
## For example, if your tenant is "contoso.onmicrosoft.com", your OneDrive for Business URL is "contoso-my.sharepoint.com.
+
# '''Admin consent & additional information'''
# Click Save changes.
+
## '''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 Office 365. An administrator will have to log in, and then will be given the option to approve the new permissions.
# Click the '''System API User''' link and log in with an Azure AD user to use to perform operations that are not user-specific. We recommend that you select either the account of an administrator or create a dedicated account to use.
+
## '''Azure AD Tenant:''' This is the domain name that identifies your Office 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.
# Click Save changes.
+
## '''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/"
# In the '''SharePoint Link''' field, type the URL of a SharePoint site you'd like to use to connect to Moodle. As you type, Moodle will verify the URL. You should type a complete URL of a SharePoint subsite. If the subsite does not exist, Moodle will attempt to create it.
+
## Click Save changes.
## For example: http://contoso.sharepoint.com/moodle
+
# '''Verify Setup'''
# If you want to sync users from Azure AD to your Moodle instance, click the '''Select Sync users from Azure AD''' checkbox. This will create users in Moodle for each user in the Active Directory you registered the Moodle app with.
+
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
[[image:SettingsO365Integraton.png|border|none|550px|Office 365 Integration Settings]]
+
## 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 Office 365 ==
 
== Connecting users to Office 365 ==
Line 171: Line 269:
 
=== 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 Office 365 account credentials.
 
With this method, the user will log in to Moodle using their Office 365 account credentials.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[OpenID_Connect_Authentication_Plugin#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 [[OpenID_Connect_Authentication_Plugin#Migrating_an_existing_user]].
+
* 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 an Office 365 user. ===
 
=== Link a Moodle user to an Office 365 user. ===
 
Users in Moodle can also be linked to Office 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 Office 365 features.
 
Users in Moodle can also be linked to Office 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 Office 365 features.
# As the user, visit the user's profile page.
+
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Assuming all plugins are installed (specifically profilefield_o365), there should be an '''Office 365 Connection''' profile field listed. It should read '''You are not connected to Office 365.''' with a link reading '''Connect to Office 365'''
+
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click '''Connect to Office 365'''
+
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 Connection Management''' page, where you should see a connection status section with two indicators,one for '''Office 365 login''' and one for '''Office 365 connection'''.
+
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click '''Connect to Office 365''' next to the '''Office 365 Connection''' indicator.
+
# There will be a "Connection Status" indicator box on the right side of the screen, click the "Click here to connect" link.
 
# You will be brought to the AzureAD authentication screen. Log in with the Office 365 user's credentials you'd like to connect to the Moodle user you are logged in as.
 
# You will be brought to the AzureAD authentication screen. Log in with the Office 365 user's credentials you'd like to connect to the Moodle user you are logged in as.
# If login was successful, you will be brought back to the Office 365 Connection Management page, where the Office 365 connection indicator should now read '''Active'''.
+
# If login was successful, you will be brought back to the '''Office 365 / Moodle Control Panel''' page, where the Office 365 connection indicator should now read '''Active'''.
 
# This user is now connected to the Office 365 user.
 
# This user is now connected to the Office 365 user.
# To disconnect the Moodle user from the Office 365 user, click the '''Disconnect from Office 365''' link that appears next to the Office 365 connection indicator when the connection is active.
 
  
 
= Office 365 Integration Local Plugin =
 
= Office 365 Integration Local Plugin =
== Calendar sync ==
+
== Administrator Features and Settings ==
This feature allows users to sync their Moodle calendars with Office 365. Users can have events in their Moodle calendar appear in any Office 365 calendar, and have events created in Office 365 synced back to Moodle.
+
These features are accessible from the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft Office 365 Integration), on the '''Options''' 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 four 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 Office 365 credentials to log in to Moodle (using the OpenID Connect authentication plugin), and will be able to use all the features of the Office 365 plugin set.
 +
 
 +
==== 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 case-insentitive and ignore the Office 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 Office 365/Moodle integration features. The user's authentication method will not change unless the setting below is enabled.
 +
 
 +
==== Switch matched users to Office 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 Office 365 credentials. Note: Please ensure the OpenID Connect authentication plugin is enabled if you want to use this setting.
 +
 
 +
====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:
 +
# Click "Add Mapping"
 +
# In the row that appears, select an Azure field to bring into Moodle.
 +
# In the second column on the same row, select a Moodle field to copy the value into.
 +
# In the third colum 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.
 +
 
 +
To Delete A Mapping
 +
# Click the "X" button at the end of the row you want to delete.
 +
# Click "Save changes" at the bottom of the page.
 +
# Note this will only prevent future information syncing, it will not undo past operations.
 +
 
 +
=== Course Groups ===
 +
The course groups setting creates Office 365 groups for courses in Moodle.
 +
 
 +
Features:
 +
* Group membership is kept up-to-date with enrolments in Moodle.
 +
* Provides an easy was to address all users in a course from Office 365. For example, a teacher can share a document from OneDrive with all of their students by choosing the user group for their course - they don't have to choose each student individually.
 +
* Course group file stores are accessible from the Office 365 Moodle file repository plugin, allowing users to access group files from Moodle.
  
To use this feature:
+
The course groups option allows a great deal of customization. An administrator can choose to create groups 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 groups created, and choose which features are enabled for each group.
# As a user connected to Office 365 go to your profile and look for the "Manage" link next to "Office 365 connection".
 
## [[File:localo365calsync1.png|border|none|550px|User's profile showing o365 and OIDC profile fields]]
 
# Clicking the link should bring you to the "Office 365 Connection Management" page. This page is the main page for a user to manage their Office 365 integration features.
 
## [[File:localo365managementpage.png|border|none|550px|Office 365 Connection Management page]]
 
# On this page you should see a section called "Office 365 Features", under which you should see a "Outlook Calendar Sync" link.
 
# Click the "Outlook Calendar sync" link.
 
# From here, you should see a list of your available Moodle calendars. Click the checkmark next to the ones you'd like to sync.
 
## [[File:localo365calsyncindex.png|border|none|550px|Calendar sync selection page]]
 
## By default, the calendars will sync with your Office 365 "primary" calendar. You can choose a different calendar to sync with using the "Sync with" select box.
 
## [[File:localo365calsynccalselected.png|border|none|550px|Calendar sync options]]
 
# You can also choose to sync from Office 365 in to Moodle (or both from Moodle to Office 365 and from Office 365 to Moodle). This is done using the "Sync behavior" select box.
 
# Once you're subscribed to a calendar, wait for the site's cron function to run to sync older calendar events. However, new events should sync right away.
 
  
== User sync ==
+
Once enabled, new groups will be created every cron run for any enabled course that doesn't have a group set up. Once groups are set up, membership will be maintained automatically whenever someone joins or leaves a Moodle course.
Users from AzureAD can be automatically created in Moodle using the user sync option. This creates a Moodle account for every user in the connected Active Directory allowing you to manage and enrol users in Moodle without the user having to log in first. When the user does log in using the OpenID Connect authentication plugin and their Office 365 account, they will be logged in to the account created for them during the user sync.
 
  
To enable:
+
=== SharePoint Link ===
# Visit the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft Office 365 Integration).
+
'''This feature is deprecated and is likely to be removed in a future version.'''
# Under the "Options" section, look for the "Sync users from AzureAD" setting.
 
# Check the checkbox next to this setting.
 
# Users are synced in 200-user increments. Each time the user sync scheduled task runs, the next 200 users will be synced. When all users have been synced, the task will start again at the beginning and update the Moodle users' information based on the current information in AzureAD.
 
# By default the user sync scheduled task runs '''once per day''' at 1am. Meaning, by default, 200 users are synced per day. This may be too low for sites with lots of users, in which case you should increase the frequency of the scheduled task. For more information on managing scheduled tasks, see [[Scheduled_tasks]]. You may want to set this to run at every cron run for the initial sync on a large site - just remember to lessen the frequency once all users have been synced!
 
  
== SharePoint Connection ==
 
 
SharePoint sites can be created for each course on your Moodle site. You will provide a parent SharePoint site and subsites for each course will be automatically created. The document library for each of these subsites can then be accessed by teachers using the OneDrive for Business repository. This provides a shared store of files for a course, allowing teachers to collaborate on documents and share resources.
 
SharePoint sites can be created for each course on your Moodle site. You will provide a parent SharePoint site and subsites for each course will be automatically created. The document library for each of these subsites can then be accessed by teachers using the OneDrive for Business repository. This provides a shared store of files for a course, allowing teachers to collaborate on documents and share resources.
  
 
* Any AzureAD-connected Moodle user with the '''moodle/course:managefiles''' capability in a course will be able to access the document library from the repository.
 
* Any AzureAD-connected Moodle user with the '''moodle/course:managefiles''' capability in a course will be able to access the document library from the repository.
  
=== Setting up the SharePoint connection ===
+
==== Setting up the SharePoint connection ====
 
# Visit the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft Office 365 Integration).
 
# Visit the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft Office 365 Integration).
# Under the '''Setup''' section, look for the '''SharePoint Link''' setting.
+
# Under the '''Options''' tab, look for the '''SharePoint Link''' setting.
 
# Type in the URL of the parent SharePoint site you'd like to use for the course subsites.
 
# Type in the URL of the parent SharePoint site you'd like to use for the course subsites.
 
## This should be the entire URL to the SharePoint site - for example: '''https://contoso.sharepoint.com/moodle'''.
 
## This should be the entire URL to the SharePoint site - for example: '''https://contoso.sharepoint.com/moodle'''.
Line 232: Line 360:
 
# The SharePoint Link is set up during the Moodle cron, so ensure your Moodle cron is set up and running.
 
# The SharePoint Link is set up during the Moodle cron, so ensure your Moodle cron is set up and running.
  
== User Groups ==
+
===Office 365 for China===
User groups provide an easy way to share documents will all users of a course. For example, a teacher can share a document from OneDrie will all their students by choosing the user group for their course - they don't have to choose each student individually.
+
Office 365 in China differs slightly in some technical aspects. If you are using Office 365 for China, select this box to ensure everything will work properly.
 +
===Disable Office 365 OneNote===
 +
In earlier versions of the Office 365 plugin, the OneNote integration used a Microsoft account version of OneNote. This is separate from the OneNote now provided with your Office 365 subscription. If you are established in this version of OneNote, enable this setting. For everyone else, you can leave this setting off.
 +
===Enable 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.
 +
===Record debug messages===
 +
If you experience problems using any Office 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 Administation > Reports > Logs, changing the "All activities" select box to "Site errors", and clicking "Get these logs".
 +
===Minimum inexact username length to switch to Office 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.
 +
== Administrator Tools ==
 +
===Tenants===
 +
This tool allows you to add additional Office 365 tenants to be used with Moodle. Users from additional tenants can log-in to Moodle using their Office 365 account, and use features like calendar sync and the OneDrive repository.
 +
 
 +
===Health Check===
 +
If you are experiencing problems with any Office 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 Office 365 accounts. Each user in the system is listed alongside the Office 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 Office 365 users using a CSV file. Administrators can upload a CSV file containing, on each line, a Moodle username, and Office 365 username, and a 1 or 0 indicating whether to enable Office 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 Office 365 groups====
 +
Course groups are created from Moodle courses when using the course group feature. If a group is manually deleted from the Office 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.
  
You can have groups created and maintained automatically in Office 365 by enabling the "Create User Groups" setting. Once enabled, new groups will be created every cron run for any course that doesn't have a group set up. Once groups are set up, membership will be maintained automatically whenever someone joins or leaves a Moodle course.
+
== User Features ==
 +
=== Calendar sync ===
 +
This feature allows users to sync their Moodle calendars with Office 365. Users can have events in their Moodle calendar appear in any Office 365 calendar, and have events created in Office 365 synced back to Moodle.
  
 +
To use this feature:
 +
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
 +
# As a user connected to Office 365, visit a page where the Microsoft block is visible.
 +
# Click the "Configure Outlook sync" link in the Microsoft block.
 +
# From here, you should see a list of your available Moodle calendars. Click the checkmark next to the ones you'd like to sync.
 +
## By default, the calendars will sync with your Office 365 "primary" calendar. You can choose a different calendar to sync with using the "Sync with" select box.
 +
# You can also choose to sync from Office 365 in to Moodle (or both from Moodle to Office 365 and from Office 365 to Moodle). This is done using the "Sync behavior" select box.
 +
# Once you're subscribed to a calendar, wait for the site's cron function to run to sync older calendar events. However, new events should sync right away.
  
 
= OpenID Connect Authentication Plugin =
 
= OpenID Connect Authentication Plugin =
Line 245: Line 419:
 
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.
  
== Icon selection ==
+
== Settings ==
This plugin 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.
+
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 Office 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:
 +
# Enter a regular expression pattern that matches the usernames of users you want to allow.
 +
# Enter one pattern per line
 +
# If you enter multiple patterns a user will be allowed if they match ANY of the patterns.
 +
# The character "/" should be escaped with "\".
 +
# 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.
 +
 
 +
====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.
  
 
# Visit the plugin settings page (Site Administration > Plugins > Authentication > OpenID Connect)
 
# Visit the plugin settings page (Site Administration > Plugins > Authentication > OpenID Connect)
Line 277: Line 482:
 
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 Office 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 Office 365.
  
# Log in as the user to be migrated.
+
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Visit the user's profile.
+
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Locate the profile field that shows the configured Provider Name
+
# Click the '''Connect to Office 365''' link in the Microsoft block.
## We'll use Office 365 in this description, if you've configured a different provider name, replace "Office 365" with you provider name in the following instructions.
+
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the "Start using Office 365 to log in." link. You will be directed to the Office 365 Management page.
+
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# You will see an indicator saying "Office 365 login is: Disabled." and a link saying "Start using Office 365 to log in to Moodle."
 
 
# Click the "Start using Office 365 to log in to Moodle." link.
 
# Click the "Start using Office 365 to log in to Moodle." link.
 
# You will be redirected to Office 365 to log in. Log in with the account you'd like to link to the Moodle account you're using.
 
# You will be redirected to Office 365 to log in. Log in with the account you'd like to link to the Moodle account you're using.
Line 290: Line 494:
  
 
== Connecting existing Moodle users to Office 365 without changing login method ==
 
== Connecting existing Moodle users to Office 365 without changing login method ==
# Log in as the user to be migrated.
+
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Visit the user's profile.
+
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Locate the profile field that shows the configured Provider Name and the word "connection", for example "Office 365 Connection".
+
# Click the '''Connect to Office 365''' link in the Microsoft block.
## We'll use Office 365 in this description, if you've configured a different provider name, replace "Office 365" with you provider name in the following instructions.
+
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the "Connect to Office 365".
+
# There will be a "Connection Status" indicator box on the right side of the screen, click the "Click here to connect" link.
# You will be brought to the "Office 365 Connection Management" page
+
# You will be brought to the AzureAD authentication screen. Log in with the Office 365 user's credentials you'd like to connect to the Moodle user you are logged in as.
# You will see two indicators: "Office 365 login is: Disabled" and "Office 365 connection is: Not Connected".
 
## The first indicator shows whether you are using Office 365 to log in to Moodle. See the above section for migrating existing Moodle users to Office 365 login.
 
## The second indicator shows whether the Moodle user is connected to Office 365. If you are using Office 365 to log in to Moodle, you are also connected to Office 365. However, you can be connected to Office 365 without using Office 365 to log in to Moodle.
 
# Click the "Connect to Office 365" link.
 
# You will be redirected to Office 365 to log in. Log in with the account you'd like to link to the Moodle account you're using.
 
 
## '''NOTE:''' If you're already logged in to Office 365, you will not have to enter your credentials on the Office 365 login page. This Office 365 account will be linked to the Moodle account. Ensure you are logged in to the correct account, or log out of Office 365 first to show the Office 365 login screen.
 
## '''NOTE:''' If you're already logged in to Office 365, you will not have to enter your credentials on the Office 365 login page. This Office 365 account will be linked to the Moodle account. Ensure you are logged in to the correct account, or log out of Office 365 first to show the Office 365 login screen.
 +
# If login was successful, you will be brought back to the '''Office 365 / Moodle Control Panel''' page, where the Office 365 connection indicator should now read '''Active'''.
 
# The Moodle account is now linked to the Office 365 account and can use Office 365 features as that user.
 
# The Moodle account is now linked to the Office 365 account and can use Office 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.
Line 334: Line 534:
 
# Start as a user connected to Office 365 and who has access to modify a course.
 
# Start as a user connected to Office 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.
## [[File:repositoryoffice365addcourseactivity.png|border|none|550px|Adding a course activity]]
 
 
# Choose the "File" resource to add to the course.
 
# Choose the "File" resource to add to the course.
## [[File:repositoryoffice365choosefileresource.png|border|none|550px|Adding a file resource to a course]]
 
 
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
 
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
## [[File:repositoryoffice365addfile.png|border|none|550px|File resource settings page]]
 
 
# Choose the "OneDrive for Business" repository and choose your Office document.
 
# Choose the "OneDrive for Business" repository and choose your Office document.
 
# When you select a file, make sure "Create an alias/shortcut to the file" is selected, the click "Select this file"
 
# When you select a file, make sure "Create an alias/shortcut to the file" is selected, the click "Select this file"
## [[File:repositoryoffice365choosefile.png|border|none|550px|Selecting a file]]
 
 
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
 
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
## [[File:repositoryoffice365chooseembed.png|border|none|550px|Display option for a file resource]]
 
 
# 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.
## [[File:repositoryoffice365embeddeddoc.png|border|none|550px|Office document embedded into page]]
 
  
 
= OneNote =
 
= OneNote =
OneNote is now available through Office 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 Office 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 Office 365 tenant. This sometimes expedites to the process of adding the OneNote preview to your tenant. For more information on OneNote, see [[MicrosoftServices#Configuring_OneNote]]
+
OneNote is now available through Office 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 Office 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 Office 365 tenant. This sometimes expedites to the process of adding the OneNote preview to your tenant.  
 +
 
 +
=Any further questions?=
 +
 
 +
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.
 +
 
 +
[[es:Office365]]

Latest revision as of 09:00, 7 February 2019

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.


Contents

Introduction

Office 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 Office 365 authentication and basic OneDrive repository support, the Office 365 plugin suite provides a much wider set of features.

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

  • User sync from Office 365/Azure AD to Moodle
  • Automatic and manual user matching from Office 365/Azure AD to Moodle
  • Calendar sync
  • Course to Office 365 group sync and shared file repositories
  • OneNote assignment submission and feedback types
  • Office document embedding using Office web apps
  • Fully customizable sign-in experience

Requirements

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

  • An Office 365 subscription.
  • A Microsoft Azure subscription.
  • Moodle version 3.1 or above.

Plugins & Features

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

  • Office 365 Local Plugin (local_office365)
    • This is a shell plugin which has dependencies on the current version of each of the 5 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 Office 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.
    • 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.
      • 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.
  • Office 365 support plugin (local_o365)
    • This plugin provides most of the Office 365 integration back-end. This provides shared code to communicate with Office 365, and powers the calendar sync.
    • Features
      • Calendar sync from/to Office 365 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.
      • Course Groups
        • Office 365 groups can be automatically created for each course in Moodle (or you can select which courses are used), and group membership is kept up-to-date with Moodle enrolments.
      • SharePoint sites for each Moodle course (Deprecated)
        • 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.
        • This feature is now deprecated. It is mainly used to provide shared document repositories for courses, which can now be accomplished by course groups.
  • Microsoft Block (block_microsoft)
    • This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
    • Links to: Course SharePoint sites, Azure AD login preferences, Calendar sync preferences, OneNote notebooks, and the Office 365 integration user control panel.
  • OneDrive for Business Repository (repository_office 365)
    • 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.

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 an 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. These should be set by default but if not, set the endpoints to the following:
    1. Authorization Endpoint: https://login.microsoftonline.com/common/oauth2/authorize
    2. Token Endpoint: https://login.microsoftonline.com/common/oauth2/token
  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 AD later, so note this value and put it aside.
    1. For example, https://www.example.com/auth/oidc/
    2. 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 of the following reasons, you must change your Moodle site's configured domain name ($CFG->wwwroot).
      2. This URL must be a fully qualified domain name pointing to your Moodle instance.
      3. 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.
      4. 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 Office 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 Office 365 for SSO, you must configure Microsoft Azure to manage your Office 365 Microsoft Azure Active Directory:

  1. Create a new Active Directory.
  2. Select Use existing directory.
  3. Select I am ready to be signed out now and click the check mark.
  4. Sign in with your Office 365 subscription credentials.
  5. Click Continue.
  6. Log out and sign back in to your Azure account.

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

  1. Sign in to the Microsoft Azure Management Portal.
  2. Click on the Azure Active Directory link on the left menu, then App Registrations.
  3. Click New application 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 Web app/ API for the Application Type.
  6. The Sign-on URI is the Redirect URI you from the OpenID Connect authentication plugin configuration. Ensure there is a trailing slash for this URL - i.e. https://example.com/auth/oidc/
  7. Click Create.
  8. You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

Configure application

  1. Sign in to the Microsoft Azure Management Portal.
  2. Click on the Azure Active Directory link on the left menu, then App Registrations.
  3. Click on the App you created for Moodle.
    1. You may need to change the dropdown from "My apps" to "All apps"
  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 "Settings"
  6. Create a client secret key.
    1. Click the Keys link, under "API Access".
    2. Enter a description, and select a duration for "Expires"
    3. Click Save
    4. A value will appear under Value, note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
  7. Configure Permissions
    1. Click the Required Permissions link under API Access.
    2. Click Add at the top of the pane.
    3. Click Select an API, choose "Microsoft Graph", then click Select.
    4. Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections:
Type Name Use
Application Permissions Read and write domains Required to automatically detect your Office 365 tenant during setup.
Read and write all users' full profiles Required to sync user information between Moodle and Office 365.
Read and write all OneNote notebooks Required for the OneNote integration to create notebooks, sections, and pages for assignments.
Read and write all groups Required for course group integration.
Read directory data Required for setup detection and verification.
Read and write calendars in all mailboxes Required for calendar event sync.
Read and write files in all site collections Required for the Office 365 repository to access, download, and upload files to OneDrive.
Delegated Permissions Read and write all OneNote notebooks that user can access Required for the OneNote integration to create notebooks, sections, and pages for assignments.
Sign in and read user profile Required to sign users in using Office 365, and to access Office 365 APIs.
Read and write all users' full profiles Required to sync user information between Moodle and Office 365.
Read and write all groups Required for course group integration.
Read and write directory data Required for setup detection and verification.
Access directory as the signed in user Required to access Office 365 APIs.
Have full access to user calendars Required for calendar event sync.
Have full access to user files Required for the Office 365 repository to access, download, and upload files to OneDrive.
Read items in all site collections Required for SharePoint integration (deprecated)
Sign users in Required to sign users in using Office 365 (required for all integration).

When you're done, click save at the top of the screen.

Add a user to the app

  1. Sign in to the Microsoft Azure Management Portal.
  2. Click on the Azure Active Directory link on the left menu, then App Registrations.
  3. Click on the App you created for Moodle.
    1. You may need to change the dropdown from "My apps" to "All apps"
  4. Click the name of the app under Managed application in local directory
  5. Click Users and groups under the Manage section.
  6. Add users to your application using the Add user button.

The application will appear in the My apps page of the application launcher on the o365 portal for the users which have been assigned.

Enter Azure application credentials into Moodle

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

Configure the Office 365 support plugin

  1. Navigate to Site Administration > Plugins > Local plugins and click Microsoft Office 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 Office 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 Office 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 Office 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 Office 365

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

Switch the user to use OpenID Connect authentication.

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

Link a Moodle user to an Office 365 user.

Users in Moodle can also be linked to Office 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 Office 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 Office 365, visit a page that has the Microsoft block visible.
  3. Click the Connect to Office 365 link in the Microsoft block.
  4. You will be brought to the Office 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 Office 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 Office 365 / Moodle Control Panel page, where the Office 365 connection indicator should now read Active.
  8. This user is now connected to the Office 365 user.

Office 365 Integration Local Plugin

Administrator Features and Settings

These features are accessible from the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft Office 365 Integration), on the Options 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 four 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 Office 365 credentials to log in to Moodle (using the OpenID Connect authentication plugin), and will be able to use all the features of the Office 365 plugin set.

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 case-insentitive and ignore the Office 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 Office 365/Moodle integration features. The user's authentication method will not change unless the setting below is enabled.

Switch matched users to Office 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 Office 365 credentials. Note: Please ensure the OpenID Connect authentication plugin is enabled if you want to use this setting.

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 colum 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.

Course Groups

The course groups setting creates Office 365 groups for courses in Moodle.

Features:

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

The course groups option allows a great deal of customization. An administrator can choose to create groups 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 groups created, and choose which features are enabled for each group.

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

SharePoint Link

This feature is deprecated and is likely to be removed in a future version.

SharePoint sites can be created for each course on your Moodle site. You will provide a parent SharePoint site and subsites for each course will be automatically created. The document library for each of these subsites can then be accessed by teachers using the OneDrive for Business repository. This provides a shared store of files for a course, allowing teachers to collaborate on documents and share resources.

  • Any AzureAD-connected Moodle user with the moodle/course:managefiles capability in a course will be able to access the document library from the repository.

Setting up the SharePoint connection

  1. Visit the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft Office 365 Integration).
  2. Under the Options tab, look for the SharePoint Link setting.
  3. Type in the URL of the parent SharePoint site you'd like to use for the course subsites.
    1. This should be the entire URL to the SharePoint site - for example: https://contoso.sharepoint.com/moodle.
    2. This site must be accessible to the System API user
  4. When you are done typing in the URL, the URL will be checked for suitability.
    1. If the valid is invalid, you will see a red box and the text "This is not a usable SharePoint site."
    2. If the site already exists, you will see a blue box and the text "This site is usable, but already exists". You can use this site, but conflicts can arise. It's recommended to use a URL to a SharePoint site that doesn't yet exist. The site will be created during initialization.
    3. If the site does not exist but can be created, you will see a green box and the text "This SharePoint site will be created by Moodle and used for Moodle content.". This SharePoint site will be created by Moodle during initialization.
  5. Click Save changes at the bottom of the settings page.
  6. You will see a spinning icon below the SharePoint Link setting, and the text "Moodle is setting up this SharePoint site.". This will not automatically update - refresh the page to check if the connection has been set up..
  7. The SharePoint Link is set up during the Moodle cron, so ensure your Moodle cron is set up and running.

Office 365 for China

Office 365 in China differs slightly in some technical aspects. If you are using Office 365 for China, select this box to ensure everything will work properly.

Disable Office 365 OneNote

In earlier versions of the Office 365 plugin, the OneNote integration used a Microsoft account version of OneNote. This is separate from the OneNote now provided with your Office 365 subscription. If you are established in this version of OneNote, enable this setting. For everyone else, you can leave this setting off.

Enable 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.

Record debug messages

If you experience problems using any Office 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 Administation > Reports > Logs, changing the "All activities" select box to "Site errors", and clicking "Get these logs".

Minimum inexact username length to switch to Office 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.

Administrator Tools

Tenants

This tool allows you to add additional Office 365 tenants to be used with Moodle. Users from additional tenants can log-in to Moodle using their Office 365 account, and use features like calendar sync and the OneDrive repository.

Health Check

If you are experiencing problems with any Office 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 Office 365 accounts. Each user in the system is listed alongside the Office 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 Office 365 users using a CSV file. Administrators can upload a CSV file containing, on each line, a Moodle username, and Office 365 username, and a 1 or 0 indicating whether to enable Office 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 Office 365 groups

Course groups are created from Moodle courses when using the course group feature. If a group is manually deleted from the Office 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.

User Features

Calendar sync

This feature allows users to sync their Moodle calendars with Office 365. Users can have events in their Moodle calendar appear in any Office 365 calendar, and have events created in Office 365 synced back to Moodle.

To use this feature:

  1. Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
  2. As a user connected to Office 365, visit a page where the Microsoft block is visible.
  3. Click the "Configure Outlook sync" link in the Microsoft block.
  4. From here, you should see a list of your available Moodle calendars. Click the checkmark next to the ones you'd like to sync.
    1. By default, the calendars will sync with your Office 365 "primary" calendar. You can choose a different calendar to sync with using the "Sync with" select box.
  5. You can also choose to sync from Office 365 in to Moodle (or both from Moodle to Office 365 and from Office 365 to Moodle). This is done using the "Sync behavior" select box.
  6. Once you're subscribed to a calendar, wait for the site's cron function to run to sync older calendar events. However, new events should sync right away.

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 Office 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 Office 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 Office 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 Office 365 account information.

Using this flow:

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

Switching existing Moodle users to use Office 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 Office 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 Office 365 link in the Microsoft block.
  4. You will be brought to the Office 365 / Moodle Control Panel.
  5. Click the Office 365 Login link under Office 365 Features'
  6. Click the "Start using Office 365 to log in to Moodle." link.
  7. You will be redirected to Office 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 Office 365, you will not have to enter your credentials on the Office 365 login page. This Office 365 account will be linked to the Moodle account. Ensure you are logged in to the correct account, or log out of Office 365 first to show the Office 365 login screen.
  8. The Moodle account will now use Office 365 to log in. The previous login method will not work.
  9. The Moodle user can now use any of the Office 365 features in Moodle.

Connecting existing Moodle users to Office 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 Office 365 link in the Microsoft block.
  4. You will be brought to the Office 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 Office 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 Office 365, you will not have to enter your credentials on the Office 365 login page. This Office 365 account will be linked to the Moodle account. Ensure you are logged in to the correct account, or log out of Office 365 first to show the Office 365 login screen.
  7. If login was successful, you will be brought back to the Office 365 / Moodle Control Panel page, where the Office 365 connection indicator should now read Active.
  8. The Moodle account is now linked to the Office 365 account and can use Office 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 Office 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 Office 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 Office 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 Office 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 Office 365 tenant. This sometimes expedites to the process of adding the OneNote preview to your tenant.

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.