MoodleDocs - User contributions [en]

ad-hoc contributed reports

2021-09-03T08:59:16Z

Enovationdevteam: /* Most Active courses */

{{Sitewide reports}}
==User and Role Report==

===Count number of distinct learners and teachers enrolled per category (including all its sub categories)===
<code sql>SELECT COUNT(DISTINCT lra.userid) AS learners, COUNT(DISTINCT tra.userid) as teachers
FROM prefix_course AS c #, mdl_course_categories AS cats
LEFT JOIN prefix_context AS ctx ON c.id = ctx.instanceid
JOIN prefix_role_assignments AS lra ON lra.contextid = ctx.id
JOIN prefix_role_assignments AS tra ON tra.contextid = ctx.id
JOIN prefix_course_categories AS cats ON c.category = cats.id
WHERE c.category = cats.id
AND (
cats.path LIKE '%/CATEGORYID/%' #Replace CATEGORYID with the category id you want to count (eg: 80)
OR cats.path LIKE '%/CATEGORYID'
)
AND lra.roleid=5
AND tra.roleid=3</code>

===Detailed ACTIONs for each ROLE (TEACHER, NON-EDITING TEACHER and STUDENT)===
<code sql>
SELECT r.name, l.action, COUNT( l.userid ) AS counter
FROM prefix_log AS l
JOIN prefix_context AS context ON context.instanceid = l.course AND context.contextlevel = 50
JOIN prefix_role_assignments AS ra ON l.userid = ra.userid AND ra.contextid = context.id
JOIN prefix_role AS r ON ra.roleid = r.id
WHERE ra.roleid IN ( 3, 4, 5 )
GROUP BY roleid, l.action
</code>

===Student (user) COUNT in each Course===
Including (optional) filter by: year (if included in course fullname).
<code sql>
SELECT CONCAT('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',course.id,'">',course.fullname,'</a>') AS Course
,CONCAT('<a target="_new" href="%%WWWROOT%%/user/index.php?contextid=',context.id,'">Show users</a>') AS Users
, COUNT(course.id) AS Students
FROM prefix_role_assignments AS asg
JOIN prefix_context AS context ON asg.contextid = context.id AND context.contextlevel = 50
JOIN prefix_user AS user ON user.id = asg.userid
JOIN prefix_course AS course ON context.instanceid = course.id
WHERE asg.roleid = 5
# AND course.fullname LIKE '%2013%'
GROUP BY course.id
ORDER BY COUNT(course.id) DESC
</code>

=== Enrolment count in each Course ===

Shows the total number of enroled users of all roles in each course. Sorted by course name.

<code sql>
SELECT c.fullname, COUNT(ue.id) AS Enroled
FROM prefix_course AS c
JOIN prefix_enrol AS en ON en.courseid = c.id
JOIN prefix_user_enrolments AS ue ON ue.enrolid = en.id
GROUP BY c.id
ORDER BY c.fullname
</code>

===LIST of all site USERS by COURSE enrollment (Moodle 2.x)===

<code sql>
SELECT
user2.firstname AS Firstname,
user2.lastname AS Lastname,
user2.email AS Email,
user2.city AS City,
course.fullname AS Course
,(SELECT shortname FROM prefix_role WHERE id=en.roleid) as Role
,(SELECT name FROM prefix_role WHERE id=en.roleid) as RoleName

FROM prefix_course as course
JOIN prefix_enrol AS en ON en.courseid = course.id
JOIN prefix_user_enrolments AS ue ON ue.enrolid = en.id
JOIN prefix_user AS user2 ON ue.userid = user2.id
</code>

===Enrolled users,which did not login into the Course, even once (Moodle 2)===
Designed forMoodle 2 table structure and uses special plugin filter : %%FILTER_SEARCHTEXT:table.field%%

<code sql>
SELECT
user2.id as ID,
ul.timeaccess,
user2.firstname AS Firstname,
user2.lastname AS Lastname,
user2.email AS Email,
user2.city AS City,
user2.idnumber AS IDNumber,
user2.phone1 AS Phone,
user2.institution AS Institution,

IF (user2.lastaccess = 0,'never',
DATE_FORMAT(FROM_UNIXTIME(user2.lastaccess),'%Y-%m-%d')) AS dLastAccess

,(SELECT DATE_FORMAT(FROM_UNIXTIME(timeaccess),'%Y-%m-%d') FROM prefix_user_lastaccess WHERE userid=user2.id and courseid=c.id) as CourseLastAccess

,(SELECT r.name
FROM prefix_user_enrolments AS uenrol
JOIN prefix_enrol AS e ON e.id = uenrol.enrolid
JOIN prefix_role AS r ON e.id = r.id
WHERE uenrol.userid=user2.id and e.courseid = c.id) AS RoleName

FROM prefix_user_enrolments as ue
JOIN prefix_enrol as e on e.id = ue.enrolid
JOIN prefix_course as c ON c.id = e.courseid
JOIN prefix_user as user2 ON user2 .id = ue.userid
LEFT JOIN prefix_user_lastaccess as ul on ul.userid = user2.id
WHERE c.id=16 AND ul.timeaccess IS NULL
%%FILTER_SEARCHTEXT:user2.firstname%%
</code>

===Enrolled users who have never accessed a given course (simpler version)===

<code sql>
SELECT username, firstname, lastname, idnumber
FROM prefix_user_enrolments ue
JOIN prefix_enrol en ON ue.enrolid = en.id
JOIN prefix_user uu ON uu.id = ue.userid
WHERE en.courseid = 123456
AND NOT EXISTS (
SELECT * FROM prefix_user_lastaccess la
WHERE la.userid = ue.userid
AND la.courseid = en.courseid
)
</code>

(Replace 123456 near the middle with your courseid)

===Role assignments on categories===
<code sql>
SELECT
concat('<a target="_new" href="%%WWWROOT%%/course/category.php?id=',cc.id,'">',cc.id,'</a>') AS id,
concat('<a target="_new" href="%%WWWROOT%%/course/category.php?id=',cc.id,'">',cc.name,'</a>') AS category,
cc.depth, cc.path, r.name AS role,
concat('<a target="_new" href="%%WWWROOT%%/user/view.php?id=',usr.id,'">',usr.lastname,'</a>') AS name,
usr.firstname, usr.username, usr.email
FROM prefix_course_categories cc
INNER JOIN prefix_context cx ON cc.id = cx.instanceid
AND cx.contextlevel = '40'
INNER JOIN prefix_role_assignments ra ON cx.id = ra.contextid
INNER JOIN prefix_role r ON ra.roleid = r.id
INNER JOIN prefix_user usr ON ra.userid = usr.id
ORDER BY cc.depth, cc.path, usr.lastname, usr.firstname, r.name, cc.name
</code>

===Permissions Overides on Categories===
(By: [http://moodle.org/mod/forum/discuss.php?d=153059#p712834 Séverin Terrier] )
<code sql>
SELECT rc.id, ct.instanceid, ccat.name, rc.roleid, rc.capability, rc.permission,
DATE_FORMAT( FROM_UNIXTIME( rc.timemodified ) , '%Y-%m-%d' ) AS timemodified, rc.modifierid, ct.instanceid, ct.path, ct.depth
FROM `prefix_role_capabilities` AS rc
INNER JOIN `prefix_context` AS ct ON rc.contextid = ct.id
INNER JOIN `prefix_course_categories` AS ccat ON ccat.id = ct.instanceid
AND `contextlevel` =40
</code>

===Lists "Totally Opened Courses" (visible, opened to guests, with no password)===
(By: [http://moodle.org/mod/forum/discuss.php?d=153059#p712837 Séverin Terrier] )
<code sql>
SELECT
concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.id,'</a>') AS id,
concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.shortname,'</a>') AS 'Course',
concat('<a target="_new" href="%%WWWROOT%%/enrol/instances.php?id=',c.id,'">Méthodes inscription</a>') AS 'Enrollment plugins',
e.sortorder
FROM prefix_enrol AS e, prefix_course AS c
WHERE e.enrol='guest' AND e.status=0 AND e.password='' AND c.id=e.courseid AND c.visible=1
</code>

===Lists "loggedin users" from the last 120 days===
<code sql>
SELECT id,username,FROM_UNIXTIME(`lastlogin`) as days
FROM `prefix_user`
WHERE DATEDIFF( NOW(),FROM_UNIXTIME(`lastlogin`) ) < 120
</code>

''and user count for that same population:''
<code sql>
SELECT COUNT(id) as Users FROM `prefix_user`
WHERE DATEDIFF( NOW(),FROM_UNIXTIME(`lastlogin`) ) < 120
</code>

==== Users loggedin within the last 7 days ====
<code sql>
SELECT
l.* FROM mdl_logstore_standard_log l
WHERE
l.eventname = '\\core\\event\\user_loggedin'
AND FROM_UNIXTIME(l.timecreated, '%Y-%m-%d') >= DATE_SUB(NOW(), INTERVAL 7 DAY)

SELECT l.eventname FROM mdl_logstore_standard_log l
GROUP BY l.eventname
</code>

===Lists the users who have only logged into the site once===
<code sql>
SELECT id, username, firstname, lastname, idnumber
FROM prefix_user
WHERE prefix_user.deleted = 0
AND prefix_user.lastlogin = 0
AND prefix_user.lastaccess > 0
</code>

===Students in all courses of some institute===
What is the status (deleted or not) of all Students (roleid = 5) in all courses of some Institute
<code sql>
SELECT c.id, c.fullname, u.firstname, u.lastname, u.deleted
FROM prefix_course AS c
JOIN prefix_context AS ctx ON c.id = ctx.instanceid
JOIN prefix_role_assignments AS ra ON ra.contextid = ctx.id
JOIN prefix_user AS u ON u.id = ra.userid
WHERE ra.roleid =5
AND ctx.instanceid = c.id
AND u.institution = 'please enter school name here'
</code>

===Full User info (for deleted users)===
Including extra custom profile fields (from prefix_user_info_data)
<code sql>
SELECT *
FROM prefix_user as u
JOIN prefix_user_info_data as uid ON uid.userid = u.id
JOIN prefix_user_info_field as uif ON (uid.fieldid = uif.id AND uif.shortname = 'class')
WHERE `deleted` = "1" and `institution`="your school name" and `department` = "your department" and `data` = "class level and number"
</code>

===User's courses===
change "u.id = 2" with a new user id
<code sql>
SELECT u.firstname, u.lastname, c.id, c.fullname
FROM prefix_course AS c
JOIN prefix_context AS ctx ON c.id = ctx.instanceid
JOIN prefix_role_assignments AS ra ON ra.contextid = ctx.id
JOIN prefix_user AS u ON u.id = ra.userid
WHERE u.id = 2
</code>

===List Users with extra info (email) in current course===
blocks/configurable_reports replaces %%COURSEID%% with course id.
<code sql>
SELECT u.firstname, u.lastname, u.email
FROM prefix_role_assignments AS ra
JOIN prefix_context AS context ON context.id = ra.contextid AND context.contextlevel = 50
JOIN prefix_course AS c ON c.id = context.instanceid AND c.id = %%COURSEID%%
JOIN prefix_user AS u ON u.id = ra.userid
</code>

===List Students with enrollment and completion dates in current course===
This is meant to be a "global" report in Configurable Reports containing the following:
firstname, lastname, idnumber, institution, department, email, student enrolment date, student completion date
Note: for PGSQL, use to_timestamp() instead of FROM_UNIXTIME()
Contributed by Elizabeth Dalton, Moodle HQ

<code sql>
SELECT
u.firstname
, u.lastname
, u.idnumber
, u.institution
, u.department
, u.email
, FROM_UNIXTIME(cc.timeenrolled)
, FROM_UNIXTIME(cc.timecompleted)

FROM prefix_role_assignments AS ra
JOIN prefix_context AS context ON context.id = ra.contextid AND context.contextlevel = 50
JOIN prefix_course AS c ON c.id = context.instanceid AND c.id = %%COURSEID%%
JOIN prefix_user AS u ON u.id = ra.userid
JOIN prefix_course_completions AS cc ON cc.course = c.id AND cc.userid = u.id
</code>

===Special Roles===
<code sql>
SELECT ra.roleid,r.name
,concat('<a target="_new" href="%%WWWROOT%%/course/user.php?id=1&user=',ra.userid,'">',u.firstname ,' ',u.lastname,'</a>') AS Username
,concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.fullname,'</a>') AS Course
FROM prefix_role_assignments AS ra
JOIN prefix_role AS r ON r.id = ra.roleid
JOIN prefix_user AS u ON u.id = ra.userid
JOIN prefix_context AS ctx ON (ctx.id = ra.contextid AND ctx.contextlevel = 50)
JOIN prefix_course AS c ON ctx.instanceid = c.id
WHERE ra.roleid > 6
</code>

===Courses without Teachers===
Actually, shows the number of Teachers in a course.
<code sql>
SELECT concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.fullname,'</a>') as Course
,(SELECT Count( ra.userid ) AS Users FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid = 3 AND ctx.instanceid = c.id) AS Teachers
FROM prefix_course AS c
ORDER BY Teachers ASC
</code>

===List of users who have been enrolled for more than 4 weeks===
For Moodle 2.2 , by Isuru Madushanka Weerarathna
<code sql>
SELECT uenr.userid As User, IF(enr.courseid=uenr.courseid ,'Y','N') As Enrolled,
IF(DATEDIFF(NOW(), FROM_UNIXTIME(uenr.timecreated))>=28,'Y','N') As EnrolledMoreThan4Weeks
FROM prefix_enrol As enr, prefix_user_enrolments AS uenr
WHERE enr.id = uenr.enrolid AND enr.status = uenr.status
</code>

=== List of users with language===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

An issue with systems that do not have their default language set up properly is the need to do a mass change for all users to a localization. A common case (in the U.S., Canada and the Americas) is changing the default English to United States English.

This will show you the language setting for all users:
<code sql>
SELECT username, lang from prefix_user
</code>

NOTE: UPDATE commands require the ability to alter the database directly via tools like Adminer or PHPMyAdmin or other db tools.

This code will change the setting from 'en' to 'en_us' for all users:

<code sql>
UPDATE prefix_user SET lang = 'en_us' WHERE lang = 'en'
</code>

To do this for only users who have a particular country set, use this as an example:
<code sql>
UPDATE prefix_user SET lang = 'en_us' WHERE country = 'US' AND lang = 'en'
</code>

=== List of users with Authentication ===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

Sometimes you need to do mass changes of authentication methods. A common case is changing default manual to LDAP.

This will show you the Authentication setting for all users:
<code sql>
SELECT username, auth from prefix_user
</code>

NOTE: UPDATE commands require the ability to alter the database directly via tools like Adminer or PHPMyAdmin or other db tools.

This code will change the setting from 'manual' to 'ldap' for all users except for the first two accounts which are Guest and Admin. (WARNING: it is bad practice to change your admin account from manual to an external method as failure of that external method will lock you out of Moodle as admin.)

<code sql>
UPDATE prefix_user SET auth = 'ldap' WHERE auth = 'manual' AND id > 2
</code>

=== Compare role capability and permissions ===
Compatibility: MySQL and PostgreSQL

<code sql>
SELECT DISTINCT mrc.capability
,(SELECT 'X' FROM prefix_role_capabilities AS rc WHERE rc.capability = mrc.capability AND rc.roleid = '1' AND rc.contextid = '1') AS Manager
,(SELECT 'X' FROM prefix_role_capabilities AS rc WHERE rc.capability = mrc.capability AND rc.roleid = '2' AND rc.contextid = '1') AS Course_Creator
,(SELECT 'X' FROM prefix_role_capabilities AS rc WHERE rc.capability = mrc.capability AND rc.roleid = '3' AND rc.contextid = '1') AS Teacher
,(SELECT 'X' FROM prefix_role_capabilities AS rc WHERE rc.capability = mrc.capability AND rc.roleid = '4' AND rc.contextid = '1') AS Assistant_Teacher
,(SELECT 'X' FROM prefix_role_capabilities AS rc WHERE rc.capability = mrc.capability AND rc.roleid = '5' AND rc.contextid = '1') AS Student
,(SELECT 'X' FROM prefix_role_capabilities AS rc WHERE rc.capability = mrc.capability AND rc.roleid = '6' AND rc.contextid = '1') AS Guest
,(SELECT 'X' FROM prefix_role_capabilities AS rc WHERE rc.capability = mrc.capability AND rc.roleid = '7' AND rc.contextid = '1') AS Authenticated
,(SELECT 'X' FROM prefix_role_capabilities AS rc WHERE rc.capability = mrc.capability AND rc.roleid = '8' AND rc.contextid = '1') AS Auth_front
FROM prefix_role_capabilities AS mrc
</code>

=== User's accumulative time spent in course ===
A sum up of the time delta between logstore_standard_log user's records, considering the a 2 hour session limit.

Uses: current user's id %%USERID%% and current course's id %%COURSEID%%

And also using a date filter (which can be ignored)

The extra "User" field is used as a dummy field for the Line chart Series field, in which I use X=id, Series=Type, Y=delta.

<code sql>
SELECT
l.id,
l.timecreated,
DATE_FORMAT(FROM_UNIXTIME(l.timecreated),'%d-%m-%Y') AS dTime,
@prevtime := (SELECT max(timecreated) FROM mdl_logstore_standard_log
WHERE userid = %%USERID%% and id < l.id ORDER BY id ASC LIMIT 1) AS prev_time,
IF (l.timecreated - @prevtime < 7200, @delta := @delta + (l.timecreated-@prevtime),0) AS sumtime,
l.timecreated-@prevtime AS delta,
"User" as type

FROM prefix_logstore_standard_log as l,
(SELECT @delta := 0) AS s_init
# Change UserID
WHERE l.userid = %%USERID%% AND l.courseid = %%COURSEID%%
%%FILTER_STARTTIME:l.timecreated:>%% %%FILTER_ENDTIME:l.timecreated:<%%
</code>

=== Low-Participation Student Report ===
Contributed by Elizabeth Dalton, Granite State College / Moodle HQ

This report returns a list of students who are enrolled in courses filtered by a short-name text marker (in this case "OL-") in the specified category, but have very low participation in the course during the specified time period (fewer than 2 "Edits" to Activity Modules, indicating few active contributions to the course). The number of "Edits" is provided for each student for the time period specified.

An "Edit" is defined as course activity other than viewing content. Click the "Logs" link to review the student activity. The Logs offer the option to review "View" activity as well as "Edit" activity.

Only "visible" courses are included in this report. The report may be downloaded as an Excel spreadsheet.

Don't forget to set up Filters: "Start / End date filter" and "Filter categories" on the Filters tab in Configurable reports.

<code sql>
SELECT u.lastname AS Last, u.firstname AS First, u.idnumber AS IDnumber, u.email AS email, c.shortname AS CourseID, count(l.id) AS Edits, CONCAT('<a target="_new" href="https://learn.granite.edu/report/log/index.php',CHAR(63),'chooselog=1&showusers=1&showcourses=0&id=',c.id,'&user=',u.id,'&date=0&modid=&modaction=-view&logformat=showashtml','">','Logs','</a>') AS Link

FROM prefix_user AS u
JOIN prefix_role_assignments AS ra ON u.id = ra.userid
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
JOIN prefix_course AS c ON c.id = ctx.instanceid

LEFT JOIN prefix_log AS l ON l.userid = u.id AND l.course = c.id AND l.action NOT LIKE "view%" %%FILTER_STARTTIME:l.TIME:>%% %%FILTER_ENDTIME:l.TIME:<%%

WHERE ra.roleid =5
AND ctx.instanceid = c.id
AND c.visible=1
# This prefix filter allows the exclusion of non-online courses at the original institution. Alter this to fit your institution, or remove it.
AND c.shortname LIKE '%OL-%'
%%FILTER_CATEGORIES:c.category%%

GROUP BY u.idnumber

HAVING Edits < 2
</code>

=== Messages of All Users in a Specific Course ===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

NOTE: This query will probably not work at all in 3.5 now due to the changes in the structure of the Messages database. - RT

This query shows the personal messages between users in a specific course, given the course id number. Properly speaking, personal messages pertain only to users and are not part of courses, but by filtering enrollments for roles in a course, you can show this.

This report as is shows only the messages between Teachers and Students, as the WHERE statement contains and AND ((...))) section that restrict this report to ONLY messages between Teachers (role id = 3) and Students (role id =5). Remove that part of the statement if you wish to see _all_ messages between all users, e.g. teachers to teachers, student to student.

Also, if you have created custom roles, you can replace the default id numbers with custom ones to further enhance the report.

<code sql>
SELECT
u.username AS 'From',
CONCAT(u.firstname ,' ',u.lastname) AS 'From Name',
u2.username AS 'To',
CONCAT(u2.firstname ,' ',u2.lastname) AS 'To Name',
DATE_FORMAT(FROM_UNIXTIME(me.timecreated), '%Y-%m-%d %H:%i') AS 'When',
me.subject AS 'Subject',
me.smallmessage AS 'Message'
FROM prefix_message me
JOIN prefix_role_assignments AS ra ON ra.userid = me.useridfrom AND ra.roleid IN (3,4,5)
JOIN prefix_role_assignments AS ra2 ON ra2.userid = me.useridto AND ra2.roleid IN (3,4,5)
JOIN prefix_context AS ctx ON ra.contextid = ctx.id AND ra2.contextid = ctx.id
JOIN prefix_course AS c ON c.id = ctx.instanceid
JOIN prefix_user u ON u.id = me.useridfrom
JOIN prefix_user u2 ON u2.id = me.useridto
WHERE c.id=##
AND ((ra.roleid = 3 AND ra2.roleid = 5) OR (ra.roleid = 5 AND ra2.roleid = 3))
ORDER BY me.useridfrom, me.useridto, me.timecreated
</code>

===List of attendees/students that were marked present across courses===
This report will pull all Present students across a specific category.
Contributed by: Emma Richardson

<code sql>
SELECT u.firstname AS "First Name", u.lastname AS "Last Name", u.Institution AS "District",c.fullname AS "Training", DATE_FORMAT(FROM_UNIXTIME(att.sessdate),'%d %M %Y')AS Date

FROM prefix_attendance_sessions AS att
JOIN prefix_attendance_log AS attlog ON att.id = attlog.sessionid
JOIN prefix_attendance_statuses AS attst ON attlog.statusid = attst.id
JOIN prefix_attendance AS a ON att.attendanceid = a.id
JOIN prefix_course AS c ON a.course = c.id
JOIN prefix_user AS u ON attlog.studentid = u.id

WHERE attst.acronym = "P"
AND c.category = INSERT YOUR CATEGORY ID HERE
ORDER BY c.fullname
</code>

==Log Activity Reports==
===Count all Active Users by ROLE in a course category (including all of its sub-categories)===
<code sql>
SELECT COUNT(DISTINCT l.userid) as active
FROM mdl_course as c
JOIN mdl_context AS ctx ON ctx.instanceid=c.id
JOIN mdl_role_assignments AS ra ON ra.contextid = ctx.id
JOIN mdl_user_lastaccess as l ON ra.userid = l.userid
JOIN mdl_course_categories AS cats ON c.category = cats.id
WHERE c.category=cats.id AND (
cats.path LIKE '%/80/%'
OR cats.path LIKE '%/80'
)
AND ra.roleid=3 AND ctx.contextlevel=50 #ra.roleid= TEACHER 3, NON-EDITING TEACHER 4, STUDENT 5
AND l.timeaccess > (unix_timestamp() - ((60*60*24)*NO_OF_DAYS)) #NO_OF_DAYS change to number
</code>
===Detailed "VIEW" ACTION for each ROLE (TEACHER,NONE-EDITING TEACHER and STUDENT)===
<code sql>
SELECT l.action, count( l.userid ) as counter , r.name
FROM `prefix_log` as l
JOIN `prefix_role_assignments` AS ra on l.userid = ra.userid
JOIN `prefix_role` AS r ON ra.roleid = r.id
WHERE (ra.roleid IN (3,4,5)) AND (l.action LIKE '%view%' )
GROUP BY roleid,l.action
order by r.name,counter desc
</code>

===Total Activity of Roles:"Teacher" and "None-Editing Teacher" by Dates and by Hours===
The output columns of this report table can be used as base for a Pivot-Table
which will show the amount of '''activity''' per '''hour''' per '''days''' in 3D graph view.

<code sql>
SELECT DATE_FORMAT( FROM_UNIXTIME( l.time ) , '%Y-%m-%d' ) AS grptimed ,
DATE_FORMAT( FROM_UNIXTIME( l.time ) , '%k' ) AS grptimeh , count( l.userid ) AS counter
FROM `prefix_log` AS l
JOIN prefix_user AS u ON u.id = l.userid
JOIN prefix_role_assignments AS ra ON l.userid = ra.userid
JOIN prefix_role AS r ON r.id = ra.roleid
WHERE ra.roleid IN (3,4)
GROUP BY grptimed,grptimeh
ORDER BY grptimed,grptimeh
</code>

===How many LOGINs per user and user's Activity===
+ link username to a user activity graph report
<code sql>
SELECT concat('<a target="_new" href="%%WWWROOT%%/course/user.php?id=1&user=',u.id,'&mode=alllogs">',u.firstname ,' ',u.lastname,'</a>') as Username
,count(*) as logins
,(SELECT count(*) FROM prefix_log WHERE userid = l.userid GROUP BY userid) as Activity
FROM prefix_log as l JOIN prefix_user as u ON l.userid = u.id
WHERE `action` LIKE '%login%' group by userid
ORDER BY Activity DESC
</code>
===Distinct user logins per month===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

The following will show you the months of the current calendar year with the total number of distinct, unique user logins per month. Change the year in the WHERE clause to the year you need.

<code sql>
SELECT
COUNT(DISTINCT l.userid) AS 'DistinctUserLogins',
DATE_FORMAT(FROM_UNIXTIME(l.timecreated), '%M') AS 'Month'
FROM prefix_logstore_standard_log l
WHERE l.action = 'loggedin' AND YEAR(FROM_UNIXTIME(l.timecreated)) = '2017'
GROUP BY MONTH(FROM_UNIXTIME(l.timecreated))
</code>

===Total activity per course, per unique user on the last 24h===
<code sql>
SELECT
COUNT(DISTINCT userid) AS countUsers
, COUNT(l.courseid) AS countVisits
, CONCAT('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">', c.fullname, '</a>') AS Course

FROM mdl_logstore_standard_log AS l
JOIN mdl_course AS c ON c.id = l.courseid
WHERE l.courseid > 0
AND FROM_UNIXTIME(l.timecreated) >= DATE_SUB(NOW(), INTERVAL 1 DAY)
AND c.fullname LIKE '%תשעו%'
GROUP BY l.courseid
ORDER BY countVisits DESC
</code>

===Weekly Instructor Online Participation===
Contributed by Elizabeth Dalton, Granite State College

Displays participation of instructors in all courses per week of a term, including pre-term and post-term edits. An edit is defined as a change to the course, such as a discussion post, the grading of an assignment, or the uploading of file attachments, as well as alterations to course content.

* To specify a subject and/or course number, use % as a wildcard, e.g. ARTS% or ARTS501%
* To match part of a last name, use %, e.g. Smi% will match "Smith", "Smile", etc.

At our institution, we include filters on the course name or category to constrain by terms. These are very specific to how course names and categories are constructed at our institution, so I've removed those elements from this code. Also, our terms are 12 weeks long. You would want to insert additional "SUM" lines for longer terms, or remove lines for shorter terms.

'''Note''': This report can take a long time to run. While it can be run in Configurable Reports on demand, it may be more appropriate to implement it in the Ad Hoc Queries plugin as a scheduled report.

'''Note''': This version uses legacy (pre-2.7) logs. See below for post-2.7 Standard Logs version.

<code sql>
SELECT
c.shortname AS CourseID
, cc.name AS Category
, CONCAT(u.firstname ,' ',u.lastname) AS Instructor

, (SELECT COUNT( ra2.userid ) AS Users2 FROM prefix_role_assignments AS ra2
JOIN prefix_context AS ctx2 ON ra2.contextid = ctx2.id
WHERE ra2.roleid = 5 AND ctx2.instanceid = c.id) AS Students

, c.startdate AS Course_Start_Date

, c.visible AS Visible

, COUNT(l.id) AS Edits

, SUM(IF(WEEK(FROM_UNIXTIME(l.time)) - WEEK(FROM_UNIXTIME(c.startdate))<0,1,0)) AS BeforeTerm

, SUM(IF(WEEK(FROM_UNIXTIME(l.time))-WEEK(FROM_UNIXTIME(c.startdate))=0,1,0)) AS Week1
, SUM(IF(WEEK(FROM_UNIXTIME(l.time))-WEEK(FROM_UNIXTIME(c.startdate))=1,1,0)) AS Week2
, SUM(IF(WEEK(FROM_UNIXTIME(l.time))-WEEK(FROM_UNIXTIME(c.startdate))=2,1,0)) AS Week3
, SUM(IF(WEEK(FROM_UNIXTIME(l.time))-WEEK(FROM_UNIXTIME(c.startdate))=3,1,0)) AS Week4
, SUM(IF(WEEK(FROM_UNIXTIME(l.time))-WEEK(FROM_UNIXTIME(c.startdate))=4,1,0)) AS Week5
, SUM(IF(WEEK(FROM_UNIXTIME(l.time))-WEEK(FROM_UNIXTIME(c.startdate))=5,1,0)) AS Week6
, SUM(IF(WEEK(FROM_UNIXTIME(l.time))-WEEK(FROM_UNIXTIME(c.startdate))=6,1,0)) AS Week7
, SUM(IF(WEEK(FROM_UNIXTIME(l.time))-WEEK(FROM_UNIXTIME(c.startdate))=7,1,0)) AS Week8
, SUM(IF(WEEK(FROM_UNIXTIME(l.time))-WEEK(FROM_UNIXTIME(c.startdate))=8,1,0)) AS Week9
, SUM(IF(WEEK(FROM_UNIXTIME(l.time))-WEEK(FROM_UNIXTIME(c.startdate))=9,1,0)) AS Week10
, SUM(IF(WEEK(FROM_UNIXTIME(l.time))-WEEK(FROM_UNIXTIME(c.startdate))=10,1,0)) AS Week11
, SUM(IF(WEEK(FROM_UNIXTIME(l.time))-WEEK(FROM_UNIXTIME(c.startdate))=11,1,0)) AS Week12

, SUM(IF(WEEK(FROM_UNIXTIME(l.time))-WEEK(FROM_UNIXTIME(c.startdate))>=12,1,0)) AS AfterTerm

, CONCAT('<a target="_new" href="%%WWWROOT%%/report/log/index.php',CHAR(63),'chooselog=1&showusers=1&showcourses=0&id=',c.id,'&user=',u.id,'&date=0&modid=&modaction=&logformat=showashtml','">','Logs','</a>') AS Link

FROM prefix_user AS u
JOIN prefix_role_assignments AS ra ON u.id = ra.userid
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
JOIN prefix_course AS c ON c.id = ctx.instanceid
JOIN prefix_course_categories as cc ON c.category = cc.id

LEFT JOIN prefix_log AS l ON l.userid = u.id AND l.course = c.id AND l.action NOT LIKE "view%"

WHERE ra.roleid =3
AND ctx.instanceid = c.id
AND c.shortname LIKE :course
AND u.lastname LIKE :last_name

GROUP BY u.idnumber, c.id
HAVING students > 0
ORDER BY c.shortname
</code>

'''Note''': Post-2.7 log version:

<code sql>
SELECT
c.shortname AS CourseID
, cc.name AS Category
, CONCAT(u.firstname ,' ',u.lastname) AS Instructor

, (SELECT COUNT( ra2.userid ) AS Users2 FROM prefix_role_assignments AS ra2
JOIN prefix_context AS ctx2 ON ra2.contextid = ctx2.id
WHERE ra2.roleid = 5 AND ctx2.instanceid = c.id) AS Students

, FROM_UNIXTIME(c.startdate) AS Course_Start_Date

, c.visible AS Visible

, COUNT(DISTINCT l.id) AS Edits

, COUNT(DISTINCT IF((l.timecreated-c.startdate)<0,l.id,NULL)) AS 'Before Term'

, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=0,l.id,NULL)) AS 'Week 1'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=1,l.id,NULL)) AS 'Week 2'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=2,l.id,NULL)) AS 'Week 3'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=3,l.id,NULL)) AS 'Week 4'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=4,l.id,NULL)) AS 'Week 5'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=5,l.id,NULL)) AS 'Week 6'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=6,l.id,NULL)) AS 'Week 7'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=7,l.id,NULL)) AS 'Week 8'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=8,l.id,NULL)) AS 'Week 9'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=9,l.id,NULL)) AS 'Week 10'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=10,l.id,NULL)) AS 'Week 11'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=11,l.id,NULL)) AS 'Week 12'

, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))>=12,l.id,NULL)) AS 'After Term'

, CONCAT('<a target="_new" href="%%WWWROOT%%/report/log/index.php',CHAR(63),'chooselog=1&showusers=1&showcourses=0&id=',c.id,'&user=',u.id,'&date=0&modid=&modaction=&logformat=showashtml','">','Logs','</a>') AS Link

FROM prefix_user AS u
LEFT JOIN prefix_role_assignments AS ra ON u.id = ra.userid
LEFT JOIN prefix_context AS ctx ON ra.contextid = ctx.id
LEFT JOIN prefix_course AS c ON c.id = ctx.instanceid
LEFT JOIN prefix_course_categories as cc ON c.category = cc.id

LEFT JOIN prefix_logstore_standard_log AS l ON l.userid = u.id AND l.courseid = c.id AND l.crud IN ('c','u')

WHERE ra.roleid =3
AND ctx.instanceid = c.id
AND c.shortname LIKE '%OL-%'
AND cc.idnumber LIKE '%current%'

GROUP BY u.idnumber, c.id
#HAVING students > 0
ORDER BY RIGHT(c.shortname,2), c.shortname
</code>

===Weekly Student Online Participation===
Contributed by Elizabeth Dalton, Granite State College

Displays participation of students in the current course by week, including pre-term and post-term edits. An edit is defined as a change to the course, such as a discussion post, the submission of an assignment, or the completion of a quiz, as well as alterations to course content such as database entries (if permitted).

Links to three other reports are also provided:

* Logs: complete log entries for the student in the course, organized by date
* Activity Outline: the "Outline Report" from the User Activity Reports, summarizing the student's activity in the course, organized by course content
* Consolidated Activity Report: the "Complete Report" from the User Activity Reports, detailing the student's activity in the course, organized by course content (includes text of forum posts)

'''Note''': This should be defined as a "Global" report (visible from within all courses). At our institution, our terms are 12 weeks long. You would want to insert additional "SUM" lines for longer terms, or remove lines for shorter terms. We pull advisor names into student user profiles as part of our configuration. These lines are present in the code below, but are commented out, as they are very specific to your Moodle configuration.

'''Note''': This version of the report uses legacy (pre-2.7) logs. See below for a post-2.7 Standard Logs version.

<code sql>
SELECT
u.lastname AS 'Last Name'
, u.firstname AS 'First Name'
, COUNT(l.id) AS 'Edits'

, SUM(IF((l.time-c.startdate)/7<0,1,0)) AS 'Before Term'

, SUM(IF(FLOOR((l.time - c.startdate)/(60*60*24*7))=0,1,0)) AS 'Week 1'
, SUM(IF(FLOOR((l.time - c.startdate)/(60*60*24*7))=1,1,0)) AS 'Week 2'
, SUM(IF(FLOOR((l.time - c.startdate)/(60*60*24*7))=2,1,0)) AS 'Week 3'
, SUM(IF(FLOOR((l.time - c.startdate)/(60*60*24*7))=3,1,0)) AS 'Week 4'
, SUM(IF(FLOOR((l.time - c.startdate)/(60*60*24*7))=4,1,0)) AS 'Week 5'
, SUM(IF(FLOOR((l.time - c.startdate)/(60*60*24*7))=5,1,0)) AS 'Week 6'
, SUM(IF(FLOOR((l.time - c.startdate)/(60*60*24*7))=6,1,0)) AS 'Week 7'
, SUM(IF(FLOOR((l.time - c.startdate)/(60*60*24*7))=7,1,0)) AS 'Week 8'
, SUM(IF(FLOOR((l.time - c.startdate)/(60*60*24*7))=8,1,0)) AS 'Week 9'
, SUM(IF(FLOOR((l.time - c.startdate)/(60*60*24*7))=9,1,0)) AS 'Week 10'
, SUM(IF(FLOOR((l.time - c.startdate)/(60*60*24*7))=10,1,0)) AS 'Week 11'
, SUM(IF(FLOOR((l.time - c.startdate)/(60*60*24*7))=11,1,0)) AS 'Week 12'

, SUM(IF(FLOOR((l.time - c.startdate)/(60*60*24*7))>=15,1,0)) AS 'After Term'

, CONCAT('<a target="_blank" href="%%WWWROOT%%/report/log/index.php',CHAR(63),'chooselog=1&showusers=1&showcourses=0&id=',c.id,'&user=',u.id,'&date=0&modid=&modaction=&logformat=showashtml','">','Logs','</a>') AS 'Logs'

, CONCAT('<a target="_blank" href="%%WWWROOT%%/report/outline/user.php',CHAR(63),'id=',u.id,'&course=',c.id,'&mode=outline">','Outline','</a>') AS 'Activity Outline'

, CONCAT('<a target="_blank" href="%%WWWROOT%%/report/outline/user.php',CHAR(63),'id=',u.id,'&course=',c.id,'&mode=complete">','Activity','</a>') AS 'Consolidated Activity'

FROM prefix_user AS u
JOIN prefix_role_assignments AS ra ON u.id = ra.userid
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
JOIN prefix_course AS c ON c.id = ctx.instanceid
JOIN prefix_course_categories as cc ON c.category = cc.id

LEFT JOIN prefix_log AS l ON l.userid = u.id AND l.course = c.id AND l.action NOT LIKE "view%"

WHERE ra.roleid =5
AND ctx.instanceid = c.id

AND c.id = %%COURSEID%%

GROUP BY u.idnumber

ORDER BY u.lastname, u.firstname
</code>

'''Note''': Post-2.7 (Standard Logs) version

<code sql>
SELECT
u.lastname AS 'Last Name'
, u.firstname AS 'First Name'
, COUNT(l.id) AS 'Edits'

, COUNT(DISTINCT IF((l.timecreated-c.startdate)<0,l.id,NULL)) AS 'Before Term'

, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=0,l.id,NULL)) AS 'Week 1'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=1,l.id,NULL)) AS 'Week 2'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=2,l.id,NULL)) AS 'Week 3'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=3,l.id,NULL)) AS 'Week 4'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=4,l.id,NULL)) AS 'Week 5'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=5,l.id,NULL)) AS 'Week 6'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=6,l.id,NULL)) AS 'Week 7'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=7,l.id,NULL)) AS 'Week 8'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=8,l.id,NULL)) AS 'Week 9'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=9,l.id,NULL)) AS 'Week 10'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=10,l.id,NULL)) AS 'Week 11'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=11,l.id,NULL)) AS 'Week 12'

, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))>=12,l.id,NULL)) AS 'After Term'

# Our institution stores academic advisor names and emails in custom profile fields
#, CONCAT('<a href="mailto:',uce.data,'">',uid.data, '</a>') AS 'Academic Advisor'

, CONCAT('<a target="_blank" href="%%WWWROOT%%/report/log/index.php',CHAR(63),'chooselog=1&showusers=1&showcourses=0&id=',c.id,'&user=',u.id,'&date=0&modid=&modaction=&logformat=showashtml','">','Logs','</a>') AS 'Logs'

, CONCAT('<a target="_blank" href="%%WWWROOT%%/report/outline/user.php',CHAR(63),'id=',u.id,'&course=',c.id,'&mode=outline">','Outline','</a>') AS 'Activity Outline'

, CONCAT('<a target="_blank" href="%%WWWROOT%%/report/outline/user.php',CHAR(63),'id=',u.id,'&course=',c.id,'&mode=complete">','Activity','</a>') AS 'Consolidated Activity'

, CONCAT('<a target="_blank" href="%%WWWROOT%%/mod/forum/user.php',CHAR(63),'id=',u.id,'&course=',c.id,'">','Posts','</a>') AS 'Posts'

FROM prefix_user AS u
JOIN prefix_role_assignments AS ra ON u.id = ra.userid
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
JOIN prefix_course AS c ON c.id = ctx.instanceid
JOIN prefix_course_categories as cc ON c.category = cc.id

# student academic coach - you can include custom profile field data with these methods
# LEFT JOIN prefix_user_info_data as uid ON u.id = uid.userid AND uid.fieldid = '2'
# student academic coach email
# LEFT JOIN prefix_user_info_data as uce on u.id = uce.userid AND uce.fieldid = '6'

LEFT JOIN prefix_logstore_standard_log AS l ON l.userid = u.id AND l.courseid = c.id AND l.crud IN ('c','u')

WHERE ra.roleid =5
AND ctx.instanceid = c.id

AND c.id = %%COURSEID%%

GROUP BY u.idnumber

ORDER BY u.lastname, u.firstname
</code>

===My Weekly Online Participation===
Contributed by Elizabeth Dalton, Granite State College

Displays participation of the '''current user''' in the '''current course''' by week, including pre-term and post-term submissions/edits. A submission/edit is defined as a change to the course, such as a discussion post, the submission of an assignment, or the completion of a quiz, as well as alterations to course content such as database entries or new course activities or resources (if permitted).

This report uses Standard Logs (post 2.7).

<code sql>
SELECT

l.component AS 'activity'

, COUNT(DISTINCT IF((l.timecreated-c.startdate)<0,l.id,NULL)) AS 'Before Term'

, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=0,l.id,NULL)) AS 'Week 1'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=1,l.id,NULL)) AS 'Week 2'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=2,l.id,NULL)) AS 'Week 3'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=3,l.id,NULL)) AS 'Week 4'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=4,l.id,NULL)) AS 'Week 5'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=5,l.id,NULL)) AS 'Week 6'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=6,l.id,NULL)) AS 'Week 7'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=7,l.id,NULL)) AS 'Week 8'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=8,l.id,NULL)) AS 'Week 9'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=9,l.id,NULL)) AS 'Week 10'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=10,l.id,NULL)) AS 'Week 11'
, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))=11,l.id,NULL)) AS 'Week 12'

, COUNT(DISTINCT IF(FLOOR((l.timecreated - c.startdate)/(60*60*24*7))>=12,l.id,NULL)) AS 'After Term'

, COUNT(l.id) AS 'Total'

FROM prefix_user AS u
JOIN prefix_role_assignments AS ra ON u.id = ra.userid
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
JOIN prefix_course AS c ON c.id = ctx.instanceid
JOIN prefix_course_categories as cc ON c.category = cc.id

LEFT JOIN prefix_logstore_standard_log AS l ON l.userid = u.id AND l.courseid = c.id AND l.crud IN ('c','u')

WHERE 1
AND ctx.instanceid = c.id

AND c.id = %%COURSEID%%
AND u.id = %%USERID%%

GROUP BY l.component

ORDER BY l.component
</code>

===Faculty/Student Interactions===
Contributed by Elizabeth Dalton, Granite State College

Returns a count of instructor and other-student responses to student activity for the specified time period. This report can help indicate whether students' comments are being responded to, as well as summarizing post activity by students during the specified time.

'''Note''': This version of the report uses legacy (pre-2.7) logs. See below for the post-2.7 Standard Logs version.

'''Note''': This should be defined as a "Global" report (visible from within all courses).

'''Note''': This report can take a long time to run.

<code sql>
SELECT

# Identify student
CONCAT('<a target="_blank" href="%%WWWROOT%%/message/index.php?id=' , allstu.id , '">' , allstu.firstname , ' ' , allstu.lastname , '</a>' ) AS 'Student - click to send message'

, IF((COUNT(DISTINCT IF(fps.created > (UNIX_TIMESTAMP() - (7*24*60*60)),fps.id,NULL) )>0) OR (COUNT(DISTINCT IF(asb.timemodified > (UNIX_TIMESTAMP() - (7*24*60*60)),asb.id,NULL))>0) OR (SELECT COUNT(DISTINCT mfs.id) FROM prefix_message AS mfs WHERE mfs.useridfrom = allstu.id AND mfs.useridto = instr.id AND mfs.timecreated > (UNIX_TIMESTAMP() - (7*24*60*60))),'YES','NO') AS 'Student Participated This week'

, IF((COUNT(DISTINCT IF(fpi.created > (UNIX_TIMESTAMP() - (7*24*60*60)),fpi.id,NULL) )>0) OR (COUNT(DISTINCT IF(asg.timemodified > (UNIX_TIMESTAMP() - (7*24*60*60)),asg.id,NULL))>0) OR (SELECT COUNT(DISTINCT mts.id) FROM prefix_message AS mts WHERE mts.useridfrom = instr.id AND mts.useridto = allstu.id AND mts.timecreated > (UNIX_TIMESTAMP() - (7*24*60*60))),'YES','NO') AS 'Student Contacted This week'

## Only posts within last 7 days

# Count posts by student
, COUNT(DISTINCT IF(fps.created > (UNIX_TIMESTAMP() - (7*24*60*60)),fps.id,NULL)) AS 'Forum Stu Posts - 7 days'

# Count replies to student posts by instructors
, COUNT(DISTINCT IF(fpi.created > (UNIX_TIMESTAMP() - (7*24*60*60)),fpi.id,NULL) ) AS 'Forum Instr Replies - 7 days'

# using link back to student posts on replies, get unique student IDs responded
, COUNT(DISTINCT IF(fpsr.created > (UNIX_TIMESTAMP() - (7*24*60*60)),fpsr.id,NULL)) - COUNT(DISTINCT IF(fpi.created > (UNIX_TIMESTAMP() - (7*24*60*60)),fpi.id,NULL) ) AS 'Forum Stu Replies - 7 days'

# all replies
, COUNT(DISTINCT IF(fpsr.created > (UNIX_TIMESTAMP() - (7*24*60*60)),fpsr.id,NULL)) AS 'Forum All Replies - 7 days'

# add in count of graded assignments - 7 days
, COUNT(DISTINCT IF(asb.timemodified > (UNIX_TIMESTAMP() - (7*24*60*60)),asb.id,NULL)) AS 'Assign Submit - 7 days'
, COUNT(DISTINCT IF(asg.timemodified > (UNIX_TIMESTAMP() - (7*24*60*60)),asg.id,NULL)) AS 'Assign Grades - 7 days'

# Messages between students and instructors - 7 days
, (SELECT COUNT(DISTINCT mfs.id) FROM prefix_message AS mfs WHERE mfs.useridfrom = allstu.id AND mfs.useridto = instr.id AND mfs.timecreated > (UNIX_TIMESTAMP() - (7*24*60*60))) AS 'Msg Stu to Instr - 7 days'
, (SELECT COUNT(DISTINCT mts.id) FROM prefix_message AS mts WHERE mts.useridfrom = instr.id AND mts.useridto = allstu.id AND mts.timecreated > (UNIX_TIMESTAMP() - (7*24*60*60))) AS 'Msg Instr to Stu - 7 days'

## All posts in course so far
# Count posts by student
, COUNT(DISTINCT fps.id) AS 'Forum Stu Posts - to date'

# Count replies to student posts by instructors
, COUNT(DISTINCT fpi.id) AS 'Forum Instr Replies - to date'

# using link back to student posts on replies, get unique student IDs responded
, COUNT(DISTINCT fpsr.id) - COUNT(DISTINCT fpi.id) AS 'Forum Stu Replies - to date'

# all replies
, COUNT(DISTINCT fpsr.id) AS 'Forum All Replies - to date'

# add in count of graded assignments - whole course
, COUNT(DISTINCT asb.id) AS 'Assign Submit - to date'
, COUNT(DISTINCT asg.id) AS 'Assign Grades - to date'

# Messages between students and instructors - to date
, (SELECT COUNT(DISTINCT mfs.id) FROM prefix_message AS mfs WHERE mfs.useridfrom = allstu.id AND mfs.useridto = instr.id ) AS 'Msg Stu to Instr - to date'
, (SELECT COUNT(DISTINCT mts.id) FROM prefix_message AS mts WHERE mts.useridfrom = instr.id AND mts.useridto = allstu.id) AS 'Msg Instr to Stu - to date'

## JOINS

# Start by getting all the students in the course
FROM prefix_user AS allstu
JOIN prefix_role_assignments AS ras ON allstu.id = ras.userid AND ras.roleid = 5
JOIN prefix_context AS ctx ON ras.contextid = ctx.id
JOIN prefix_course AS c ON c.id = ctx.instanceid
JOIN prefix_course_categories as cc ON c.category = cc.id

# Now we get the forums and forum discussions from this course only
LEFT JOIN prefix_forum AS frm ON frm.course = c.id AND c.id = %%COURSEID%%
LEFT JOIN prefix_forum_discussions AS fd ON fd.course = %%COURSEID%% AND fd.forum = frm.id

# These are forum discussion posts just by students within specified time
LEFT JOIN prefix_forum_posts AS fps ON fps.userid = allstu.id AND fps.discussion = fd.id

# Separately, we connect the instructors of the courses
# We can use the context we have already gotten for the students
LEFT JOIN prefix_role_assignments AS rai ON rai.contextid = ctx.id
LEFT JOIN prefix_user AS instr ON instr.id = rai.userid AND rai.roleid =3

# Now we will connect to posts by instructors that are replies to student posts
# This is a left join, because we don't want to eliminate any students from the list
LEFT JOIN prefix_forum_posts AS fpi ON fpi.discussion = fd.id AND fpi.userid = instr.id AND fpi.parent = fps.id

# To get identities of only those students who were replied to:
# Connect from instr replies back up to parent posts by students again
# This has to be a LEFT JOIN, we know these posts exist but don't eliminate non-responded students
LEFT JOIN prefix_forum_posts AS fpir ON fpir.id = fpi.parent

# We also want to know if students are replying to one another
# These are posts that are replies to student posts
# Again, a left join
LEFT JOIN prefix_forum_posts AS fpsr ON fpsr.discussion = fd.id AND fpsr.parent = fps.id

# get the activity modules
LEFT JOIN prefix_course_modules AS cm ON c.id = cm.course

# get the assignments
LEFT JOIN prefix_assign AS a ON cm.instance = a.id
LEFT JOIN prefix_assign_submission AS asb ON a.id = asb.assignment AND asb.userid=allstu.id
LEFT JOIN prefix_assign_grades AS asg ON asg.assignment = a.id AND asg.userid = allstu.id AND asg.assignment = asb.assignment

# We care about messages that involve both the instructor and students of this course
# messages from instructor to students:
# LEFT JOIN prefix_message AS mts ON mts.useridfrom = instr.id AND mts.useridto = allstu.id
# LEFT JOIN prefix_message AS mfs ON mfs.useridfrom = instr.id AND mfs.useridto = allstu.id

WHERE
c.id = %%COURSEID%%

# GROUP BY c.shortname , allstu.id
GROUP BY allstu.id

ORDER BY allstu.lastname
</code>

'''Note''': Post-2.7 Standard Logs version

<code sql>
SELECT

# Identify student
CONCAT('<a target="_blank" href="%%WWWROOT%%/message/index.php?id=' , allstu.id , '">' , allstu.firstname , ' ' , allstu.lastname , '</a>' ) AS 'Student - click to send message'

, IF((COUNT(DISTINCT IF(fps.created > (UNIX_TIMESTAMP() - (7*24*60*60)),fps.id,NULL) )>0) OR (COUNT(DISTINCT IF(asb.timemodified > (UNIX_TIMESTAMP() - (7*24*60*60)),asb.id,NULL))>0) OR (SELECT COUNT(DISTINCT mfs.id) FROM prefix_message AS mfs WHERE mfs.useridfrom = allstu.id AND mfs.useridto = instr.id AND mfs.timecreated > (UNIX_TIMESTAMP() - (7*24*60*60))),'YES','NO') AS 'Student Participated This week'

, IF((COUNT(DISTINCT IF(fpi.created > (UNIX_TIMESTAMP() - (7*24*60*60)),fpi.id,NULL) )>0) OR (COUNT(DISTINCT IF(asg.timemodified > (UNIX_TIMESTAMP() - (7*24*60*60)),asg.id,NULL))>0) OR (SELECT COUNT(DISTINCT mts.id) FROM prefix_message AS mts WHERE mts.useridfrom = instr.id AND mts.useridto = allstu.id AND mts.timecreated > (UNIX_TIMESTAMP() - (7*24*60*60))),'YES','NO') AS 'Student Contacted This week'

## Only posts within last 7 days

# Count posts by student
, COUNT(DISTINCT IF(fps.created > (UNIX_TIMESTAMP() - (7*24*60*60)),fps.id,NULL)) AS 'Forum Stu Posts - 7 days'

# Count replies to student posts by instructors
, COUNT(DISTINCT IF(fpi.created > (UNIX_TIMESTAMP() - (7*24*60*60)),fpi.id,NULL) ) AS 'Forum Instr Replies - 7 days'

# using link back to student posts on replies, get unique student IDs responded
, COUNT(DISTINCT IF(fpsr.created > (UNIX_TIMESTAMP() - (7*24*60*60)),fpsr.id,NULL)) - COUNT(DISTINCT IF(fpi.created > (UNIX_TIMESTAMP() - (7*24*60*60)),fpi.id,NULL) ) AS 'Forum Stu Replies - 7 days'

# all replies
, COUNT(DISTINCT IF(fpsr.created > (UNIX_TIMESTAMP() - (7*24*60*60)),fpsr.id,NULL)) AS 'Forum All Replies - 7 days'

# add in count of graded assignments - 7 days
, COUNT(DISTINCT IF(asb.timemodified > (UNIX_TIMESTAMP() - (7*24*60*60)),asb.id,NULL)) AS 'Assign Submit - 7 days'
, COUNT(DISTINCT IF(asg.timemodified > (UNIX_TIMESTAMP() - (7*24*60*60)),asg.id,NULL)) AS 'Assign Grades - 7 days'

# Messages between students and instructors - 7 days
, (SELECT COUNT(DISTINCT mfs.id) FROM prefix_message AS mfs WHERE mfs.useridfrom = allstu.id AND mfs.useridto = instr.id AND mfs.timecreated > (UNIX_TIMESTAMP() - (7*24*60*60))) AS 'Msg Stu to Instr - 7 days'
, (SELECT COUNT(DISTINCT mts.id) FROM prefix_message AS mts WHERE mts.useridfrom = instr.id AND mts.useridto = allstu.id AND mts.timecreated > (UNIX_TIMESTAMP() - (7*24*60*60))) AS 'Msg Instr to Stu - 7 days'

## All posts in course so far
# Count posts by student
, COUNT(DISTINCT fps.id) AS 'Forum Stu Posts - to date'

# Count replies to student posts by instructors
, COUNT(DISTINCT fpi.id) AS 'Forum Instr Replies - to date'

# using link back to student posts on replies, get unique student IDs responded
, COUNT(DISTINCT fpsr.id) - COUNT(DISTINCT fpi.id) AS 'Forum Stu Replies - to date'

# all replies
, COUNT(DISTINCT fpsr.id) AS 'Forum All Replies - to date'

# add in count of graded assignments - whole course
, COUNT(DISTINCT asb.id) AS 'Assign Submit - to date'
, COUNT(DISTINCT asg.id) AS 'Assign Grades - to date'

# Messages between students and instructors - to date
, (SELECT COUNT(DISTINCT mfs.id) FROM prefix_message AS mfs WHERE mfs.useridfrom = allstu.id AND mfs.useridto = instr.id ) AS 'Msg Stu to Instr - to date'
, (SELECT COUNT(DISTINCT mts.id) FROM prefix_message AS mts WHERE mts.useridfrom = instr.id AND mts.useridto = allstu.id) AS 'Msg Instr to Stu - to date'

## JOINS

# Start by getting all the students in the course
FROM prefix_user AS allstu
JOIN prefix_role_assignments AS ras ON allstu.id = ras.userid AND ras.roleid = 5
JOIN prefix_context AS ctx ON ras.contextid = ctx.id
JOIN prefix_course AS c ON c.id = ctx.instanceid
JOIN prefix_course_categories as cc ON c.category = cc.id

# Now we get the forums and forum discussions from this course only
JOIN prefix_forum AS frm ON frm.course = c.id AND c.id = %%COURSEID%%
JOIN prefix_forum_discussions AS fd ON fd.course = %%COURSEID%% AND fd.forum = frm.id

# These are forum discussion posts just by students within specified time
LEFT JOIN prefix_forum_posts AS fps ON fps.userid = allstu.id AND fps.discussion = fd.id

# Separately, we connect the instructors of the courses
# We can use the context we have already gotten for the students
JOIN prefix_role_assignments AS rai ON rai.contextid = ctx.id
JOIN prefix_user AS instr ON instr.id = rai.userid AND rai.roleid =3

# Now we will connect to posts by instructors that are replies to student posts
# This is a left join, because we don't want to eliminate any students from the list
LEFT JOIN prefix_forum_posts AS fpi ON fpi.discussion = fd.id AND fpi.userid = instr.id AND fpi.parent = fps.id

# To get identities of only those students who were replied to:
# Connect from instr replies back up to parent posts by students again
# This has to be a LEFT JOIN, we know these posts exist but don't eliminate non-responded students
LEFT JOIN prefix_forum_posts AS fpir ON fpir.id = fpi.parent

# We also want to know if students are replying to one another
# These are posts that are replies to student posts
# Again, a left join
LEFT JOIN prefix_forum_posts AS fpsr ON fpsr.discussion = fd.id AND fpsr.parent = fps.id

# get the activity modules
JOIN prefix_course_modules AS cm ON c.id = cm.course

# get the assignments
JOIN prefix_assign AS a ON cm.instance = a.id
LEFT JOIN prefix_assign_submission AS asb ON a.id = asb.assignment AND asb.userid=allstu.id
LEFT JOIN prefix_assign_grades AS asg ON asg.assignment = a.id AND asg.userid = allstu.id AND asg.assignment = asb.assignment

WHERE
c.id = %%COURSEID%%

# GROUP BY c.shortname , allstu.id
GROUP BY allstu.id

ORDER BY allstu.lastname
</code>

===Student Resource Usage===
Contributed by Elizabeth Dalton, Granite State College

Displays usage by students of all activities and resources in the current course by activity. Only activities and sections which are visible in the course are included. This version requires the new "Standard Logs" from Moodle 2.7+.

'''Note''': This should be defined as a "Global" report (visible from within all courses).

<code sql>
SELECT
cs.section AS 'Week'
, cs.name AS 'Section Name'
, m.name AS 'item type'

, CONCAT(
COALESCE(a.name, ''),
COALESCE(b.name,''),
COALESCE(cert.name,''),
COALESCE(chat.name,''),
COALESCE(choice.name,''),
COALESCE(data.name,''),
COALESCE(feedback.name,''),
COALESCE(folder.name,''),
COALESCE(forum.name,''),
COALESCE(glossary.name,''),
COALESCE(imscp.name,''),
COALESCE(lesson.name,''),
COALESCE(p.name,''),
COALESCE(questionnaire.name,''),
COALESCE(quiz.name,''),
COALESCE(cr.name,''),
COALESCE(scorm.name,''),
COALESCE(survey.name,''),
COALESCE(url.name,''),
COALESCE(wiki.name,''),
COALESCE(workshop.name,''),
COALESCE(kalvidassign.name,''),
COALESCE(attendance.name,''),
COALESCE(checklist.name,''),
COALESCE(flashcard.name,''),
COALESCE(lti.name,''),
COALESCE(oublog.name,''),
COALESCE(ouwiki.name,''),
COALESCE(subpage.name,''),
COALESCE(journal.name,''),
COALESCE(lightboxgallery.name,''),
COALESCE(elluminate.name,''),
COALESCE(adaptivequiz.name,''),
COALESCE(hotpot.name,''),
COALESCE(wiziq.name,''),
COALESCE(turnitintooltwo.name,''),
COALESCE(kvr.name,'')
) AS 'item name'

, SUM(IF(l.crud IN ('r'),1,0)) AS 'total views'
, SUM(IF(l.crud IN ('c','u'),1,0)) AS 'total submissions'
, COUNT(DISTINCT IF(l.crud IN ('r'),u.id,NULL)) AS 'count of students who viewed'
, COUNT(DISTINCT IF(l.crud IN ('c','u'),u.id,NULL)) AS 'count of students who submitted'

FROM prefix_user AS u
JOIN prefix_role_assignments AS ra ON u.id = ra.userid
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
JOIN prefix_course AS c ON c.id = ctx.instanceid
JOIN prefix_course_categories as cc ON c.category = cc.id

JOIN prefix_course_sections AS cs ON cs.course = c.id AND cs.section <= 14 #AND cs.section > 0
LEFT JOIN prefix_course_modules AS cm ON cm.course = c.id AND cm.section = cs.id
JOIN prefix_modules AS m ON m.id = cm.module AND m.name NOT LIKE 'label'

LEFT JOIN prefix_assign AS a ON a.id = cm.instance AND m.name = 'assign'
LEFT JOIN prefix_book AS b ON b.id = cm.instance AND m.name = 'book'
LEFT JOIN prefix_certificate AS cert ON cert.id = cm.instance AND m.name = 'certificate'
LEFT JOIN prefix_chat AS chat ON chat.id = cm.instance AND m.name = 'chat'
LEFT JOIN prefix_choice AS choice ON choice.id = cm.instance AND m.name = 'choice'
LEFT JOIN prefix_data AS data ON data.id = cm.instance AND m.name = 'data'
LEFT JOIN prefix_feedback AS feedback ON feedback.id = cm.instance AND m.name = 'feedback'
LEFT JOIN prefix_folder AS folder ON folder.id = cm.instance AND m.name = 'folder'
LEFT JOIN prefix_forum AS forum ON forum.id = cm.instance AND m.name = 'forum'
LEFT JOIN prefix_glossary AS glossary ON glossary.id = cm.instance AND m.name = 'glossary'
LEFT JOIN prefix_imscp AS imscp ON imscp.id = cm.instance AND m.name = 'imscp'
LEFT JOIN prefix_lesson AS lesson ON lesson.id = cm.instance AND m.name = 'lesson'
LEFT JOIN prefix_page AS p ON p.id = cm.instance AND m.name = 'page'
LEFT JOIN prefix_questionnaire AS questionnaire ON questionnaire.id = cm.instance AND m.name = 'questionnaire'
LEFT JOIN prefix_quiz AS quiz ON quiz.id = cm.instance AND m.name = 'quiz'
LEFT JOIN prefix_resource AS cr ON cr.id = cm.instance AND m.name = 'resource'
LEFT JOIN prefix_scorm AS scorm ON scorm.id = cm.instance AND m.name = 'scorm'
LEFT JOIN prefix_survey AS survey ON survey.id = cm.instance AND m.name = 'survey'
LEFT JOIN prefix_url AS url ON url.id = cm.instance AND m.name = 'url'
LEFT JOIN prefix_wiki AS wiki ON wiki.id = cm.instance AND m.name = 'wiki'
LEFT JOIN prefix_workshop AS workshop ON workshop.id = cm.instance AND m.name = 'workshop'
LEFT JOIN prefix_kalvidassign AS kalvidassign ON kalvidassign.id = cm.instance AND m.name = 'kalvidassign'
LEFT JOIN prefix_kalvidres AS kvr ON kvr.id = cm.instance AND m.name = 'kalvidres'
LEFT JOIN prefix_attendance AS attendance ON attendance.id = cm.instance AND m.name = 'attendance'
LEFT JOIN prefix_checklist AS checklist ON checklist.id = cm.instance AND m.name = 'checklist'
LEFT JOIN prefix_flashcard AS flashcard ON flashcard.id = cm.instance AND m.name = 'flashcard'
LEFT JOIN prefix_lti AS lti ON lti.id = cm.instance AND m.name = 'lti'
LEFT JOIN prefix_oublog AS oublog ON oublog.id = cm.instance AND m.name = 'oublog'
LEFT JOIN prefix_ouwiki AS ouwiki ON ouwiki.id = cm.instance AND m.name = 'ouwiki'
LEFT JOIN prefix_subpage AS subpage ON subpage.id = cm.instance AND m.name = 'subpage'
LEFT JOIN prefix_journal AS journal ON journal.id = cm.instance AND m.name = 'journal'
LEFT JOIN prefix_lightboxgallery AS lightboxgallery ON lightboxgallery.id = cm.instance AND m.name = 'lightboxgallery'
LEFT JOIN prefix_elluminate AS elluminate ON elluminate.id = cm.instance AND m.name = 'elluminate'
LEFT JOIN prefix_adaptivequiz AS adaptivequiz ON adaptivequiz.id = cm.instance AND m.name = 'adaptivequiz'
LEFT JOIN prefix_hotpot AS hotpot ON hotpot.id = cm.instance AND m.name = 'hotpot'
LEFT JOIN prefix_wiziq AS wiziq ON wiziq.id = cm.instance AND m.name = 'wiziq'
LEFT JOIN prefix_turnitintooltwo AS turnitintooltwo ON turnitintooltwo.id = cm.instance AND m.name = 'turnitintooltwo'

LEFT JOIN prefix_logstore_standard_log AS l ON l.userid = u.id AND l.courseid = c.id

WHERE ra.roleid =5
AND ctx.instanceid = c.id
AND cs.visible = 1
AND cm.visible = 1

AND c.id = %%COURSEID%%

GROUP BY cm.id

ORDER BY cs.section
</code>

===Module activity (Hits) between dates===
<code sql>
SELECT module, COUNT( * )
FROM prefix_logstore_standard_log AS l
WHERE (FROM_UNIXTIME( l.`timecreated` ) BETWEEN '2018-10-01 00:00:00' AND '2019-09-31 00:00:00')
GROUP BY module
</code>

===Module activity (Instances and Hits) for each academic year===
<code sql>
SELECT name

,(SELECT COUNT(*)
FROM prefix_logstore_standard_log AS l
WHERE (FROM_UNIXTIME(l.`timecreated`) BETWEEN '2017-10-01 00:00:00' AND '2018-09-31 00:00:00')
AND l.module = m.name AND l.action = 'add'
) AS "Added 2017"

,(SELECT COUNT(*)
FROM prefix_logstore_standard_log AS l
WHERE (FROM_UNIXTIME(l.`timecreated`) BETWEEN '2017-10-01 00:00:00' AND '2018-09-31 00:00:00')
AND l.module = m.name
) AS "Used 2017"

,(SELECT COUNT(*)
FROM prefix_logstore_standard_log AS l
WHERE (FROM_UNIXTIME(l.`timecreated`) BETWEEN '2018-10-01 00:00:00' AND '2019-09-31 00:00:00')
AND l.module = m.name AND l.action = 'add'
) AS "Added 2018"

,(SELECT COUNT(*)
FROM prefix_logstore_standard_log AS l
WHERE (FROM_UNIXTIME(l.`timecreated`) BETWEEN '2018-10-01 00:00:00' AND '2019-09-31 00:00:00')
AND l.module = m.name
) AS "Used 2018"

,(SELECT COUNT(*)
FROM prefix_logstore_standard_log AS l
WHERE (FROM_UNIXTIME(l.`timecreated`) BETWEEN '2019-10-01 00:00:00' AND '2020-09-31 00:00:00')
AND l.module = m.name AND l.action = 'add'
) AS "Added 2019"

,(SELECT COUNT(*)
FROM prefix_logstore_standard_log AS l
WHERE (FROM_UNIXTIME(l.`timecreated`) BETWEEN '2019-10-01 00:00:00' AND '2020-09-31 00:00:00')
AND l.module = m.name
) AS "Used 2019"

FROM mdl_modules AS m
</code>

===Unique user sessions per day and month + graph===
The "graph" column is used when displaying a graph (which needs at least three columns to pick from)
<code sql>
SELECT COUNT(DISTINCT userid) AS "Unique User Logins"
,DATE_FORMAT(FROM_UNIXTIME(timecreated), "%y /%m / %d") AS "Year / Month / Day", "Graph"
FROM `mdl_logstore_standard_log`
WHERE action LIKE 'loggedin'
#AND timecreated > UNIX_TIMESTAMP('2015-01-01 00:00:00') # optional start date
#AND timecreated <= UNIX_TIMESTAMP('2015-01-31 23:59:00') # optional end date
GROUP BY MONTH(FROM_UNIXTIME(timecreated)), DAY(FROM_UNIXTIME(timecreated))
ORDER BY MONTH(FROM_UNIXTIME(timecreated)), DAY(FROM_UNIXTIME(timecreated))
</code>

And...

Counting user's global and unique hits per day + counting individual usage of specific activities and resources (on that day),

And since I am using phpMyAdmin's "Display Graph" feature (at the bottom of the query's output page), I have scaled down the "User Hits" by 10 to fit the graph. that's it.
<code sql>
SELECT DATE_FORMAT(FROM_UNIXTIME(timecreated), "%y-%m-%d") AS "Datez"
,COUNT(DISTINCT userid) AS "Unique Users"
,ROUND(COUNT(*)/10) "User Hits (K)"
,SUM(IF(component='mod_quiz',1,0)) "Quizzes"
,SUM(IF(component='mod_forum' or component='mod_forumng',1,0)) "Forums"
,SUM(IF(component='mod_assign',1,0)) "Assignments"
,SUM(IF(component='mod_oublog',1,0)) "Blogs"
,SUM(IF(component='mod_resource',1,0)) "Files (Resource)"
,SUM(IF(component='mod_url',1,0)) "Links (Resource)"
,SUM(IF(component='mod_page',1,0)) "Pages (Resource)"

FROM `mdl_logstore_standard_log`
WHERE 1=1
AND timecreated > UNIX_TIMESTAMP('2015-03-01 00:00:00') # optional START DATE
AND timecreated <= UNIX_TIMESTAMP('2015-05-31 23:59:00') # optional END DATE
GROUP BY MONTH(FROM_UNIXTIME(timecreated)), DAY(FROM_UNIXTIME(timecreated))
ORDER BY MONTH(FROM_UNIXTIME(timecreated)), DAY(FROM_UNIXTIME(timecreated))
</code>

===System wide, daily unique user hits for the last 7 days===
<code sql>
SELECT
DATE_FORMAT(FROM_UNIXTIME(l.timecreated), '%m%d') 'Day'
,COUNT(DISTINCT l.userid) AS 'Distinct Users Hits'
,COUNT( l.userid) AS 'Users Hits'

FROM prefix_logstore_standard_log AS l
WHERE l.courseid > 1
AND FROM_UNIXTIME(l.timecreated) >= DATE_SUB(NOW(), INTERVAL 7 DAY)
GROUP BY DAY(FROM_UNIXTIME(timecreated))
</code>

===User detailed activity in course modules===
Considering only several modules: url, resource, forum, quiz, questionnaire.

<code sql>
SELECT u.id, ra.roleid,
CONCAT(u.lastname, ' ', u.firstname) AS 'Student'
,COUNT(l.id) AS 'Actions'
,l.component "Module type"
,l.objectid "Module ID"
,CASE
WHEN l.component = 'mod_url' THEN (SELECT u.name FROM prefix_url AS u WHERE u.id = l.objectid )
WHEN l.component = 'mod_resource' THEN (SELECT r.name FROM prefix_resource AS r WHERE r.id = l.objectid )
WHEN l.component = 'mod_forum' THEN (SELECT f.name FROM prefix_forum AS f WHERE f.id = l.objectid )
WHEN l.component = 'mod_quiz' THEN (SELECT q.name FROM prefix_quiz AS q WHERE q.id = l.objectid )
WHEN l.component = 'mod_questionnaire' THEN (SELECT q.name FROM prefix_questionnaire AS q WHERE q.id = l.objectid )
END AS 'Module name'

,(SELECT GROUP_CONCAT(g.name) FROM prefix_groups AS g
JOIN prefix_groups_members AS m ON g.id = m.groupid WHERE g.courseid = l.courseid AND m.userid = u.id) "user_groups"

,(SELECT s.name
FROM prefix_course_modules AS cm
JOIN prefix_course_sections AS s ON s.course = cm.course AND s.id = cm.section
WHERE cm.id = l.contextinstanceid) AS "Section name"

FROM prefix_logstore_standard_log AS l
JOIN prefix_user AS u ON u.id = l.userid
JOIN prefix_role_assignments AS ra ON ra.userid = l.userid
AND ra.contextid = (SELECT id FROM prefix_context WHERE instanceid = l.courseid AND contextlevel = 50)
WHERE l.courseid = %%COURSEID%%
AND l.component IN ('mod_url', 'mod_resource', 'mod_forum', 'mod_quiz', 'mod_questionnaire')
%%FILTER_STARTTIME:l.timecreated:>%% %%FILTER_ENDTIME:l.timecreated:<%%

GROUP BY u.id, l.component
ORDER BY u.lastname, u.firstname
</code>

===What teachers and courses considered active?===
This report display several calculations and parameters that help the Online academic training team find teachers that might need more support getting their courses more supporting of online learning pedagogical methodologies.
<code sql>
SELECT concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',
course.id,'">',course.fullname,'</a>') AS Course

#,course.shortname

,CASE
WHEN course.fullname LIKE '%2012%' THEN '2012'
WHEN course.fullname LIKE '%2013%' THEN '2013'
WHEN course.fullname LIKE '%2014%' THEN '2014'
WHEN course.fullname LIKE '%2015%' THEN '2015'
END AS Year

,CASE
WHEN course.fullname LIKE '%semester a%' THEN 'Spring semester'
WHEN course.fullname LIKE '%semester b%' THEN 'Fall semester'
WHEN course.fullname LIKE '%semester s%' THEN 'Summer semester'
END AS Semester

,IF(course.startdate>0, DATE_FORMAT(FROM_UNIXTIME(startdate), '%d-%m-%Y'), 'no date') AS "Course Start Date"

,(SELECT COUNT( ra.userid ) AS Users
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid = 5 AND ctx.instanceid = course.id
) AS Students

,(SELECT COUNT( ra.userid ) AS Users
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid = 4 AND ctx.instanceid = course.id
) AS "Assistant teacher"

,(SELECT COUNT( ra.userid ) AS Users
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid = 3 AND ctx.instanceid = course.id
) AS Teachers

# Uncomment to use the new Moodle 2.8+ logstore
#,(SELECT COUNT(*) FROM mdl_logstore_standard_log AS l WHERE l.courseid = course.id) AS Hits

#,(SELECT COUNT(*)
#FROM mdl_logstore_standard_log AS l
#JOIN mdl_role_assignments AS ra ON ra.userid= l.userid AND ra.roleid = 5 AND ra.contextid = (SELECT id FROM mdl_context WHERE instanceid = l.courseid AND contextlevel = 50)
#WHERE l.courseid = course.id ) AS "Student HITs"

#,(SELECT COUNT(*)
#FROM mdl_logstore_standard_log AS l
#JOIN mdl_role_assignments AS ra ON ra.userid= l.userid AND ra.roleid = 3 AND ra.contextid = (SELECT id FROM mdl_context WHERE instanceid = l.courseid AND contextlevel = 50)
#WHERE l.courseid = course.id ) AS "Teacher HITs"

,(SELECT COUNT(*) FROM mdl_log AS l WHERE l.course = course.id) AS Hits

,(SELECT COUNT(*)
FROM mdl_log AS l
JOIN mdl_context AS con ON con.instanceid= l.course AND con.contextlevel=50
JOIN mdl_role_assignments AS ra ON ra.contextid= con.id AND ra.userid= l.userid AND ra.roleid = 5
WHERE l.course = course.id) AS "Students HITs"

,(SELECT COUNT(*)
FROM mdl_log AS l
JOIN mdl_context AS con ON con.instanceid= l.course AND con.contextlevel=50
JOIN mdl_role_assignments AS ra ON ra.contextid= con.id AND ra.userid= l.userid AND ra.roleid = 3
WHERE l.course = course.id) AS "Teachers HITs"

,(SELECT GROUP_CONCAT( CONCAT( u.firstname, " ", u.lastname ) )
FROM prefix_course c
JOIN prefix_context con ON con.instanceid = c.id
JOIN prefix_role_assignments ra ON con.id = ra.contextid AND con.contextlevel = 50
JOIN prefix_role r ON ra.roleid = r.id
JOIN prefix_user u ON u.id = ra.userid
WHERE r.id = 3 AND c.id = course.id
GROUP BY c.id
) AS Teachers

,(SELECT COUNT(*) FROM prefix_course_modules cm WHERE cm.course = course.id) Modules

,(SELECT COUNT(DISTINCT cm.module) FROM prefix_course_modules cm
WHERE cm.course = course.id) UniqueModules

,(SELECT GROUP_CONCAT(DISTINCT m.name)
FROM prefix_course_modules cm
JOIN mdl_modules as m ON m.id = cm.module
WHERE cm.course = course.id) UniqueModuleNames

,(SELECT COUNT(*) FROM mdl_course_modules cm JOIN mdl_modules as m ON m.id = cm.module
WHERE cm.course = course.id AND m.name IN ( 'ouwiki', 'wiki') ) "Num Wikis"

,(SELECT COUNT(*) FROM mdl_course_modules cm JOIN mdl_modules as m ON m.id = cm.module
WHERE cm.course = course.id AND m.name IN ( 'oublog') ) "Num Blogs"

,(SELECT COUNT(*) FROM mdl_course_modules cm JOIN mdl_modules as m ON m.id = cm.module
WHERE cm.course = course.id AND m.name IN ( 'forum', 'forumng') ) "Num Forums"

,(SELECT COUNT(*) FROM prefix_course_modules cm JOIN mdl_modules as m ON m.id = cm.module
WHERE cm.course = course.id AND m.name IN ('resource', 'folder', 'url', 'tab', 'file', 'book', 'page') ) Resources

,(SELECT COUNT(*) FROM prefix_course_modules cm JOIN mdl_modules as m ON m.id = cm.module
WHERE cm.course = course.id AND m.name IN ('forum', 'forumng', 'oublog', 'page', 'file', 'url', 'wiki' , 'ouwiki') ) "Basic Activities"

,(SELECT COUNT(*) FROM prefix_course_modules cm JOIN mdl_modules as m ON m.id = cm.module
WHERE cm.course = course.id AND m.name IN ('advmindmap', 'assign', 'attendance', 'book', 'choice', 'folder', 'tab', 'glossary', 'questionnaire', 'quiz', 'label' ) ) "Avarage Activities"

,(SELECT COUNT(*) FROM prefix_course_modules cm JOIN mdl_modules as m ON m.id = cm.module
WHERE cm.course = course.id AND m.name IN ('elluminate', 'game', 'workshop') ) "Advanced Activities"

FROM prefix_course AS course

#WHERE course.shortname LIKE '%2015%'
#WHERE 1=1
#%%FILTER_SEARCHTEXT:course.shortname:~%%

WHERE course.fullname LIKE '%2015%'

HAVING Modules > 2
ORDER BY UniqueModules DESC
</code>

===Weekly attendance report===
This report display weekly report in format HH:M:SS This MySQL query works together with AttendaceRegister module, and gather Log information from Attendanceregister_log table.
<code sql>
SELECT u.username, SEC_TO_TIME (SUM(arsess.duration)) AS weekly_online_attendance, FROM_UNIXTIME (arsess.logout) AS Last_Logout
FROM prefix_attendanceregister_session AS arsess
JOIN prefix_user AS u ON arsess.userid = u.id

WHERE (((arsess.logout) BETWEEN UNIX_TIMESTAMP(DATE_SUB(CURDATE(), INTERVAL 7 DAY)) AND UNIX_TIMESTAMP(CURDATE())))

GROUP BY arsess.userid
</code>

===How many distinct users connected to Moodle using the app by month===
https://moodle.org/mod/forum/discuss.php?d=336086#p1354194 by
Iñigo Zendegi Urzelai
<code sql>
SELECT
to_char(to_timestamp("timecreated"),'YYYY') as year,
to_char(to_timestamp("timecreated"),'MM') as month,
count(distinct userid) as distinct_users

FROM prefix_logstore_standard_log l
WHERE l.origin='ws'
GROUP BY to_char(to_timestamp("timecreated"),'YYYY'), to_char(to_timestamp("timecreated"),'MM')
ORDER BY to_char(to_timestamp("timecreated"),'YYYY'), to_char(to_timestamp("timecreated"),'MM');
</code>

==Course Reports==
===Most Active courses===
<code sql>
SELECT count(l.userid) AS Views
FROM `mdl_logstore_standard_log` l, `mdl_user` u, `mdl_role_assignments` r
WHERE l.courseid=35
AND l.userid = u.id
AND (l.timecreated > UNIX_TIMESTAMP('2015-01-01 00:00:00') AND l.timecreated <= UNIX_TIMESTAMP('2015-01-31 23:59:59'))AND r.contextid= (
SELECT id
FROM mdl_context
WHERE contextlevel=50 AND instanceid=l.courseid
)
AND r.roleid=5
AND r.userid = u.id
</code>

===Active courses, advanced===
Including: Teacher's name, link to the course, All types of log activities, special YEAR generated field, Activities and Resource count, enrolled Student count
<code sql>
SELECT COUNT(l.id) hits, concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.fullname,'</a>') AS Course

,(SELECT CONCAT(u.firstname,' ', u.lastname) AS Teacher
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
JOIN prefix_user AS u ON u.id = ra.userid
WHERE ra.roleid = 3 AND ctx.instanceid = c.id LIMIT 1) AS Teacher

,CASE
WHEN c.fullname LIKE '%תשע' THEN 'תשע'
WHEN c.fullname LIKE '%תשעא' THEN 'תשעא'
WHEN c.fullname LIKE '%תשעב' THEN 'תשעב'
END AS Year

,(SELECT count(*) FROM prefix_course_modules cm WHERE cm.course = l.course) Modules

,(SELECT Count( ra.userid ) AS Users FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid = 5 AND ctx.instanceid = c.id) AS Students

FROM prefix_log l
INNER JOIN prefix_course c ON l.course = c.id
GROUP BY c.id
#The following line restricts the courses returned to those having more than 2 modules. Adjust based on your needs.
HAVING Modules > 2
ORDER BY Year DESC, hits DESC
</code>

=== Least active or probably empty courses===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

It is difficult to know sometimes when a course is actually empty or was never really in use. Other than the simple case where the course was created and never touched again, in which case the course timecreated and timemodified will be the same, many courses created as shells for teachers or other users may be used once or a few times and have few or no test users enrollments in them. This query helps you see the range of such courses, showing you how many days if any it was used after initial creation, and how many user are enrolled. It denotes a course never ever modified by "-1" instead of "0" so you can sort those to the top. By default it limits this to courses used within 60 days of creation, and to courses with 3 or less enrollments (for example, teacher and assistant and test student account only.) You can easily adjust these numbers. The query includes a link to the course as well.

<code sql>
SELECT
c.fullname,
CONCAT('<a target="_blank" href="%%WWWROOT%%/course/view.php',CHAR(63),'id=',c.id,'">',c.shortname,'</a>') AS 'CourseLink',
DATE_FORMAT(FROM_UNIXTIME(c.timecreated), '%Y-%m-%d %H:%i') AS 'Timecreated',
DATE_FORMAT(FROM_UNIXTIME(c.timemodified), '%Y-%m-%d %H:%i') AS 'Timemodified',
CASE
WHEN c.timecreated = c.timemodified THEN '-1'
ELSE DATEDIFF(FROM_UNIXTIME(c.timemodified),FROM_UNIXTIME(c.timecreated))
END AS 'DateDifference',
COUNT(ue.id) AS Enroled
FROM prefix_course AS c
JOIN prefix_enrol AS en ON en.courseid = c.id
LEFT JOIN prefix_user_enrolments AS ue ON ue.enrolid = en.id
WHERE DATEDIFF(FROM_UNIXTIME(c.timemodified),FROM_UNIXTIME(c.timecreated) ) < 60
GROUP BY c.id
HAVING COUNT(ue.id) <= 3
ORDER BY c.fullname
</code>

===Count unique teachers with courses that use at least X module (Moodle19)===
You can remove the outer "SELECT COUNT(*) FROM (...) AS ActiveTeachers" SQL query and get the list of the Teachers and Courses.
<code sql>
SELECT COUNT(*)
FROM (SELECT c.id AS CourseID, c.fullname AS Course, ra.roleid AS RoleID, CONCAT(u.firstname, ' ', u.lastname) AS Teacher
,(SELECT COUNT(*) FROM prefix_course_modules cm WHERE cm.course = c.id) AS Modules
FROM prefix_course AS c
JOIN prefix_context AS ctx ON c.id = ctx.instanceid AND ctx.contextlevel = 50
JOIN prefix_role_assignments AS ra ON ra.contextid = ctx.id
JOIN prefix_user AS u ON u.id = ra.userid
JOIN prefix_course_categories AS cc ON cc.id = c.category
WHERE ra.roleid = 3
GROUP BY u.id
HAVING Modules > 5) AS ActiveTeachers
</code>

===RESOURCE count for each COURSE===
<code sql>
SELECT COUNT(l.id) count, l.course, c.fullname coursename
FROM prefix_resource l INNER JOIN prefix_course c on l.course = c.id
GROUP BY course
ORDER BY count DESC
</code>

===Common resource types count for each Category (Moodle19)===
Including sub-categories in total count.
<code sql>
SELECT mcc.id AS mccid, CONCAT( LPAD( '', mcc.depth, '.' ) , mcc.name ) AS Category
,(SELECT COUNT( * )
FROM prefix_resource AS r
JOIN prefix_course AS c ON c.id = r.course
JOIN prefix_course_categories AS cc ON cc.id = c.category
WHERE cc.path LIKE CONCAT( '%', mccid, '%' ) AND r.TYPE = 'file' AND r.reference LIKE 'http://%'
) AS Links

,(SELECT COUNT( * )
FROM prefix_resource AS r
JOIN prefix_course AS c ON c.id = r.course
JOIN prefix_course_categories AS cc ON cc.id = c.category
WHERE cc.path LIKE CONCAT( '%', mccid, '%' ) AND r.TYPE = 'file' AND r.reference NOT LIKE 'http://%'
) AS Files

,(SELECT COUNT( * )
FROM prefix_resource AS r
JOIN prefix_course AS c ON c.id = r.course
JOIN prefix_course_categories AS cc ON cc.id = c.category
WHERE cc.path LIKE CONCAT( '%', mccid, '%' ) AND r.TYPE = 'directory'
) AS Folders

,(SELECT COUNT( * )
FROM prefix_resource AS r
JOIN prefix_course AS c ON c.id = r.course
JOIN prefix_course_categories AS cc ON cc.id = c.category
WHERE cc.path LIKE CONCAT( '%', mccid, '%' ) AND r.TYPE = 'html'
) AS Pages

,(SELECT COUNT(*)
FROM stats_log_context_role_course
WHERE roleid = 5 AND module = 'resource' AND category = mcc.id
) AS Hits

FROM prefix_course_categories AS mcc
ORDER BY mcc.path
</code>
Where "stats_log_context_role_course" (in the above SQL query) is a VIEW generated by:
<code sql>
CREATE VIEW stats_log_context_role_course AS
SELECT l.course, c.category, cc.path, l.module, l.action, ra.userid, ra.roleid
FROM prefix_log AS l
JOIN prefix_context AS context ON context.instanceid = l.course AND context.contextlevel = 50
JOIN prefix_role_assignments AS ra ON ra.userid = l.userid AND ra.contextid = context.id
JOIN prefix_course AS c ON c.id = l.course
JOIN prefix_course_categories AS cc ON cc.id = c.category
</code>

Same query but for Moodle2+
<code sql>
SELECT mcc.id AS mccid, CONCAT( LPAD( '', mcc.depth, '.' ) , mcc.name ) AS Category,
mcc.path,

(SELECT COUNT(*)
FROM prefix_url AS u
JOIN prefix_course AS c ON c.id = u.course
JOIN prefix_course_categories AS cc ON cc.id = c.category
WHERE cc.path LIKE CONCAT( '%/', mccid, '%' )
) AS URLs,

(SELECT COUNT(*)
FROM prefix_folder AS f
JOIN prefix_course AS c ON c.id = f.course
JOIN prefix_course_categories AS cc ON cc.id = c.category
WHERE cc.path LIKE CONCAT( '%/', mccid, '%' )
) AS FOLDERs,

(SELECT COUNT(*)
FROM prefix_page AS p
JOIN prefix_course AS c ON c.id = p.course
JOIN prefix_course_categories AS cc ON cc.id = c.category
WHERE cc.path LIKE CONCAT( '%/', mccid, '%' )
) AS PAGEs,

(SELECT COUNT(*)
FROM prefix_book AS b
JOIN prefix_course AS c ON c.id = b.course
JOIN prefix_course_categories AS cc ON cc.id = c.category
WHERE cc.path LIKE CONCAT( '%/', mccid, '%' )
) AS BOOKs,

(SELECT COUNT(*)
FROM prefix_label AS l
JOIN prefix_course AS c ON c.id = l.course
JOIN prefix_course_categories AS cc ON cc.id = c.category
WHERE cc.path LIKE CONCAT( '%/', mccid, '%' )
) AS LABELs,

(SELECT COUNT(*)
FROM prefix_tab AS t
JOIN prefix_course AS c ON c.id = t.course
JOIN prefix_course_categories AS cc ON cc.id = c.category
WHERE cc.path LIKE CONCAT( '%/', mccid, '%' )
) AS TABs

FROM prefix_course_categories AS mcc
ORDER BY mcc.path
</code>

===Detailed Resource COUNT by Teacher in each course===

Including (optional) filter by: year, semester and course id.

<code sql>
SELECT concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.fullname,'</a>') AS CourseID
, c.id
,( SELECT DISTINCT CONCAT(u.firstname,' ',u.lastname)
FROM prefix_role_assignments AS ra
JOIN prefix_user AS u ON ra.userid = u.id
JOIN prefix_context AS ctx ON ctx.id = ra.contextid
WHERE ra.roleid = 3 AND ctx.instanceid = c.id AND ctx.contextlevel = 50 LIMIT 1) AS Teacher

, (CASE
WHEN c.fullname LIKE '%תשעב%' THEN '2012'
WHEN c.fullname LIKE '%תשעא%' THEN '2011'
END ) as Year
, (CASE
WHEN c.fullname LIKE '%סמסטר א%' THEN 'Semester A'
WHEN c.fullname LIKE '%סמסטר ב%' THEN 'Semester B'
WHEN c.fullname LIKE '%סמסטר ק%' THEN 'Semester C'
END ) as Semester
,COUNT(c.id) AS Total
,(SELECT count(*) FROM prefix_course_modules AS cm WHERE cm.course = c.id AND cm.module= 20) AS TABs
,(SELECT count(*) FROM prefix_course_modules AS cm WHERE cm.course = c.id AND cm.module= 33) AS BOOKs

FROM `prefix_resource` as r
JOIN `prefix_course` AS c on c.id = r.course
#WHERE type= 'file' and reference NOT LIKE 'http://%'

#WHERE 1=1
#%%FILTER_YEARS:c.fullname%%
#AND c.fullname LIKE '%2013%'

GROUP BY course
ORDER BY COUNT(c.id) DESC
</code>

===Courses that are defined as using GROUPs===
<code sql>
SELECT concat('<a target="_new" href="%%WWWROOT%%/group/index.php?id=',c.id,'">',c.fullname,'</a>') AS Course
,(SELECT count(*) FROM prefix_course_modules cm WHERE cm.course = c.id) Modules
,(SELECT count(*) FROM prefix_groups g WHERE g.courseid = c.id) Groups
FROM `prefix_course` AS c
WHERE groupmode > 0
</code>

===Courses with Groups===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

List of all courses with Groups in them (groupmode > 0). You can also use groupmode=1 to list just Separate type groups or groupmode=2 to list Visible type groups.

<code sql>
SELECT c.shortname, g.name, c.groupmode
FROM prefix_course AS c
JOIN prefix_groups AS g ON c.id = g.courseid
WHERE c.groupmode > 0
</code>

===Users enrolled in a course with groups but not assigned a group ===

Displays by course all enrolled users that have not been assigned a group in courses that have groups. NOTE: This needs to be optimized.

<code sql>
SELECT DISTINCT
user2.firstname AS Firstname,
user2.lastname AS Lastname,
user2.email AS Email,
user2.city AS City,
course.fullname AS Course
,(SELECT shortname FROM prefix_role WHERE id=en.roleid) AS ROLE
,(SELECT name FROM prefix_role WHERE id=en.roleid) AS RoleName

FROM prefix_course AS course
JOIN prefix_enrol AS en ON en.courseid = course.id
JOIN prefix_user_enrolments AS ue ON ue.enrolid = en.id
JOIN prefix_user AS user2 ON ue.userid = user2.id
JOIN prefix_groups AS g ON g.courseid = course.id

WHERE ue.enrolid NOT IN (select userid from prefix_groups_members WHERE g.id=groupid)

ORDER BY Course, Lastname
</code>

===Groups in course with member list===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

List the groups in a course (replace the # by the course id number) with the members of each group.

<code sql>
SELECT c.shortname, g.name AS Groupname, u.username
FROM prefix_course AS c
JOIN prefix_groups AS g ON g.courseid = c.id
JOIN prefix_groups_members AS m ON g.id = m.groupid
JOIN prefix_user AS u ON m.userid = u.id
WHERE c.id = #
</code>

Note: if you are using Configurable Reports block and want to perform this query on the current course you are in, then you can use a WHERE clause like this:
<code sql>
WHERE c.id = %%COURSEID%%
</code>

===Group Export===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

There's a [[Import_groups|group import]] function, but no export. Use this to give you a report with the proper column order and headings to export to a csv file you can then import into another course to replicate the groups. This is a simple version with just the main fields: groupname, description, enrolment key.

<code sql>
SELECT g.name AS groupname, g.description, g.enrolmentkey
FROM prefix_groups AS g
JOIN prefix_course as c ON g.courseid = c.id
WHERE c.id = #
</code>
Note: if you are using Configurable Reports block and want to perform this query on the current course you are in, then you can use a WHERE clause like this:
<code sql>
WHERE c.id = %%COURSEID%%
</code>

===List all Courses in and below a certain category===
Use this SQL code to retrieve all courses that exist in or under a set category.

$s should be the id of the category you want to know about...
<code sql>
SELECT prefix_course. * , prefix_course_categories. *
FROM prefix_course, prefix_course_categories
WHERE prefix_course.category = prefix_course_categories.id
AND (
prefix_course_categories.path LIKE '%/$s/%'
OR prefix_course_categories.path LIKE '%/$s'
)
</code>

===List all Categories in one level below a certain category===
Use this PHP code to retrieve a list of all categories below a certain category.

$s should be the id of the top level category you are interested in.
<code php>
<?php

require_once('./config.php');

$parent_id = $s;

$categories= array();

$categories = get_categories($parent_id);

echo '<ol>';
foreach ($categories as $category)
{
echo '<li><a href="'.$CFG->wwwroot.'/course/category.php?id='.$category->id.'">'.$category->name.'</a></li>';
}
echo '</ol>';

?>
</code>

===Blog activity per Course (not including VIEW)===
Filter activity logging to some specific Course Categories!
+ link course name to actual course (for quick reference)
(you can change %blog% to %wiki% to filter down all wiki activity or any other module you wish)
<code sql>
SELECT concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',cm.course,'">',c.fullname,'</a>') as CourseID
,m.name ,count(cm.id) as counter
,(SELECT Count( ra.userid ) AS Users
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid = 5
AND ctx.instanceid = c.id
) AS Students
, ( SELECT count(id) FROM prefix_log WHERE `module` LIKE '%blog%' AND course = c.id AND action NOT LIKE '%view%' ) as BlogActivity
FROM `prefix_course_modules` as cm JOIN prefix_modules as m ON cm.module=m.id JOIN prefix_course as c ON cm.course = c.id
WHERE m.name LIKE '%blog%' AND c.category IN ( 8,13,15)
GROUP BY cm.course,cm.module order by counter desc
</code>

===Student's posts content in all course blogs (oublog)===
<code sql>
SELECT
b.name
,op.title
,op.message
,( SELECT CONCAT(u.firstname, ' ',u.lastname) FROM prefix_user AS u WHERE u.id = oi.userid) AS "Username"

FROM prefix_oublog_posts AS op
JOIN prefix_oublog_instances AS oi ON oi.id = op.oubloginstancesid
JOIN prefix_oublog as b ON b.id = oi.oublogid
JOIN prefix_course AS c ON b.course = c.id

WHERE c.id = %%COURSEID%%
</code>

===All Courses which uploaded a Syllabus file===
+ under specific Category
+ show first Teacher in that course
+ link Course's fullname to actual course
<code sql>
SELECT
concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.fullname,'</a>') as Course
,c.shortname,r.name
,(SELECT CONCAT(u.firstname,' ', u.lastname) as Teacher
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
JOIN prefix_user as u ON u.id = ra.userid
WHERE ra.roleid = 3 AND ctx.instanceid = c.id LIMIT 1) as Teacher
FROM prefix_resource as r
JOIN prefix_course as c ON r.course = c.id
WHERE ( r.name LIKE '%סילבוס%' OR r.name LIKE '%סילאבוס%' OR r.name LIKE '%syllabus%' OR r.name LIKE '%תכנית הקורס%' )
AND c.category IN (10,18,26,13,28)
</code>

===Site-wide completed SCORM activities by Course name===
This report will list all completed attempts for all SCORM activities. It is ordered first by Course name, then student's last name, then student's first name, then attempt number. Please note: the FROM_UNIXTIME command is for MySQL.
<code sql>
SELECT u.firstname First,u.lastname Last,c.fullname Course, st.attempt Attempt,st.value Status,FROM_UNIXTIME(st.timemodified,"%m-%d-%Y") Date
FROM prefix_scorm_scoes_track AS st
JOIN prefix_user AS u ON st.userid=u.id
JOIN prefix_scorm AS sc ON sc.id=st.scormid
JOIN prefix_course AS c ON c.id=sc.course
WHERE st.value='completed'
ORDER BY c.fullname, u.lastname,u.firstname, st.attempt
</code>
===All users enrolled in a course without a role===
Identifies All users that are enrolled in a course but are not assigned a role.
<code sql>
SELECT
user.firstname AS Firstname,
user.lastname AS Lastname,
user.idnumber Employee_ID,
course.fullname AS Course

FROM prefix_course AS course
JOIN prefix_enrol AS en ON en.courseid = course.id
JOIN prefix_user_enrolments AS ue ON ue.enrolid = en.id
JOIN prefix_user as user ON user.id = ue.userid

WHERE user.id NOT IN (
SELECT u.id
FROM prefix_course AS c
JOIN prefix_context AS ctx ON c.id = ctx.instanceid
JOIN prefix_role_assignments AS ra ON ra.contextid = ctx.id
JOIN prefix_role AS r ON r.id = ra.roleid
JOIN prefix_user AS u ON u.id = ra.userid
WHERE c.id=course.id
)
ORDER BY Course, Lastname, Firstname

</code>

===List course resources accumulative file size and count===
This is the main (first) report, which has a link (alias) to a second report (the following on this page) which list each file in the course.
<code sql>
SELECT c.id "CourseID", context.id "ContextID"
,CONCAT('<a target="_new" href="%%WWWROOT%%/course/view.php?id=', c.id, '">', c.fullname ,'</a>') AS "Course Name"
, COUNT(*) "Course Files" , ROUND( SUM( f.filesize ) /1048576 ) AS file_size_MB
,CONCAT('<a target="_new" href="%%WWWROOT%%/blocks/configurable_reports/viewreport.php?alias=coursefiles&courseid=1&filter_courses=', c.id, '">List files</a>') AS "List Files"

FROM mdl_files AS f
JOIN mdl_context AS context ON context.id = f.contextid
JOIN mdl_course AS c ON c.id = (
SELECT instanceid
FROM mdl_context
WHERE id = SUBSTRING_INDEX( SUBSTRING_INDEX( context.path, '/' , -2 ) , '/', 1 ) )
WHERE filesize >0
GROUP BY c.id
</code>

With this report, you will have to define "alias" report property to "coursefiles" for it to be able to be called from the above report.
And also setup (add) a FILTER_COURSES filter.
<code sql>
SELECT
id ,CONCAT('<a target="_new" href="%%WWWROOT%%/pluginfile.php/', contextid, '/', component, '/', filearea, '/', itemid, '/', filename, '">', filename,'</a>') AS "File"
,filesize, mimetype ,author, license, timecreated, component, filearea, filepath

FROM mdl_files AS f
WHERE filesize >0
AND f.contextid
IN ( SELECT id
FROM mdl_context
WHERE path
LIKE ( SELECT CONCAT('%/',id,'/%')
AS contextquery
FROM mdl_context
WHERE 1=1
%%FILTER_COURSES:instanceid%%
AND contextlevel = 50
)
)
</code>

===Which courses has redundant topics===
This report list several "active topics" calculations, per course. which should give an administrator some indications for which topics/sections/weeks are filled with resources and activities and which ones are empty and not used (usually, at the end of the course).

The following, second SQL query, could be used to "trim" down those redundant course topics/sections/weeks by updating the course format's numsection (Number of sections) setting. (It's a per course format setting!)

<code sql>
SELECT id, format,
concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">', c.fullname,'</a>') AS Course

,(SELECT value FROM `mdl_course_format_options` WHERE `courseid` = c.id AND `format` = c.format AND `name` = 'numsections' ) AS "numsections"
,(SELECT COUNT(*) FROM `mdl_course_sections` WHERE `course` = c.id AND `sequence` != '' ) AS "Non empty sections count"
,(SELECT COUNT(*) FROM `mdl_course_sections` WHERE `course` = c.id ) AS "Total section count"
,(SELECT COUNT(*) FROM `mdl_course_sections` WHERE `course` = c.id AND sequence IS NOT NULL) AS "Non NULL sections count"
,(SELECT COUNT(*) FROM `mdl_course_sections` WHERE `course` = c.id AND name != '') AS "Non empty section Name count"
,(SELECT COUNT(*) FROM mdl_course_modules cm WHERE cm.course = c.id) "Modules count"

FROM mdl_course AS c
</code>

The following SQL REPLACE query is used for "fixing" (updating) the "numsections" of a specific course format "onetopics" (you can always change it, or discard it to use this SQL REPLACE on all course formats)
<code sql>
REPLACE INTO `mdl_course_format_options` (`id`, `courseid`, `format`, `sectionid`, `name`, `value`)
SELECT NULL, c.id, 'onetopic', '0', 'numsections', (SELECT COUNT(*) FROM `mdl_course_sections` WHERE `course` = c.id AND name != '')
FROM `mdl_course` c where format = 'onetopic'
</code>

===Hidden Courses with Students Enrolled===
Contributed by Eric Strom

This query identifies courses with student enrollment that are currently hidden from students. Includes the defined course start date, count of students and instructors, and a clickable email link of instructor (first found record if more than one).

<code sql>
SELECT c.visible AS Visible,
DATE(FROM_UNIXTIME(c.startdate)) AS StartDate,
concat('<a target="_new" href="%%WWWROOT%%/course/view.php',CHAR(63),'id=',
c.id,'">',c.idnumber,'</a>') AS Course_ID,

(SELECT COUNT( ra.userid ) FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid = 5 AND ctx.instanceid = c.id) AS Students,

(SELECT COUNT( ra.userid ) FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid = 3 AND ctx.instanceid = c.id) AS Instructors,

(SELECT DISTINCT concat('<a href="mailto:',u.email,'">',u.email,'</a>')
FROM prefix_role_assignments AS ra
JOIN prefix_user AS u ON ra.userid = u.id
JOIN prefix_context AS ctx ON ctx.id = ra.contextid
WHERE ra.roleid = 3 AND ctx.instanceid = c.id AND ctx.contextlevel = 50 LIMIT 1) AS 'Instructor_Email',

now() AS Report_Timestamp

FROM prefix_course AS c
WHERE c.visible = 0 AND (SELECT COUNT( ra.userid ) FROM prefix_role_assignments AS ra JOIN prefix_context AS ctx ON ra.contextid = ctx.id WHERE ra.roleid = 5 AND ctx.instanceid = c.id) > 0
ORDER BY StartDate, Instructor_Email, Course_ID
</code>

==Course Design Reports==

These are reports which summarize course design aspects, such as activity and resource modules per section, types of activities used, etc.

===Course Content/Week===
Contributed by Elizabeth Dalton, Granite State College

This report assumes that the first 14 sections in a course, not including the "0" or "Welcome" section, correspond to weeks (with "Subsections" given numbers much higher in the sequence). Of those sections, each is checked to count the number of:

Forums
Graded Activities (may include Forums)
Resources (not including a Label)

Totals of each of these types of content elements per section are provided.

'''Note''': Only visible resources and activities are counted.
'''Note''': this is a "Global" report. Run it within a course to see a summary of the contents of that course.

<code sql>
SELECT

cs.section AS 'Week'
, cs.name AS 'Section Name'

, COUNT(DISTINCT IF((gi.id IS NULL) AND (m.name NOT LIKE 'label'),cm.id,NULL)) AS 'Ungraded Resources'

, COUNT(DISTINCT IF(m.name LIKE 'forum', cm.id, NULL)) AS 'Forums'

, COUNT(DISTINCT IF(gi.id, cm.id, NULL)) AS 'Graded Activities'

FROM prefix_course AS c
JOIN prefix_course_sections AS cs ON cs.course = c.id AND cs.section <= 14 AND cs.section > 0
LEFT JOIN prefix_course_modules AS cm ON cm.course = c.id AND cm.section = cs.id
JOIN prefix_modules AS m ON m.id = cm.module
LEFT JOIN prefix_grade_items AS gi ON gi.courseid = c.id AND gi.itemmodule = m.name AND gi.iteminstance = cm.instance

WHERE
cs.visible = 1
AND cm.visible = 1
AND c.id = %%COURSEID%%

GROUP BY cs.section
ORDER BY cs.section

</code>

===Assignments and Weights===
Contributed by Elizabeth Dalton, Granite State College

Returns a list of grade book categories for the current course, grade book weightings, the first type of assignment included in the category, a count of different assignment types for each category, and a count of assignments for each category.

Categories with weights of 0 are not included in this report.

Only visible activities are included in this report.

'''Note''': This is designed to be a "Global" report in Configurable Reports.
<code sql>
SELECT

IF(gc.parent IS NOT NULL, gc.fullname, 'None') AS 'Grade Book Category'
, IF(gc.parent IS NOT NULL, ROUND(gic.aggregationcoef, 2), ROUND(SUM(DISTINCT gi.aggregationcoef), 2)+ROUND(SUM(DISTINCT mgi.aggregationcoef), 2)) AS 'Category weight'

, CONCAT_WS(', ',GROUP_CONCAT(DISTINCT gi.itemmodule SEPARATOR ', '), IF(mgi.id, 'manual',NULL)) AS 'Activity Types'
, COUNT(DISTINCT gi.itemmodule) + IF(mgi.id,1,0) AS 'Different Activity Types'
, CONCAT_WS(' ', GROUP_CONCAT(DISTINCT gi.itemname ORDER BY gi.itemname SEPARATOR ' '), GROUP_CONCAT(DISTINCT mgi.itemname ORDER BY mgi.itemname SEPARATOR ' ')) AS 'Activity Names'
, COUNT(DISTINCT IF(gi.id, cm.id, NULL)) + COUNT(DISTINCT mgi.id) AS 'Activity Count'

FROM prefix_course AS c

#get grade categories
LEFT JOIN prefix_grade_categories AS gc ON gc.courseid = c.id
# back from categories to grade items to get aggregations and weights
JOIN prefix_grade_items AS gic ON gic.courseid = c.id AND gic.itemtype = 'category' AND gic.aggregationcoef != 0 AND (LOCATE(gic.iteminstance, gc.path) OR (gc.parent IS NULL))

# attach activities to course
JOIN prefix_course_modules AS cm ON cm.course = c.id
# attach grade items to activities
LEFT JOIN prefix_grade_items AS gi ON gi.courseid = c.id AND gi.iteminstance = cm.instance AND gi.itemtype = 'mod' AND gi.categoryid = gc.id AND gi.hidden != 1

# attach manual grade items to course-- they don't have modules
LEFT JOIN prefix_grade_items AS mgi ON mgi.courseid = c.id and mgi.itemtype = 'manual' AND mgi.categoryid = gc.id

WHERE
cm.visible = 1
AND c.id = %%COURSEID%%

GROUP BY gc.id
ORDER BY gc.id

</code>

===Pre-Term Course Review===
Contributed by Elizabeth Dalton, Granite State College

Provides an overview of the readiness of ONLINE, HYBRID, and BLENDED courses in the Staging category and all subcategories. Links to each course are provided. Other details:

# "Required blocks" include Instructor Block (mooprofile), Activities, and the Research block.
# "Instructor Details" block is not the "Instructor" block (mooprofile) automatically provided by the system. It is an optional block that can be edited by the instructor. If not edited to remove boilerplate text, it should be hidden.
# All courses should be in the "Collapsed Topics" format with the "Weeks" structure.
# "Weeks defined in course settings" is taken from our SIS when the course shells are created, but can be edited by faculty. "# of weeks named and visible" should usually match or exceed this value.
# We recommend that each week contain at least one forum, at least one graded activity, and at least one ungraded resource.
# "Syllabus updated" date is for the first attached file found with the text "syllabus" in the name. The "Days ago" calculation is included for convenience.

'''Note''': At our institution, we construct categories each term, and insert a text string "staging" in the Category ID for pre-term courses during the preparation or "staging" phase of course development. We remove this text string (and change it to "production") when courses go live at the start of the new term.

<code sql>
SELECT CONCAT('<a target="_blank" href="%%WWWROOT%%/course/view.php',CHAR(63),'id=',c.id,'">',c.shortname,'</a>') AS Course

#,RIGHT(c.idnumber,2) AS Type # Specific to GSC "Instructional Method" storage

#, substring_index(substr(c.shortname FROM locate('.',c.shortname)+1),'-',1) AS Section # Specific to GSC

,(SELECT CONCAT('<a target="_blank" href="%%WWWROOT%%/user/view.php',CHAR(63),'id=',u.id,'">',u.lastname,', ', u.firstname,'</a>')
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
JOIN prefix_user AS u ON u.id = ra.userid
WHERE ra.roleid = 3 AND ctx.instanceid = c.id LIMIT 1) AS 'Instructor'

,(SELECT IF((u2.description IS NULL) OR (u2.description LIKE ''),'NO', 'YES')
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
JOIN prefix_user AS u2 ON u2.id = ra.userid
WHERE ra.roleid = 3 AND ctx.instanceid = c.id LIMIT 1) AS 'Profile Has Bio'

,(SELECT IF(u3.picture > 0,'YES','NO')
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
JOIN prefix_user AS u3 ON u3.id = ra.userid
WHERE ra.roleid = 3 AND ctx.instanceid = c.id LIMIT 1) AS 'Profile Has Picture'

, IF(((bpi.visible IS NULL) OR (bpi.visible !=0)) AND ((bpm.visible IS NULL) OR (bpm.visible !=0)) AND ((bpa.visible IS NULL) OR (bpa.visible !=0)) AND ((bpr.visible IS NULL) OR (bpr.visible !=0)),'YES','NO') AS 'Required blocks visible'
#, IF((bpm.visible IS NULL) OR (bpm.visible !=0),'YES','NO') AS 'Messages block visible'
#, IF((bpa.visible IS NULL) OR (bpa.visible !=0),'YES','NO') AS 'activities block visible'
#, IF((bpr.visible IS NULL) OR (bpr.visible !=0),'YES','NO') AS 'research block visible'

#, IF(SUM(IF(bi.configdata LIKE 'Tzo4OiJzdGRDbGFzcyI6Mzp7czo1OiJ0aXRsZSI7czoxODoiSW5zdHJ1Y3RvciBEZXRhaWxzI%',1,0)) AND (bip.visible !=0),'YES','') AS 'Instructor Details Block visible' # This is a hack based on UUencoded string data from the title of HTML "Instructor Details" block

#, IF(bi.configdata LIKE '%ZGl0IHRoaXMgYmxvY2s%','NO','') AS 'Instructor Details Block Updated' # HTML block has string 'dit this block'

#, IF(COUNT(bi.id) - SUM(IF(bi.configdata LIKE 'Tzo4OiJzdGRDbGFzcyI6Mzp7czo1OiJ0aXRsZSI7czoxODoiSW5zdHJ1Y3RvciBEZXRhaWxzI%',1,0)),'YES','') AS 'possible extra instructor blocks' #looking for any HTML block with "instructor" in the title

, IF(c.format='topcoll','YES', c.format) AS 'Collapsed Topics course format' # change this if you want to test for a different format
, IF(cfo.value = 2, 'YES','NO') AS 'weeks structure'

, cfw.value AS 'weeks defined in course settings'

, COUNT(DISTINCT IF(((cs.name IS NOT NULL) AND (cs.visible = 1) AND (cs.section != '0') AND (cs.sequence IS NOT NULL)),cs.id,NULL)) AS '# of weeks named & visible (includes orphans)'

, COUNT(DISTINCT IF(m.name LIKE 'forum', cm.id, NULL)) AS 'Forums'
, COUNT(DISTINCT IF(m.name LIKE 'forum' ,cs.id , NULL)) AS 'Weeks with Forum'

, COUNT(DISTINCT IF(gi.id, cm.id, NULL)) AS 'Activities'
, COUNT(DISTINCT IF(gi.id, cs.id, NULL)) AS 'Weeks with Activities'
, COUNT(DISTINCT mgi.id) AS 'Manual Grade Items'

, COUNT(DISTINCT IF((gi.id IS NULL) AND (m.name NOT IN ('forum','label')),cm.id,NULL)) AS 'Resources'
, COUNT(DISTINCT IF((gi.id IS NULL) AND (m.name NOT IN ('forum','label')), cs.id, NULL)) AS 'Weeks with Resources'

# Here are some other things you could check for per course
#,(SELECT count( m.name ) AS count FROM prefix_course_modules AS cm JOIN prefix_modules AS m ON cm.module = m.id WHERE cm.course = c.id AND m.name LIKE '%forum%') AS Forums

#,(SELECT count( m.name ) AS count FROM prefix_course_modules AS cm JOIN prefix_modules AS m ON cm.module = m.id WHERE cm.course = c.id AND m.name LIKE '%quiz%') AS Quizzes

#,(SELECT count( m.name ) AS count FROM prefix_course_modules AS cm JOIN prefix_modules AS m ON cm.module = m.id WHERE cm.course = c.id AND m.name LIKE '%assign%') AS Assignments

#,(SELECT COUNT(prefix_resource.id) FROM prefix_resource JOIN prefix_course ON prefix_course.id = prefix_resource.course WHERE c.id = prefix_resource.course) AS Files

#,(SELECT COUNT(prefix_url.id) FROM prefix_url JOIN prefix_course ON prefix_course.id = prefix_url.course WHERE c.id = prefix_url.course) AS Links

,(SELECT FROM_UNIXTIME(MAX(prefix_resource.timemodified))
FROM prefix_resource
JOIN prefix_course ON prefix_course.id = prefix_resource.course WHERE c.id = prefix_resource.course AND prefix_resource.name LIKE '%syllabus%') AS SyllabusDate

,(SELECT TO_DAYS(NOW())-TO_DAYS(FROM_UNIXTIME(MAX(prefix_resource.timemodified)))
FROM prefix_resource
JOIN prefix_course ON prefix_course.id = prefix_resource.course WHERE c.id = prefix_resource.course AND prefix_resource.name LIKE '%syllabus%') AS DaysAgo

, IF(COUNT(DISTINCT IF(f.type LIKE 'news', f.id,NULL)),'YES','NO' ) AS 'Announcement Forum Visible'

, IF(COUNT(DISTINCT IF(f.type LIKE 'news', fd.id,NULL)),'YES','NO' ) AS 'Announcement posted'

FROM prefix_course AS c
LEFT JOIN prefix_course_categories as cc ON c.category = cc.id
LEFT JOIN prefix_context AS ctxx ON c.id = ctxx.instanceid

LEFT JOIN prefix_block_positions AS bpi ON bpi.contextid = ctxx.id AND bpi.blockinstanceid = '43692' # mooprofile
LEFT JOIN prefix_block_positions AS bpm ON bpm.contextid = ctxx.id AND bpm.blockinstanceid = '43962' # messages
LEFT JOIN prefix_block_positions AS bpa ON bpa.contextid = ctxx.id AND bpa.blockinstanceid = '43963' # activities
LEFT JOIN prefix_block_positions AS bpr ON bpr.contextid = ctxx.id AND bpr.blockinstanceid = '38368' # html research help

LEFT JOIN prefix_course_sections AS cs ON cs.course = c.id AND cs.visible = 1 AND cs.sequence IS NOT NULL
LEFT JOIN prefix_course_modules AS cm ON cm.course = c.id AND cm.section = cs.id
LEFT JOIN prefix_modules AS m ON m.id = cm.module
LEFT JOIN prefix_grade_items AS gi ON gi.courseid = c.id AND gi.itemmodule = m.name AND gi.iteminstance = cm.instance

LEFT JOIN prefix_forum AS f ON f.course = c.id AND cm.instance = f.id AND cm.visible = 1
LEFT JOIN prefix_forum_discussions AS fd ON fd.forum = f.id

# attach manual grade items to course-- they don't have modules
LEFT JOIN prefix_grade_items AS mgi ON mgi.courseid = c.id and mgi.itemtype = 'manual'

LEFT JOIN prefix_course_format_options AS cfo ON cfo.courseid = c.id AND cfo.name = 'layoutstructure'
LEFT JOIN prefix_course_format_options AS cfw ON cfw.courseid = c.id AND cfw.name = 'numsections'

LEFT JOIN prefix_block_instances AS bi ON bi.parentcontextid = ctxx.id AND bi.blockname = 'html' AND (bi.configdata LIKE '%SW5zdHJ1Y3Rvc%' or bi.configdata LIKE '%bnN0cnVjdG9y%')
LEFT JOIN prefix_block_positions AS bip ON bip.blockinstanceid = bi.id

WHERE RIGHT(c.idnumber,2) IN ('OL', 'BL', 'HY')
# AND substring(cc.path,2,2) IN ('26') # Staging
#AND substring(cc.path,2,3) IN ('158') # UG
AND cc.idnumber LIKE '%staging%'
AND ctxx.contextlevel = 50

GROUP BY c.shortname
</code>

===Module instances + Module HITs by role teacher and student in course===
<code sql>
SELECT
m.name AS "Module name"
, COUNT(*) AS "Module count"

,(SELECT COUNT(*)
FROM prefix_log AS l
WHERE l.course = cm.course AND l.module = m.name ) AS "Hits"

,(SELECT COUNT(*)
FROM prefix_log AS l
JOIN prefix_context AS con ON con.instanceid= l.course AND con.contextlevel=50
JOIN prefix_role_assignments AS ra ON ra.contextid= con.id AND ra.userid= l.userid AND ra.roleid = 5
WHERE l.course = cm.course AND l.module = m.name) AS "Students HITs"

,(SELECT COUNT(*)
FROM prefix_log AS l
JOIN prefix_context AS con ON con.instanceid= l.course AND con.contextlevel=50
JOIN prefix_role_assignments AS ra ON ra.contextid= con.id AND ra.userid= l.userid AND ra.roleid = 3
WHERE l.course = cm.course AND l.module = m.name) AS "Teachers HITs"

FROM mdl_course_modules AS cm
JOIN mdl_modules AS m on m.id = cm.module
WHERE cm.course = '%%COURSEID%%'
GROUP BY cm.module
</code>

===Course Syllabus===
Contributed by Elizabeth Dalton, Granite State College / Moodle HQ

This report requires ELIS. It runs from within a course and constructs a course syllabus based on content in the course and in the ELIS entries related to the course (Class Instance, Course Description, and Program). It is a proof-of-concept of an automated syllabus production tool. Fields such as "Course Policies" and "Teaching Philosophy" are added to the Class Instance records, and instructors enter them there. The Instructor Bio is pulled from the User Profile of all users with the Teacher role in the course.

<code sql>
SELECT

c.fullname AS 'fullname'
, ec.idnumber AS 'elis-id'
, DATE_FORMAT(FROM_UNIXTIME(ec.startdate), '%b %e, %Y') AS 'start'
, DATE_FORMAT(FROM_UNIXTIME(ec.enddate), '%b %e, %Y') AS 'end'
, ecd.name AS 'longname'
, ecd.code AS 'coursecode'
, ecd.credits AS 'coursecredits'
, ecd.syllabus AS 'description'

, (SELECT eft.data
FROM prefix_local_eliscore_fld_data_text AS eft
JOIN prefix_local_eliscore_field AS ef ON ef.id = eft.fieldid AND ef.shortname = 'learning-outcomes'
WHERE ctxecd.id = eft.contextid) AS 'outcomes'

,(SELECT CONCAT('<a target="_blank" href="%%WWWROOT%%/user/view.php',CHAR(63),'id=',u.id,'">',u.firstname,' ', u.lastname,'</a> ', u.email)
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
JOIN prefix_user AS u ON u.id = ra.userid
WHERE ra.roleid = 3 AND ctx.instanceid = c.id LIMIT 1) AS 'Instructor'

, (SELECT efc.data
FROM prefix_local_eliscore_fld_data_char AS efc
JOIN prefix_local_eliscore_field AS ef ON ef.id = efc.fieldid AND ef.shortname = 'term-code'
WHERE ctxci.id = efc.contextid) AS 'termcode'

, (SELECT eft.data
FROM prefix_local_eliscore_fld_data_text AS eft
JOIN prefix_local_eliscore_field AS ef ON ef.id = eft.fieldid AND ef.shortname = 'prerequisites'
WHERE ctxecd.id = eft.contextid) AS 'prerequisites'

, (SELECT eft.data
FROM prefix_local_eliscore_fld_data_text AS eft
JOIN prefix_local_eliscore_field AS ef ON ef.id = eft.fieldid AND ef.shortname = 'textbooks'
WHERE ctxci.id = eft.contextid) AS 'textbooks'

, (SELECT eft.data
FROM prefix_local_eliscore_fld_data_text AS eft
JOIN prefix_local_eliscore_field AS ef ON ef.id = eft.fieldid AND ef.shortname = 'other-class-materials'
WHERE ctxci.id = eft.contextid) AS 'other-class-materials'

, (SELECT eft.data
FROM prefix_local_eliscore_fld_data_text AS eft
JOIN prefix_local_eliscore_field AS ef ON ef.id = eft.fieldid AND ef.shortname = 'course-policies'
WHERE ctxci.id = eft.contextid) AS 'course-policies'

, (SELECT eft.data
FROM prefix_local_eliscore_fld_data_text AS eft
JOIN prefix_local_eliscore_field AS ef ON ef.id = eft.fieldid AND ef.shortname = 'teaching-philosophy'
WHERE ctxci.id = eft.contextid) AS 'teaching-philosophy'

, (SELECT eft.data
FROM prefix_local_eliscore_fld_data_text AS eft
JOIN prefix_local_eliscore_field AS ef ON ef.id = eft.fieldid AND ef.shortname = 'course-methods'
WHERE ctxci.id = eft.contextid) AS 'course-methods'

,(SELECT u2.description
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
JOIN prefix_user AS u2 ON u2.id = ra.userid
WHERE ra.roleid = 3 AND ctx.instanceid = c.id LIMIT 1) AS 'Bio'

,(SELECT

GROUP_CONCAT(DISTINCT CONCAT(

'<tr><td style="border: solid #000 .5px">',IF(gc.parent IS NOT NULL, gc.fullname, 'None')
, ' </td><td style="border: solid #000 .5px"> '
,IF(gc.parent IS NOT NULL, ROUND(gic.aggregationcoef, 2), ROUND( gi.aggregationcoef, 2)+ROUND(mgi.aggregationcoef, 2))

) SEPARATOR '</td></tr>')
#get grade categories
FROM prefix_grade_categories AS gc
# back from categories to grade items to get aggregations and weights
LEFT JOIN prefix_grade_items AS gic ON gic.courseid = gc.courseid AND gic.itemtype = 'category' AND gic.aggregationcoef != 0 AND (LOCATE(gic.iteminstance, gc.path) OR (gc.parent IS NULL))
# attach grade items to activities
LEFT JOIN prefix_grade_items AS gi ON gi.courseid = gc.courseid AND gi.itemtype = 'mod' AND gi.categoryid = gc.id AND gi.hidden != 1
# attach manual grade items to course-- they don't have modules
LEFT JOIN prefix_grade_items AS mgi ON mgi.courseid = gc.courseid and mgi.itemtype = 'manual' AND mgi.categoryid = gc.id
WHERE gc.courseid = c.id ) AS 'grade categories'

, '<table width = "50%" >' AS 'table start'
, '<table width = "100%" >' AS 'table start 2'
, '</table>' AS 'table end'

, (SELECT eft.data
FROM prefix_local_eliscore_fld_data_text AS eft
JOIN prefix_local_eliscore_field AS ef ON ef.id = eft.fieldid AND ef.shortname = 'activities-schedule'
WHERE ctxci.id = eft.contextid) AS 'activities'

, (SELECT eft.data
FROM prefix_local_eliscore_fld_data_text AS eft
JOIN prefix_local_eliscore_field AS ef ON ef.id = eft.fieldid AND ef.shortname = 'schedule'
WHERE ctxci.id = eft.contextid) AS 'schedule'

, (SELECT eft.data
FROM prefix_local_eliscore_fld_data_text AS eft
JOIN prefix_local_eliscore_field AS ef ON ef.id = eft.fieldid AND ef.shortname = 'grading-scale'
WHERE ctxepm.id = eft.contextid) AS 'gradescale'

FROM
prefix_course AS c

# connect moodle course to ELIS class instance
LEFT JOIN prefix_local_elisprogram_cls_mdl AS ecm ON ecm.moodlecourseid = c.id
LEFT JOIN prefix_local_elisprogram_cls AS ec ON ec.id = ecm.classid
# class instance context
LEFT JOIN prefix_context AS ctxci ON ctxci.instanceid = ec.id AND ctxci.contextlevel = '14'

# connect ELIS class instance to ELIS course description
LEFT JOIN prefix_local_elisprogram_crs AS ecd ON ecd.id = ec.courseid
# course description context
LEFT JOIN prefix_context AS ctxecd ON ctxecd.instanceid = ecd.id AND ctxecd.contextlevel = '13'

#connect ELIS program to ELIS Course Description
LEFT JOIN prefix_local_elisprogram_pgm_crs AS epc ON epc.courseid = ecd.id
LEFT JOIN prefix_local_elisprogram_pgm AS epm ON epm.id = epc.curriculumid
# course program context
LEFT JOIN prefix_context AS ctxepm ON ctxepm.instanceid = epm.id AND ctxepm.contextlevel = '11'

WHERE

c.id = %%COURSEID%%
</code>

===Course Activities Helper===
Contributed by Elizabeth Dalton, Granite State College

This report provides a list of the graded activities in a course.
* '''Note''': Only graded activities are displayed.
* '''Note''': This is a "Global" report. Run it within a course to see a summary of the contents of that course.
* '''Note''': This report assumes that course sections each last one week.

<code sql>
# 303 Course Activities Helper

SELECT

gi.itemmodule AS 'activity type'
# cs.section AS 'section number'

# Calculation assumes each section lasts one week
, CONCAT(DATE_FORMAT(FROM_UNIXTIME(c.startdate + (7*24*60*60* (cs.section-1))), '%b %e, %Y'),' - ',DATE_FORMAT(FROM_UNIXTIME(c.startdate + (7*24*60*60* (cs.section))), '%b %e, %Y')) AS 'Date'

, gi.itemname AS 'activity name'

#, (SELECT asg.intro FROM prefix_assign AS asg WHERE asg.id = cm.instance) AS 'intro'

#, (SELECT f.intro FROM prefix_forum AS f WHERE f.id = cm.instance) AS 'f intro'

, CASE gi.itemmodule
WHEN 'assign' THEN (SELECT asg.intro FROM prefix_assign AS asg WHERE asg.id = gi.iteminstance)
WHEN 'forum' THEN (SELECT f.intro FROM prefix_forum AS f WHERE f.id = gi.iteminstance)
WHEN 'quiz' THEN (SELECT q.intro FROM prefix_quiz AS q WHERE q.id = gi.iteminstance)
END AS 'test case'

#, (SELECT GROUP_CONCAT(CONCAT(' - ',gi.itemname) SEPARATOR ' ') FROM prefix_grade_items AS gi JOIN prefix_course_modules AS cm ON gi.iteminstance = cm.instance WHERE gi.gradetype = 1 AND gi.hidden != 1 AND gi.courseid = c.id AND cm.course = c.id AND cm.section = cs.id ) AS 'activities'

FROM
prefix_course AS c

#get grade sections
LEFT JOIN prefix_course_sections AS cs ON cs.course = c.id AND cs.section > 0 AND cs.section <=14
LEFT JOIN prefix_course_modules AS cm ON cm.course = c.id AND cm.section = cs.id

#LEFT JOIN prefix_assign AS asg ON asg.id = cm.instance

JOIN prefix_grade_items AS gi ON gi.iteminstance = cm.instance AND gi.gradetype = 1 AND gi.hidden != 1 AND gi.courseid = c.id AND cm.course = c.id AND cm.section = cs.id

WHERE
c.id = %%COURSEID%%
AND cs.visible = 1

ORDER BY gi.itemmodule, cs.section
</code>

==Grade and Course Completion Reports==
===Site-Wide Grade Report with All Items===
Shows grades for all course items along with course totals for each student. Works with ad-hoc reports or Configurable Reports
<code sql>
SELECT u.firstname AS 'First' , u.lastname AS 'Last',
u.firstname + ' ' + u.lastname AS 'Display Name',
c.fullname AS 'Course',
cc.name AS 'Category',

CASE
WHEN gi.itemtype = 'course'
THEN c.fullname + ' Course Total'
ELSE gi.itemname
END AS 'Item Name',

ROUND(gg.finalgrade,2) AS Grade,
DATEADD(ss,gg.timemodified,'1970-01-01') AS Time

FROM prefix_course AS c
JOIN prefix_context AS ctx ON c.id = ctx.instanceid
JOIN prefix_role_assignments AS ra ON ra.contextid = ctx.id
JOIN prefix_user AS u ON u.id = ra.userid
JOIN prefix_grade_grades AS gg ON gg.userid = u.id
JOIN prefix_grade_items AS gi ON gi.id = gg.itemid
JOIN prefix_course_categories as cc ON cc.id = c.category

WHERE gi.courseid = c.id
ORDER BY lastname
</code>
For MySQL users, you'll need to use the MySQL DATE_ADD function instead of DATEADD. Replace the line:
<code>
DATEADD(ss,gg.timemodified,'1970-01-01') AS Time
</code>
with:
<code>
FROM_UNIXTIME(gg.timemodified) AS Time
</code>
And:
<code>
u.firstname + ' ' + u.lastname AS 'Display Name',
</code>
with:
<code>
CONCAT(u.firstname,' ',u.lastname) AS 'Display Name',
</code>

===Site-Wide Grade Report with Just Course Totals===
A second site-wide grade report for all students that just shows course totals. Works with ad-hoc reports or Configurable Reports
<code sql>
SELECT u.firstname AS 'First' , u.lastname AS 'Last', u.firstname + ' ' + u.lastname AS 'Display Name',
cc.name AS 'Category',
CASE
WHEN gi.itemtype = 'course'
THEN c.fullname + ' Course Total'
ELSE gi.itemname
END AS 'Item Name',

ROUND(gg.finalgrade,2) AS Grade,
DATEADD(ss,gg.timemodified,'1970-01-01') AS Time

FROM prefix_course AS c
JOIN prefix_context AS ctx ON c.id = ctx.instanceid
JOIN prefix_role_assignments AS ra ON ra.contextid = ctx.id
JOIN prefix_user AS u ON u.id = ra.userid
JOIN prefix_grade_grades AS gg ON gg.userid = u.id
JOIN prefix_grade_items AS gi ON gi.id = gg.itemid
JOIN prefix_course_categories as cc ON cc.id = c.category

WHERE gi.courseid = c.id AND gi.itemtype = 'course'

ORDER BY lastname
</code>

For MySQL users:
<code sql>
SELECT u.firstname AS 'First' , u.lastname AS 'Last', CONCAT(u.firstname , ' ' , u.lastname) AS 'Display Name',
c.fullname AS 'Course',
cc.name AS 'Category',
CASE
WHEN gi.itemtype = 'course'
THEN CONCAT(c.fullname, ' - Total')
ELSE gi.itemname
END AS 'Item Name',

ROUND(gg.finalgrade,2) AS Grade,
FROM_UNIXTIME(gg.timemodified) AS TIME

FROM prefix_course AS c
JOIN prefix_context AS ctx ON c.id = ctx.instanceid
JOIN prefix_role_assignments AS ra ON ra.contextid = ctx.id
JOIN prefix_user AS u ON u.id = ra.userid
JOIN prefix_grade_grades AS gg ON gg.userid = u.id
JOIN prefix_grade_items AS gi ON gi.id = gg.itemid
JOIN prefix_course_categories AS cc ON cc.id = c.category

WHERE gi.courseid = c.id AND gi.itemtype = 'course'
ORDER BY lastname
</code>

===Learner report by Learner with grades===
Which Learners in which course and what are the grades
<code sql>
SELECT u.firstname AS 'Name' , u.lastname AS 'Surname', c.fullname AS 'Course', cc.name AS 'Category',
CASE WHEN gi.itemtype = 'Course'
THEN c.fullname + ' Course Total'
ELSE gi.itemname
END AS 'Item Name', ROUND(gg.finalgrade,2) AS Score,ROUND(gg.rawgrademax,2) AS Max, ROUND(gg.finalgrade / gg.rawgrademax * 100 ,2) as Percentage,

if (ROUND(gg.finalgrade / gg.rawgrademax * 100 ,2) > 79,'Yes' , 'No') as Pass

FROM prefix_course AS c
JOIN prefix_context AS ctx ON c.id = ctx.instanceid
JOIN prefix_role_assignments AS ra ON ra.contextid = ctx.id
JOIN prefix_user AS u ON u.id = ra.userid
JOIN prefix_grade_grades AS gg ON gg.userid = u.id
JOIN prefix_grade_items AS gi ON gi.id = gg.itemid
JOIN prefix_course_categories AS cc ON cc.id = c.category
WHERE gi.courseid = c.id and gi.itemname != 'Attendance'
ORDER BY `Name` ASC
</code>

===User Course Completion===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

A very simple report with a list of course completion status by username. Completions are noted by date, blank otherwise.

<code sql>
SELECT
u.username,
c.shortname,
DATE_FORMAT(FROM_UNIXTIME(p.timecompleted),'%Y-%m-%d') AS completed
FROM prefix_course_completions AS p
JOIN prefix_course AS c ON p.course = c.id
JOIN prefix_user AS u ON p.userid = u.id
WHERE c.enablecompletion = 1
ORDER BY u.username
</code>

===User Course Completion with Criteria===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

A report with course completions by username, with Aggregation method, Criteria types, and Criteria detail where available.

<code sql>
SELECT u.username AS user,
c.shortname AS course,
DATE_FORMAT(FROM_UNIXTIME(t.timecompleted),'%Y-%m-%d') AS completed,
CASE
WHEN (SELECT a.method FROM prefix_course_completion_aggr_methd AS a WHERE (a.course = c.id AND a.criteriatype IS NULL) = 1) THEN "Any"
ELSE "All"
END AS aggregation,
CASE
WHEN p.criteriatype = 1 THEN "Self"
WHEN p.criteriatype = 2 THEN "By Date"
WHEN p.criteriatype = 3 THEN "Unenrol Status"
WHEN p.criteriatype = 4 THEN "Activity"
WHEN p.criteriatype = 5 THEN "Duration"
WHEN p.criteriatype = 6 THEN "Course Grade"
WHEN p.criteriatype = 7 THEN "Approve by Role"
WHEN p.criteriatype = 8 THEN "Previous Course"
END AS criteriatype,
CASE
WHEN p.criteriatype = 1 THEN "*"
WHEN p.criteriatype = 2 THEN DATE_FORMAT(FROM_UNIXTIME(p.timeend),'%Y-%m-%d')
WHEN p.criteriatype = 3 THEN t.unenroled
WHEN p.criteriatype = 4 THEN
CONCAT('<a target="_new" href="%%WWWROOT%%/mod/',p.module,'/view.php?id=',p.moduleinstance,'">',p.module,'</a>')
WHEN p.criteriatype = 5 THEN p.enrolperiod
WHEN p.criteriatype = 6 THEN CONCAT('Needed: ',ROUND(p.gradepass,2),' Achieved: ',ROUND(t.gradefinal,2))
WHEN p.criteriatype = 7 THEN p.role
WHEN p.criteriatype = 8 THEN (SELECT pc.shortname FROM prefix_course AS pc WHERE pc.id = p.courseinstance)
END AS criteriadetail
FROM prefix_course_completion_crit_compl AS t
JOIN prefix_user AS u ON t.userid = u.id
JOIN prefix_course AS c ON t.course = c.id
JOIN prefix_course_completion_criteria AS p ON t.criteriaid = p.id

</code>

===Courses with Completion Enabled and their settings===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

List of all courses with completion enabled and their Aggregation setting, Criteria types, and Criteria details.

<code sql>

SELECT c.shortname AS Course,
CASE
WHEN (SELECT a.method FROM prefix_course_completion_aggr_methd AS a WHERE (a.course = t.course AND a.criteriatype IS NULL)) = 2 THEN "All"
ELSE "Any"
END AS Course_Aggregation,
CASE
WHEN t.criteriatype = 1 THEN "Self completion"
WHEN t.criteriatype = 2 THEN "Date done by"
WHEN t.criteriatype = 3 THEN "Unenrolement"
WHEN t.criteriatype = 4 THEN "Activity completion"
WHEN t.criteriatype = 5 THEN "Duration in days"
WHEN t.criteriatype = 6 THEN "Final grade"
WHEN t.criteriatype = 7 THEN "Approve by role"
WHEN t.criteriatype = 8 THEN "Previous course"
END AS Criteria_type,
CASE
WHEN t.criteriatype = 1 THEN "On"
WHEN t.criteriatype = 2 THEN DATE_FORMAT(FROM_UNIXTIME(t.timeend),'%Y-%m-%d')
WHEN t.criteriatype = 3 THEN "On"
WHEN t.criteriatype = 4 THEN
CONCAT('<a target="_new" href="%%WWWROOT%%/mod/',t.module,'/view.php?id=',t.moduleinstance,'">',t.module,'</a>')
WHEN t.criteriatype = 5 THEN ROUND(t.enrolperiod/86400)
WHEN t.criteriatype = 6 THEN ROUND(t.gradepass,2)
WHEN t.criteriatype = 7 THEN (SELECT r.shortname FROM prefix_role AS r WHERE r.id = t.role)
WHEN t.criteriatype = 8 THEN (SELECT pc.shortname FROM prefix_course AS pc WHERE pc.id = t.courseinstance)
END AS Criteria_detail
FROM prefix_course_completion_criteria as t
JOIN prefix_course AS c ON t.course = c.id
WHERE c.enablecompletion = 1
ORDER BY course
</code>

===Course Completion Report with custom dates===

List of users who completed multiple or single course/s from a start date to end date chosen by the user. The output gives username, name, course name, completion date and score

<code sql>

SELECT u.username AS 'User Name',
CONCAT(u.firstname , ' ' , u.lastname) AS 'Name',
c.shortname AS 'Course Name',
DATE_FORMAT(FROM_UNIXTIME(p.timecompleted),'%W %e %M, %Y') AS 'Completed Date',
ROUND(c4.gradefinal,2) AS 'Score'
FROM prefix_course_completions AS p
JOIN prefix_course AS c ON p.course = c.id
JOIN prefix_user AS u ON p.userid = u.id
JOIN prefix_course_completion_crit_compl AS c4 ON u.id = c4.userid
WHERE c.enablecompletion = 1 AND (p.timecompleted IS NOT NULL OR p.timecompleted !='')
AND (p.timecompleted>= :start_date AND p.timecompleted<=:end_date)
GROUP BY u.username
ORDER BY c.shortname

</code>

===Scales used in activities===
<code sql>
SELECT scale.name
,CONCAT('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.fullname,'</a>') AS Course
,CONCAT('<a target="_new" href="%%WWWROOT%%/mod/',gi.itemmodule,'/view.php?id=',cm.id,'">',gi.itemname,'</a>') AS "Module View"
,CONCAT('<a target="_new" href="%%WWWROOT%%/course/modedit.php?up','date=',cm.id,'">',gi.itemname,'</a>') AS "Module Settings"

FROM prefix_grade_items AS gi
JOIN prefix_course AS c ON c.id = gi.courseid
JOIN prefix_course_modules AS cm ON cm.course = gi.courseid AND cm.instance = gi.iteminstance
JOIN prefix_scale AS scale ON scale.id = gi.scaleid
WHERE gi.scaleid IS NOT NULL
</code>

===Extra Credit Items by Name Only===
Contributed by Eric Strom

This query identifies grade items in visible courses with student enrollment that have "extra credit" in the name of the item but set as extra credit in the grade settings. Includes the defined course start date, count of students and instructors, and a clickable email link of instructor (first found record if more than one).

<code sql>
SELECT DATE(FROM_UNIXTIME(c.startdate)) AS StartDate,
concat('<a target="_new" href="%%WWWROOT%%/grade/edit/tree/index.php',CHAR(63),'id=',
c.id,'">',c.idnumber,'</a>') AS Course_ID, gi.itemname AS Item_Name

,(SELECT COUNT( ra.userid ) FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid = 5 AND ctx.instanceid = c.id) AS Students

,(SELECT COUNT( ra.userid ) FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid = 3 AND ctx.instanceid = c.id) AS Instructors

,(SELECT DISTINCT concat('<a href="mailto:',u.email,'">',u.email,'</a>')
FROM prefix_role_assignments AS ra
JOIN prefix_user AS u ON ra.userid = u.id
JOIN prefix_context AS ctx ON ctx.id = ra.contextid
WHERE ra.roleid = 3 AND ctx.instanceid = c.id AND ctx.contextlevel = 50 LIMIT 1) AS 'Instructor_Email'

,now() AS Report_Timestamp

FROM prefix_grade_items AS gi
JOIN prefix_course AS c ON gi.courseid = c.id

WHERE gi.itemname LIKE '%extra credit%'
AND gi.gradetype = '1'
AND gi.hidden = '0'
AND gi.aggregationcoef = '0'
AND c.visible = 1
AND (SELECT COUNT( ra.userid ) FROM prefix_role_assignments AS ra JOIN prefix_context AS ctx ON ra.contextid = ctx.id WHERE ra.roleid = 5 AND ctx.instanceid = c.id) > 0

GROUP BY Course_ID, gi.id
ORDER BY StartDate, Course_ID

%%FILTER_SEARCHTEXT:Course_ID:~%%
</code>

===Site Wide Number of Courses Completed by User===
Contributed by Ken St. John

Simple report that shows the number of completed courses for all users site wide

<code sql>
SELECT u.lastname, u.firstname,
COUNT(p.timecompleted) AS TotalCompletions
FROM prefix_course_completions AS p
JOIN prefix_user AS u ON p.userid = u.id
GROUP BY p.userid
ORDER BY u.lastname
</code>

==Activity Module Reports==

=== User activity completions with dates===
Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

This report shows the users completion status of activities across all courses. It is intended to be uses with Configurable Reports filters for user, start and end times, and also to be able to search the Module names.

Note: The CASE statement with module numbers may differ on different systems, depending on the number give to the module when the site was created or the module added to the site. These are common default numbers, but you should check your id numbers for them in the course_modules table and adjust as required. You can also add other, third-party plugins too if you wish.

<code sql>
SELECT
u.username As 'User',
c.shortname AS 'Course',
m.name AS Activitytype,
CASE
WHEN cm.module = 1 THEN (SELECT a1.name FROM prefix_assign a1 WHERE a1.id = cm.instance)
WHEN cm.module = 2 THEN (SELECT a2.name FROM prefix_assignment a2 WHERE a2.id = cm.instance)
WHEN cm.module = 3 THEN (SELECT a3.name FROM prefix_book a3 WHERE a3.id = cm.instance)
WHEN cm.module = 4 THEN (SELECT a4.name FROM prefix_chat a4 WHERE a4.id = cm.instance)
WHEN cm.module = 5 THEN (SELECT a5.name FROM prefix_choice a5 WHERE a5.id = cm.instance)
WHEN cm.module = 6 THEN (SELECT a6.name FROM prefix_data a6 WHERE a6.id = cm.instance)
WHEN cm.module = 7 THEN (SELECT a7.name FROM prefix_feedback a7 WHERE a7.id = cm.instance)
WHEN cm.module = 8 THEN (SELECT a8.name FROM prefix_folder a8 WHERE a8.id = cm.instance)
WHEN cm.module = 9 THEN (SELECT a9.name FROM prefix_forum a9 WHERE a9.id = cm.instance)
WHEN cm.module = 10 THEN (SELECT a10.name FROM prefix_glossary a10 WHERE a10.id = cm.instance)
WHEN cm.module = 11 THEN (SELECT a11.name FROM prefix_imscp a11 WHERE a11.id = cm.instance)
WHEN cm.module = 12 THEN (SELECT a12.name FROM prefix_label a12 WHERE a12.id = cm.instance)
WHEN cm.module = 13 THEN (SELECT a13.name FROM prefix_lesson a13 WHERE a13.id = cm.instance)
WHEN cm.module = 14 THEN (SELECT a14.name FROM prefix_lti a14 WHERE a14.id = cm.instance)
WHEN cm.module = 15 THEN (SELECT a15.name FROM prefix_page a15 WHERE a15.id = cm.instance)
WHEN cm.module = 16 THEN (SELECT a16.name FROM prefix_quiz a16 WHERE a16.id = cm.instance)
WHEN cm.module = 17 THEN (SELECT a17.name FROM prefix_resource a17 WHERE a17.id = cm.instance)
WHEN cm.module = 18 THEN (SELECT a18.name FROM prefix_scorm a18 WHERE a18.id = cm.instance)
WHEN cm.module = 19 THEN (SELECT a19.name FROM prefix_survey a19 WHERE a19.id = cm.instance)
WHEN cm.module = 20 THEN (SELECT a20.name FROM prefix_url a20 WHERE a20.id = cm.instance)
WHEN cm.module = 21 THEN (SELECT a21.name FROM prefix_wiki a21 WHERE a21.id = cm.instance)
WHEN cm.module = 22 THEN (SELECT a22.name FROM prefix_workshop a22 WHERE a22.id = cm.instance)
END AS Actvityname,
# cm.section AS Coursesection,
CASE
WHEN cm.completion = 0 THEN '0 None'
WHEN cm.completion = 1 THEN '1 Self'
WHEN cm.completion = 2 THEN '2 Auto'
END AS Activtycompletiontype,
CASE
WHEN cmc.completionstate = 0 THEN 'In Progress'
WHEN cmc.completionstate = 1 THEN 'Completed'
WHEN cmc.completionstate = 2 THEN 'Completed with Pass'
WHEN cmc.completionstate = 3 THEN 'Completed with Fail'
ELSE 'Unknown'
END AS 'Progress',
DATE_FORMAT(FROM_UNIXTIME(cmc.timemodified), '%Y-%m-%d %H:%i') AS 'When'
FROM prefix_course_modules_completion cmc
JOIN prefix_user u ON cmc.userid = u.id
JOIN prefix_course_modules cm ON cmc.coursemoduleid = cm.id
JOIN prefix_course c ON cm.course = c.id
JOIN prefix_modules m ON cm.module = m.id
# skip the predefined admin and guest user
WHERE u.id > 2
# config reports filters
%%FILTER_USERS:u.username%%
%%FILTER_SEARCHTEXT:m.name:~%%
%%FILTER_STARTTIME:cmc.timemodified:>%% %%FILTER_ENDTIME:cmc.timemodified:<%%

ORDER BY u.username

</code>

===How many SCORM activities are used in each Course===
<code sql>
SELECT cm.course,c.fullname ,m.name
,concat('<a target="_new" href="%%WWWROOT%%/mod/scorm/index.php?id=',c.id,'">',count(cm.id),'</a>') AS Counter

FROM `prefix_course_modules` as cm
JOIN prefix_modules as m ON cm.module=m.id
JOIN prefix_course as c ON cm.course = c.id
WHERE m.name LIKE '%scorm%'
GROUP BY cm.course,cm.module
ORDER BY count(cm.id) desc
</code>

===SCORM Usage by Course Start Date===
Contributed by Elizabeth Dalton, Granite State College

Report of number of inclusions of SCORM activities in courses, filtered by course start date.

<code sql>
SELECT

CONCAT('<a target="_blank" href="%%WWWROOT%%/course/view.php',CHAR(63),'id=',c.id,'">',c.shortname,'</a>') AS 'course'

, cc.name AS 'Category'
, scm.name AS 'Sample Activity Name'
, FROM_UNIXTIME(c.startdate) AS 'Course Start Date'
, COUNT(DISTINCT cm.id) AS 'Resources Used'
#, FROM_UNIXTIME(cm.added) AS 'resource added'

FROM prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id AND m.name LIKE 'SCO%'

JOIN prefix_course AS c ON c.id = cm.course
JOIN prefix_course_categories AS cc ON cc.id = c.category
JOIN prefix_scorm AS scm ON scm.id = cm.instance

WHERE
1

%%FILTER_STARTTIME:c.startdate:>%%
%%FILTER_ENDTIME:c.startdate:<%%

GROUP BY c.shortname, m.name
ORDER BY c.startdate, c.shortname
</code>

=== LTI (External Tool) Usage by Course Start Date===
Contributed by Elizabeth Dalton, Granite State College

Report of number of inclusions of LTI (External Tool) Usage activities in courses, filtered by course start date.

<code sql>
SELECT

CONCAT('<a target="_blank" href="%%WWWROOT%%/course/view.php',CHAR(63),'id=',c.id,'">',c.shortname,'</a>') AS 'course'

, cc.name AS 'Category'
, lti.name AS 'Sample Activity Name'
, FROM_UNIXTIME(c.startdate) AS 'Course Start Date'
, COUNT(DISTINCT cm.id) AS 'Resources Used'
#, FROM_UNIXTIME(cm.added) AS 'resource added'

FROM prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id AND m.name LIKE 'lti'

JOIN prefix_course AS c ON c.id = cm.course
JOIN prefix_course_categories AS cc ON cc.id = c.category
JOIN prefix_lti AS lti ON lti.id = cm.instance
WHERE
1

%%FILTER_STARTTIME:c.startdate:>%%
%%FILTER_ENDTIME:c.startdate:<%%

GROUP BY c.shortname, m.name
ORDER BY c.startdate, c.shortname
</code>

===Detailed ACTIONs for each MODULE===
<code sql>
SELECT module,action,count(id) as counter
FROM prefix_log
GROUP BY module,action
ORDER BY module,counter desc
</code>

===Most popular ACTIVITY===
<code sql>
SELECT COUNT(l.id) hits, module
FROM prefix_log l
WHERE module != 'login' AND module != 'course' AND module != 'role'
GROUP BY module
ORDER BY hits DESC
</code>

===System wide use of ACTIVITIES and RESOURCES===
<code sql>
SELECT count( cm.id ) AS counter, m.name
FROM `prefix_course_modules` AS cm
JOIN prefix_modules AS m ON cm.module = m.id
GROUP BY cm.module
ORDER BY counter DESC
</code>

===LOG file ACTIONS per MODULE per COURSE (IDs)===
<code sql>
select course,module,action,count(action) as summa from prefix_log
where action <> 'new'
group by course,action,module
order by course,module,action
</code>

===System Wide usage count of various course Activities===
(Tested and works fine in Moodle 2.x)
Like: Forum, Wiki, Blog, Assignment, Database,
#Within specific category
#Teacher name in course

<code sql>
SELECT concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.fullname,'</a>') as Course

,(SELECT CONCAT(u.firstname,' ', u.lastname) AS Teacher
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
JOIN prefix_user AS u ON u.id = ra.userid
WHERE ra.roleid = 3 AND ctx.instanceid = c.id LIMIT 1) AS Teacher

,(SELECT count( m.name ) AS count FROM prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
WHERE cm.course = c.id AND m.name LIKE '%wiki%') AS Wikis
,(SELECT count( m.name ) AS count FROM prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
WHERE cm.course = c.id AND m.name LIKE '%blog%') AS Blogs

,(SELECT count( m.name ) AS count FROM
prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
WHERE cm.course = c.id AND m.name LIKE '%forum%') AS Forums

,(SELECT count( m.name ) AS count FROM prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
WHERE cm.course = c.id AND m.name LIKE '%data%') AS Databses

,(SELECT count( m.name ) AS count FROM prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
WHERE cm.course = c.id AND m.name LIKE '%assignment%') AS Assignments

,(SELECT Count( ra.userid ) AS Users FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid = 5 AND ctx.instanceid = c.id) AS Students

FROM prefix_course AS c
WHERE c.category IN ( 18)
ORDER BY Wikis DESC,Blogs DESC, Forums DESC
</code>

===Course wiki usage/activity over the last 6 semesters===
<code sql>
SELECT "Courses with Wikis"

,(SELECT count( m.name ) AS count FROM
prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
JOIN prefix_course AS c ON c.id = cm.course
WHERE cm.course = c.id AND m.name LIKE '%wiki%'
and c.fullname LIKE CONCAT('%','2010','%') and c.fullname LIKE '%Semester A%') AS '2010 Semester A'

,(SELECT count( m.name ) AS count FROM
prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
JOIN prefix_course AS c ON c.id = cm.course
WHERE cm.course = c.id AND m.name LIKE '%wiki%'
and c.fullname LIKE CONCAT('%','2010','%') and c.fullname LIKE '%Semester B%') AS '2010 Semester B'

,(SELECT count( m.name ) AS count FROM
prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
JOIN prefix_course AS c ON c.id = cm.course
WHERE cm.course = c.id AND m.name LIKE '%wiki%'
and c.fullname LIKE CONCAT('%','תשעא','%') and c.fullname LIKE '%סמסטר א%') AS 'תשעא סמסטר א'

,(SELECT count( m.name ) AS count FROM
prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
JOIN prefix_course AS c ON c.id = cm.course
WHERE cm.course = c.id AND m.name LIKE '%wiki%'
and c.fullname LIKE CONCAT('%','תשעא','%') and c.fullname LIKE '%סמסטר ב%') AS 'תשעא סמסטר ב'

,(SELECT count( m.name ) AS count FROM
prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
JOIN prefix_course AS c ON c.id = cm.course
WHERE cm.course = c.id AND m.name LIKE '%wiki%'
and c.fullname LIKE CONCAT('%','תשעב','%') and c.fullname LIKE '%סמסטר א%') AS 'תשעב סמסטר א'

,(SELECT count( m.name ) AS count FROM
prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
JOIN prefix_course AS c ON c.id = cm.course
WHERE cm.course = c.id AND m.name LIKE '%wiki%'
and c.fullname LIKE CONCAT('%','תשעב','%') and c.fullname LIKE '%סמסטר ב%') AS 'תשעב סמסטר ב'

,(SELECT count( m.name ) AS count FROM
prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
JOIN prefix_course AS c ON c.id = cm.course
WHERE cm.course = c.id AND m.name LIKE '%wiki%'
and c.fullname LIKE CONCAT('%','תשעג','%') and c.fullname LIKE '%סמסטר א%') AS 'תשעג סמסטר א'

,(SELECT count( m.name ) AS count FROM
prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
JOIN prefix_course AS c ON c.id = cm.course
WHERE cm.course = c.id AND m.name LIKE '%wiki%'
and c.fullname LIKE CONCAT('%','תשעג','%') and c.fullname LIKE '%סמסטר ב%') AS 'תשעג סמסטר ב'
</code>

===Detailed WIKI activity (per wiki per course)===
Including Number of Students in course (for reference)
<code sql>
SELECT concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',cm.course,'">',c.fullname,'</a>') as CourseID
,(SELECT Count( ra.userid ) AS Users
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid = 5 AND ctx.instanceid = c.id ) AS Students
,m.name
, ( SELECT count(id) FROM prefix_log WHERE cmid = cm.id AND action LIKE '%updat%' ) as 'UPDAT E'
, ( SELECT count(id) FROM prefix_log WHERE cmid = cm.id AND action LIKE '%annotate%' ) as ANNOTATE
, ( SELECT count(id) FROM prefix_log WHERE cmid = cm.id AND action LIKE '%comment%' ) as COMMENT
, ( SELECT count(id) FROM prefix_log WHERE cmid = cm.id AND action LIKE '%add%' ) as 'A DD'
, ( SELECT count(id) FROM prefix_log WHERE cmid = cm.id AND action LIKE '%edit%' ) as EDIT
, ( SELECT count(id) FROM prefix_log WHERE cmid = cm.id AND action NOT LIKE '%view%' ) as 'All (NO View)'
FROM `prefix_course_modules` as cm
JOIN prefix_modules as m ON cm.module=m.id
JOIN prefix_course as c ON cm.course = c.id
WHERE m.name LIKE '%wiki%'
GROUP BY cm.course,cm.module
ORDER BY 'All (NO View)' DESC
</code>

===Wiki usage, system wide===
(you can filter the output by selecting some specific course categories : "WHERE c.category IN ( 8,13,15)")

<code sql>
SELECT concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.fullname,'</a>') as Course

,(SELECT count( m.name ) AS count FROM prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
WHERE cm.course = c.id AND m.name LIKE '%wiki%') AS Wikis

,(SELECT count(*) FROM prefix_log as l WHERE l.course = c.id AND l.module LIKE '%wiki%') AS 'WikiActivity ALL'

,(SELECT count(*) FROM prefix_log as l WHERE l.course = c.id AND l.module LIKE '%wiki%' and l.action LIKE '%add%' ) AS 'WikiActivity ADD'

,(SELECT count(*) FROM prefix_log as l WHERE l.course = c.id AND l.module LIKE '%wiki%' and l.action LIKE '%edit%' ) AS 'WikiActivity EDIT'

,(SELECT count(*) FROM prefix_log as l WHERE l.course = c.id AND l.module LIKE '%wiki%' and l.action LIKE '%annotate%' ) AS 'WikiActivity ANNOTATE'

,(SELECT count(*) FROM prefix_log as l WHERE l.course = c.id AND l.module LIKE '%wiki%' and l.action LIKE '%comments%' ) AS 'WikiActivity Comments'

,(SELECT Count( ra.userid ) AS Users FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid = 5 AND ctx.instanceid = c.id) AS Students

,(SELECT count(*) FROM prefix_ouwiki_pages as ouwp
JOIN prefix_ouwiki as ouw ON ouw.id = ouwp.subwikiid
WHERE ouw.course = c.id GROUP BY ouw.course ) as OUWikiPages

,(SELECT count( DISTINCT nwp.pagename ) FROM prefix_wiki_pages AS nwp
JOIN prefix_wiki AS nw ON nw.id = nwp.dfwiki WHERE nw.course = c.id ) As NWikiPages

FROM prefix_course AS c
WHERE c.category IN ( 8,13,15)
HAVING Wikis > 0
ORDER BY 'WikiActivity ALL' DESC
</code>

===Aggregated Teacher activity by "WEB2" Modules===
(Tested and works fine in Moodle 2.x)
The NV column shows activity without VIEW log activity
<code sql>
SELECT ra.userid, u.firstname,u.lastname
,(SELECT count(*) FROM prefix_log as l WHERE l.userid = u.id AND l.module LIKE '%wiki%') AS Wiki
,(SELECT count(*) FROM prefix_log as l WHERE l.userid = u.id AND l.module LIKE '%wiki%' AND l.action NOT LIKE '%view%') AS Wiki_NV
,(SELECT count(*) FROM prefix_log as l WHERE l.userid = u.id AND l.module LIKE '%forum%') AS Forum
,(SELECT count(*) FROM prefix_log as l WHERE l.userid = u.id AND l.module LIKE '%forum%' AND l.action NOT LIKE '%view%') AS Forum_NV
,(SELECT count(*) FROM prefix_log as l WHERE l.userid = u.id AND l.module LIKE '%blog%') AS Blog
,(SELECT count(*) FROM prefix_log as l WHERE l.userid = u.id AND l.module LIKE '%blog%' AND l.action NOT LIKE '%view%') AS Blog_NV
,(SELECT count(*) FROM prefix_log as l WHERE l.userid = u.id AND l.module LIKE '%assignment%') AS Assignment
,(SELECT count(*) FROM prefix_log as l WHERE l.userid = u.id AND l.module LIKE '%assignment%' AND l.action NOT LIKE '%view%') AS Assignment_NV
FROM prefix_role_assignments AS ra
JOIN prefix_user AS u ON u.id = ra.userid
WHERE ra.roleid = 3
GROUP BY ra.userid
</code>

===List all the certificates issued, sort by variables in the custom profile fields===
Note: The SQL queries look intimidating at first, but isn't really that difficult to learn. I've seen in the forums that users wanted to do 'site-wide' groups in 1.9x. This is sort of the idea. It pulls all the certificates issued to all users sorted by the custom profile fields, which in my case is the Units or Depts (i.e. my site wide groups). Why certificates? I've explored with both grades and quizzes, the course admins are not really interested in the actual grades but whether the learner received a certificate (i.e. passed the course with x, y, z activities). It also saves me from creating groups and assigning them into the right groups. Even assigning in bulk is not efficient, since I have upward of 25 groups per course and constantly new learners enrolling in courses. The limitation is something to do with the server? as it only pull 5000 rows of data. If anyone figured out how to change this, please let me know. In the meantime, the work around is to pull only a few units/depts at a time to limit the number of rows. This is fine at the moment, since each course admin are only responsible for certain units/depts.

<code sql>
SELECT
DATE_FORMAT( FROM_UNIXTIME(prefix_certificate_issues.timecreated), '%Y-%m-%d' ) AS Date,
prefix_certificate_issues.classname AS Topic,
prefix_certificate.name AS Certificate,
prefix_certificate_issues.studentname as Name,
prefix_user_info_data.data AS Units

FROM
prefix_certificate_issues

INNER JOIN prefix_user_info_data
on prefix_certificate_issues.userid = prefix_user_info_data.userid

INNER JOIN prefix_certificate
on prefix_certificate_issues.certificateid = prefix_certificate.id

WHERE prefix_user_info_data.data='Unit 1'
OR prefix_user_info_data.data='Unit 2'
OR prefix_user_info_data.data='Unit 3'

ORDER BY Units, Name, Topic ASC
</code>

=== All Simple Certificates Earned in the Site===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

Basic report of all certificates earned with the Simple Certificate plugin module in the whole site, sorted by most recent first. (Note: this uses the MySQL [http://www.mysqltutorial.org/mysql-date_format/ DATE_FORMAT] function.)

<code sql>
SELECT
CONCAT (u.firstname, ' ',u.lastname) As 'User',
c.fullname AS 'Course',
sc.name AS 'Certificate',
DATE_FORMAT( FROM_UNIXTIME(sci.timecreated), '%Y-%m-%d' ) As 'Date Awarded'
# sci.code 'CertificateId'
FROM prefix_simplecertificate_issues sci
JOIN prefix_user u ON sci.userid = u.id
JOIN prefix_simplecertificate sc ON sci.certificateid = sc.id
JOIN prefix_course AS c ON sc.course = c.id
ORDER BY sci.timecreated DESC
</code>

If you want to limit this to the most recent ones, you can add a condition to limit it to a certain number of days past. For example, adding this WHERE clause (above the ORDER BY) will show only those earned in the last 30 days:
<code sql>
WHERE DATEDIFF(NOW(),FROM_UNIXTIME(sci.timecreated) ) < 30
</code>

===Counter Blog usage in Courses,system wide===
What teachers in what courses, uses blogs and how many + student count in that course.
<code sql>

SELECT ( @counter := @counter+1) as counter,
concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.fullname,'</a>') as Course

,( SELECT DISTINCT CONCAT(u.firstname,' ',u.lastname)
FROM prefix_role_assignments AS ra
JOIN prefix_user AS u ON ra.userid = u.id
JOIN prefix_context AS ctx ON ctx.id = ra.contextid
WHERE ra.roleid = 3 AND ctx.instanceid = c.id AND ctx.contextlevel = 50 LIMIT 1) AS Teacher

,(SELECT count( m.name ) AS count FROM prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
WHERE cm.course = c.id AND m.name LIKE '%blog%') AS Blogs

,(SELECT Count( ra.userid ) AS Users FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid = 5 AND ctx.instanceid = c.id) AS Students

FROM prefix_course AS c, (SELECT @counter := 0) as s_init
WHERE c.category IN ( 8,13,15)
HAVING Blogs > 0
ORDER BY Blogs DESC
</code>

=== Elluminate (Blackboard Collaborate) - system wide usage===
<code sql>
SELECT e.name As Session ,er.recordingsize
,c.fullname As Course
,u.firstname,u.lastname
,DATE_FORMAT(FROM_UNIXTIME(e.timestart),'%d-%m-%Y') AS dTimeStart
,concat('<a target="_new" href="%%WWWROOT%%/moodle/mod/elluminate/loadrecording.php?id=',er.id,'">Show</a>') AS RecordedSession

FROM prefix_elluminate_recordings AS er
JOIN prefix_elluminate AS e ON e.meetingid = er.meetingid
JOIN prefix_course as c ON c.id = e.course
JOIN prefix_user AS u ON u.id = e.creator
ORDER BY er.recordingsize DESC
</code>

=== Choice ===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

Results of the Choice activity. For all courses, shows course shortname, username, the Choice text, and the answer chosen by the user.

<code sql>
SELECT c.shortname AS course, u.username, h.name as question, o.text AS answer
FROM prefix_choice AS h
JOIN prefix_course AS c ON h.course = c.id
JOIN prefix_choice_answers AS a ON h.id = a.choiceid
JOIN prefix_user AS u ON a.userid = u.id
JOIN prefix_choice_options AS o ON a.optionid = o.id
</code>

=== Assignment type usage in courses ===
<code sql>
SELECT

CONCAT('<a target="_new" href="%%WWWROOT%%/mod/assign/index.php?id=',c.id,'">',c.fullname,'</a>') AS "List assignments"

,(SELECT COUNT(*) FROM prefix_assign WHERE c.id = course) AS Assignments

,(SELECT COUNT(*)
FROM prefix_assign_plugin_config AS apc
JOIN prefix_assign AS iassign ON iassign.id = apc.assignment
WHERE iassign.course = c.id AND apc.plugin = 'file' AND apc.subtype = 'assignsubmission' AND apc.name = 'enabled' AND apc.value = '1'
#GROUP BY apc.plugin
) AS "File Assignments"

,(SELECT COUNT(*)
FROM prefix_assign_plugin_config AS apc
JOIN prefix_assign AS iassign ON iassign.id = apc.assignment
WHERE iassign.course = c.id AND apc.plugin = 'onlinetext' AND apc.subtype = 'assignsubmission' AND apc.name = 'enabled' AND apc.value = '1'
) AS "Online Assignments"

,(SELECT COUNT(*)
FROM prefix_assign_plugin_config AS apc
JOIN prefix_assign AS iassign ON iassign.id = apc.assignment
WHERE iassign.course = c.id AND apc.plugin = 'pdf' AND apc.subtype = 'assignsubmission' AND apc.name = 'enabled' AND apc.value = '1'
) AS "PDF Assignments"

,(SELECT COUNT(*)
FROM prefix_assign_plugin_config AS apc
JOIN prefix_assign AS iassign ON iassign.id = apc.assignment
WHERE iassign.course = c.id AND apc.plugin = 'offline' AND apc.subtype = 'assignsubmission' AND apc.name = 'enabled' AND apc.value = '1'
) AS "Offline Assignments"

,(SELECT COUNT(*)
FROM prefix_assign_plugin_config AS apc
JOIN prefix_assign AS iassign ON iassign.id = apc.assignment
WHERE iassign.course = c.id AND apc.plugin = 'comments' AND apc.subtype = 'assignsubmission' AND apc.name = 'enabled' AND apc.value = '1'
) AS "Assignments Comments"

FROM prefix_assign AS assign
JOIN prefix_course AS c ON c.id = assign.course
GROUP BY c.id
</code>

==Assignment Module Reports==
===All Ungraded Assignments===

'''NOTE: This query is for the deprecated old Assignment module from Moodle 2.2, not the new Assignments module. Please update this query if you are the author or it will be removed as the 2.2 Assignment module is no longer supported since release 2.7.
''' See: [https://docs.moodle.org/dev/Moodle_2.7_release_notes#Assignment]

Returns all the submitted assignments that still need grading
<code sql>
select
u.firstname AS "First",
u.lastname AS "Last",
c.fullname AS "Course",
a.name AS "Assignment"

from prefix_assignment_submissions as asb
join prefix_assignment as a ON a.id = asb.assignment
join prefix_user as u ON u.id = asb.userid
join prefix_course as c ON c.id = a.course
join prefix_course_modules as cm ON c.id = cm.course

where asb.grade < 0 and cm.instance = a.id
and cm.module = 1

order by c.fullname, a.name, u.lastname
</code>

===All Ungraded Assignments w/ Link===
Returns all assignments submitted by those with the student role that have the status of 'submitted', along with a link that goes directly to the submission to grade it. The links work if you view the report within Moodle.

'''This query is updated for use with Moodle 2.2 or later. Contributed by Carly J. Born, Carleton College'''
<code sql>
SELECT
u.firstname AS "First",
u.lastname AS "Last",
c.fullname AS "Course",
a.name AS "Assignment",

concat('<a target="_new" href="%%WWWROOT%%/mod/assign/view.php?id=',
cm.id,
'&rownum=0&action=grader&userid=',
u.id,
'">Grade</a>')
AS "Assignment link"

FROM prefix_assign_submission sub
JOIN prefix_assign a ON a.id = sub.assignment
JOIN prefix_user u ON u.id = sub.userid
JOIN prefix_course c ON c.id = a.course AND c.id = %%COURSEID%%
JOIN prefix_course_modules cm ON c.id = cm.course
JOIN prefix_context cxt ON c.id=cxt.instanceid AND cxt.contextlevel=50
JOIN prefix_role_assignments ra ON cxt.id = ra.contextid AND ra.roleid=5 AND ra.userid=u.id

WHERE cm.instance = a.id AND cm.module = 22 AND sub.status='submitted'

ORDER BY c.fullname, a.name, u.lastname
</code sql>

NOTE: This query is for the deprecated old Assignment module from Moodle 2.2, not the new Assignments module. Please update this query if you are the author or it will be removed as the 2.2 Assignment module is no longer supported since release 2.7.
See: [https://docs.moodle.org/dev/Moodle_2.7_release_notes#Assignment]

Returns all the submitted assignments that still need grading, along with a link that goes directly to the submission to grade it. The links work if you view the report within Moodle.

<code sql>
select
u.firstname AS "First",
u.lastname AS "Last",
c.fullname AS "Course",
a.name AS "Assignment",

'<a href="http://education.varonis.com/mod/assignment/submissions.php' + char(63) +
+ 'id=' + cast(cm.id as varchar) + '&userid=' + cast(u.id as varchar)
+ '&mode=single&filter=0&offset=2">' + a.name + '</a>'
AS "Assignmentlink"

from prefix_assignment_submissions as asb
join prefix_assignment as a ON a.id = asb.assignment
join prefix_user as u ON u.id = asb.userid
join prefix_course as c ON c.id = a.course
join prefix_course_modules as cm ON c.id = cm.course

where asb.grade < 0 and cm.instance = a.id and cm.module = 1

order by c.fullname, a.name, u.lastname
</code>

===Assignments (and Quizzes) waiting to be graded===

'''NOTE: This query is for the deprecated old Assignment module from Moodle 2.2, not the new Assignments module. Please update this query if you are the author or it will be removed as the 2.2 Assignment module is no longer supported since release 2.7.
''' See: [https://docs.moodle.org/dev/Moodle_2.7_release_notes#Assignment]

This report requires a YEAR filter to be added (Available when using the latest block/configurable_reports)

Which you can always remove, to make this query work on earlier versions.

The report includes:
*number of quizzes
*unFinished Quiz attempts
*Finished Quiz attempts
*number of students
*number of Assignments
*number of submitted answers by students
*number of unchecked assignments (waiting for the Teacher) in a Course.

<code sql>
SELECT concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.fullname,'</a>') AS Course

,(SELECT CONCAT(u.firstname,' ', u.lastname) AS Teacher
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
JOIN prefix_user AS u ON u.id = ra.userid
WHERE ra.roleid = 3 AND ctx.instanceid = c.id LIMIT 1) AS Teacher

,concat('<a target="_new" href="%%WWWROOT%%/mod/assignment/index.php?id=',c.id,'">מטלות</a>') AS Assignments

,concat('<a target="_new" href="%%WWWROOT%%/mod/quiz/index.php?id=',c.id,'">בחנים</a>') AS 'Quizzes'

,(SELECT COUNT(*)
FROM prefix_course_modules cm
JOIN prefix_modules as m ON m.id = cm.module
WHERE m.name LIKE 'quiz' AND cm.course = c.id
GROUP BY cm.course
) AS 'nQuizzes'

,(SELECT COUNT(*)
FROM prefix_quiz_attempts AS qa
JOIN prefix_quiz AS q ON q.id = qa.quiz
WHERE q.course = c.id
AND qa.timefinish = 0
GROUP BY q.course) AS 'unFinished Quiz attempts'

,(SELECT COUNT(*)
FROM prefix_quiz_attempts AS qa
JOIN prefix_quiz AS q ON q.id = qa.quiz
WHERE q.course = c.id
AND qa.timefinish > 0
GROUP BY q.course) AS 'finished quiz attempts'

,(SELECT Count( ra.userid ) AS Users
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid = 5
AND ctx.instanceid = c.id
) AS nStudents

,(
SELECT count(a.id)
FROM prefix_assignment AS a
JOIN prefix_course_modules AS cm ON a.course = cm.course
WHERE cm.instance = a.id AND cm.module = 1 AND a.course = c.id
) nAssignments

,(
SELECT count(*)
FROM prefix_assignment AS a
WHERE a.course = c.id AND FROM_UNIXTIME(a.timedue) > NOW()
GROUP BY a.course
) 'Open Assignments'

, CONCAT(ROUND( (100 / iAssignments ) * iOpenAssignments ) ,'%') 'unFinished Assignments (percent)'

,(
SELECT count(asb.id)
FROM prefix_assignment_submissions AS asb
JOIN prefix_assignment AS a ON a.id = asb.assignment
JOIN prefix_course_modules AS cm ON a.course = cm.course
WHERE asb.grade < 0 AND cm.instance = a.id AND cm.module = 1 AND a.course = c.id
) 'unChecked Submissions'

,(
SELECT count(asb.id)
FROM prefix_assignment_submissions AS asb
JOIN prefix_assignment AS a ON a.id = asb.assignment
JOIN prefix_course_modules AS cm ON a.course = cm.course
WHERE cm.instance = a.id AND cm.module = 1 AND a.course = c.id
) 'Submitted Assignments'

FROM prefix_course AS c
LEFT JOIN (
SELECT course, count(*) AS iAssignments
FROM prefix_assignment AS a
GROUP BY a.course
) AS tblAssignmentsCount ON tblAssignmentsCount.course = c.id

LEFT JOIN (
SELECT course, count(*) AS iOpenAssignments
FROM prefix_assignment AS a
WHERE FROM_UNIXTIME(a.timedue) > NOW()
GROUP BY a.course
) AS tblOpenAssignmentsCount ON tblOpenAssignmentsCount.course = c.id

WHERE 1=1
#AND c.fullname LIKE '%תשעג%'
%%FILTER_YEARS:c.fullname%%
## You can enable the SEMESTER filter as well,
## by uncommenting the following line:
## %%FILTER_SEMESTERS:c.fullname%%
ORDER BY 'Open Assignments' DESC
</code>

===Rubrics without zero values in criteria===
Contributed by Eric Strom

Rubric calculations in Moodle can fail to align with instructors expectations if they lack a zero value for each criterion used in the assessment. From documentation at https://docs.moodle.org/32/en/Rubrics#Grade_calculation:

"For example, when the teacher in the previous example chose both levels with 1 point, the plain sum would be 2 points. But that is actually the lowest possible score so it maps to the grade 0 in Moodle.
TIP: To avoid confusion from this sort of thing, we recommend including a level with 0 points in every rubric criterion."

This report identifies rubrics having criteria without a zero value level and the courses they live in. This also refines to only assignments with active rubrics that are visible to students in the course. Links to the each rubric id is the direct link to edit the rubric. Fix by adding a zero level for each criteria that is missing it. In general, the grading changes that result will be in the students' favor.

Includes search filter of course idnumber.

<code sql>
SELECT cat.name AS Department, concat('<a target="_new" href="%%WWWROOT%%/course/view.php',CHAR(63),'id=',
c.id,'">',c.idnumber,'</a>') AS Course_ID,
c.fullname AS Course_Name,
concat('<a target="_new" href="%%WWWROOT%%/grade/grading/form/rubric/edit.php',CHAR(63),'areaid=',gd.areaid,'">',gd.areaid,'</a>') AS Rubric
FROM prefix_course AS c
JOIN prefix_course_categories AS cat
ON cat.id = c.category
JOIN prefix_course_modules AS cm
ON c.id=cm.course
JOIN prefix_context AS ctx
ON cm.id = ctx.instanceid
JOIN prefix_grading_areas AS garea
ON ctx.id = garea.contextid
JOIN prefix_grading_definitions AS gd
ON garea.id = gd.areaid
JOIN prefix_gradingform_rubric_criteria AS crit
ON gd.id = crit.definitionid
JOIN prefix_gradingform_rubric_levels AS levels
ON levels.criterionid = crit.id
WHERE cm.visible='1' AND garea.activemethod = 'rubric' AND (crit.id NOT IN
(SELECT crit.id
FROM prefix_gradingform_rubric_criteria AS crit
JOIN prefix_gradingform_rubric_levels AS levels
ON levels.criterionid = crit.id WHERE levels.score = '0'))

GROUP BY Rubric
ORDER BY Course_ID, Rubric

%%FILTER_SEARCHTEXT:c.idnumber:~%%
</code>

===Who is using "Single File Upload" assignment===
<code sql>
SELECT
concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.fullname,'</a>') AS Course

,(SELECT CONCAT(u.firstname,' ', u.lastname) AS Teacher
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
JOIN prefix_user AS u ON u.id = ra.userid
WHERE ra.roleid = 3 AND ctx.instanceid = c.id LIMIT 1) AS Teacher

,ass.name as "Assignment Name"

FROM
prefix_assignment as ass

JOIN
prefix_course as c ON c.id = ass.course

WHERE `assignmenttype` LIKE 'uploadsingle'
</code>

==Feedback Module Reports==
===List the answers to all the Feedback activities within the current course, submitted by the current user===
<code sql>
SELECT /* crs.fullname as "Course name", f.name AS "Journal name", CONCAT(u.firstname,' ',UPPER(u.lastname)) as "Participant", */ /* include these fields if you want to check the composition of the recordset */
DATE_FORMAT(FROM_UNIXTIME(c.timemodified),'%W %e %M, %Y') as "Answer Date",
CASE i.typ WHEN 'label' THEN i.presentation ELSE i.name END as "Topic", /* usually labels are used as section titles, so you'd want them present in the recordset */
v.value as "My Answer"

FROM prefix_feedback AS f
INNER JOIN prefix_course as crs on crs.id=f.course %%FILTER_COURSES:f.course%%
INNER JOIN prefix_feedback_item AS i ON f.id=i.feedback
INNER JOIN prefix_feedback_completed AS c on f.id=c.feedback %%FILTER_COURSEUSER:c.userid%%
LEFT JOIN prefix_feedback_value AS v on v.completed=c.id AND v.item=i.id
INNER JOIN prefix_user AS u on c.userid=u.id

WHERE c.id = %%COURSEID%% AND u.id = %%USERID%% AND c.anonymous_response = 1 /* This clause limits the recordset to the current course and the current user and includes/ excludes the anonymous responses as needed */

ORDER BY f.id, c.timemodified, i.id
</code>

===Show all Feedbacks from all courses for all users including showing names of anonymous users===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

Shows all Feedbacks in all Courses with all multi-choice questions including showing the username of anonymous users. Also shows truly anonymous users on the front page as 'Not-logged-in' users. This is a rough report, not a pretty report, and is limited to multiple-choice type questions, but is shows the answer number and the list of possible answers in raw form. I post it here as a basis for further reports, and also as away to get the identities of anonymous users if needed.

<code sql>
SELECT
c.shortname AS Course,
f.name AS Feedback,
# i.id AS Itemid,
i.name AS Itemname,
i.label AS Itemlabel,
CASE
WHEN f.anonymous = 1 AND u.id != 0 THEN CONCAT(u.username, ' :ANON')
WHEN fc.userid = 0 THEN 'Not-logged-in'
ELSE u.username
END AS 'User',
DATE_FORMAT(FROM_UNIXTIME(fc.timemodified),'%Y-%m-%d %H:%i') AS "Completed",
v.value AS "Choice",
CASE
WHEN i.typ = 'multichoice' THEN
IF ( SUBSTRING(i.presentation,1,6)='r>>>>>',
SUBSTRING(i.presentation,7),
i.presentation)
ELSE i.presentation
END AS "Answers",
i.typ,
i.dependitem,
i.dependvalue

FROM prefix_feedback f
JOIN prefix_course c ON c.id=f.course
JOIN prefix_feedback_item AS i ON f.id=i.feedback
JOIN prefix_feedback_completed fc ON f.id=fc.feedback
LEFT JOIN prefix_feedback_value v ON v.completed=fc.id AND v.item=i.id
LEFT JOIN prefix_user AS u ON fc.userid=u.id
WHERE i.typ != 'pagebreak'
</code>

===Show all Feedbacks from all courses for all users with their answers===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

Shows all Feedbacks in all Courses with all multi-choice questions and answers of all users for multi-choice questions. It shows the possible answers, the number of the chosen answer and the text of the chosen answer by the user. As always, I disavow any prettiness here and you should update the fields as you need.

Known to work in Moodle 3.5 to 3.10.

<code sql>
SELECT
c.fullname as "Course",
f.name AS "Feedback",
CONCAT(u.firstname,' ',u.lastname) as "User",
DATE_FORMAT(FROM_UNIXTIME(fc.timemodified), '%Y-%m-%d %H:%i') AS "When",
IF(i.typ = 'label', i.presentation, i.name) AS "Question",
# answers presentation string starts with these 6 characters: r>>>>>
CASE WHEN i.typ = 'multichoice' THEN SUBSTRING(i.presentation,7) END AS "Possible Answers",

CASE i.typ WHEN 'multichoice' THEN v.value ELSE '-' END AS "Chosen Answer Num",
CASE v.value
WHEN 1 THEN SUBSTRING(i.presentation, 7, POSITION('|' IN i.presentation) - 7)
WHEN 2 THEN SUBSTRING_INDEX(SUBSTRING_INDEX(i.presentation, '|',2), '|',-1)
WHEN 3 THEN SUBSTRING_INDEX(SUBSTRING_INDEX(i.presentation, '|',3), '|',-1)
WHEN 4 THEN SUBSTRING_INDEX(SUBSTRING_INDEX(i.presentation, '|',4), '|',-1)
WHEN 5 THEN SUBSTRING_INDEX(SUBSTRING_INDEX(i.presentation, '|',5), '|',-1)
WHEN 6 THEN SUBSTRING_INDEX(SUBSTRING_INDEX(i.presentation, '|',6), '|',-1)
WHEN 7 THEN SUBSTRING_INDEX(SUBSTRING_INDEX(i.presentation, '|',7), '|',-1)
WHEN 8 THEN SUBSTRING_INDEX(SUBSTRING_INDEX(i.presentation, '|',8), '|',-1)
WHEN 9 THEN SUBSTRING_INDEX(SUBSTRING_INDEX(i.presentation, '|',9), '|',-1)
ELSE CONCAT("More:", v.value)
END AS "Chosen Answer Text"

FROM prefix_feedback AS f
JOIN prefix_course AS c ON c.id=f.course
JOIN prefix_feedback_item AS i ON f.id=i.feedback
JOIN prefix_feedback_completed AS fc ON f.id=fc.feedback
LEFT JOIN prefix_feedback_value AS v ON v.completed=fc.id AND v.item=i.id
JOIN prefix_user AS u ON fc.userid=u.id

WHERE i.typ IN ('label', 'multichoice')

</code>

==Resource Module Reports==
===List "Recently uploaded files"===
see what users are uploading
<code sql>
SELECT FROM_UNIXTIME(time,'%Y %M %D %h:%i:%s') as time ,ip,userid,url,info
FROM `prefix_log`
WHERE `action` LIKE 'upload'
ORDER BY `prefix_log`.`time` DESC
</code>

===List Courses that loaded a specific file: "X"===
Did the Teacher (probably) uploaded course's Syllabus ?
<code sql>
SELECT c.id, c.fullname FROM `prefix_log` as l
JOIN prefix_course as c ON c.id = l.course
WHERE `action` LIKE '%upload%' AND ( info LIKE '%Syllabus%' OR info LIKE '%Sylabus%' ) GROUP BY c.id
</code>

===All resources that link to some specific external website===
+ link to course
+ who's the teacher
+ link to external resource
<code sql>
SELECT
concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.fullname,'</a>') AS Course
,c.shortname,r.name
,(SELECT CONCAT(u.firstname,' ', u.lastname) AS Teacher
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
JOIN prefix_user AS u ON u.id = ra.userid
WHERE ra.roleid = 3 AND ctx.instanceid = c.id LIMIT 1) AS Teacher
,concat('<a target="_new" href="%%WWWROOT%%/mod/resource/view.php?id=',r.id,'">',r.name,'</a>') AS Resource
FROM prefix_resource AS r
JOIN prefix_course AS c ON r.course = c.id
WHERE r.reference LIKE 'http://info.oranim.ac.il/home%'
</code>

==="Compose Web Page" RESOURCE count===
<code sql>
SELECT course,prefix_course.fullname, COUNT(*) AS Total
FROM `prefix_resource`
JOIN `prefix_course` ON prefix_course.id = prefix_resource.course
WHERE type='html'
GROUP BY course
</code>

===Resource count in courses===
+ (First)Teacher name
+ Where course is inside some specific Categories
<code sql>
SELECT
COUNT(*) AS count
,r.course
,c.shortname shortname
,c.fullname coursename
,( SELECT DISTINCT CONCAT(u.firstname,' ',u.lastname)
FROM prefix_role_assignments AS ra
JOIN prefix_user as u ON ra.userid = u.id
JOIN prefix_context AS ctx ON ctx.id = ra.contextid
WHERE ra.roleid = 3 AND ctx.instanceid = r.course AND ctx.contextlevel = 50 LIMIT 1) AS Teacher
FROM prefix_resource r
JOIN prefix_course c ON r.course = c.id
WHERE c.category IN (10,13,28,18,26)
GROUP BY r.course
ORDER BY COUNT(*) DESC
</code>

===Delete all the automated backup files===
Prepare bash cli script to delete all the automated backup files on the file system. (clean up some disk space)
<code sql>
SELECT CONCAT( 'rm -f /var/moodledatanew/filedir/', SUBSTRING( contenthash, 1, 2 ) , '/', SUBSTRING( contenthash, 3, 2 ) , '/', contenthash )
FROM `mdl_files`
WHERE `filename` LIKE '%mbz%'
AND filearea = 'automated'
</code>

Find out how much disk space is used by all automated backup files:
<code sql>
SELECT SUM(filesize)/(1024*1024*1024) FROM `mdl_files` WHERE `filename` LIKE '%mbz%' AND filearea = 'automated'
</code>

==Forum Module Reports==
===print all User's post in course Forums===
%%COURSEID%% is a variable the is replace by the current CourseID you are running the sql report from. if you are using the latest block/configurable_reports ! (You can always change it to a fixed course or remove it to display all courses.)
<code sql>
SELECT
concat('<a target="_new" href="%%WWWROOT%%/mod/forum/user.php?course=',c.id,'&id=',u.id,'&mode=posts">',CONCAT(u.firstname,' ', u.lastname),'</a>') As Fullname
,concat('<a target="_new" href="%%WWWROOT%%/mod/forum/view.php?f=',fd.forum,'">',f.name,'</a>') AS Forum
,count(*) as Posts
,(SELECT count(*) FROM prefix_forum_discussions AS ifd JOIN prefix_forum as iforum ON iforum.id = ifd.forum WHERE ifd.userid = fp.userid AND iforum.id = f.id) AS cAllDiscussion

FROM prefix_forum_posts AS fp
JOIN prefix_user as u ON u.id = fp.userid
JOIN prefix_forum_discussions AS fd ON fp.discussion = fd.id
JOIN prefix_forum AS f ON f.id = fd.forum
JOIN prefix_course as c ON c.id = fd.course
WHERE fd.course = %%COURSEID%%
GROUP BY f.id,u.id
ORDER BY u.id
</code>

===FORUM use Count per COURSE -- not including NEWS Forum!===
<code sql>
SELECT prefix_course.fullname, prefix_forum.course, count(*) as total FROM prefix_forum
INNER JOIN prefix_course
ON prefix_course.id = prefix_forum.course
WHERE NOT(prefix_forum.type = 'news')
GROUP BY prefix_forum.course
ORDER BY total desc
</code>

===FORUM use Count per COURSE by type -- not including NEWS Forum!===
<code sql>
SELECT prefix_course.fullname, prefix_forum.course, prefix_forum.type, count(*) as total FROM prefix_forum
INNER JOIN prefix_course
ON prefix_course.id = prefix_forum.course
WHERE NOT(prefix_forum.type = 'news')
GROUP BY prefix_forum.course,prefix_forum.type
ORDER BY total desc
</code>

===Forum activity - system wide===
<code sql>
SELECT concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.id,'</a>') AS CourseID
,( SELECT DISTINCT CONCAT(u.firstname,' ',u.lastname)
FROM prefix_role_assignments AS ra
JOIN prefix_user AS u ON ra.userid = u.id
JOIN prefix_context AS ctx ON ctx.id = ra.contextid
WHERE ra.roleid = 3 AND ctx.instanceid = c.id AND ctx.contextlevel = 50 LIMIT 1) AS Teacher
,c.fullname as Course
,f.type
,(SELECT Count( ra.userid ) AS Users FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid = 5 AND ctx.instanceid = c.id) AS Students
, fd.forum, f.name,count(*) AS cPostAndDisc
,(SELECT count(*) FROM prefix_forum_discussions AS ifd WHERE ifd.forum = f.id) AS cDiscussion
FROM prefix_forum_posts AS fp
JOIN prefix_forum_discussions AS fd ON fd.id = fp.discussion
JOIN prefix_forum AS f ON f.id = fd.forum
JOIN prefix_course AS c ON c.id = f.course
WHERE f.type != 'news' AND c.fullname LIKE '%2013%'
## WHERE 1=1
## %%FILTER_YEARS:c.fullname%%
## You can enable the SEMESTER filter as well,
## by uncommenting the following line:
## %%FILTER_SEMESTERS:c.fullname%%

GROUP BY fd.forum
ORDER BY count( * ) DESC
</code>

===Activity In Forums===
Trying to figure out how much real activity we have in Forums by aggregating:
Users in Course, Number of Posts, Number of Discussions, Unique student post, Unique student discussions, Number of Teachers , Number of Students, ratio between unique Student posts and the number of students in the Course...
<code sql>
SELECT c.fullname,f.name,f.type
,(SELECT count(id) FROM prefix_forum_discussions as fd WHERE f.id = fd.forum) as Discussions
,(SELECT count(distinct fd.userid) FROM prefix_forum_discussions as fd WHERE fd.forum = f.id) as UniqueUsersDiscussions
,(SELECT count(fp.id) FROM prefix_forum_discussions fd JOIN prefix_forum_posts as fp ON fd.id = fp.discussion WHERE f.id = fd.forum) as Posts
,(SELECT count(distinct fp.userid) FROM prefix_forum_discussions fd JOIN prefix_forum_posts as fp ON fd.id = fp.discussion WHERE f.id = fd.forum) as UniqueUsersPosts
,(SELECT Count( ra.userid ) AS Students
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid =5
AND ctx.instanceid = c.id
) AS StudentsCount
,(SELECT Count( ra.userid ) AS Teachers
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid =3
AND ctx.instanceid = c.id
) AS 'Teacher Count'
,(SELECT Count( ra.userid ) AS Users
FROM prefix_role_assignments AS ra
JOIN prefix_context AS ctx ON ra.contextid = ctx.id
WHERE ra.roleid IN (3,5)
AND ctx.instanceid = c.id
) AS UserCount
, (SELECT (UniqueUsersDiscussions / StudentsCount )) as StudentDissUsage
, (SELECT (UniqueUsersPosts /StudentsCount)) as StudentPostUsage
FROM prefix_forum as f
JOIN prefix_course as c ON f.course = c.id
WHERE `type` != 'news'
ORDER BY StudentPostUsage DESC
</code>

===All Forum type:NEWS===
<code sql>
SELECT f.id, f.name
FROM prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
JOIN prefix_forum AS f ON cm.instance = f.id
WHERE m.name = 'forum'
AND f.type = 'news'
</code>

===All new forum NEWS items (discussions) from all my Courses===
change "userid = 26" and "id = 26" to a new user id
<code sql>
SELECT c.shortname,f.name,fd.name,FROM_UNIXTIME(fd.timemodified ,"%d %M %Y ") as Date
FROM prefix_forum_discussions as fd
JOIN prefix_forum as f ON f.id = fd.forum
JOIN prefix_course as c ON c.id = f.course
JOIN prefix_user_lastaccess as ul ON (c.id = ul.courseid AND ul.userid = 26)
WHERE fd.timemodified > ul.timeaccess
AND fd.forum IN (SELECT f.id
FROM prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
JOIN prefix_forum AS f ON cm.instance = f.id
WHERE m.name = 'forum'
AND f.type = 'news')
AND c.id IN (SELECT c.id
FROM prefix_course AS c
JOIN prefix_context AS ctx ON c.id = ctx.instanceid
JOIN prefix_role_assignments AS ra ON ra.contextid = ctx.id
JOIN prefix_user AS u ON u.id = ra.userid
WHERE u.id = 26) ORDER BY `fd`.`timemodified` DESC
</code>

===News Forum - Discussions COUNT===
Which is actually... How much instructions students get from their teachers
<code sql>
SELECT c.shortname ,
concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.fullname,'</a>') AS Course
,( SELECT DISTINCT CONCAT(u.firstname,' ',u.lastname)
FROM prefix_role_assignments AS ra
JOIN prefix_user AS u ON ra.userid = u.id
JOIN prefix_context AS ctx ON ctx.id = ra.contextid
WHERE ra.roleid = 3 AND ctx.instanceid = c.id AND ctx.contextlevel = 50 LIMIT 1) AS Teacher
,concat('<a target="_new" href="%%WWWROOT%%/mod/forum/view.php?f=',fd.forum,'">',count(fd.id),'</a>') AS DiscussionsSum
FROM prefix_forum_discussions AS fd
INNER JOIN prefix_forum AS f ON f.id = fd.forum
INNER JOIN prefix_course AS c ON c.id = f.course
WHERE f.type = 'news' AND c.category IN (10,13,28,18,26)
GROUP BY fd.forum
ORDER BY count(fd.id) DESC
</code>

===Cantidad de foros que han sido posteados por profesor===

(Number of forums that have been posted by teacher/Google translator)

Queriamos saber cuales son las acciones del profesor dentro de los foros de cada curso, por ello se hizo este informe.

(We wanted to know what the teacher's actions are in the forums of each course, so this report was made. /Google translator)
<code sql>
SELECT
concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.shortname,'</a>') AS curso,
CONCAT(u.firstname ,' ',u.lastname) AS Facilitador,

(SELECT COUNT( m.name ) AS COUNT FROM
prefix_course_modules AS cm
JOIN prefix_modules AS m ON cm.module = m.id
WHERE cm.course = c.id AND m.name LIKE '%forum%') AS foros,

COUNT(*) AS Posts

FROM prefix_forum_posts AS fp
JOIN prefix_forum_discussions AS fd ON fp.discussion = fd.id
JOIN prefix_forum AS f ON f.id = fd.forum
JOIN prefix_course AS c ON c.id = fd.course
JOIN prefix_user AS u ON u.id = fp.userid

WHERE fp.userid =
(
select distinct prefix_user.id
from prefix_user
join prefix_role_assignments as ra on ra.userid = prefix_user.id
where ra.roleid = 3
and userid = fp.userid
limit 1
)

and c.shortname like '%2014-2-1%'
GROUP BY c.id, u.id
</code>

===List all the Posts in all the Forums that got high rating===
We setup a scale that let teachers and students Rate forum post with "Important, interesting, valuable, not rated" scale
And then add a link to the following report at the begining of the course "Link to all interesting posts"
<code sql>
SELECT
CONCAT('<a target="_new" href="%%WWWROOT%%/mod/forum/view.php?f=',f.id,'">',f.name,'</a>') AS 'Forum name,
CONCAT('<a target="_new" href="%%WWWROOT%%/mod/forum/discuss.php?d=',fd.id,'#p',fp.id,'">',fp.subject,'</a>') AS 'Post link',
SUM(r.rating) AS 'Rating'
FROM mdl_rating AS r
JOIN mdl_forum_posts AS fp ON fp.id = r.itemid
JOIN mdl_forum_discussions AS fd ON fd.id = fp.discussion
JOIN mdl_forum AS f ON f.id = fd.forum
WHERE r.component = 'mod_forum' AND r.ratingarea = 'post' AND f.course = %%COURSEID%%
GROUP BY r.itemid
ORDER BY SUM(r.rating) DESC
</code>

===List all the Posts in all Discussions of a single Forum===
This report is used to help export all the student's posts and discussions of a single forum, by passing the context module id as a parameter to the report using "&filter_var=cmid"
<code sql>
SELECT
CONCAT('<a target="_new" href="%%WWWROOT%%/mod/forum/view.php?f=', f.id, '">', f.name, '</a>') AS 'Forum name',
fd.name AS 'Discussion',
CONCAT('<a target="_new" href="%%WWWROOT%%/mod/forum/discuss.php?d=', fd.id, '#p', fp.id, '">', fp.subject, '</a>') AS 'Post (link)',
fp.message

FROM mdl_forum_posts AS fp
JOIN mdl_forum_discussions AS fd ON fd.id = fp.discussion
JOIN mdl_forum AS f ON f.id = fd.forum
JOIN mdl_course_modules AS cm ON cm.module = 9 AND cm.instance = f.id
WHERE cm.id = %%FILTER_VAR%%
ORDER BY f.id, fd.id
</code>

==Quiz Module Reports==
===Generate a list of instructors and their email addresses for those courses that has "essay questions" in their quizzes===
<code sql>
SELECT qu.id AS quiz_id, qu.course AS course_id, qu.questions,
co.fullname AS course_fullname, co.shortname AS course_shortname,
qu.name AS quiz_name, FROM_UNIXTIME(qu.timeopen) AS quiz_timeopen, FROM_UNIXTIME(qu.timeclose) AS quiz_timeclose,
u.firstname, u.lastname, u.email,
FROM prefix_quiz qu, prefix_course co, prefix_role re, prefix_context ct, prefix_role_assignments ra, prefix_user u
WHERE FROM_UNIXTIME(timeopen) > '2008-05-14' AND
qu.course = co.id AND
co.id = ct.instanceid AND
ra.roleid = re.id AND
re.name = 'Teacher' AND
ra.contextid = ct.id AND
ra.userid = u.id

SELECT Count('x') As NumOfStudents
FROM prefix_role_assignments a
JOIN prefix_user u ON userid = u.id
WHERE roleid = 5 AND contextid = (SELECT id FROM prefix_context WHERE instanceid = 668 AND contextlevel = 50)
</code>

===Number of Quizes per Course===
<code sql>
SELECT count(*)
,concat('<a target="_new" href="%%WWWROOT%%/course/view.php?id=',c.id,'">',c.fullname,'</a>') AS Course
,concat('<a target="_new" href="%%WWWROOT%%/mod/quiz/index.php?id=',c.id,'">Link</a>') AS Quizes

FROM prefix_course_modules cm
JOIN prefix_course c ON c.id = cm.course
JOIN prefix_modules as m ON m.id = cm.module
WHERE m.name LIKE 'quiz'
GROUP BY c.id
</code>

===List all MultiAnswer (Cloze) Questions===
<code sql>
SELECT concat('<a target="_new" href="%%WWWROOT%%/mod/quiz/attempt.php?q=', quiz.id, '">', quiz.name, '</a>') AS Quiz
,question.id question_id, question.questiontext
FROM prefix_question question
JOIN prefix_quiz_question_instances qqi ON question.id = qqi.question
JOIN prefix_quiz quiz ON qqi.quiz = quiz.id
WHERE `qtype` LIKE 'multianswer'
</code>

===List courses with MANUAL grades===
Which is basically and indication to teachers using Moodle to hold offline grades inside Moodle's Gradebook,
So grades could be uploaded into an administrative SIS. Use with Configurable Reports.
<code sql>
SELECT COUNT( * )
,concat('<a target="_new" href="%%WWWROOT%%/grade/edit/tree/index.php?showadvanced=1&id=',c.id,'">',c.fullname,'</a>') AS Course
FROM prefix_grade_items AS gi
JOIN prefix_course as c ON c.id = gi.courseid
WHERE `itemtype` = 'manual'
GROUP BY courseid
</code>
===List the users that did not took the Quiz===
Do not forget to change "c.id = 14" and q.name LIKE '%quiz name goes here%'
<code sql>
SELECT
user2.id AS ID,
ul.timeaccess,
user2.firstname AS Firstname,
user2.lastname AS Lastname,
user2.email AS Email,
user2.username AS IDNumber,
user2.institution AS Institution,

IF (user2.lastaccess = 0,'never',
DATE_FORMAT(FROM_UNIXTIME(user2.lastaccess),'%Y-%m-%d')) AS dLastAccess

,(SELECT DATE_FORMAT(FROM_UNIXTIME(timeaccess),'%Y-%m-%d') FROM prefix_user_lastaccess WHERE userid=user2.id AND courseid=c.id) AS CourseLastAccess

,(SELECT r.name
FROM prefix_user_enrolments AS uenrol
JOIN prefix_enrol AS e ON e.id = uenrol.enrolid
JOIN prefix_role AS r ON e.id = r.id
WHERE uenrol.userid=user2.id AND e.courseid = c.id) AS RoleName

FROM prefix_user_enrolments AS ue
JOIN prefix_enrol AS e ON e.id = ue.enrolid
JOIN prefix_course AS c ON c.id = e.courseid
JOIN prefix_user AS user2 ON user2 .id = ue.userid
LEFT JOIN prefix_user_lastaccess AS ul ON ul.userid = user2.id
WHERE c.id=14 and ue.userid NOT IN (SELECT qa.userid FROM prefix_quiz_attempts AS qa
JOIN prefix_quiz AS q ON qa.quiz = q.id
JOIN prefix_course AS c ON q.course = c.id
WHERE c.id = 14 AND q.name LIKE '%quiz name goes here%')
</code>

===List Questions in each Quiz===

<code sql>
SELECT quiz.id,quiz.name, q.id, q.name
FROM mdl_quiz AS quiz
JOIN mdl_question AS q ON FIND_IN_SET(q.id, quiz.questions)
WHERE quiz.course = %%COURSEID%%
ORDER BY quiz.id ASC
</code>

Note: this query does not work in Moodle 2.8+. There is no mdl_quiz.questions field. It will need to be rewritten to use the usage/contextid organization.

Here is a version for Moodle 3.x

<code sql>
SELECT cm.id 'cmid', quiz.id 'quiz id'
,CONCAT('<a target="_new" href="%%WWWROOT%%/mod/quiz/edit.php?cmid=',
cm.id, '">', quiz.name, '</a>') AS 'edit quiz'
,q.id 'qid', q.name 'question name'
FROM mdl_quiz AS quiz
JOIN mdl_course_modules cm ON cm.instance = quiz.id AND cm.module = 33 # 33=quiz mdl_modules
JOIN mdl_quiz_slots qs ON qs.quizid = quiz.id
JOIN mdl_question AS q ON q.id = qs.questionid
WHERE quiz.course = %%COURSEID%%
ORDER BY quiz.id ASC
</code>

===Quiz activity research===
This report was made to extract student full activity in quizzes for an academic research about adapting instructional design teaching methods in online learning. The students do not use the Quiz module as a standard quiz but more as Study booklets or mini courses with embedded questions and hints to assist students evaluate their progress (Similar to what you expect to find in a SCORM activity)

<code sql>
SELECT
cm.course "course_id", cm.id "moduel_id", q.id "quiz_id", q.name "quiz_name",

CASE q.grademethod
WHEN 1 THEN "GRADEHIGHEST"
WHEN 2 THEN "GRADEAVERAGE"
WHEN 3 THEN "ATTEMPTFIRST"
WHEN 4 THEN "ATTEMPTLAST"
END "grade method"

, q.attempts "quiz_attempts_allowed", cm.groupmode "group_mode"
, qa.id "attempt_id", qa.state "attempt_state", qa.sumgrades "attempt_grade", qg.grade "user_final_grade", q.grade "quiz_max_grade"
,(SELECT GROUP_CONCAT(g.name) FROM mdl_groups AS g
JOIN mdl_groups_members AS m ON g.id = m.groupid WHERE g.courseid = q.course AND m.userid = u.id) "user_groups",
DATE_FORMAT(FROM_UNIXTIME(qa.timestart), '%d-%m-%Y %h:%k') "attempt_start",
DATE_FORMAT(FROM_UNIXTIME(qa.timefinish), '%d-%m-%Y %h:%k') "attempt_finish",
u.id "user_id", u.firstname, u.lastname,
question.id "question_id", question.name "question_name",
qas.state "question_step_state",qas.fraction "question_grade", qh.hint, question.qtype "question_type"

FROM mdl_quiz as q
JOIN mdl_course_modules as cm ON cm.instance = q.id and cm.module = 14
JOIN mdl_quiz_attempts qa ON q.id = qa.quiz
LEFT JOIN mdl_quiz_grades as qg ON qg.quiz = q.id and qg.userid = qa.userid
JOIN mdl_user as u ON u.id = qa.userid
JOIN mdl_question_usages as qu ON qu.id = qa.uniqueid
JOIN mdl_question_attempts as qatt ON qatt.questionusageid = qu.id
JOIN mdl_question as question ON question.id = qatt.questionid
JOIN mdl_question_attempt_steps as qas ON qas.questionattemptid = qatt.id
LEFT JOIN mdl_question_hints as qh ON qh.questionid = q.id
#WHERE q.id = "SOME QUIZ ID"
WHERE cm.course = "SOME COURSE ID"
</code>

===Quiz Usage in Courses by Date===
Contributed by Elizabeth Dalton, Granite State College

This report lists the courses containing quizzes with the course start date between the two values, and provides a summary of the types of questions in the quizzes in each course and whether question randomization and answer randomization functions were used.

"Multiple Choice" questions include true/false and matching question types.

"Short Answer" are questions that accept a single phrase.

"Other" questions include fixed numerical, calculated, essay, and various drag and drop types.

"Min Quiz Age" and "Max Quiz Age" provide data about the last modified date for the quizzes in the course, compared to the course start date. The values are expressed in units of days. A negative value indicates that a quiz was edited after the start of the course. A value greater than 90 days indicates that the quiz may have been used in an earlier term (cohort) without modification.

'''Note''': In Configurable Reports, the Date Filter is not applied until the "Apply" button is clicked.

<code sql>
SELECT

c.shortname AS 'Course'
#, u.lastname AS 'Instructor'
, COUNT(DISTINCT q.id) AS 'Quizzes'
, COUNT(DISTINCT qu.id) AS 'Questions'
, SUM(IF (qu.qtype = 'multichoice', 1, 0 )) + SUM(IF (qu.qtype = 'truefalse', 1, 0 )) + SUM(IF (qu.qtype = 'match', 1, 0 )) AS 'multichoice'

, SUM(IF (qu.qtype = 'shortanswer', 1, 0 )) AS 'shortanswer'

, COUNT( qu.id) - SUM(IF (qu.qtype = 'multichoice', 1, 0 )) - SUM(IF (qu.qtype = 'truefalse', 1, 0 )) - SUM(IF (qu.qtype = 'match', 1, 0 )) - SUM(IF (qu.qtype = 'shortanswer', 1, 0 )) AS 'Other'

, (SUM(IF (qu.qtype = 'multichoice', 1, 0 )) + SUM(IF (qu.qtype = 'truefalse', 1, 0 )) + SUM(IF (qu.qtype = 'match', 1, 0 )))/COUNT( qu.id) AS 'Percent MC'

#, SUM(IF (qu.qtype = 'numerical', 1, 0 )) AS 'numerical'
#, SUM(IF (qu.qtype LIKE 'calc%', 1, 0 )) AS 'calculated'
#, SUM(IF (qu.qtype = 'random', 1, 0 )) AS 'random'
#, SUM(IF (qu.qtype = 'shortanswer', 1, 0 )) AS 'shortanswer'
#, SUM(IF (qu.qtype = 'essay', 1, 0 )) AS 'essay'

, IF(q.shufflequestions > 0,'Yes','No') AS 'Randomized Questions'
, IF(q.shuffleanswers > 0,'Yes','No') AS 'Randomized Answers'

#, FROM_UNIXTIME(c.startdate) AS 'Course Start Date'
#, FROM_UNIXTIME(MIN(q.timemodified)) AS 'Last Modified'

#, DATEDIFF(FROM_UNIXTIME(c.startdate),FROM_UNIXTIME(MIN(q.timemodified))) AS 'Quiz age'

, MIN(DATEDIFF(FROM_UNIXTIME(c.startdate),FROM_UNIXTIME(q.timemodified))) AS 'Min Quiz Age'
, MAX(DATEDIFF(FROM_UNIXTIME(c.startdate),FROM_UNIXTIME(q.timemodified))) AS 'Max Quiz Age'

#, SUM(IF (DATEDIFF(FROM_UNIXTIME(c.startdate),FROM_UNIXTIME(q.timemodified)) < 90, 1,0)) AS 'new quizzes'

FROM prefix_quiz AS q
JOIN prefix_course AS c on c.id = q.course
JOIN prefix_quiz_question_instances AS qqi ON qqi.quiz = q.id
LEFT JOIN prefix_question AS qu ON qu.id = qqi.question

WHERE
1
%%FILTER_STARTTIME:c.startdate:>%% %%FILTER_ENDTIME:c.startdate:<%%

GROUP BY c.id

ORDER BY c.shortname
</code>

===Student responses (answers) to quiz questions===
(Contributed by Juan F with help from Tim hunt and fellow Moodlers on the forums)
A report that targets a specific quiz for all of our Biology courses, a summary of all questions and how many students get them right/wrong.
<code sql>
SELECT
concat( u.firstname, " ", u.lastname ) AS "Student Name",
u.id,
quiza.userid,
q.course,
q.name,
quiza.attempt,
qa.slot,
que.questiontext AS 'Question',
qa.rightanswer AS 'Correct Answer',
qa.responsesummary AS 'Student Answer'

FROM mdl_quiz_attempts quiza
JOIN mdl_quiz q ON q.id=quiza.quiz
JOIN mdl_question_usages qu ON qu.id = quiza.uniqueid
JOIN mdl_question_attempts qa ON qa.questionusageid = qu.id
JOIN mdl_question que ON que.id = qa.questionid
JOIN mdl_user u ON u.id = quiza.userid

WHERE q.name = "BIO 208 Post Test Assessment"
AND q.course = "17926"

ORDER BY quiza.userid, quiza.attempt, qa.slot
</code>

===Questions which are tagged within a course/quiz===
Calculates subgrades for tags in the each of the quizzes in a course.
Contributed by Daniel Thies in https://moodle.org/mod/forum/discuss.php?d=324314#p1346542

<code sql>
SELECT
quiz.name AS quiz,
t.rawname AS tag,
CONCAT('<a target="_new" href="%%WWWROOT%%/mod/quiz/review.php?attempt=',
MAX(quiza.id),'">',u.firstname,' ',u.lastname,'</a>') AS student,
CAST(SUM(qas.fraction) as decimal(12,1)) AS correct,
CAST(SUM(qa.maxmark) as decimal(12,1)) AS maximum,
CAST(SUM(qas.fraction)/SUM(qa.maxmark)*100 as decimal(4,2)) AS score
FROM prefix_quiz_attempts quiza
JOIN prefix_user u ON quiza.userid = u.id
JOIN prefix_question_usages qu ON qu.id = quiza.uniqueid
JOIN prefix_question_attempts qa ON qa.questionusageid = qu.id
JOIN prefix_quiz quiz ON quiz.id = quiza.quiz
JOIN prefix_tag_instance ti ON qa.questionid = ti.itemid
JOIN prefix_tag t ON t.id = ti.tagid
JOIN (SELECT MAX(fraction) AS fraction, questionattemptid
FROM prefix_question_attempt_steps
GROUP BY questionattemptid) qas ON qas.questionattemptid = qa.id
WHERE quiz.course = %%COURSEID%%
GROUP BY quiza.userid,
quiza.quiz,
quiz.name,
u.firstname,
u.lastname,
ti.tagid,
t.rawname
ORDER BY quiza.quiz, t.rawname, u.lastname, u.firstname, score
</code>

==SCORM Activity Reports==

===Lists All completed SCORM activites by Course name===
This report will list all completed attempts for all SCORM activities. It is ordered first by Course name, then student's last name, then student's first name, then attempt number. Please note: the FROM_UNIXTIME command is for MySQL.
<code sql>
SELECT u.firstname First,u.lastname Last,c.fullname Course, st.attempt Attempt,st.value Status,FROM_UNIXTIME(st.timemodified,"%m-%d-%Y") Date
FROM prefix_scorm_scoes_track AS st
JOIN prefix_user AS u ON st.userid=u.id
JOIN prefix_scorm AS sc ON sc.id=st.scormid
JOIN prefix_course AS c ON c.id=sc.course
WHERE st.value='completed'
ORDER BY c.fullname, u.lastname,u.firstname, st.attempt
</code>

===Lists SCORM status for all enrolled users by Course name===
This report will list the SCORM status for all users enrolled in the course. It is ordered first by Course name, then student's last name, then student's first name, then attempt number. This can be limited to individual courses by adding to the where clause the course id to report on.
<code sql>
SELECT
u.firstname AS First,
u.lastname AS Last,
u.idnumber AS Employee_ID,
u.city AS City,
uid.data AS State,
u.country AS Country,
g.name AS Group_name,
c.fullname AS Course,
st.attempt AS Attempt,
st.value AS Status,
FROM_UNIXTIME(st.timemodified,"%m-%d-%Y") AS Date

FROM prefix_scorm_scoes_track AS st
JOIN prefix_user AS u ON st.userid=u.id
JOIN prefix_user_info_data AS uid ON uid.userid = u.id
JOIN prefix_scorm AS sc ON sc.id=st.scormid
JOIN prefix_course AS c ON c.id=sc.course
JOIN prefix_groups AS g ON g.courseid = c.id
JOIN prefix_groups_members AS m ON g.id = m.groupid

WHERE st.element='cmi.core.lesson_status' AND m.userid=u.id

UNION

SELECT
user2.firstname AS First,
user2.lastname AS Last,
user2. idnumber AS Employee_ID,
user2.city AS City,
uid.data AS State,
user2.country AS Country,
g.name AS Group_name,
c.fullname AS Course,
"-" AS Attempt,
"not_started" AS Status,
"-" AS Date

FROM prefix_user_enrolments AS ue
JOIN prefix_enrol AS e ON e.id = ue.enrolid
JOIN prefix_course AS c ON c.id = e.courseid
JOIN prefix_user AS user2 ON user2 .id = ue.userid
JOIN prefix_user_info_data AS uid ON uid.userid = user2.id
JOIN prefix_groups AS g ON g.courseid = c.id
JOIN prefix_groups_members AS m ON g.id = m.groupid
JOIN prefix_scorm AS sc ON sc.course=c.id
Left Join prefix_scorm_scoes_track AS st on st.scormid=sc.id AND st.userid=user2.id

WHERE st.timemodified IS NULL AND m.userid=user2.id

ORDER BY Course, Last, First, Attempt

</code>

== Badges==

=== All badges issued, by User ===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

This report will show you all the badges on a site that have been issued, both site and all courses, by the username of each user issued a badge. Includes the type of criteria passed (activity, course completion, manual), date issued, date expires, and a direct link to that issued badge page so you can see all the other details for that badge.

<code sql>
SELECT u.username, b.name AS badgename,
CASE
WHEN b.courseid IS NOT NULL THEN
(SELECT c.shortname
FROM prefix_course AS c
WHERE c.id = b.courseid)
WHEN b.courseid IS NULL THEN "*"
END AS Context,
CASE
WHEN t.criteriatype = 1 AND t.method = 1 THEN "Activity Completion (All)"
WHEN t.criteriatype = 1 AND t.method = 2 THEN "Activity Completion (Any)"
WHEN t.criteriatype = 2 AND t.method = 2 THEN "Manual Award"
WHEN t.criteriatype = 4 AND t.method = 1 THEN "Course Completion (All)"
WHEN t.criteriatype = 4 AND t.method = 2 THEN "Course Completion (Any)"
ELSE CONCAT ('Other: ', t.criteriatype)
END AS Criteriatype,
DATE_FORMAT( FROM_UNIXTIME( d.dateissued ) , '%Y-%m-%d' ) AS dateissued,
DATE_FORMAT( FROM_UNIXTIME( d.dateexpire ), '%Y-%m-%d' ) AS dateexpires,
CONCAT ('<a target="_new" href="%%WWWROOT%%/badges/badge.php?hash=',d.uniquehash,'">link</a>') AS Details
FROM prefix_badge_issued AS d
JOIN prefix_badge AS b ON d.badgeid = b.id
JOIN prefix_user AS u ON d.userid = u.id
JOIN prefix_badge_criteria AS t on b.id = t.badgeid
WHERE t.criteriatype <> 0
ORDER BY u.username
</code>

Please note: the FROM_UNIXTIME command is for MySQL.

=== All badges available in the system, with Earned count ===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

Report of all badges in the system, with badge name and description, context, course shortname if a course badge, whether it is active and available, and a count of how many users have been issued that badge.

<code sql>
SELECT b.id, b.name, b.description,
CASE
WHEN b.type = 1 THEN "System"
WHEN b.type = 2 THEN "Course"
END AS Context,
CASE
WHEN b.courseid IS NOT NULL THEN
(SELECT c.shortname
FROM prefix_course AS c
WHERE c.id = b.courseid)
WHEN b.courseid IS NULL THEN "*"
END AS Course,
CASE
WHEN b.status = 0 OR b.status = 2 THEN "No"
WHEN b.status = 1 OR b.status = 3 THEN "Yes"
WHEN b.status = 4 THEN "x"
END AS Available,
CASE
WHEN b.status = 0 OR b.status = 1 THEN "0"
WHEN b.status = 2 OR b.status = 3 OR b.status = 4 THEN
(SELECT COUNT(*)
FROM prefix_badge_issued AS d
WHERE d.badgeid = b.id
)
END AS Earned
FROM prefix_badge AS b

</code>

=== Badges Leaderboard ===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

A simple list of usernames and how many badges they have earned overall.

<code sql>
SELECT u.username, (SELECT COUNT(*) FROM prefix_badge_issued AS d WHERE d.userid = u.id) AS earned
FROM prefix_user AS u
ORDER BY earned DESC, u.username ASC
</code>

=== Manage badges (System & Course) ===

List system wide badges, course and system level badges + a link to relevant "manage badges" page.

<code sql>
SELECT b.id, b.name, b.description
,CASE
WHEN b.type = 1 THEN 'System'
WHEN b.type = 2 THEN 'Course'
END AS Level
,CONCAT('<a target="_new" href="%%WWWROOT%%/badges/index.php?type=', b.type, '&id=',
c.id, '">Manage badges in: ', c.fullname, '</a>') AS Manage
FROM prefix_badge AS b
JOIN prefix_course AS c ON c.id = b.courseid
</code>

==Administrator Reports==

===Config changes in Export friendly form===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

The Administrative report Config changes is very useful but it would be nice to have it in a format that could be easily exported in one listing. Here is code to do that.

<code sql>
SELECT
DATE_FORMAT( FROM_UNIXTIME( g.timemodified ) , '%Y-%m-%d' ) AS date,
u.username AS user,
g.name AS setting,
CASE
WHEN g.plugin IS NULL THEN "core"
ELSE g.plugin
END AS plugin,
g.value AS new_value,
g.oldvalue AS original_value
FROM prefix_config_log AS g
JOIN prefix_user AS u ON g.userid = u.id
ORDER BY date DESC
</code>

===Cohorts by user===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

How to get a list of all users and which cohorts they belong to.

<code sql>
SELECT u.firstname, u.lastname, h.idnumber, h.name
FROM prefix_cohort AS h
JOIN prefix_cohort_members AS hm ON h.id = hm.cohortid
JOIN prefix_user AS u ON hm.userid = u.id
ORDER BY u.firstname
</code>

===Cohorts with Courses===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

List of all cohorts with name, id, visibility, and which courses they are enrolled in.

<code sql>
SELECT
# h.id,
# e.customint1,
h.name AS Cohort,
h.idnumber AS Cohortid,
CASE
WHEN h.visible = 1 THEN 'Yes'
ELSE '-'
END AS Cohortvisible,
CONCAT('<a target="_new" href="%%WWWROOT%%/course/view.php', CHAR(63),'id=',c.id,'">',c.fullname,'</a>') AS Course
FROM prefix_cohort h
JOIN prefix_enrol e ON h.id = e.customint1
JOIN prefix_course c ON c.id = e.courseid %%FILTER_COURSES:e.courseid%%
WHERE e.enrol = 'cohort' AND e.roleid = 5
</code>

===Courses created And Active courses by Year===
Active courses is counting course that have at least one Hit, And "Active_MoreThan100Hits" counts courses that have at least 100 Hits
<code sql>
SELECT

YEAR( FROM_UNIXTIME( `timecreated` ) ) AS YEAR, COUNT( * ) AS Counter

, (SELECT COUNT( DISTINCT course )
FROM prefix_log AS l
WHERE YEAR( FROM_UNIXTIME( l.`time` ) ) = YEAR( FROM_UNIXTIME( `timecreated` ) )
) AS "Active"

,(SELECT COUNT(*) FROM (
SELECT COUNT( * ),time
FROM prefix_log AS l
GROUP BY course
HAVING COUNT(*) > 100) AS courses_log
WHERE YEAR( FROM_UNIXTIME( courses_log.`time` ) ) = YEAR( FROM_UNIXTIME( `timecreated` ) )
) AS "Active_MoreThan100Hits"

FROM `prefix_course`
GROUP BY YEAR( FROM_UNIXTIME( `timecreated` ) )
</code>

===Users created And Active users by Year===
Active users is counting users that have at least one Hit, And "Active_MoreThan500Hits" counts users that have at least 500 Hits
<code sql>
SELECT

YEAR( FROM_UNIXTIME( `firstaccess` ) ) AS YEAR, COUNT( * ) AS Counter

, (SELECT COUNT( DISTINCT userid )
FROM prefix_log AS l
WHERE YEAR( FROM_UNIXTIME( l.`time` ) ) = YEAR( FROM_UNIXTIME( `firstaccess` ) )
) AS "Active"

,(SELECT COUNT(*) FROM (
SELECT COUNT( * ),time
FROM prefix_log AS l
GROUP BY userid
HAVING COUNT(*) > 500) AS users_log
WHERE YEAR( FROM_UNIXTIME( users_log.`time` ) ) = YEAR( FROM_UNIXTIME( `firstaccess` ) )
) AS "Active_MoreThan500Hits"

FROM `prefix_user`
GROUP BY YEAR( FROM_UNIXTIME( `timecreated` ) )
</code>

===Course Aggregation Report===
Contributed by Elizabeth Dalton, Granite State College

If you are considering upgrading from Moodle 2.6 to 2.8 or later, your grades may be changed. This report can help quantify and identify the courses at risk of changes.

In particular, be on the lookout for any courses with the following combinations of parameters, which are known to cause changes in calculations:

# mean of grades set with aggregate with subcategory.
# Simple weighted mean of grades with aggregate with sub category and drop the lowest
# Sum of grades drop the lowest

Also review:
https://tracker.moodle.org/browse/MDL-48618
https://tracker.moodle.org/browse/MDL-48634
https://tracker.moodle.org/browse/MDL-49257
https://tracker.moodle.org/browse/MDL-50089
https://tracker.moodle.org/browse/MDL-50062

<code sql>
SELECT

COUNT(c.shortname) AS 'Count of Courses'

# If you want to display all the courses for each aggregation type, uncomment the next line and change GROUP BY settings
#, c.shortname AS 'course name'

# If you need to display grade categories for each aggregation type, uncomment the next line and change GROUP BY settings
#, gc.fullname AS 'grade category name'

, gc.aggregation AS 'aggregation method'

#These aggregation text strings appear to be hard-coded. I couldn't find a table for them. If you have aggregation types I haven't included here, they'll be blank in your report results.
, CASE gc.aggregation
WHEN 0 THEN 'Mean of Grades'
WHEN 2 THEN 'Median of Grades'
WHEN 6 THEN 'Highest Grade'
WHEN 8 THEN 'Mode of Grades'
WHEN 10 THEN 'Weighted Mean of Grades'
WHEN 11 THEN 'Simple Weighted Mean of Grades'
WHEN 12 THEN 'Mean of Grades (with extra credits)'
WHEN 13 THEN 'Sum of Grades'
END AS 'aggregation name'

# Note that gc.aggregatesubcats column is eliminated in 2.8 and later per MDL-47503, so comment that line on updated systems or you'll get an error
, gc.keephigh AS 'keep high'
, gc.droplow AS 'dr0p low'
, gc.aggregateonlygraded AS 'Aggregate only graded'
, gc.aggregateoutcomes AS 'aggregate outcomes'
, gc.aggregatesubcats AS 'aggregate subcategories'

# If you are displaying data about individual courses, you may want to know how old they are
#, FROM_UNIXTIME(c.startdate) AS 'course start date'

# If you are trying to use this report to check to see if final grades have changed after an upgrade, you might want these data items, but calculations can still change later when the courses are actually viewed. Also, you'll need to uncomment the necessary JOINs below
#, gi.itemname AS 'grade item'
#, gg.finalgrade AS 'final grade'

FROM

prefix_course AS c
JOIN prefix_grade_categories AS gc ON gc.courseid = c.id
JOIN prefix_course_categories AS cc ON cc.id = c.category

#LEFT JOIN prefix_grade_items AS gi ON gi.courseid = c.id #AND gi.categoryid=gc.id
#LEFT JOIN prefix_grade_grades AS gg ON gg.itemid = gi.id AND gg.userid = u.id

WHERE
1
#AND gc.aggregation = 13 #only the dreaded Sum of Grades aggregations
#AND gc.depth = 1 # if for some reason you only want course aggregations, not subcategories

GROUP BY gc.aggregation, gc.keephigh, gc.droplow, gc.aggregateonlygraded, gc.aggregateoutcomes, gc.aggregatesubcats

</code>

=== Running Cron jobs (task_scheduled) ===
<code sql>
SELECT classname
,DATE_FORMAT(FROM_UNIXTIME(lastruntime), '%H:%i [%d]') AS 'last'
,DATE_FORMAT(now(), '%H:%i') AS 'now'
,DATE_FORMAT(FROM_UNIXTIME(nextruntime), '%H:%i [%d]') AS 'next'
,DATE_FORMAT(FROM_UNIXTIME(UNIX_TIMESTAMP()-nextruntime), '%i') AS 'next in min'
FROM mdl_task_scheduled
WHERE now() > FROM_UNIXTIME(nextruntime)
</code>

=== All Meta courses with Parent and Child course relationships ===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

This shows the list of courses with Meta course link enrollments in them ('Parent course'), and the courses which are connected to them to provide enrollments ('Child courses').

<code sql>
SELECT
c.fullname AS 'Parent course name',
c.shortname AS 'Parent course shortname',
en.courseid AS 'Parent course id',
(SELECT fullname FROM prefix_course WHERE prefix_course.id = en.customint1) As 'Child course name',
(SELECT shortname FROM prefix_course WHERE prefix_course.id = en.customint1) As 'Child course shortname',
en.customint1 AS 'Child course id'
FROM prefix_enrol en
JOIN prefix_course c ON c.id = en.courseid
WHERE en.enrol = 'meta'
ORDER BY c.fullname
</code>

=== All Private Files by User ===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

Lists all files by all users in the Private Files repository, with the file path location and name in the moodledata/filedir directory structure, and time created.

<code sql>
SELECT
u.username,
f.filename,
CONCAT('/', LEFT(f.contenthash,2), '/', MID(f.contenthash,3,2), '/', f.contenthash) AS "Filedir_Location",
DATE_FORMAT(FROM_UNIXTIME(f.timecreated),'%Y-%m-%d %H:%i') AS "Created"
FROM prefix_files f
JOIN prefix_user u ON u.id = f.userid
WHERE f.component = 'user'
AND f.filearea = 'private'
AND f.filesize > 0
ORDER BY u.username, f.filename
</code>

== Learning Analytics Reports ==
(Moodle v. 3.4 and later)

=== Learning Analytics Model Summary ===
This report provides a list of the learning analytics models on your site, whether enabled or not, and several details about them.

(Note: this report was created on a system using PostgreSQL. Some changes may be needed for other forms of SQL.)
Contributed by Elizabeth Dalton, Moodle HQ

<code sql>
SELECT
am.id AS "model id",
split_part(am.target,'\',5) AS "target",
CASE WHEN am.enabled=1 THEN 'YES' ELSE 'NO' END AS "enabled",
CASE WHEN am.trained=1 THEN 'YES' ELSE 'NO' END AS "trained",
am.name,
/* indicators,*/
char_length(am.indicators) - char_length(REPLACE(am.indicators,',',''))+1 AS "indicator count",
split_part(am.timesplitting,'\',5) AS "interval",
/*
to_timestamp(am.version) AS "version",
to_timestamp(am.timecreated) AS "time created",
to_timestamp(am.timemodified) AS "time modified",
*/
COUNT(DISTINCT ap.contextid) AS "contexts",
COUNT(ap.sampleid) AS "samples",
/* AVG(ap.prediction) AS "avg prediction", */
ROUND(ap.prediction,1) AS "prediction",
ROUND(AVG(aml.score),3) AS "model accuracy (avg)",
apa.actionname AS "action",
COUNT(apa.id) AS "number actions taken"

FROM prefix_analytics_models AS am
JOIN prefix_analytics_predictions AS ap ON am.id = ap.modelid
LEFT JOIN prefix_analytics_models_log AS aml ON aml.modelid = am.id
LEFT JOIN prefix_analytics_prediction_actions AS apa ON apa.predictionid = ap.id
GROUP BY am.id, ap.prediction, apa.actionname
</code>

=== Analytics Indicator Calculations ===
Pulls calculations from the "analytics_indicator_calc" table consisting of all calculations made for each indicator for each sample within each context for every model. In most cases you will want to limit this per context or sample, or at least group by context and sample.

<code sql>
SELECT
id,
to_timestamp(starttime) AS "start time",
to_timestamp(endtime) AS "end time",
contextid,
sampleorigin,
sampleid,
/*indicator, */
split_part(indicator,'\',2) AS "module",
split_part(indicator,'\',5) AS "indicator type",
value,
to_timestamp(timecreated) AS "time created"

FROM prefix_analytics_indicator_calc
WHERE id = 1
</code>

===Analytics Models ===
Pulls data from the "analytics_models" table consisting of one row per model. See the "Learning Analytics Model Summary" report, above, for an expanded report that JOINs model data from different tables to provide a more comprehensive view.
Contributed by Elizabeth Dalton, Moodle HQ

<code sql>
SELECT
id,
enabled,
trained,
name,
split_part(target,'\',5) AS "target",
/* indicators,*/
char_length(indicators) - char_length(REPLACE(indicators,',',''))+1 AS "indicator count",
split_part(timesplitting,'\',5) AS "interval",
predictionsprocessor,
to_timestamp(version) AS "version",
to_timestamp(timecreated) AS "time created",
to_timestamp(timemodified) AS "time modified",
usermodified

FROM prefix_analytics_models
</code>

=== Analytics Models Log ===
Pulls data from the "analytics_models_log" table consisting of evaluation calculations per model. If model evaluations have not been manually executed on the system from the command line, there will be no contents in this table.
Contributed by Elizabeth Dalton, Moodle HQ

<code sql>
SELECT
id,
modelid,
to_timestamp(version) AS "version",
evaluationmode,
split_part(target,'\',5) AS "target",
/* indicators,*/
char_length(indicators) - char_length(REPLACE(indicators,',',''))+1 AS "indicator count",
split_part(timesplitting,'\',5) AS "interval",
score,
info,
dir,
to_timestamp(timecreated) AS "time created",
usermodified

FROM prefix_analytics_models_log
</code>

=== Analytics Predictions ===
Pulls data from the "analytics_predictions" table consisting of one row per prediction per model. Counts the number of indicators calculated for each prediction, but does not list them. If a model has not yet been trained, the system cannot make predictions and this table will not include rows for that model ID. See the "Learning Analytics Model Summary" report, above, for an expanded report that JOINs model data from different tables to provide a more comprehensive view.
Contributed by Elizabeth Dalton, Moodle HQ

<code sql>
SELECT
id,
modelid,
contextid,
sampleid,
rangeindex,
prediction,
predictionscore,
char_length(calculations) - char_length(REPLACE(calculations,',',''))+1 AS "indicators calculated",
to_timestamp(timecreated) AS "time created",
to_timestamp(timestart) AS "time start",
to_timestamp(timeend) AS "time end"

from prefix_analytics_predictions
</code>

=== Analytics Prediction Actions ===
Pulls data from the "analytics_prediction_actions" table consisting of one row per action taken per prediction (e.g. a teacher viewing the outline report for a student at risk). If the model has not yet made predictions, there can be no prediction actions. See the "Learning Analytics Model Summary" report, above, for an expanded report that JOINs model data from different tables to provide a more comprehensive view.
Contributed by Elizabeth Dalton, Moodle HQ

<code sql>
SELECT
id,
predictionid,
userid,
actionname,
to_timestamp(timecreated) AS "time created"

FROM prefix_analytics_prediction_actions
</code>

=== Analytics Predictions with All Indicators ===
Pulls data from the "analytics_predictions" table consisting of one row per prediction per model. Lists the indicators calculated for each prediction. If a model has not yet been trained, the system cannot make predictions and this table will not include rows for that model ID.
Contributed by Elizabeth Dalton, Moodle HQ

<code sql>
SELECT
id AS "Prediction ID",
modelid AS "Model ID",
contextid AS "Context ID",
sampleid AS "Sample ID",
rangeindex AS "Analysis Interval",
prediction AS "Prediction value",
predictionscore,
calculations,
char_length(calculations) - char_length(REPLACE(calculations,',',''))+1 AS "indicators calculated",
to_timestamp(timecreated) AS "time created",
to_timestamp(timestart) AS "time start",
to_timestamp(timeend) AS "time end"

from prefix_analytics_predictions
</code>

=== Analytics Predict Samples ===
Pulls data from the "analytics_predict_samples" table consisting of one row per analysis interval per model, with a count of the samples used for each prediction. Sample details are not included here, but the report can be modified to list samples by IDs if needed by parsing the contents of the sampleids field. For example, this counts the number of student enrolments for which the system has generated predictions for a given model and analysis interval.
Contributed by Elizabeth Dalton, Moodle HQ

<code sql>
SELECT
id,
modelid,
analysableid,
split_part(timesplitting,'\',5) AS "interval",
rangeindex,
/* sampleids, */
char_length(sampleids) - char_length(REPLACE(sampleids,',',''))+1 AS "samples used",
to_timestamp(timecreated) AS "time created",
to_timestamp(timemodified) AS "time modified"

FROM prefix_analytics_predict_samples
</code>

=== Analytics Train Samples ===
Pulls data from the "analytics_train_samples" table consisting of one row per analysis interval per model, with a count of the samples used for each training calculation.
Contributed by Elizabeth Dalton, Moodle HQ

<code sql>
SELECT
id,
modelid,
analysableid,
split_part(timesplitting,'\',5) AS "interval",
/* sampleids, */
char_length(sampleids) - char_length(REPLACE(sampleids,',',''))+1 AS "samples used",
to_timestamp(timecreated) AS "time created"

FROM prefix_analytics_train_samples
</code>

=== Analytics Used Analysables ===
Pulls data from the "analytics_used_analysables" table consisting of one row per context per model, noting whether the analysable was used to train the model or to make a prediction. This data is used to control the training and prediction processes.
Contributed by Elizabeth Dalton, Moodle HQ

<code sql>
SELECT
id,
modelid,
action,
analysableid,
to_timestamp(firstanalysis) AS "first analysis",
to_timestamp(timeanalysed) AS "time analysed"

FROM prefix_analytics_used_analysables
</code>

=== Analytics Used Files ===
Pulls data from the "analytics_used_files" table consisting of one row per file per model, noting whether the file was used to train the model or to make a prediction. This data is used to control the training and prediction processes.
Contributed by Elizabeth Dalton, Moodle HQ

<code sql>
SELECT

id,
modelid,
fileid,
action,
TO_TIMESTAMP(time) AS Time

FROM prefix_analytics_used_files
</code>

===Average Cognitive Depth and Social Breadth===

Here is a simple SQL snippet to calculate average cognitive depth and social breadth indicators for all students in the system. This one ignores indicator values of 0, as they are nulls as defined in this model.
Contributed by Elizabeth Dalton, Moodle HQ

<code sql>
SELECT

i.contextid,
i.sampleid,

TRUNC(AVG(CASE
WHEN i.indicator LIKE '%cognitive%' THEN i.value
ELSE '0'
END),2) AS "Average Cognitive Depth",

TRUNC(AVG(CASE
WHEN i.indicator LIKE '%social%' THEN i.value
ELSE '0'
END),2) AS "Average Social Breadth"

FROM prefix_analytics_indicator_calc as i
WHERE
i.value != 0
GROUP BY i.contextid, i.sampleid
</code>

==Competencies==

===List of competencies from a framework and the courses including them===
Contributed by [https://moodle.org/user/profile.php?id=2049965 François Parlant]

<code sql>
SELECT
f.shortname AS 'Framework',
comp.shortname AS 'Competency',
cccomp.courseid AS 'Course id',
c.fullname AS 'Course name',
c.shortname AS 'Course code'
FROM
prefix_competency_coursecomp AS cccomp
INNER JOIN prefix_competency AS comp ON cccomp.competencyid = comp.id
INNER JOIN prefix_course AS c ON cccomp.courseid = c.id
INNER JOIN prefix_competency_framework AS f ON comp.competencyframeworkid = f.id
</code>

===Count the courses using each competency from frameworks===
Contributed by [https://moodle.org/user/profile.php?id=2049965 François Parlant]

Unfortunately, there is not a filter by competency framework.

<code sql>
select
f.shortname AS framework,
comp.shortname AS 'Competency',
COUNT(cccomp.competencyid) AS 'nb course'
FROM prefix_competency AS comp
INNER JOIN prefix_competency_framework AS f ON comp.competencyframeworkid = f.id
LEFT JOIN prefix_competency_coursecomp AS cccomp ON cccomp.competencyid = comp.id
GROUP BY comp.id, comp.shortname
</code>

=== Scale details with ids ===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

Competency import and export files include scales with id numbers. However, the management page in Grades > Scales does not have the scale id, nor other useful details that scales store about themselves, like who made them and when, and what context they pertain to. This simple query shows you that information.

<code sql>
SELECT
s.id AS Scaleid,
s.name AS Scale_Name,
s.scale AS Scale,
CASE
WHEN s.courseid = 0 THEN 'System'
ELSE (SELECT shortname FROM prefix_course WHERE id = s.courseid)
END AS Context,
CASE
WHEN s.userid = 0 THEN 'System'
ELSE (SELECT username FROM prefix_user WHERE id = s.userid)
END AS User,
s.description,
DATE_FORMAT( FROM_UNIXTIME(s.timemodified), '%Y-%m-%d %H:%i' ) AS 'Modified'
FROM prefix_scale s

</code>

==Syllabus==

Our school simply asks teachers to drop a file (resource) on their course page
and rename this resource (not the file) starting with "syllabus" (case insensitive)

===Count the number of resources whose name starts by "Syllabus"===
Contributed by [https://moodle.org/user/profile.php?id=2049965 François Parlant]
<code sql>
Select
r.name As 'Resource name',
cc.name AS 'Category',
CONCAT('<a href="%%WWWROOT%%/pluginfile.php/', ct.id, '/mod_resource/content/1/', f.filename, '">',f.filename,'</a>') AS 'Clickable filename',

c.fullname AS 'Course name',
c.shortname AS 'Course shortname',

# the date filters are connected to this "last modif" field
# userful to check if the syllabus has been updated this year
DATE_FORMAT(FROM_UNIXTIME(f.timemodified), '%e %b %Y') AS 'last modif',

# tell if the file is visible by the students or hidden
IF(cm.visible=0,"masqué","visible") AS 'Visibility',

# next line tries to give the real path (local path) if you want to create a zip file using an external script)
# notice that the path is in the column "contenthash" and NOT in the column pathhash
# if the contenthash starts with 9af3... then the file is stored in moodledata/filedir/9a/f3/contenthash
# I try to get the path to moodledata from the value of the geoip variable in the mdl_config table... maybe a bad idea
CONCAT('"',(Select left(value, length(value)-25) from prefix_config where name ="geoip2file"),'/filedir/', left(f.contenthash,2), "/",substring(f.contenthash,3,2),'/', f.contenthash, '"') AS 'link'

FROM prefix_resource AS r
INNER JOIN prefix_course_modules AS cm ON cm.instance = r.id
INNER JOIN prefix_course AS c ON c.id = r.course
INNER JOIN prefix_context AS ct ON ct.instanceid = cm.id
JOIN prefix_course_categories cc ON c.category = cc.id
INNER JOIN prefix_files AS f ON f.contextid = ct.id AND f.mimetype IS NOT NULL AND f.component = 'mod_resource'
WHERE LOWER( r.name) LIKE 'syllabus%'
%%FILTER_STARTTIME:f.timemodified:>%% %%FILTER_ENDTIME:f.timemodified:<%%
%%FILTER_SUBCATEGORIES:cc.path%%
</code>

===List files which have been tagged "Syllabus"===
Contributed by [https://moodle.org/user/profile.php?id=2049965 François Parlant]

<code sql>
Select
t.rawname AS 'rawtag',
c.shortname AS 'Cours shortname',
c.fullname AS 'Course name',
r.name As 'Resource name',
CONCAT('<a href="%%WWWROOT%%/pluginfile.php/', ti.contextid, '/mod_resource/content/1/', f.filename, '">cliquez ici</a>') AS 'link',
ti.contextid AS 'Instance for link',
f.id AS 'file id'
FROM prefix_tag_instance AS ti
INNER JOIN prefix_tag AS t ON ti.tagid = t.id
INNER JOIN prefix_course_modules AS cm ON ti.itemid = cm.id
INNER JOIN prefix_course AS c ON cm.course = c.id
INNER JOIN prefix_resource AS r ON r.id = cm.instance
INNER JOIN prefix_files AS f ON f.contextid = ti.contextid AND f.mimetype IS NOT NULL
WHERE t.rawname = 'Syllabus'
</code>

===List of courses WITHOUT a resource with a name starting by "syllabus"===
Contributed by [https://moodle.org/user/profile.php?id=2049965 François Parlant]

<code sql>
select c.id, c.shortname,
CONCAT('<a href="%%WWWROOT%%/course/view.php?id=', c.id, '">',c.fullname,'</a>') AS 'Course link'
FROM prefix_course AS c
LEFT JOIN (
Select r.course
from prefix_resource AS r
WHERE LOWER( r.name) LIKE 'syllabus%'
GROUP BY r.course) AS r ON r.course = c.id
INNER JOIN prefix_course_categories cc ON c.category = cc.id
WHERE r.course IS NULL
%%FILTER_SUBCATEGORIES:cc.path%%
%%FILTER_STARTTIME:c.startdate:>%% %%FILTER_ENDTIME:c.enddate:<%%
</code>

===List of courses have MULTIPLE resource with a name like "Syllabus%"===
Contributed by [https://moodle.org/user/profile.php?id=2049965 François Parlant]

<code sql>
select
r.course,
c.shortname,
CONCAT('<a href="%%WWWROOT%%/course/view.php?id=', r.id, '">',c.fullname,'</a>') AS 'Course link'
FROM prefix_resource AS r
INNER JOIN prefix_course AS c ON c.id = r.course
JOIN prefix_course_categories cc ON c.category = cc.id
WHERE LOWER( r.name) LIKE 'syllabus%'
GROUP BY r.course HAVING count(r.course)>1
%%FILTER_SUBCATEGORIES:cc.path%%
</code>

==Chat==

===List the chats===
Contributed by [https://moodle.org/user/profile.php?id=2049965 François Parlant]
This report gives the list of all chats with the name of the course and various ids needed for further queries.

The column "participants" is intended to work with an (optional) secondary report. If you don't need it , you can erase it.
It produces a direct link to another (optional) report which will give you the current participants list to this chat.

<code sql>
select
c.shortname,
c.fullname,
ch.course,
ch.id,
# if you intend to use a secondary report to see the participants of a specific chat
# create the secondary report, check the id of the report in the url, and change the 21 in next line to your participant report's id
CONCAT('<a href="%%WWWROOT%%/blocks/configurable_reports/viewreport.php?id=21&filter_courses=', ch.id,'">Chat participants</a>') AS 'Course link',
ch.chattime

FROM
prefix_chat ch
INNER JOIN prefix_course c ON c.id = ch.course

ORDER BY ch.chattime, c.fullname
</code>
===Participants to a chat (optional secondary report)===
This version of the participant list is intended to work with a link given in the previous report.
* User opens the report listing all the chats on the platform
* user clicks on the link from the column "chat participant"
* which open this report with a filter on the chatid
''(careful, we are tweaking the coursefilter to carry instead the chatid: the displayed "course filter" will not work! but we need it)''

<code sql>

SELECT
c.id AS courseid,
chu.chatid,
chu.userid AS 'chat user userid',
c.fullname,
u.username,
u.firstname,
u.lastname,
u.email

FROM
prefix_user u
LEFT JOIN prefix_chat_users chu ON chu.userid = u.id
INNER JOIN prefix_course c ON c.id = chu.course

WHERE 1=1
%%FILTER_COURSES:chu.chatid%%
# you can also filter by course
# but don't put comment line between where and filter
# %%FILTER_COURSES:chu.course%%

ORDER BY c.fullname

</code>

===List current participants to chat===
Contributed by [https://moodle.org/user/profile.php?id=2049965 François Parlant]
<code sql>
SELECT
c.id AS courseid,
chu.chatid,
chu.userid AS 'chat user userid',
c.fullname,
u.username,
u.firstname,
u.lastname,
u.email

FROM
prefix_user u
LEFT JOIN prefix_chat_users chu ON chu.userid = u.id
INNER JOIN prefix_course c ON c.id = chu.course

WHERE 1=1
%%FILTER_COURSES:chu.course%%

ORDER BY c.fullname
</code>

== Useful sub queries ==

IN this section please put any short one purpose sub queries that show how common procedures often useful as part of larger queries.

=== All teachers in the course ===

This snippet shows how to get teachers from a course. The contextevel for course objects is 50. And the default Teacher role is role id 3.

<code sql>
,(SELECT GROUP_CONCAT( CONCAT( u.firstname, " ", u.lastname ) )
FROM prefix_course ic
JOIN prefix_context con ON con.instanceid = ic.id
JOIN prefix_role_assignments ra ON con.id = ra.contextid AND con.contextlevel = 50
JOIN prefix_role r ON ra.roleid = r.id
JOIN prefix_user u ON u.id = ra.userid
WHERE r.id = 3 AND ic.id = c.id
GROUP BY ic.id
) AS TeacherNames
</code>

=== Get custom User profile fields for a user ===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

This snippet of code shows how to connect a user with their custom profile field data. This will list all users with all custom profile fields and data. Custom profile fields have two tables, one for the definition of the profile field (user_info_field) and its settings, and a separate table to hold the data entered by users (user_info_data).

<code sql>
SELECT u.username, uif.name, uid.data
FROM prefix_user AS u
JOIN prefix_user_info_data AS uid ON uid.userid = u.id
JOIN prefix_user_info_field AS uif ON uid.fieldid = uif.id
</code>

If you want to limit it to one of those fields, you can restrict it by shortname of the custom profile field, so:

<code sql>
SELECT u.username, uif.name, uid.data
FROM prefix_user AS u
JOIN prefix_user_info_data AS uid ON uid.userid = u.id
JOIN prefix_user_info_field AS uif ON (uid.fieldid = uif.id AND uif.shortname = 'shortname1')
</code>

will show you only the data from the custom profile field with the shortname 'shortname1'.

If you want to do this with two or more custom profile fields, you will need to have a JOIN and table alias for each with a restriction for each profile field shortname. Example:

<code sql>
SELECT u.username, d1.data AS 'Profile One', d2.data As 'Profile Two'
FROM prefix_user u
JOIN prefix_user_info_data d1 ON d1.userid = u.id
JOIN prefix_user_info_field f1 ON d1.fieldid = f1.id AND f1.shortname = 'shortname1'
JOIN prefix_user_info_data d2 ON d2.userid = u.id
JOIN prefix_user_info_field f2 ON d2.fieldid = f2.id AND f2.shortname = 'shortname2'
</code>

==== NOTE: Alternate Method ====

If you have more than a couple of fields you need to use, then this query may time out or not return data due to too many joins. The limit seems to be around 10 custom profile fields.

Instead you should use an alternate method which uses Subselects for each of the profile fields. Details and sample code are in this forum discussion: https://moodle.org/mod/forum/discuss.php?d=355502#p1434854. A sample of the style is:

<code sql>
SELECT u.username

,(SELECT d1.data FROM prefix_user_info_data d1
JOIN prefix_user_info_field f1 ON d1.fieldid = f1.id AND f1.shortname = 'shortname1'
WHERE d1.userid = u.id
) AS thefirstfield

,(SELECT d1.data FROM prefix_user_info_data d1
JOIN prefix_user_info_field f1 ON d1.fieldid = f1.id AND f1.shortname = 'shortname2'
WHERE d1.userid = u.id
) AS thesecondfield

FROM prefix_user u
</code>

=== How to use Configurable Reports Date Time Filters===

Contributed by: [https://moodle.org/user/profile.php?id=88992 Randy Thornton]

In the Configurable Reports block, you can set the Time and Date filter to allow you to pick your report Start date/time and End date/time interactively. This will work on any column in a table that is a timestamp.

Here is a simple example:

<code sql>
SELECT u.username,
DATE_FORMAT(FROM_UNIXTIME(u.firstaccess),'%Y-%m-%d %H:%i') AS 'FirstAccess',
DATE_FORMAT(FROM_UNIXTIME(u.lastaccess),'%Y-%m-%d %H:%i') AS 'LastAccess'
FROM prefix_user u

WHERE 1=1
%%FILTER_STARTTIME:u.firstaccess:>%%
%%FILTER_ENDTIME:u.lastaccess:<%%
</code>

1) You will need to replace name of the table and column for the filter to use the time and date column you need for your query. In the example above, it filters on the firstaccess and lastaccess columns in the user table. If you were doing a report on course completion, you might put the timecompleted column, and so forth.

2) You MUST then add the Start / End date filter on the Filters tab of the Report. If you don't, the report will still run, probably, but the filter will be ignored.

Note: the WHERE 1=1 statement is a peculiarity of the filters in Config reports: if you don't have a WHERE statement in your query already, then you must add this dummy WHERE to keep the statement valid. If you already have a WHERE statement in your code, simply add the %%FILTER%% placeholders after it (and before any GROUP or ORDER BY statements.)

==See also==
* [https://github.com/jleyva/moodle-configurable_reports_repository Configurable Reports Repository on GitHub]
* [https://moodleschema.zoola.io/index.html Moodle DB schema explorer] - searching and filtering tables, fields and external key connections between tables.

[[Category:Contributed code]]

[[es:Reportes específicos hechos por usuarios]]

Microsoft 365

2021-07-30T15:48:13Z

Enovationdevteam:

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams https://moodle.org/plugins/assignsubmission_onenote https://moodle.org/plugins/assignfeedback_onenote
|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 =
Microsoft 365 services complement the Moodle learning platform to provide a more productive experience for teachers and students.
== Differences from Moodle Core ==
Although Moodle core now provides Microsoft 365 authentication and basic OneDrive repository support, the Microsoft 365 plugin suite provides a much wider set of features.

A few key features only found in the Microsoft 365 plugin suite:
* User sync from Microsoft 365/Azure AD to Moodle
* Automatic and manual user matching from Microsoft 365/Azure AD to Moodle
* Calendar sync
* Course to Microsoft 365 group/teams sync and shared file repositories
* OneNote assignment submission and feedback types
* Office document embedding using Office web apps
* Fully customizable sign-in experience
= Requirements =
To use the Microsoft 365 plugins, you need the following:
* A Microsoft 365 subscription.
* A Microsoft Azure subscription.
* Moodle version 3.5 or above. The plugins are available for Moodle versions 2.7 and above. Features available in each version, and the support status vary.
= Plugins & Features =
The Microsoft 365 set of plugins contains 6 core plugins, and 3 optional plugins, which provide a wide variety of features to enhance your Moodle instance.
* '''Microsoft 365 Local Plugin''' (local_office365)
** This is a shell plugin which has dependencies on the current version of each of the 5 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''OpenID Connect Authentication Plugin''' (auth_oidc)
** This plugin allows users to log in to Moodle using their Microsoft 365 accounts.
** Users with existing Moodle accounts can switch to using this authentication type, and new users can log in with this plugin and have an account created for them.
** If the administrator allows, users can also choose to disconnect from OpenID Connect and revert their previous login method, or to a username/password.
** Features:
*** Standards-Compliant OpenID Connect Authentication.
*** Supports authorization code or resource-owner credentials grants.
**** Users can log in to Moodle by clicking the identity provider on the login page, or by entering their OpenID Connect credentials.
*** User profile field mapping
**** User profiles can be mapped and synced from IdP to Moodle.
*** Customizable Icon + Identity Provider name
**** The icon and identity provider name shown on the Moodle login page can be customized. A number of prechosen icons are available, as well as the ability to upload your own.
*** Provides hooks to link OpenID Connect accounts to Moodle accounts
**** If you do not want to change your users' login method, you can still connect to an OpenID Connect provider. The plugin provides code-level hooks to link a Moodle account to an OpenID Connect account without changing the Moodle user's authentication method. This means you can obtain tokens from an OpenID Connect service in the background.
*** Optional user-self-service connection and disconnection
**** A user-facing page is available for users to switch to and from OpenID Connect authentication. Access to this page and feature is controlled by a capability so administrators can disable it.
* '''Microsoft 365 support plugin''' (local_o365)
** This plugin provides most of the Microsoft 365 integration back-end. It provides shared code to communicate with Microsoft 365, and powers the calendar sync.
** Features:
*** Calendar sync from/to Outlook.
**** Users can sync site events, course events, assignment due dates, and their personal Moodle calendar to their Outlook calendar.
*** User Sync and Matching
**** Users can be synced from Azure AD, or matched with existing users.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Microsoft 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Microsoft 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features:
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.
* '''Microsoft 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
== Optional Plugins ==
These 3 plugins provide support for OneNote assignment submission and feedback. While they are not required, they provide a powerful way to submit and review assignments.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.
== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =
== Installation ==
The packages are available from:
* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Microsoft 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle
When you log back in to your Moodle instance, you are presented with the all the plugin configuration options. Save the settings without configuring them for now, you will come back to them later.

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

To use Moodle with Microsoft 365 for SSO, you must configure Microsoft Azure to manage your Microsoft 365 Microsoft Azure Active Directory. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

You should only follow the manual process if you are unable to setup the AzureAd app via PowerShell script, or you need to verify some specific settings.
==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.
===== Configure application =====
# Locate the App.
#* If you followed steps above to create the Azure app, you should be redirected to the app settings page already.
#* Otherwise:
#*# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
#*# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
#*# Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
#*# Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
#*# Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires".
## Click '''Add'''.
## A value will appear under '''Value''', note this value (write it down or copy it somewhere) and set it aside. You'll need it later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the '''Set''' link next to '''Application ID URI'''.
## This should open a '''Set the APP ID URI''' prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://'''URL.TO.MOODLE'''/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click '''Save''' to create the Application ID URI.
## Click '''Add a scope'''.
## Enter '''access_as_user''' as scope name.
## Set '''Who can consent?''' to '''Admins and users'''.
## Set '''Admin consent title''' to '''Teams can access the user’s profile'''.
## Set '''Admin consent description''' to '''Allows Teams to call the app’s web APIs as the current user'''.
## Set '''User consent title''' to '''Teams can access the user profile and make requests on the user's behalf'''.
## Set '''User consent description''' to '''Enable Teams to call this app’s APIs with the same rights as the user'''.
## Ensure that '''State''' is set to be '''Enabled'''.
## Select the '''Add scope''' button to save.
## In the '''Authorized client applications''' section, identify the applications that you want to authorize for your app’s web application. Select '''Add a client application'''. Enter each of the following client IDs and select the authorized scope you created in the previous step:
##* '''<code>1fec8e78-bce4-4aaf-ab1b-5451cc387264</code>''' (Teams mobile/desktop application)
##* '''<code>5e3ce6c0-2b1f-4285-8d4b-75ee78787346</code>''' (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose '''Microsoft Graph'''.
## Click the checkbox for the following permissions in each of the '''Application''' and '''Delegated''' permissions sections according to the section below.
## After all the permissions are added, click the '''Grant admin consent for YOUR ORGANISATION NAME''' link.
## When you're done, click '''Add permissions''' at bottom of the page.
===== Azure app permissions =====
The integration uses various [https://docs.microsoft.com/en-us/graph/overview Microsoft Graph APIs] to communicate with Microsoft 365 to get and set data. Each Graph API would require a different set of app permissions. The integration provides a list of recommended permissions to be given to ensure all features in the integration works, all of which are added automatically by the PowerShell script if it's used. Advanced users can customise the permissions according to the need of their own organisation, e.g. if group/team integration is not used, all permissions related to group can be removed, e.g. Group.ReadWrite.All.
====== Application permissions vs delegated permissions ======
In general, if the Moodle site uses the '''Application access''' connection method, giving only application permissions would be enough; if the Moodle site uses the '''System API user''' connection method, only delegated permission are required.

Note the following exception:
* '''User.Read''' delegated permission is always required regardless of connection method.
* If teams integration feature is used, the following delegated permissions are required for teams SSO to work, regardless of connection method:
** '''openid'''
** '''offline_access'''
** '''email'''
** '''profile'''
* As of release 3.9.6 and 3.10.3 release of the plugins in June 2021, there are a small number of Microsoft Graph APIs used in the integration making calls to the "/me/" path, which would require the corresponding delegated permissions regardless of connection method. A plan is in place to replace calls like this in the next release, so that these delegated permissions can be removed. The delegated permissions affected are:
** '''Calendars.ReadWrite''' for calendar sync.
** '''Sites.Read.All''' and '''Files.ReadWrite.All''' for OneDrive integration.
** '''Notes.ReadWrite.All''' for OneNote integration.
====== Permissions ======
For a full list of Microsoft Graph API used, and the permissions required, please refer to [https://docs.google.com/spreadsheets/d/1XIFnnQ8RuFjlPGB8CiiMmK8x9Uta9XIR_icvAdx0G6k this spreadsheet]. Note that:
* This document is constantly updated.
* For each Graph API, a few permissions may be listed. Graph API can be called if permissions in any line is added, and the admin consent is granted for your organisation.

The recommended permissions to ensure all integration features work are listed below. These would be the same set of permissions that are applied when using the PowerShell script to set up the Azure app.
{| class="wikitable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="10" | Application Permissions
|'''Directory.ReadWrite.All'''
|'''Read and write directory data'''
| A common permission used in both user syncs and group integration.
|-
|'''Directory.Read.All'''
|'''Read directory data'''
| A common permission used in both user syncs and group integration.
|-
|'''Group.ReadWrite.All'''
|'''Read and write all groups'''
| Required for course group/team integration.
|-
|'''User.Read.All'''
|'''Read all users' full profiles'''
| Required for SSO and to sync user information between Microsoft 365 and Moodle.
|-
|'''Files.ReadWrite.All'''
|'''Read and write files in all site collections'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
|'''Calendars.ReadWrite'''
|'''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
|'''Sites.Read.All'''
|'''Read items in all site collections'''
|Required to detect OneDrive for Business URL setting.
|-
|'''Notes.ReadWrite.All'''
|'''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
|-
|'''MailboxSettings.Read'''
|'''Read all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
|-
|'''AppRoleAssignment.ReadWrite.All'''
|'''Manage app permission grants and app role assignments'''
| Required for assigning users to application during user sync if the option is enabled.
|-
| rowspan="16" |Delegated Permissions
|'''Directory.ReadWrite.All'''
|'''Read and write directory data'''
| A common permission used in both user syncs and group integration.
|-
|'''Directory.Read.All'''
|'''Read directory data'''
| A common permission used in both user syncs and group integration.
|-
|'''Group.ReadWrite.All'''
|'''Read and write all groups'''
| Required for course group integration.
|-
|'''User.Read.All'''
|'''Read all users' full profiles'''
|Required for SSO and to sync user information between Microsoft 365 and Moodle.
|-
|'''Files.ReadWrite.All'''
|'''Have full access to all files user can access'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
|'''Calendars.ReadWrite'''
|'''Have full access to user calendars'''
| Required for calendar event sync.
|-
|'''Sites.Read.All'''
|'''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
|'''Notes.ReadWrite.All'''
|'''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
|'''AppRoleAssignment.ReadWrite.All'''
|'''Manage app permission grants and app role assignments'''
|Required for assigning users to application during user sync if the option is enabled.
|-
|'''MailboxSettings.Read'''
|'''Read user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
|'''User.Read'''
|'''Sign-in and read user profile'''
| Required to sign users in using Microsoft 365, and to access Microsoft 365 APIs.
|-
|'''openid'''
|'''Sign users in'''
| Required for Teams SSO.
|-
|'''offline_access'''
|'''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
|'''email'''
|'''View users' email address'''
| Required for Teams SSO.
|-
|'''profile'''
|'''View users' basic profile'''
| Required for Teams SSO.
|}
=== Enter Azure application credentials into Moodle ===
# 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 Microsoft 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## Choose the method you want to use to connect to Microsoft 365. Unless you have a special reason to use the System API user, choose '''Application access'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''Admin consent:''' Every time you change a '''Requires admin''' permission in Azure, you will need an administrator to provide consent to use the permission. Clicking the '''Provide admin consent''' button will take you to a log in screen on Microsoft 365. An administrator will have to log in, and then will be given the option to approve the new permissions.
## '''Azure AD Tenant:''' This is the domain name that identifies your Microsoft 365 subscription, for example "contoso.onmicrosoft.com". If you know it, enter it in this box, if not, click the "Detect" button to attempt to detect the correct value.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.
== Connecting users to Microsoft 365 ==
To use any Microsoft 365 features, a Moodle user must be connected to a Microsoft 365 user that has an active Microsoft 365 subscription. There are two ways to connect a Moodle user to a Microsoft 365 user.
=== Switch the user to use OpenID Connect authentication. ===
With this method, the user will log in to Moodle using their Microsoft 365 account credentials.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].
=== Link a Moodle user to a Microsoft 365 user. ===
Users in Moodle can also be linked to Microsoft 365 users without changing the Moodle user's authentication method. Users will be able to log in as they always have, and still use all the Microsoft 365 features.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Microsoft 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# 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 Microsoft 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 '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# This user is now connected to the Microsoft 365 user.
= Microsoft 365 Integration Local Plugin =
== Sync Settings ==
These features are accessible from the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft 365 Integration), on the '''Sync Settings''' tab.
=== User Sync ===
This option controls how users are synced from Azure AD to Moodle. If enabled, users from Azure AD can be automatically created in Moodle. This feature can also delete users in Moodle when they are deleted from Azure AD, or attempt to automatically match Moodle users with users in the connected Azure AD.

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

'''Notes:'''
* The sync job runs in the Moodle cron, and syncs 1000 users at a time.
* By default, this runs once per day at 1:00 AM in the time zone local to your server.
* To sync large sets of users more quickly, you can increase the freqency of the Sync users with Azure AD task using the Scheduled tasks management page. See [[Scheduled_tasks]].
There are several options that affect user sync:
* '''Create accounts in Moodle for users in Azure AD''': This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their Microsoft 365 credentials to log in to Moodle (using the OpenID Connect authentication plugin), and will be able to use all the features of the Microsoft 365 plugin set.
* '''Update all accounts in Moodle for users in Azure AD''': This will update all users in Moodle from each user in the linked Azure AD.
* '''Delete previously synced accounts in Moodle when they are deleted from Azure AD''': This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!
* '''Match preexisting Moodle users with same-named accounts in Azure AD''': This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are insensitive and ignore the Microsoft 365 tenant. For example, "BoB.SmiTh" in Moodle would match "bob.smith@example.onmicrosoft.com". Users who are matched will have their Moodle and Office accounts connected and will be able to use all Microsoft 365/Moodle integration features. The user's authentication method will not change unless the setting below is enabled.
* '''Switch matched users to Microsoft 365 (OpenID Connect) authentication''': This requires the "Match" setting above to be enabled. When a user is matched, enabling this setting will switch their authentication method to OpenID Connect. They will then log in to Moodle with their Microsoft 365 credentials. Note: Please ensure the OpenID Connect authentication plugin is enabled if you want to use this setting.
* '''Assign users to application during sync''': The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.
* '''Sync Microsoft 365 profile photos to Moodle in cron job''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.
* '''Sync Microsoft 365 profile photos to Moodle on login''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.
* '''Perform a full sync each run''': By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
* '''Match Azure usernames to Moodle emails instead of Moodle usernames during the sync''': Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.
====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.
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.
=== Teams Sync ===
The Teams sync setting creates teams in Microsoft Teams for courses in Moodle. Teams creation effectively results in team members being added to a Microsoft 365 group, enabling all group features to be usable.

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

Once enabled, new Teams will be created every cron run for any enabled course that doesn't have a team set up. Once Teams are set up, membership will be maintained automatically whenever someone joins or leaves a Moodle course.
==== Teams vs Group ====
Microsoft Teams share the same base with Microsoft 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to a Microsoft 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Microsoft 365 user, only a group will be created.
== Advanced settings ==
=== Administrator Tools ===
* '''Tenants''': This tool allows you to add additional Microsoft 365 tenants to be used with Moodle. Users from additional tenants can log-in to Moodle using their Microsoft 365 account, and use features like calendar sync and the OneDrive repository.
* '''Health check''': If you are experiencing problems with any Microsoft 365 / Moodle features, click the '''Health Check''' link to run tests on your system and look for potential problems.
* '''Connections''': This tool allows administrators to see and manage the connections between their Moodle users and Microsoft 365 accounts. Each user in the system is listed alongside the Microsoft 365 username the user is connected to, if any. Administrators can choose to manually connect or disconnect each user.
* '''User Matching''': This tool allows administrators to manually match Moodle and Microsoft 365 users using a CSV file. Administrators can upload a CSV file containing, on each line, a Moodle username, and Microsoft 365 username, and a 1 or 0 indicating whether to enable Microsoft 365 login for that user. Once uploaded, the file is processed in batches during the Moodle cron. The tool page will display the progress of this process.
* '''Maintenance Tools''': These tools perform maintenance tasks that can help solve problems which may crop up from time to time. Generally, users should not need these tools unless they encounter the specific situation these tools are designed to solve.
**'''Resync users in groups for courses''': Course group membership is kept up-to-date as users are enrolled and un-enrolled from courses in Moodle. If this membership gets out-of-date for whatever reason, this tool will force a resync of group membership.
** '''Recreate deleted Microsoft 365 groups''': Course groups are created from Moodle courses when using the course group feature. If a group is manually deleted from the Microsoft 365 administrator panel, this tool will recreate it.
** '''Generate debug data package''': This tool will generate a package of information that can be sent to the plugin suite maintainers to help debug problems in environment and setup. While no API keys are present, this information does contain a lot about your environment and setup, so please be careful about who you send this information to.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Microsoft 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.
===Other advanced settings===
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Microsoft 365 as well.
* '''Microsoft 365 for China''': Microsoft 365 in China differs slightly in some technical aspects. If you are using Microsoft 365 for China, select this box to ensure everything will work properly.
* '''Record debug messages''': If you experience problems using any Microsoft 365 features in Moodle, enable this setting. Once enabled, errors will be recorded to the Moodle log for review. These errors can help you or the plugin developers debug and fix the problem. The error log can be viewed by navigating to Site Administration > Reports > Logs, changing the "All activities" select box to "Site errors", and clicking "Get these logs".
* '''Minimum inexact username length to switch to Microsoft 365''': When using automatic user matching, this setting can be used to exclude accounts with short names. The intended use of this is to avoid matching generic accounts like "admin". This setting is the minimum length of a username required for automatic matching to match users.
* '''Profile photo refresh time''': Profile photo syncing can be a resource-intensive process, so this setting allows you to set a minimum time between profile photo refresh runs.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.
===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''
===Preview features===
From time-to-time, we add features that use brand-new APIs or are slightly experimental in some way. These features often become part of our regular feature offering once they mature, but if you want to see the latest features we're working on, you can enable this setting to enable all preview features. Be careful though! These features do break from time to time.
==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.
===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Microsoft 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Microsoft 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.
=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.
=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.
=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.
==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Save changes.
=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.
== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.
To configure the field, follow these steps:
# Log in Teams, and go to app catalog by clicking the '''Apps''' button from the navigation bar on the left.
# Find the '''Moodle''' app uploaded.
# Click the option icon of the app, which is located at the top right corner of the app image.
# Click '''Copy link'''.
# In a text editor, paste the copied content. It should contain an URL such as https://teams.microsoft.com/l/app/00112233-4455-6677-8899-aabbccddeeff.
# The last part of the URL, i.e. 00112233-4455-6677-8899-aabbccddeeff, is the app ID.
# Paste the app ID in the '''Moodle app ID''' setting on '''Teams Moodle app''' tab of '''Microsoft 365 Integration''' configuration page in Moodle.
# Save changes.
= OpenID Connect Authentication Plugin =
== Basic Usage ==
Once configured, you should see a link named "OpenID Connect" on the Moodle login page. Clicking this link will redirect the browser to the identity provider. Users will log in there, and will be redirected back to Moodle. If they have logged in to Moodle using OpenID Connect before, they will be logged in to their existing Moodle account. If they have not logged in to Moodle with OpenID Connect before, an account will be created for them.

Note: If the "Prevent account creation when authenticating" setting is enabled in Moodle, new accounts will not be created.
== Settings ==
There are a number of options you can use to customize how the plugin behaves. To configure the plugin, visit the plugin's settings page. (Site Administration > Plugins > Authentication > OpenID Connect)
====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the Microsoft 365 plugins to refer to the system used to log users in. For example, if your users are used to calling their Azure AD account their "School" account, you enter "School account" here, and all references to authentication will be "Log in with your School account".
====Auto-Append====
When using the "Username/Password" login flow, this setting with automatically append a given string to an entered username. This is useful in Azure AD usernames, where a single domain name is often used for every user - i.e. [user]@contoso.onmicrosoft.com. Users would normally have to enter this entire username to successfully log in to Moodle, but in this example, entering "@contoso.onmicrosoft.com" here means users would only have to enter their unique username, i.e. "bob.smith", instead of "bob.smith@contoso.onmicrosoft.com".
====Domain Hint====
If users have several different Azure AD accounts with different tenants (i.e. @contoso.onmicrosoft.com, @example.onmicrosoft.com), but Moodle only uses one of these tenants, you can enter that tenant in this box to have the Azure AD login screen only ever suggest accounts from that tenant.
====Login Flow====
This setting changes how users log in to Moodle using the plugin. You can redirect users to the OpenID Connect provider's login page, or have users enter their credentials directly into Moodle. See the "Login Flows" section below for further information.
====User Restrictions====
This setting allows you to restrict the users that can log in to Moodle using OpenID Connect (Azure AD).

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

How to use user restrictions:
# 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.
== Login flows ==
This plugin supports two different methods for users to log in: Authorization Request and Username/Password Authentication
=== Authorization Request ===
This flow redirects the user to Microsoft 365 to log in and are then brought back to Moodle logged in.

Using this flow:
# 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.
# The user is redirected to Microsoft 365 to log in.
# Once successfully logged in, the user is redirected back to Moodle where the Moodle login takes place transparently.
=== Username/Password Authentication ===
This login flow works like a classic username and password, except the user uses their Microsoft 365 account information.

Using this flow:
# The user enters their Microsoft 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Microsoft 365 for verification.
# If the credentials are verified, the user is logged in to Moodle.
== Switching existing Moodle users to use Microsoft 365 to log in ==
If a user logs in to Moodle using OpenID Connect but does not have a Moodle account, one will be created for them. However, existing Moodle users can be migrated to use OpenID Connect and provide a connection to Microsoft 365.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# Click the '''Microsoft 365 Login'' link under '''Microsoft 365 Features'''
# Click the "Start using Microsoft 365 to log in to Moodle." link.
# You will be redirected to Microsoft 365 to log in. Log in with the account you'd like to link to the Moodle account you're using.
## '''NOTE:''' If you're already logged in to Microsoft 365, you will not have to enter your credentials on the Microsoft 365 login page. This Microsoft 365 account will be linked to the Moodle account. Ensure you are logged in to the correct account, or log out of Microsoft 365 first to show the Microsoft 365 login screen.
# The Moodle account will now use Microsoft 365 to log in. '''The previous login method will not work.'''
# The Moodle user can now use any of the Microsoft 365 features in Moodle.
== Connecting existing Moodle users to Microsoft 365 without changing login method ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# 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 Microsoft 365 user's credentials you'd like to connect to the Moodle user you are logged in as.
## '''NOTE:''' If you're already logged in to Microsoft 365, you will not have to enter your credentials on the Microsoft 365 login page. This Microsoft 365 account will be linked to the Moodle account. Ensure you are logged in to the correct account, or log out of Microsoft 365 first to show the Microsoft 365 login screen.
# If login was successful, you will be brought back to the '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# The Moodle account is now linked to the Microsoft 365 account and can use Microsoft 365 features as that user.
# The Moodle user's login method will not change, the user will log in to Moodle as they always have.
= OneDrive for Business Repository =
The OneDrive for Business repository allows users using the Microsoft 365 integration plugins to connect to their OneDrive for Business as a Moodle repository.
== Downloading and linking files ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".
== 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.
# When accessing a OneDrive document library from a file picker, you will see an "Upload New File" item in the list of files and folders.
# Click the "Upload new file" item.
# Choose the file you want to upload and click "Upload this file".
# The file will be uploaded to OneDrive and selected for the file picker.
== 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.
# Start as a user connected to Microsoft 365 and who has access to modify a course.
# Turn on editing for the course and choose "Add an activity or resource" for the section of the course you want to add the document.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# You should see the file embedded into the page.
= OneNote =
OneNote is now available through Microsoft 365. If you have installed all the plugins (for example, by installing [https://moodle.org/plugins/view/local_office365]) then you already have the OneNote plugins installed. To access OneNote using your Microsoft 365 subscription, add OneNote to the list of applications in your Azure application. This is done the same way you configured Azure permissions, above. Note that OneNote is still in preview, and may not be available to everyone yet. If you don't see OneNote in the list of applications to add to your Azure application, you can try logging in to a desktop OneNote application using an administrator account in your Microsoft 365 tenant. This sometimes expedites to the process of adding the OneNote preview to your tenant.
= Notes on special release =
== 3.8.0.4 and 3.9.1 release==
3.8.0.4 and 3.9.1 release of the plugins on 29 September 2020 introduced improvements on SSO integration for Moodle in Teams as well as Single Sign Off support, but requires additional actions from Moodle and Azure admins.
=== Moodle and Teams SSO integration ===
The new releases is capable of getting a user token from either Teams desktop/mobile app or Teams web app, and attempt to log in as the user in the Moodle Teams tab. In order for it to work, changes in 3 sections are required.
==== Update Azure app settings ====
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Microsoft 365 integration, and click its name.
# Under '''Manage''', select '''Expose an API'''.
# Select the "Set" link to generate the Application ID URI in the form of api://{AppID}. Insert your fully qualified domain name (with a forward slash "/" appended to the end) between the double forward slashes and the GUID. The entire ID should have the form of: api://fully-qualified-domain-name.com/{AppID}. e.g. api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000.
# If you get errors when selecting the "Set" link, it may be because the '''Supported account types''' setting of your app is set to a value rather than the one with "single tenant". Try updating this value to get it working.
# Select the "Add a scope" button. In the panel that opens:
## enter "access_as_user" as the "Scope name".
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to be "Teams can access the user’s profile".
## Set "Admin consent description" to be "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to be "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to be "Enable Teams to call this app’s APIs with the same rights as the user".
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
# In the Authorized client applications section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
## 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
## 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Under '''Manage''' then '''API permissions''', ensure the following permissions are added under "Microsoft Graph" > "Delegated permissions":
## User.Read (enabled by default)
## email
## offline_access
## OpenId
## profile
# Under '''Manage''' then '''Authentication''', ensure the following boxes are checked for "implicit grant":
## ID Token
## Access Token.
==== Download updated manifest file ====
# Login to Moodle as site administrator.
# Go to "Microsoft 365 Integration" page in the site admin section.
# Go to "Teams Settings" tab.
# Verify settings on the page, note that two new settings are added in this release:
## '''Microsoft app ID for the Moodle Teams app''': This is used in the "ID" field of [https://docs.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema Teams app manifest file], which is essentially a self generated app ID to identify itself. It should be set to the default value in most use cases, otherwise it may affect upgrading of the Teams app. The only scenario a custom value is to be set for this setting is when there are multiple Moodle sites in the organisation, and they all need to be integrated with Teams, thus each site will require a separate Teams app. If custom value is required, please use [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7 powershell] or [https://www.guidgenerator.com/ external tools] to generate valid ones.
## '''Teams app name''': This allows you to give a custom name, rather than the default "Moodle", to the Moodle Teams app created. It can be useful if you have multiple Moodle sites in your organisation, and each creating a separate Moodle app for Teams integration.
# Once settings are verified, save changes, go back to the tab, and click the "Download manifest file" button to download the new manifest file for the upgraded app.
==== Update Moodle app in Teams ====
# As a tenant admin, go to Teams.
# Go to "Apps" page to manage apps.
# From the menu on the left, click on the link "Built for YOUR ORGANISATION". This should list all custom apps uploaded for your tenant.
# Locate the previous Moodle app, click the options button on the card for more options, and click "update". This should open a file picker.
# Select the new manifest file downloaded from Moodle.
Note that as long as the '''Microsoft app ID for the Moodle Teams app''' setting is not changed, this should be recognised as an app upgrade, rather than uploading a new app. This means that the app will be kept in all existing Teams that have it installed, and all existing Moodle tabs will keep working.
=== Single Sign Off ===
When a Microsoft 365 authenticated user clicks the Moodle log out button, it is possible to log the user out from Microsoft 365 at the same time.

In order for this to work, configuration changes in two places are required:
==== Moodle settings change ====
# Sign in Moodle as site admin.
# Go to "OpenID Connect" settings page under Plugins - Authentication:
# Go to "Advanced" tab.
# Enable "Single sign off".
# Save changes.
==== Azure app settings change ====
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Microsoft 365 integration, and click its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the root URL of your Moodle site (wwwroot) as an entry.
== 3.8.0.5 and 3.9.2 release==
3.8.0.5 and 3.9.2 release of the plugins on 18 November 2020 added support for synching the default timezone preference of the user in Outlook to Moodle. This requires the following permissions to be granted for the Azure app.
* If your Moodle site uses '''Application access''' connection method, you will need to add and grant '''MailboxSettings.Read application permission'''.
* If your Moodle site uses '''System API User''' connection method, you will need to add and grant '''MailboxSettings.Read delegated permission'''.

== Teams integration known limitations ==

* If the Moodle site is not publicly accessible, e.g. on a intranet, Moodle tabs will not work in Teams desktop and mobile apps. They will only work in web apps from browser.

* It is a known issue that if a Microsoft 365 user has never login to Moodle ever, the first attempt of the user to SSO from Teams to Moodle will not work silently. Instead, the user will need to click a button from the prompt to login.

=Any further questions?=
For support, please open an issue on Github at [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.

Microsoft 365

2021-07-29T11:49:04Z

Enovationdevteam:

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams https://moodle.org/plugins/assignsubmission_onenote https://moodle.org/plugins/assignfeedback_onenote
|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 =
Microsoft 365 services complement the Moodle learning platform to provide a more productive experience for teachers and students.
== Differences from Moodle Core ==
Although Moodle core now provides Microsoft 365 authentication and basic OneDrive repository support, the Microsoft 365 plugin suite provides a much wider set of features.

A few key features only found in the Microsoft 365 plugin suite:
* User sync from Microsoft 365/Azure AD to Moodle
* Automatic and manual user matching from Microsoft 365/Azure AD to Moodle
* Calendar sync
* Course to Microsoft 365 group/teams sync and shared file repositories
* OneNote assignment submission and feedback types
* Office document embedding using Office web apps
* Fully customizable sign-in experience
= Requirements =
To use the Microsoft 365 plugins, you need the following:
* A Microsoft 365 subscription.
* A Microsoft Azure subscription.
* Moodle version 3.5 or above. The plugins are available for Moodle versions 2.7 and above. Features available in each version, and the support status vary.
= Plugins & Features =
The Microsoft 365 set of plugins contains 6 core plugins, and 3 optional plugins, which provide a wide variety of features to enhance your Moodle instance.
* '''Microsoft 365 Local Plugin''' (local_office365)
** This is a shell plugin which has dependencies on the current version of each of the 5 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''OpenID Connect Authentication Plugin''' (auth_oidc)
** This plugin allows users to log in to Moodle using their Microsoft 365 accounts.
** Users with existing Moodle accounts can switch to using this authentication type, and new users can log in with this plugin and have an account created for them.
** If the administrator allows, users can also choose to disconnect from OpenID Connect and revert their previous login method, or to a username/password.
** Features:
*** Standards-Compliant OpenID Connect Authentication.
*** Supports authorization code or resource-owner credentials grants.
**** Users can log in to Moodle by clicking the identity provider on the login page, or by entering their OpenID Connect credentials.
*** User profile field mapping
**** User profiles can be mapped and synced from IdP to Moodle.
*** Customizable Icon + Identity Provider name
**** The icon and identity provider name shown on the Moodle login page can be customized. A number of prechosen icons are available, as well as the ability to upload your own.
*** Provides hooks to link OpenID Connect accounts to Moodle accounts
**** If you do not want to change your users' login method, you can still connect to an OpenID Connect provider. The plugin provides code-level hooks to link a Moodle account to an OpenID Connect account without changing the Moodle user's authentication method. This means you can obtain tokens from an OpenID Connect service in the background.
*** Optional user-self-service connection and disconnection
**** A user-facing page is available for users to switch to and from OpenID Connect authentication. Access to this page and feature is controlled by a capability so administrators can disable it.
* '''Microsoft 365 support plugin''' (local_o365)
** This plugin provides most of the Microsoft 365 integration back-end. It provides shared code to communicate with Microsoft 365, and powers the calendar sync.
** Features:
*** Calendar sync from/to Outlook.
**** Users can sync site events, course events, assignment due dates, and their personal Moodle calendar to their Outlook calendar.
*** User Sync and Matching
**** Users can be synced from Azure AD, or matched with existing users.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Microsoft 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Microsoft 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features:
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.
* '''Microsoft 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
== Optional Plugins ==
These 3 plugins provide support for OneNote assignment submission and feedback. While they are not required, they provide a powerful way to submit and review assignments.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.
== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =
== Installation ==
The packages are available from:
* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Microsoft 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle
When you log back in to your Moodle instance, you are presented with the all the plugin configuration options. Save the settings without configuring them for now, you will come back to them later.

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

To use Moodle with Microsoft 365 for SSO, you must configure Microsoft Azure to manage your Microsoft 365 Microsoft Azure Active Directory. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

You should only follow the manual process if you are unable to setup the AzureAd app via PowerShell script, or you need to verify some specific settings.
==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.
===== Configure application =====
# Locate the App.
#* If you followed steps above to create the Azure app, you should be redirected to the app settings page already.
#* Otherwise:
#*# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
#*# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
#*# Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
#*# Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
#*# Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires".
## Click '''Add'''.
## A value will appear under '''Value''', note this value (write it down or copy it somewhere) and set it aside. You'll need it later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the '''Set''' link next to '''Application ID URI'''.
## This should open a '''Set the APP ID URI''' prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://'''URL.TO.MOODLE'''/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click '''Save''' to create the Application ID URI.
## Click '''Add a scope'''.
## Enter '''access_as_user''' as scope name.
## Set '''Who can consent?''' to '''Admins and users'''.
## Set '''Admin consent title''' to '''Teams can access the user’s profile'''.
## Set '''Admin consent description''' to '''Allows Teams to call the app’s web APIs as the current user'''.
## Set '''User consent title''' to '''Teams can access the user profile and make requests on the user's behalf'''.
## Set '''User consent description''' to '''Enable Teams to call this app’s APIs with the same rights as the user'''.
## Ensure that '''State''' is set to be '''Enabled'''.
## Select the '''Add scope''' button to save.
## In the '''Authorized client applications''' section, identify the applications that you want to authorize for your app’s web application. Select '''Add a client application'''. Enter each of the following client IDs and select the authorized scope you created in the previous step:
##* '''<code>1fec8e78-bce4-4aaf-ab1b-5451cc387264</code>''' (Teams mobile/desktop application)
##* '''<code>5e3ce6c0-2b1f-4285-8d4b-75ee78787346</code>''' (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose '''Microsoft Graph'''.
## Click the checkbox for the following permissions in each of the '''Application''' and '''Delegated''' permissions sections according to the section below.
## After all the permissions are added, click the '''Grant admin consent for YOUR ORGANISATION NAME''' link.
## When you're done, click '''Add permissions''' at bottom of the page.
===== Azure app permissions =====
The integration uses various [https://docs.microsoft.com/en-us/graph/overview Microsoft Graph APIs] to communicate with Microsoft 365 to get and set data. Each Graph API would require a different set of app permissions. The integration provides a list of recommended permissions to be given to ensure all features in the integration works, all of which are added automatically by the PowerShell script if it's used. Advanced users can customise the permissions according to the need of their own organisation, e.g. if group/team integration is not used, all permissions related to group can be removed, e.g. Group.ReadWrite.All.
====== Application permissions vs delegated permissions ======
In general, if the Moodle site uses the '''Application access''' connection method, giving only application permissions would be enough; if the Moodle site uses the '''System API user''' connection method, only delegated permission are required.

Note the following exception:
* '''User.Read''' delegated permission is always required regardless of connection method.
* If teams integration feature is used, the following delegated permissions are required for teams SSO to work, regardless of connection method:
** '''openid'''
** '''offline_access'''
** '''email'''
** '''profile'''
* As of release 3.9.6 and 3.10.3 release of the plugins in June 2021, there are a small number of Microsoft Graph APIs used in the integration making calls to the "/me/" path, which would require the corresponding delegated permissions regardless of connection method. A plan is in place to replace calls like this in the next release, so that these delegated permissions can be removed. The delegated permissions affected are:
** '''Calendars.ReadWrite''' for calendar sync.
** '''Sites.Read.All''' and '''Files.ReadWrite.All''' for OneDrive integration.
** '''Notes.ReadWrite.All''' for OneNote integration.
====== Permissions ======
For a full list of Microsoft Graph API used, and the permissions required, please refer to [https://docs.google.com/spreadsheets/d/1XIFnnQ8RuFjlPGB8CiiMmK8x9Uta9XIR_icvAdx0G6k this spreadsheet]. Note that:
* This document is constantly updated.
* For each Graph API, a few permissions may be listed. Graph API can be called if permissions in any line is added, and the admin consent is granted for your organisation.

The recommended permissions to ensure all integration features work are listed below. These would be the same set of permissions that are applied when using the PowerShell script to set up the Azure app.
{| class="wikitable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="10" | Application Permissions
|'''Directory.ReadWrite.All'''
|'''Read and write directory data'''
| A common permission used in both user syncs and group integration.
|-
|'''Directory.Read.All'''
|'''Read directory data'''
| A common permission used in both user syncs and group integration.
|-
|'''Group.ReadWrite.All'''
|'''Read and write all groups'''
| Required for course group/team integration.
|-
|'''User.Read.All'''
|'''Read all users' full profiles'''
| Required for SSO and to sync user information between Microsoft 365 and Moodle.
|-
|'''Files.ReadWrite.All'''
|'''Read and write files in all site collections'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
|'''Calendars.ReadWrite'''
|'''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
|'''Sites.Read.All'''
|'''Read items in all site collections'''
|Required to detect OneDrive for Business URL setting.
|-
|'''Notes.ReadWrite.All'''
|'''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
|-
|'''MailboxSettings.Read'''
|'''Read all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
|-
|'''AppRoleAssignment.ReadWrite.All'''
|'''Manage app permission grants and app role assignments'''
| Required for assigning users to application during user sync if the option is enabled.
|-
| rowspan="16" |Delegated Permissions
|'''Directory.ReadWrite.All'''
|'''Read and write directory data'''
| A common permission used in both user syncs and group integration.
|-
|'''Directory.Read.All'''
|'''Read directory data'''
| A common permission used in both user syncs and group integration.
|-
|'''Group.ReadWrite.All'''
|'''Read and write all groups'''
| Required for course group integration.
|-
|'''User.Read.All'''
|'''Read all users' full profiles'''
|Required for SSO and to sync user information between Microsoft 365 and Moodle.
|-
|'''Files.ReadWrite.All'''
|'''Have full access to all files user can access'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
|'''Calendars.ReadWrite'''
|'''Have full access to user calendars'''
| Required for calendar event sync.
|-
|'''Sites.Read.All'''
|'''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
|'''Notes.ReadWrite.All'''
|'''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
|'''AppRoleAssignment.ReadWrite.All'''
|'''Manage app permission grants and app role assignments'''
|Required for assigning users to application during user sync if the option is enabled.
|-
|'''MailboxSettings.Read'''
|'''Read user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
|'''User.Read'''
|'''Sign-in and read user profile'''
| Required to sign users in using Microsoft 365, and to access Microsoft 365 APIs.
|-
|'''openid'''
|'''Sign users in'''
| Required for Teams SSO.
|-
|'''offline_access'''
|'''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
|'''email'''
|'''View users' email address'''
| Required for Teams SSO.
|-
|'''profile'''
|'''View users' basic profile'''
| Required for Teams SSO.
|}
=== Enter Azure application credentials into Moodle ===
# 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 Microsoft 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## Choose the method you want to use to connect to Microsoft 365. Unless you have a special reason to use the System API user, choose '''Application access'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''Admin consent:''' Every time you change a '''Requires admin''' permission in Azure, you will need an administrator to provide consent to use the permission. Clicking the '''Provide admin consent''' button will take you to a log in screen on Microsoft 365. An administrator will have to log in, and then will be given the option to approve the new permissions.
## '''Azure AD Tenant:''' This is the domain name that identifies your Microsoft 365 subscription, for example "contoso.onmicrosoft.com". If you know it, enter it in this box, if not, click the "Detect" button to attempt to detect the correct value.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.
== Connecting users to Microsoft 365 ==
To use any Microsoft 365 features, a Moodle user must be connected to a Microsoft 365 user that has an active Microsoft 365 subscription. There are two ways to connect a Moodle user to a Microsoft 365 user.
=== Switch the user to use OpenID Connect authentication. ===
With this method, the user will log in to Moodle using their Microsoft 365 account credentials.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].
=== Link a Moodle user to a Microsoft 365 user. ===
Users in Moodle can also be linked to Microsoft 365 users without changing the Moodle user's authentication method. Users will be able to log in as they always have, and still use all the Microsoft 365 features.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Microsoft 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# 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 Microsoft 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 '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# This user is now connected to the Microsoft 365 user.
= Microsoft 365 Integration Local Plugin =
== Sync Settings ==
These features are accessible from the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft 365 Integration), on the '''Sync Settings''' tab.
=== User Sync ===
This option controls how users are synced from Azure AD to Moodle. If enabled, users from Azure AD can be automatically created in Moodle. This feature can also delete users in Moodle when they are deleted from Azure AD, or attempt to automatically match Moodle users with users in the connected Azure AD.

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

'''Notes:'''
* The sync job runs in the Moodle cron, and syncs 1000 users at a time.
* By default, this runs once per day at 1:00 AM in the time zone local to your server.
* To sync large sets of users more quickly, you can increase the freqency of the Sync users with Azure AD task using the Scheduled tasks management page. See [[Scheduled_tasks]].
There are several options that affect user sync:
* '''Create accounts in Moodle for users in Azure AD''': This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their Microsoft 365 credentials to log in to Moodle (using the OpenID Connect authentication plugin), and will be able to use all the features of the Microsoft 365 plugin set.
* '''Update all accounts in Moodle for users in Azure AD''': This will update all users in Moodle from each user in the linked Azure AD.
* '''Delete previously synced accounts in Moodle when they are deleted from Azure AD''': This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!
* '''Match preexisting Moodle users with same-named accounts in Azure AD''': This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are insensitive and ignore the Microsoft 365 tenant. For example, "BoB.SmiTh" in Moodle would match "bob.smith@example.onmicrosoft.com". Users who are matched will have their Moodle and Office accounts connected and will be able to use all Microsoft 365/Moodle integration features. The user's authentication method will not change unless the setting below is enabled.
* '''Switch matched users to Microsoft 365 (OpenID Connect) authentication''': This requires the "Match" setting above to be enabled. When a user is matched, enabling this setting will switch their authentication method to OpenID Connect. They will then log in to Moodle with their Microsoft 365 credentials. Note: Please ensure the OpenID Connect authentication plugin is enabled if you want to use this setting.
* '''Assign users to application during sync''': The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.
* '''Sync Microsoft 365 profile photos to Moodle in cron job''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.
* '''Sync Microsoft 365 profile photos to Moodle on login''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.
* '''Perform a full sync each run''': By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
* '''Match Azure usernames to Moodle emails instead of Moodle usernames during the sync''': Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.
====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.
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.
=== Teams Sync ===
The Teams sync setting creates teams in Microsoft Teams for courses in Moodle. Teams creation effectively results in team members being added to a Microsoft 365 group, enabling all group features to be usable.

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

Once enabled, new Teams will be created every cron run for any enabled course that doesn't have a team set up. Once Teams are set up, membership will be maintained automatically whenever someone joins or leaves a Moodle course.
==== Teams vs Group ====
Microsoft Teams share the same base with Microsoft 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to a Microsoft 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Microsoft 365 user, only a group will be created.
== Advanced settings ==
=== Administrator Tools ===
* '''Tenants''': This tool allows you to add additional Microsoft 365 tenants to be used with Moodle. Users from additional tenants can log-in to Moodle using their Microsoft 365 account, and use features like calendar sync and the OneDrive repository.
* '''Health check''': If you are experiencing problems with any Microsoft 365 / Moodle features, click the '''Health Check''' link to run tests on your system and look for potential problems.
* '''Connections''': This tool allows administrators to see and manage the connections between their Moodle users and Microsoft 365 accounts. Each user in the system is listed alongside the Microsoft 365 username the user is connected to, if any. Administrators can choose to manually connect or disconnect each user.
* '''User Matching''': This tool allows administrators to manually match Moodle and Microsoft 365 users using a CSV file. Administrators can upload a CSV file containing, on each line, a Moodle username, and Microsoft 365 username, and a 1 or 0 indicating whether to enable Microsoft 365 login for that user. Once uploaded, the file is processed in batches during the Moodle cron. The tool page will display the progress of this process.
* '''Maintenance Tools''': These tools perform maintenance tasks that can help solve problems which may crop up from time to time. Generally, users should not need these tools unless they encounter the specific situation these tools are designed to solve.
**'''Resync users in groups for courses''': Course group membership is kept up-to-date as users are enrolled and un-enrolled from courses in Moodle. If this membership gets out-of-date for whatever reason, this tool will force a resync of group membership.
** '''Recreate deleted Microsoft 365 groups''': Course groups are created from Moodle courses when using the course group feature. If a group is manually deleted from the Microsoft 365 administrator panel, this tool will recreate it.
** '''Generate debug data package''': This tool will generate a package of information that can be sent to the plugin suite maintainers to help debug problems in environment and setup. While no API keys are present, this information does contain a lot about your environment and setup, so please be careful about who you send this information to.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Microsoft 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.
===Other advanced settings===
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Microsoft 365 as well.
* '''Microsoft 365 for China''': Microsoft 365 in China differs slightly in some technical aspects. If you are using Microsoft 365 for China, select this box to ensure everything will work properly.
* '''Record debug messages''': If you experience problems using any Microsoft 365 features in Moodle, enable this setting. Once enabled, errors will be recorded to the Moodle log for review. These errors can help you or the plugin developers debug and fix the problem. The error log can be viewed by navigating to Site Administration > Reports > Logs, changing the "All activities" select box to "Site errors", and clicking "Get these logs".
* '''Minimum inexact username length to switch to Microsoft 365''': When using automatic user matching, this setting can be used to exclude accounts with short names. The intended use of this is to avoid matching generic accounts like "admin". This setting is the minimum length of a username required for automatic matching to match users.
* '''Profile photo refresh time''': Profile photo syncing can be a resource-intensive process, so this setting allows you to set a minimum time between profile photo refresh runs.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.
===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''
===Preview features===
From time-to-time, we add features that use brand-new APIs or are slightly experimental in some way. These features often become part of our regular feature offering once they mature, but if you want to see the latest features we're working on, you can enable this setting to enable all preview features. Be careful though! These features do break from time to time.
==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.
===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Microsoft 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Microsoft 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.
=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.
=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.
=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.
==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Save changes.
=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.
== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.
To configure the field, follow these steps:
# Log in Teams, and go to app catalog by clicking the '''Apps''' button from the navigation bar on the left.
# Find the '''Moodle''' app uploaded.
# Click the option icon of the app, which is located at the top right corner of the app image.
# Click '''Copy link'''.
# In a text editor, paste the copied content. It should contain an URL such as https://teams.microsoft.com/l/app/00112233-4455-6677-8899-aabbccddeeff.
# The last part of the URL, i.e. 00112233-4455-6677-8899-aabbccddeeff, is the app ID.
# Paste the app ID in the '''Moodle app ID''' setting on '''Teams Moodle app''' tab of '''Microsoft 365 Integration''' configuration page in Moodle.
# Save changes.
= OpenID Connect Authentication Plugin =
== Basic Usage ==
Once configured, you should see a link named "OpenID Connect" on the Moodle login page. Clicking this link will redirect the browser to the identity provider. Users will log in there, and will be redirected back to Moodle. If they have logged in to Moodle using OpenID Connect before, they will be logged in to their existing Moodle account. If they have not logged in to Moodle with OpenID Connect before, an account will be created for them.

Note: If the "Prevent account creation when authenticating" setting is enabled in Moodle, new accounts will not be created.
== Settings ==
There are a number of options you can use to customize how the plugin behaves. To configure the plugin, visit the plugin's settings page. (Site Administration > Plugins > Authentication > OpenID Connect)
====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the Microsoft 365 plugins to refer to the system used to log users in. For example, if your users are used to calling their Azure AD account their "School" account, you enter "School account" here, and all references to authentication will be "Log in with your School account".
====Auto-Append====
When using the "Username/Password" login flow, this setting with automatically append a given string to an entered username. This is useful in Azure AD usernames, where a single domain name is often used for every user - i.e. [user]@contoso.onmicrosoft.com. Users would normally have to enter this entire username to successfully log in to Moodle, but in this example, entering "@contoso.onmicrosoft.com" here means users would only have to enter their unique username, i.e. "bob.smith", instead of "bob.smith@contoso.onmicrosoft.com".
====Domain Hint====
If users have several different Azure AD accounts with different tenants (i.e. @contoso.onmicrosoft.com, @example.onmicrosoft.com), but Moodle only uses one of these tenants, you can enter that tenant in this box to have the Azure AD login screen only ever suggest accounts from that tenant.
====Login Flow====
This setting changes how users log in to Moodle using the plugin. You can redirect users to the OpenID Connect provider's login page, or have users enter their credentials directly into Moodle. See the "Login Flows" section below for further information.
====User Restrictions====
This setting allows you to restrict the users that can log in to Moodle using OpenID Connect (Azure AD).

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

How to use user restrictions:
# 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.
== Login flows ==
This plugin supports two different methods for users to log in: Authorization Request and Username/Password Authentication
=== Authorization Request ===
This flow redirects the user to Microsoft 365 to log in and are then brought back to Moodle logged in.

Using this flow:
# 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.
# The user is redirected to Microsoft 365 to log in.
# Once successfully logged in, the user is redirected back to Moodle where the Moodle login takes place transparently.
=== Username/Password Authentication ===
This login flow works like a classic username and password, except the user uses their Microsoft 365 account information.

Using this flow:
# The user enters their Microsoft 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Microsoft 365 for verification.
# If the credentials are verified, the user is logged in to Moodle.
== Switching existing Moodle users to use Microsoft 365 to log in ==
If a user logs in to Moodle using OpenID Connect but does not have a Moodle account, one will be created for them. However, existing Moodle users can be migrated to use OpenID Connect and provide a connection to Microsoft 365.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# Click the '''Microsoft 365 Login'' link under '''Microsoft 365 Features'''
# Click the "Start using Microsoft 365 to log in to Moodle." link.
# You will be redirected to Microsoft 365 to log in. Log in with the account you'd like to link to the Moodle account you're using.
## '''NOTE:''' If you're already logged in to Microsoft 365, you will not have to enter your credentials on the Microsoft 365 login page. This Microsoft 365 account will be linked to the Moodle account. Ensure you are logged in to the correct account, or log out of Microsoft 365 first to show the Microsoft 365 login screen.
# The Moodle account will now use Microsoft 365 to log in. '''The previous login method will not work.'''
# The Moodle user can now use any of the Microsoft 365 features in Moodle.
== Connecting existing Moodle users to Microsoft 365 without changing login method ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# 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 Microsoft 365 user's credentials you'd like to connect to the Moodle user you are logged in as.
## '''NOTE:''' If you're already logged in to Microsoft 365, you will not have to enter your credentials on the Microsoft 365 login page. This Microsoft 365 account will be linked to the Moodle account. Ensure you are logged in to the correct account, or log out of Microsoft 365 first to show the Microsoft 365 login screen.
# If login was successful, you will be brought back to the '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# The Moodle account is now linked to the Microsoft 365 account and can use Microsoft 365 features as that user.
# The Moodle user's login method will not change, the user will log in to Moodle as they always have.
= OneDrive for Business Repository =
The OneDrive for Business repository allows users using the Microsoft 365 integration plugins to connect to their OneDrive for Business as a Moodle repository.
== Downloading and linking files ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".
== 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.
# When accessing a OneDrive document library from a file picker, you will see an "Upload New File" item in the list of files and folders.
# Click the "Upload new file" item.
# Choose the file you want to upload and click "Upload this file".
# The file will be uploaded to OneDrive and selected for the file picker.
== 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.
# Start as a user connected to Microsoft 365 and who has access to modify a course.
# Turn on editing for the course and choose "Add an activity or resource" for the section of the course you want to add the document.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# You should see the file embedded into the page.
= OneNote =
OneNote is now available through Microsoft 365. If you have installed all the plugins (for example, by installing [https://moodle.org/plugins/view/local_office365]) then you already have the OneNote plugins installed. To access OneNote using your Microsoft 365 subscription, add OneNote to the list of applications in your Azure application. This is done the same way you configured Azure permissions, above. Note that OneNote is still in preview, and may not be available to everyone yet. If you don't see OneNote in the list of applications to add to your Azure application, you can try logging in to a desktop OneNote application using an administrator account in your Microsoft 365 tenant. This sometimes expedites to the process of adding the OneNote preview to your tenant.
= Notes on special release =
== 3.8.0.4 and 3.9.1 release==
3.8.0.4 and 3.9.1 release of the plugins on 29 September 2020 introduced improvements on SSO integration for Moodle in Teams as well as Single Sign Off support, but requires additional actions from Moodle and Azure admins.
=== Moodle and Teams SSO integration ===
The new releases is capable of getting a user token from either Teams desktop/mobile app or Teams web app, and attempt to log in as the user in the Moodle Teams tab. In order for it to work, changes in 3 sections are required.
==== Update Azure app settings ====
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Microsoft 365 integration, and click its name.
# Under '''Manage''', select '''Expose an API'''.
# Select the "Set" link to generate the Application ID URI in the form of api://{AppID}. Insert your fully qualified domain name (with a forward slash "/" appended to the end) between the double forward slashes and the GUID. The entire ID should have the form of: api://fully-qualified-domain-name.com/{AppID}. e.g. api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000.
# If you get errors when selecting the "Set" link, it may be because the '''Supported account types''' setting of your app is set to a value rather than the one with "single tenant". Try updating this value to get it working.
# Select the "Add a scope" button. In the panel that opens:
## enter "access_as_user" as the "Scope name".
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to be "Teams can access the user’s profile".
## Set "Admin consent description" to be "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to be "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to be "Enable Teams to call this app’s APIs with the same rights as the user".
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
# In the Authorized client applications section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
## 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
## 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Under '''Manage''' then '''API permissions''', ensure the following permissions are added under "Microsoft Graph" > "Delegated permissions":
## User.Read (enabled by default)
## email
## offline_access
## OpenId
## profile
# Under '''Manage''' then '''Authentication''', ensure the following boxes are checked for "implicit grant":
## ID Token
## Access Token.
==== Download updated manifest file ====
# Login to Moodle as site administrator.
# Go to "Microsoft 365 Integration" page in the site admin section.
# Go to "Teams Settings" tab.
# Verify settings on the page, note that two new settings are added in this release:
## '''Microsoft app ID for the Moodle Teams app''': This is used in the "ID" field of [https://docs.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema Teams app manifest file], which is essentially a self generated app ID to identify itself. It should be set to the default value in most use cases, otherwise it may affect upgrading of the Teams app. The only scenario a custom value is to be set for this setting is when there are multiple Moodle sites in the organisation, and they all need to be integrated with Teams, thus each site will require a separate Teams app. If custom value is required, please use [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7 powershell] or [https://www.guidgenerator.com/ external tools] to generate valid ones.
## '''Teams app name''': This allows you to give a custom name, rather than the default "Moodle", to the Moodle Teams app created. It can be useful if you have multiple Moodle sites in your organisation, and each creating a separate Moodle app for Teams integration.
# Once settings are verified, save changes, go back to the tab, and click the "Download manifest file" button to download the new manifest file for the upgraded app.
==== Update Moodle app in Teams ====
# As a tenant admin, go to Teams.
# Go to "Apps" page to manage apps.
# From the menu on the left, click on the link "Built for YOUR ORGANISATION". This should list all custom apps uploaded for your tenant.
# Locate the previous Moodle app, click the options button on the card for more options, and click "update". This should open a file picker.
# Select the new manifest file downloaded from Moodle.
Note that as long as the '''Microsoft app ID for the Moodle Teams app''' setting is not changed, this should be recognised as an app upgrade, rather than uploading a new app. This means that the app will be kept in all existing Teams that have it installed, and all existing Moodle tabs will keep working.
==== Known limitations ====
It is a known issue that if a Microsoft 365 user has never login to Moodle either, her first attempt to SSO from Teams to Moodle will not work silently. Instead, the user will need to click a button from the prompt to login.
=== Single Sign Off ===
When a Microsoft 365 authenticated user clicks the Moodle log out button, it is possible to log the user out from Microsoft 365 at the same time.

In order for this to work, configuration changes in two places are required:
==== Moodle settings change ====
# Sign in Moodle as site admin.
# Go to "OpenID Connect" settings page under Plugins - Authentication:
# Go to "Advanced" tab.
# Enable "Single sign off".
# Save changes.
==== Azure app settings change ====
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Microsoft 365 integration, and click its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the root URL of your Moodle site (wwwroot) as an entry.
== 3.8.0.5 and 3.9.2 release==
3.8.0.5 and 3.9.2 release of the plugins on 18 November 2020 added support for synching the default timezone preference of the user in Outlook to Moodle. This requires the following permission to be granted for the Azure app:
# '''Delegated permissions'''
## '''MailboxSettings.Read'''
## '''MailboxSettings.ReadWrite'''
# '''Application permissions'''
## '''MailboxSettings.Read'''
## '''MailboxSettings.ReadWrite'''
=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.

Microsoft 365

2021-04-21T11:11:17Z

Enovationdevteam:

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams https://moodle.org/plugins/assignsubmission_onenote https://moodle.org/plugins/assignfeedback_onenote
|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 =
Microsoft 365 services complement the Moodle learning platform to provide a more productive experience for teachers and students.
== Differences from Moodle Core ==
Although Moodle core now provides Microsoft 365 authentication and basic OneDrive repository support, the Microsoft 365 plugin suite provides a much wider set of features.

A few key features only found in the Microsoft 365 plugin suite:
* User sync from Microsoft 365/Azure AD to Moodle
* Automatic and manual user matching from Microsoft 365/Azure AD to Moodle
* Calendar sync
* Course to Microsoft 365 group 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 Microsoft 365 plugins, you need the following:
* A Microsoft 365 subscription.
* A Microsoft Azure subscription.
* Moodle version 3.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Microsoft 365 set of plugins contains 5 core plugins, and 4 optional plugins, which provide a wide variety of features to enhance your Moodle instance.

* '''Microsoft 365 Local Plugin''' (local_office365)
** This is a shell plugin which has dependencies on the current version of each of the 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''OpenID Connect Authentication Plugin''' (auth_oidc)
** This plugin allows users to log in to Moodle using their Microsoft 365 accounts.
** Users with existing Moodle accounts can switch to using this authentication 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.
* '''Microsoft 365 support plugin''' (local_o365)
** This plugin provides most of the Microsoft 365 integration back-end. It provides shared code to communicate with Microsoft 365, and powers the calendar sync.
** Features
*** Calendar sync from/to Outlook.
**** Users can sync site events, course events, assignment due dates, and their personal Moodle calendar to their Outlook calendar.
*** User Sync and Matching
**** Users can be synced from Azure AD, or matched with existing users.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Microsoft 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Microsoft 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Microsoft 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Microsoft 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### This domain name does not need to be publicly accessible (i.e. internet-wide), but does need to be accessible to users of your Moodle instance. So, for example, you can use a intranet-only domain name.

=== Prepare your Microsoft 365 account for single sign-on with your Moodle installation ===
You will need an Azure subscription. If you do not have one, you can create one by visiting [http://azure.microsoft.com/en-us/pricing/free-trial/ Microsoft Azure Sign Up].

To use Moodle with Microsoft 365 for SSO, you must configure Microsoft Azure to manage your Microsoft 365 Microsoft Azure Active Directory. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need it later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="9" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Microsoft 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Microsoft 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
|-
| '''MailboxSettings.Read'''
| '''Read all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
|-
| '''MailboxSettings.ReadWrite'''
| '''Read and write all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| rowspan="16" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Microsoft 365, and to access Microsoft 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Microsoft 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Microsoft 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''MailboxSettings.Read'''
| '''Read user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| '''MailboxSettings.ReadWrite'''
| '''Read and write user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Microsoft 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Microsoft 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## Choose the method you want to use to connect to Microsoft 365. Unless you have a special reason to use the System API user, choose '''Application access'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''Admin consent:''' Every time you change a '''Requires admin''' permission in Azure, you will need an administrator to provide consent to use the permission. Clicking the '''Provide admin consent''' button will take you to a log in screen on Microsoft 365. An administrator will have to log in, and then will be given the option to approve the new permissions.
## '''Azure AD Tenant:''' This is the domain name that identifies your Microsoft 365 subscription, for example "contoso.onmicrosoft.com". If you know it, enter it in this box, if not, click the "Detect" button to attempt to detect the correct value.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

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

=== Switch the user to use OpenID Connect authentication ===
With this method, the user will log in to Moodle using their Microsoft 365 account credentials.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== Link a Moodle user to a Microsoft 365 user===
Users in Moodle can also be linked to Microsoft 365 users without changing the Moodle user's authentication method. Users will be able to log in as they always have, and still use all the Microsoft 365 features.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Microsoft 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# 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 Microsoft 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 '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# This user is now connected to the Microsoft 365 user.

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

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

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

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

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

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.

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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Microsoft 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to a Microsoft 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Microsoft 365 user, only a group will be created.

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

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

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Microsoft 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Microsoft 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

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

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

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

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

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

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

How to use user restrictions:
# 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

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

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

Using this flow:
# 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.
# The user is redirected to Microsoft 365 to log in.
# Once successfully logged in, the user is redirected back to Moodle where the Moodle login takes place transparently.

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

Using this flow:
# The user enters their Microsoft 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Microsoft 365 for verification.
# If the credentials are verified, the user is logged in to Moodle.

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

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

== Connecting existing Moodle users to Microsoft 365 without changing login method ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# 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 Microsoft 365 user's credentials you'd like to connect to the Moodle user you are logged in as.
## '''NOTE:''' If you're already logged in to Microsoft 365, you will not have to enter your credentials on the Microsoft 365 login page. This Microsoft 365 account will be linked to the Moodle account. Ensure you are logged in to the correct account, or log out of Microsoft 365 first to show the Microsoft 365 login screen.
# If login was successful, you will be brought back to the '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# The Moodle account is now linked to the Microsoft 365 account and can use Microsoft 365 features as that user.
# The Moodle user's login method will not change, the user will log in to Moodle as they always have.

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

== Downloading and linking files ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# Start as a user connected to Microsoft 365 and who has access to modify a course.
# Turn on editing for the course and choose "Add an activity or resource" for the section of the course you want to add the document.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# You should see the file embedded into the page.

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

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

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

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

==== Download updated manifest file ====
# Login to Moodle as site administrator.
# Go to "Microsoft 365 Integration" page in the site admin section.
# Go to "Teams Settings" tab.
# Verify settings on the page, note that two new settings are added in this release:
## '''Microsoft app ID for the Moodle Teams app''': This is used in the "ID" field of [https://docs.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema Teams app manifest file], which is essentially a self generated app ID to identify itself. It should be set to the default value in most use cases, otherwise it may affect upgrading of the Teams app. The only scenario a custom value is to be set for this setting is when there are multiple Moodle sites in the organisation, and they all need to be integrated with Teams, thus each site will require a separate Teams app. If custom value is required, please use [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7 powershell] or [https://www.guidgenerator.com/ external tools] to generate valid ones.
## '''Teams app name''': This allows you to give a custom name, rather than the default "Moodle", to the Moodle Teams app created. It can be useful if you have multiple Moodle sites in your organisation, and each creating a separate Moodle app for Teams integration.
# Once settings are verified, save changes, go back to the tab, and click the "Download manifest file" button to download the new manifest file for the upgraded app.
==== Update Moodle app in Teams ====
# As a tenant admin, go to Teams.
# Go to "Apps" page to manage apps.
# From the menu on the left, click on the link "Built for YOUR ORGANISATION". This should list all custom apps uploaded for your tenant.
# Locate the previous Moodle app, click the options button on the card for more options, and click "update". This should open a file picker.
# Select the new manifest file downloaded from Moodle.
Note that as long as the '''Microsoft app ID for the Moodle Teams app''' setting is not changed, this should be recognised as an app upgrade, rather than uploading a new app. This means that the app will be kept in all existing Teams that have it installed, and all existing Moodle tabs will keep working.

==== Known limitations ====
It is a known issue that if a Microsoft 365 user has never login to Moodle either, her first attempt to SSO from Teams to Moodle will not work silently. Instead, the user will need to click a button from the prompt to login.

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

In order for this to work, configuration changes in two places are required:
==== Moodle settings change ====
# Sign in Moodle as site admin.
# Go to "OpenID Connect" settings page under Plugins - Authentication:
# Enable "Single sign off".
# Save changes.
==== Azure app settings change ====
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Microsoft 365 integration, and click its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the root URL of your Moodle site (wwwroot) as an entry.

== 3.8.0.5 and 3.9.2 release==
3.8.0.5 and 3.9.2 release of the plugins on 18 November 2020 added support for synching the default timezone preference of the user in Outlook to Moodle. This requires the following permission to be granted for the Azure app:
# '''Delegated permissions'''
## '''MailboxSettings.Read'''
## '''MailboxSettings.ReadWrite'''
# '''Application permissions'''
## '''MailboxSettings.Read'''
## '''MailboxSettings.ReadWrite'''

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

Microsoft 365

2021-02-01T11:01:17Z

Enovationdevteam:

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams https://moodle.org/plugins/assignsubmission_onenote https://moodle.org/plugins/assignfeedback_onenote
|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 =
Microsoft 365 services complement the Moodle learning platform to provide a more productive experience for teachers and students.
== Differences from Moodle Core ==
Although Moodle core now provides Microsoft 365 authentication and basic OneDrive repository support, the Microsoft 365 plugin suite provides a much wider set of features.

A few key features only found in the Microsoft 365 plugin suite:
* User sync from Microsoft 365/Azure AD to Moodle
* Automatic and manual user matching from Microsoft 365/Azure AD to Moodle
* Calendar sync
* Course to Microsoft 365 group 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 Microsoft 365 plugins, you need the following:
* A Microsoft 365 subscription.
* A Microsoft Azure subscription.
* Moodle version 3.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Microsoft 365 set of plugins contains 5 core plugins, and 4 optional plugins, which provide a wide variety of features to enhance your Moodle instance.

* '''Microsoft 365 Local Plugin''' (local_office365)
** This is a shell plugin which has dependencies on the current version of each of the 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''OpenID Connect Authentication Plugin''' (auth_oidc)
** This plugin allows users to log in to Moodle using their Microsoft 365 accounts.
** Users with existing Moodle accounts can switch to using this authentication 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.
* '''Microsoft 365 support plugin''' (local_o365)
** This plugin provides most of the Microsoft 365 integration back-end. It provides shared code to communicate with Microsoft 365, and powers the calendar sync.
** Features
*** Calendar sync from/to Outlook.
**** Users can sync site events, course events, assignment due dates, and their personal Moodle calendar to their Outlook calendar.
*** User Sync and Matching
**** Users can be synced from Azure AD, or matched with existing users.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Microsoft 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Microsoft 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Microsoft 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Microsoft 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### This domain name does not need to be publicly accessible (i.e. internet-wide), but does need to be accessible to users of your Moodle instance. So, for example, you can use a intranet-only domain name.

=== Prepare your Microsoft 365 account for single sign-on with your Moodle installation ===
You will need an Azure subscription. If you do not have one, you can create one by visiting [http://azure.microsoft.com/en-us/pricing/free-trial/ Microsoft Azure Sign Up].

To use Moodle with Microsoft 365 for SSO, you must configure Microsoft Azure to manage your Microsoft 365 Microsoft Azure Active Directory. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need it later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="9" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Microsoft 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Microsoft 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
|-
| '''MailboxSettings.Read'''
| '''Read all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
|-
| '''MailboxSettings.ReadWrite'''
| '''Read and write all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| rowspan="16" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Microsoft 365, and to access Microsoft 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Microsoft 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Microsoft 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''MailboxSettings.Read'''
| '''Read user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| '''MailboxSettings.ReadWrite'''
| '''Read and write user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Microsoft 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Microsoft 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## Choose the method you want to use to connect to Microsoft 365. Unless you have a special reason to use the System API user, choose '''Application access'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''Admin consent:''' Every time you change a '''Requires admin''' permission in Azure, you will need an administrator to provide consent to use the permission. Clicking the '''Provide admin consent''' button will take you to a log in screen on Microsoft 365. An administrator will have to log in, and then will be given the option to approve the new permissions.
## '''Azure AD Tenant:''' This is the domain name that identifies your Microsoft 365 subscription, for example "contoso.onmicrosoft.com". If you know it, enter it in this box, if not, click the "Detect" button to attempt to detect the correct value.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

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

=== Switch the user to use OpenID Connect authentication ===
With this method, the user will log in to Moodle using their Microsoft 365 account credentials.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== Link a Moodle user to a Microsoft 365 user===
Users in Moodle can also be linked to Microsoft 365 users without changing the Moodle user's authentication method. Users will be able to log in as they always have, and still use all the Microsoft 365 features.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Microsoft 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# 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 Microsoft 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 '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# This user is now connected to the Microsoft 365 user.

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

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

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

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

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

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.

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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Microsoft 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to a Microsoft 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Microsoft 365 user, only a group will be created.

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

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

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Microsoft 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Microsoft 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

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

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

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

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

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

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

How to use user restrictions:
# 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

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

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

Using this flow:
# 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.
# The user is redirected to Microsoft 365 to log in.
# Once successfully logged in, the user is redirected back to Moodle where the Moodle login takes place transparently.

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

Using this flow:
# The user enters their Microsoft 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Microsoft 365 for verification.
# If the credentials are verified, the user is logged in to Moodle.

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

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

== Connecting existing Moodle users to Microsoft 365 without changing login method ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# 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 Microsoft 365 user's credentials you'd like to connect to the Moodle user you are logged in as.
## '''NOTE:''' If you're already logged in to Microsoft 365, you will not have to enter your credentials on the Microsoft 365 login page. This Microsoft 365 account will be linked to the Moodle account. Ensure you are logged in to the correct account, or log out of Microsoft 365 first to show the Microsoft 365 login screen.
# If login was successful, you will be brought back to the '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# The Moodle account is now linked to the Microsoft 365 account and can use Microsoft 365 features as that user.
# The Moodle user's login method will not change, the user will log in to Moodle as they always have.

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

== Downloading and linking files ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# Start as a user connected to Microsoft 365 and who has access to modify a course.
# Turn on editing for the course and choose "Add an activity or resource" for the section of the course you want to add the document.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# You should see the file embedded into the page.

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

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

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

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

==== Download updated manifest file ====
# Login to Moodle as site administrator.
# Go to "Microsoft 365 Integration" page in the site admin section.
# Go to "Teams Settings" tab.
# Verify settings on the page, note that two new settings are added in this release:
## '''Microsoft app ID for the Moodle Teams app''': This is used in the "ID" field of [https://docs.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema Teams app manifest file], which is essentially a self generated app ID to identify itself. It should be set to the default value in most use cases, otherwise it may affect upgrading of the Teams app. The only scenario a custom value is to be set for this setting is when there are multiple Moodle sites in the organisation, and they all need to be integrated with Teams, thus each site will require a separate Teams app. If custom value is required, please use [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7 powershell] or [https://www.guidgenerator.com/ external tools] to generate valid ones.
## '''Teams app name''': This allows you to give a custom name, rather than the default "Moodle", to the Moodle Teams app created. It can be useful if you have multiple Moodle sites in your organisation, and each creating a separate Moodle app for Teams integration.
# Once settings are verified, save changes, go back to the tab, and click the "Download manifest file" button to download the new manifest file for the upgraded app.
==== Update Moodle app in Teams ====
# As a tenant admin, go to Teams.
# Go to "Apps" page to manage apps.
# From the menu on the left, click on the link "Built for YOUR ORGANISATION". This should list all custom apps uploaded for your tenant.
# Locate the previous Moodle app, click the options button on the card for more options, and click "update". This should open a file picker.
# Select the new manifest file downloaded from Moodle.
Note that as long as the '''Microsoft app ID for the Moodle Teams app''' setting is not changed, this should be recognised as an app upgrade, rather than uploading a new app. This means that the app will be kept in all existing Teams that have it installed, and all existing Moodle tabs will keep working.

==== Known limitations ====
It is a known issue that if a Microsoft 365 user has never login to Moodle either, her first attempt to SSO from Teams to Moodle will not work silently. Instead, the user will need to click a button from the prompt to login.

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

In order for this to work, configuration changes in two places are required:
==== Moodle settings change ====
# Sign in Moodle as site admin.
# Go to "Microsoft 365 Integration" page in the site admin section.
# Go to "Advanced" tab.
# Enable "Single sign off".
# Save changes.
==== Azure app settings change ====
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Microsoft 365 integration, and click its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the root URL of your Moodle site (wwwroot) as an entry.

== 3.8.0.5 and 3.9.2 release==
3.8.0.5 and 3.9.2 release of the plugins on 18 November 2020 added support for synching the default timezone preference of the user in Outlook to Moodle. This requires the following permission to be granted for the Azure app:
# '''Delegated permissions'''
## '''MailboxSettings.Read'''
## '''MailboxSettings.ReadWrite'''
# '''Application permissions'''
## '''MailboxSettings.Read'''
## '''MailboxSettings.ReadWrite'''

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

Microsoft365

2021-01-29T17:00:06Z

Enovationdevteam: Redirected page to Microsoft 365

#redirect [[Microsoft_365]]

Microsoft 365

2021-01-29T16:54:59Z

Enovationdevteam:

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams https://moodle.org/plugins/assignsubmission_onenote https://moodle.org/plugins/assignfeedback_onenote
|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 =
Microsoft 365 services complement the Moodle learning platform to provide a more productive experience for teachers and students.
== Differences from Moodle Core ==
Although Moodle core now provides Microsoft 365 authentication and basic OneDrive repository support, the Microsoft 365 plugin suite provides a much wider set of features.

A few key features only found in the Microsoft 365 plugin suite:
* User sync from Microsoft 365/Azure AD to Moodle
* Automatic and manual user matching from Microsoft 365/Azure AD to Moodle
* Calendar sync
* Course to Microsoft 365 group 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 Microsoft 365 plugins, you need the following:
* A Microsoft 365 subscription.
* A Microsoft Azure subscription.
* Moodle version 3.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Microsoft 365 set of plugins contains 5 core plugins, and 4 optional plugins, which provide a wide variety of features to enhance your Moodle instance.

* '''Microsoft 365 Local Plugin''' (local_office365)
** This is a shell plugin which has dependencies on the current version of each of the 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''OpenID Connect Authentication Plugin''' (auth_oidc)
** This plugin allows users to log in to Moodle using their Microsoft 365 accounts.
** Users with existing Moodle accounts can switch to using this authentication 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.
* '''Microsoft 365 support plugin''' (local_o365)
** This plugin provides most of the Microsoft 365 integration back-end. It provides shared code to communicate with Microsoft 365, and powers the calendar sync.
** Features
*** Calendar sync from/to Outlook.
**** Users can sync site events, course events, assignment due dates, and their personal Moodle calendar to their Outlook calendar.
*** User Sync and Matching
**** Users can be synced from Azure AD, or matched with existing users.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Microsoft 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Microsoft 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Microsoft 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Microsoft 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### This domain name does not need to be publicly accessible (i.e. internet-wide), but does need to be accessible to users of your Moodle instance. So, for example, you can use a intranet-only domain name.

=== Prepare your Microsoft 365 account for single sign-on with your Moodle installation ===
You will need an Azure subscription. If you do not have one, you can create one by visiting [http://azure.microsoft.com/en-us/pricing/free-trial/ Microsoft Azure Sign Up].

To use Moodle with Microsoft 365 for SSO, you must configure Microsoft Azure to manage your Microsoft 365 Microsoft Azure Active Directory. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need it later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="9" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Microsoft 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Microsoft 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
|-
| '''MailboxSettings.Read'''
| '''Read all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
|-
| '''MailboxSettings.ReadWrite'''
| '''Read and write all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| rowspan="16" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Microsoft 365, and to access Microsoft 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Microsoft 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Microsoft 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''MailboxSettings.Read'''
| '''Read user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| '''MailboxSettings.ReadWrite'''
| '''Read and write user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Microsoft 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Microsoft 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## Choose the method you want to use to connect to Microsoft 365. Unless you have a special reason to use the System API user, choose '''Application access'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''Admin consent:''' Every time you change a '''Requires admin''' permission in Azure, you will need an administrator to provide consent to use the permission. Clicking the '''Provide admin consent''' button will take you to a log in screen on Microsoft 365. An administrator will have to log in, and then will be given the option to approve the new permissions.
## '''Azure AD Tenant:''' This is the domain name that identifies your Microsoft 365 subscription, for example "contoso.onmicrosoft.com". If you know it, enter it in this box, if not, click the "Detect" button to attempt to detect the correct value.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

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

=== Switch the user to use OpenID Connect authentication ===
With this method, the user will log in to Moodle using their Microsoft 365 account credentials.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== Link a Moodle user to a Microsoft 365 user===
Users in Moodle can also be linked to Microsoft 365 users without changing the Moodle user's authentication method. Users will be able to log in as they always have, and still use all the Microsoft 365 features.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Microsoft 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# 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 Microsoft 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 '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# This user is now connected to the Microsoft 365 user.

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

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

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

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

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

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.

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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Microsoft 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to a Microsoft 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Microsoft 365 user, only a group will be created.

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

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

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Microsoft 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Microsoft 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

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

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

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

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

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

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

How to use user restrictions:
# 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

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

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

Using this flow:
# 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.
# The user is redirected to Microsoft 365 to log in.
# Once successfully logged in, the user is redirected back to Moodle where the Moodle login takes place transparently.

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

Using this flow:
# The user enters their Microsoft 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Microsoft 365 for verification.
# If the credentials are verified, the user is logged in to Moodle.

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

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

== Connecting existing Moodle users to Microsoft 365 without changing login method ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# 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 Microsoft 365 user's credentials you'd like to connect to the Moodle user you are logged in as.
## '''NOTE:''' If you're already logged in to Microsoft 365, you will not have to enter your credentials on the Microsoft 365 login page. This Microsoft 365 account will be linked to the Moodle account. Ensure you are logged in to the correct account, or log out of Microsoft 365 first to show the Microsoft 365 login screen.
# If login was successful, you will be brought back to the '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# The Moodle account is now linked to the Microsoft 365 account and can use Microsoft 365 features as that user.
# The Moodle user's login method will not change, the user will log in to Moodle as they always have.

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

== Downloading and linking files ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# Start as a user connected to Microsoft 365 and who has access to modify a course.
# Turn on editing for the course and choose "Add an activity or resource" for the section of the course you want to add the document.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# You should see the file embedded into the page.

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

= Notes on special release =
== 3.8.0.4 and 3.9.1 release==
3.8.0.4 and 3.9.1 release of the plugins on 29 September 2020 introduced improvements on SSO integration for Moodle in Teams as well as Single Sign Off support, but requires additional actions from Moodle and Azure admins.
=== Moodle and Teams SSO integration ===
The new releases is capable of getting a user token from either Teams desktop/mobile app or Teams web app, and attempt to log in as the user in the Moodle Teams tab. In order for it to work, changes in 3 sections are required.
==== Download updated manifest file ====
# Login to Moodle as site administrator.
# Go to "Microsoft 365 Integration" page in the site admin section.
# Go to "Teams Settings" tab.
# Verify settings on the page, note that two new settings are added in this release:
## '''Microsoft app ID for the Moodle Teams app''': This is used in the "ID" field of [https://docs.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema Teams app manifest file], which is essentially a self generated app ID to identify itself. It should be set to the default value in most use cases, otherwise it may affect upgrading of the Teams app. The only scenario a custom value is to be set for this setting is when there are multiple Moodle sites in the organisation, and they all need to be integrated with Teams, thus each site will require a separate Teams app. If custom value is required, please use [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7 powershell] or [https://www.guidgenerator.com/ external tools] to generate valid ones.
## '''Teams app name''': This allows you to give a custom name, rather than the default "Moodle", to the Moodle Teams app created. It can be useful if you have multiple Moodle sites in your organisation, and each creating a separate Moodle app for Teams integration.
# Once settings are verified, save changes, go back to the tab, and click the "Download manifest file" button to download the new manifest file for the upgraded app.
==== Update Moodle app in Teams ====
# As a tenant admin, go to Teams.
# Go to "Apps" page to manage apps.
# From the menu on the left, click on the link "Built for YOUR ORGANISATION". This should list all custom apps uploaded for your tenant.
# Locate the previous Moodle app, click the options button on the card for more options, and click "update". This should open a file picker.
# Select the new manifest file downloaded from Moodle.
Note that as long as the '''Microsoft app ID for the Moodle Teams app''' setting is not changed, this should be recognised as an app upgrade, rather than uploading a new app. This means that the app will be kept in all existing Teams that have it installed, and all existing Moodle tabs will keep working.
==== Update Azure app settings ====
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Microsoft 365 integration, and click its name.
# Under '''Manage''', select '''Expose an API'''.
# Select the "Set" link to generate the Application ID URI in the form of api://{AppID}. Insert your fully qualified domain name (with a forward slash "/" appended to the end) between the double forward slashes and the GUID. The entire ID should have the form of: api://fully-qualified-domain-name.com/{AppID}. e.g. api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000.
# If you get errors when selecting the "Set" link, it may be because the '''Supported account types''' setting of your app is set to a value rather than the one with "single tenant". Try updating this value to get it working.
# Select the "Add a scope" button. In the panel that opens:
## enter "access_as_user" as the "Scope name".
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to be "Teams can access the user’s profile".
## Set "Admin consent description" to be "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to be "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to be "Enable Teams to call this app’s APIs with the same rights as the user".
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
# In the Authorized client applications section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
## 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
## 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Under '''Manage''' then '''API permissions''', ensure the following permissions are added under "Microsoft Graph" > "Delegated permissions":
## User.Read (enabled by default)
## email
## offline_access
## OpenId
## profile
# Under '''Manage''' then '''Authentication''', ensure the following boxes are checked for "implicit grant":
## ID Token
## Access Token.

==== Known limitations ====
It is a known issue that if an Microsoft 365 user has never login to Moodle either, her first attempt to SSO from Teams to Moodle will not work silently. Instead, the user will need to click a button from the prompt to login.

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

In order for this to work, configuration changes in two places are required:
==== Moodle settings change ====
# Sign in Moodle as site admin.
# Go to "Microsoft 365 Integration" page in the site admin section.
# Go to "Advanced" tab.
# Enable "Single sign off".
# Save changes.
==== Azure app settings change ====
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Microsoft 365 integration, and click its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the root URL of your Moodle site (wwwroot) as an entry.

== 3.8.0.5 and 3.9.2 release==
3.8.0.5 and 3.9.2 release of the plugins on 18 November 2020 added support for synching the default timezone preference of the user in Outlook to Moodle. This requires the following permission to be granted for the Azure app:
# '''Delegated permissions'''
## '''MailboxSettings.Read'''
## '''MailboxSettings.ReadWrite'''
# '''Application permissions'''
## '''MailboxSettings.Read'''
## '''MailboxSettings.ReadWrite'''

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

Office365

2021-01-29T16:52:07Z

Enovationdevteam: Redirected page to Microsoft 365

#redirect [[Microsoft_365]]

Microsoft 365

2021-01-29T16:51:11Z

Enovationdevteam: Created page with "{{Infobox plugin |type = set |set=https://moodle.org/plugins/browse.php?list=set&id=72 |entry = https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o3..."

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
Microsoft 365 services complement the Moodle learning platform to provide a more productive experience for teachers and students.
== Differences from Moodle Core ==
Although Moodle core now provides Microsoft 365 authentication and basic OneDrive repository support, the Microsoft 365 plugin suite provides a much wider set of features.

A few key features only found in the Microsoft 365 plugin suite:
* User sync from Microsoft 365/Azure AD to Moodle
* Automatic and manual user matching from Microsoft 365/Azure AD to Moodle
* Calendar sync
* Course to Microsoft 365 group 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 Microsoft 365 plugins, you need the following:
* A Microsoft 365 subscription.
* A Microsoft Azure subscription.
* Moodle version 3.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Microsoft 365 set of plugins contains 5 core plugins, and 4 optional plugins, which provide a wide variety of features to enhance your Moodle instance.

* '''Microsoft 365 Local Plugin''' (local_office365)
** This is a shell plugin which has dependencies on the current version of each of the 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''OpenID Connect Authentication Plugin''' (auth_oidc)
** This plugin allows users to log in to Moodle using their Microsoft 365 accounts.
** Users with existing Moodle accounts can switch to using this authentication 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.
* '''Microsoft 365 support plugin''' (local_o365)
** This plugin provides most of the Microsoft 365 integration back-end. It provides shared code to communicate with Microsoft 365, and powers the calendar sync.
** Features
*** Calendar sync from/to Outlook.
**** Users can sync site events, course events, assignment due dates, and their personal Moodle calendar to their Outlook calendar.
*** User Sync and Matching
**** Users can be synced from Azure AD, or matched with existing users.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Microsoft 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Microsoft 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Microsoft 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Microsoft 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### This domain name does not need to be publicly accessible (i.e. internet-wide), but does need to be accessible to users of your Moodle instance. So, for example, you can use a intranet-only domain name.

=== Prepare your Microsoft 365 account for single sign-on with your Moodle installation ===
You will need an Azure subscription. If you do not have one, you can create one by visiting [http://azure.microsoft.com/en-us/pricing/free-trial/ Microsoft Azure Sign Up].

To use Moodle with Microsoft 365 for SSO, you must configure Microsoft Azure to manage your Microsoft 365 Microsoft Azure Active Directory. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need it later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="9" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Microsoft 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Microsoft 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
|-
| '''MailboxSettings.Read'''
| '''Read all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
|-
| '''MailboxSettings.ReadWrite'''
| '''Read and write all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| rowspan="16" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Microsoft 365, and to access Microsoft 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Microsoft 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Microsoft 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''MailboxSettings.Read'''
| '''Read user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| '''MailboxSettings.ReadWrite'''
| '''Read and write user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Microsoft 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Microsoft 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## Choose the method you want to use to connect to Microsoft 365. Unless you have a special reason to use the System API user, choose '''Application access'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''Admin consent:''' Every time you change a '''Requires admin''' permission in Azure, you will need an administrator to provide consent to use the permission. Clicking the '''Provide admin consent''' button will take you to a log in screen on Microsoft 365. An administrator will have to log in, and then will be given the option to approve the new permissions.
## '''Azure AD Tenant:''' This is the domain name that identifies your Microsoft 365 subscription, for example "contoso.onmicrosoft.com". If you know it, enter it in this box, if not, click the "Detect" button to attempt to detect the correct value.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

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

=== Switch the user to use OpenID Connect authentication ===
With this method, the user will log in to Moodle using their Microsoft 365 account credentials.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== Link a Moodle user to a Microsoft 365 user===
Users in Moodle can also be linked to Microsoft 365 users without changing the Moodle user's authentication method. Users will be able to log in as they always have, and still use all the Microsoft 365 features.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Microsoft 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# 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 Microsoft 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 '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# This user is now connected to the Microsoft 365 user.

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

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

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

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

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

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.

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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Microsoft 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to a Microsoft 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Microsoft 365 user, only a group will be created.

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

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

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Microsoft 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Microsoft 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

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

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

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

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

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

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

How to use user restrictions:
# 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

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

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

Using this flow:
# 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.
# The user is redirected to Microsoft 365 to log in.
# Once successfully logged in, the user is redirected back to Moodle where the Moodle login takes place transparently.

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

Using this flow:
# The user enters their Microsoft 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Microsoft 365 for verification.
# If the credentials are verified, the user is logged in to Moodle.

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

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

== Connecting existing Moodle users to Microsoft 365 without changing login method ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# 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 Microsoft 365 user's credentials you'd like to connect to the Moodle user you are logged in as.
## '''NOTE:''' If you're already logged in to Microsoft 365, you will not have to enter your credentials on the Microsoft 365 login page. This Microsoft 365 account will be linked to the Moodle account. Ensure you are logged in to the correct account, or log out of Microsoft 365 first to show the Microsoft 365 login screen.
# If login was successful, you will be brought back to the '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# The Moodle account is now linked to the Microsoft 365 account and can use Microsoft 365 features as that user.
# The Moodle user's login method will not change, the user will log in to Moodle as they always have.

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

== Downloading and linking files ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# Start as a user connected to Microsoft 365 and who has access to modify a course.
# Turn on editing for the course and choose "Add an activity or resource" for the section of the course you want to add the document.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# You should see the file embedded into the page.

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

= Notes on special release =
== 3.8.0.4 and 3.9.1 release==
3.8.0.4 and 3.9.1 release of the plugins on 29 September 2020 introduced improvements on SSO integration for Moodle in Teams as well as Single Sign Off support, but requires additional actions from Moodle and Azure admins.
=== Moodle and Teams SSO integration ===
The new releases is capable of getting a user token from either Teams desktop/mobile app or Teams web app, and attempt to log in as the user in the Moodle Teams tab. In order for it to work, changes in 3 sections are required.
==== Download updated manifest file ====
# Login to Moodle as site administrator.
# Go to "Microsoft 365 Integration" page in the site admin section.
# Go to "Teams Settings" tab.
# Verify settings on the page, note that two new settings are added in this release:
## '''Microsoft app ID for the Moodle Teams app''': This is used in the "ID" field of [https://docs.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema Teams app manifest file], which is essentially a self generated app ID to identify itself. It should be set to the default value in most use cases, otherwise it may affect upgrading of the Teams app. The only scenario a custom value is to be set for this setting is when there are multiple Moodle sites in the organisation, and they all need to be integrated with Teams, thus each site will require a separate Teams app. If custom value is required, please use [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7 powershell] or [https://www.guidgenerator.com/ external tools] to generate valid ones.
## '''Teams app name''': This allows you to give a custom name, rather than the default "Moodle", to the Moodle Teams app created. It can be useful if you have multiple Moodle sites in your organisation, and each creating a separate Moodle app for Teams integration.
# Once settings are verified, save changes, go back to the tab, and click the "Download manifest file" button to download the new manifest file for the upgraded app.
==== Update Moodle app in Teams ====
# As a tenant admin, go to Teams.
# Go to "Apps" page to manage apps.
# From the menu on the left, click on the link "Built for YOUR ORGANISATION". This should list all custom apps uploaded for your tenant.
# Locate the previous Moodle app, click the options button on the card for more options, and click "update". This should open a file picker.
# Select the new manifest file downloaded from Moodle.
Note that as long as the '''Microsoft app ID for the Moodle Teams app''' setting is not changed, this should be recognised as an app upgrade, rather than uploading a new app. This means that the app will be kept in all existing Teams that have it installed, and all existing Moodle tabs will keep working.
==== Update Azure app settings ====
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Microsoft 365 integration, and click its name.
# Under '''Manage''', select '''Expose an API'''.
# Select the "Set" link to generate the Application ID URI in the form of api://{AppID}. Insert your fully qualified domain name (with a forward slash "/" appended to the end) between the double forward slashes and the GUID. The entire ID should have the form of: api://fully-qualified-domain-name.com/{AppID}. e.g. api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000.
# If you get errors when selecting the "Set" link, it may be because the '''Supported account types''' setting of your app is set to a value rather than the one with "single tenant". Try updating this value to get it working.
# Select the "Add a scope" button. In the panel that opens:
## enter "access_as_user" as the "Scope name".
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to be "Teams can access the user’s profile".
## Set "Admin consent description" to be "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to be "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to be "Enable Teams to call this app’s APIs with the same rights as the user".
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
# In the Authorized client applications section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
## 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
## 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Under '''Manage''' then '''API permissions''', ensure the following permissions are added under "Microsoft Graph" > "Delegated permissions":
## User.Read (enabled by default)
## email
## offline_access
## OpenId
## profile
# Under '''Manage''' then '''Authentication''', ensure the following boxes are checked for "implicit grant":
## ID Token
## Access Token.

==== Known limitations ====
It is a known issue that if an Microsoft 365 user has never login to Moodle either, her first attempt to SSO from Teams to Moodle will not work silently. Instead, the user will need to click a button from the prompt to login.

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

In order for this to work, configuration changes in two places are required:
==== Moodle settings change ====
# Sign in Moodle as site admin.
# Go to "Microsoft 365 Integration" page in the site admin section.
# Go to "Advanced" tab.
# Enable "Single sign off".
# Save changes.
==== Azure app settings change ====
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Microsoft 365 integration, and click its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the root URL of your Moodle site (wwwroot) as an entry.

== 3.8.0.5 and 3.9.2 release==
3.8.0.5 and 3.9.2 release of the plugins on 18 November 2020 added support for synching the default timezone preference of the user in Outlook to Moodle. This requires the following permission to be granted for the Azure app:
# '''Delegated permissions'''
## '''MailboxSettings.Read'''
## '''MailboxSettings.ReadWrite'''
# '''Application permissions'''
## '''MailboxSettings.Read'''
## '''MailboxSettings.ReadWrite'''

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

Office365

2021-01-29T16:50:39Z

Enovationdevteam:

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
Microsoft 365 services complement the Moodle learning platform to provide a more productive experience for teachers and students.
== Differences from Moodle Core ==
Although Moodle core now provides Microsoft 365 authentication and basic OneDrive repository support, the Microsoft 365 plugin suite provides a much wider set of features.

A few key features only found in the Microsoft 365 plugin suite:
* User sync from Microsoft 365/Azure AD to Moodle
* Automatic and manual user matching from Microsoft 365/Azure AD to Moodle
* Calendar sync
* Course to Microsoft 365 group 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 Microsoft 365 plugins, you need the following:
* A Microsoft 365 subscription.
* A Microsoft Azure subscription.
* Moodle version 3.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Microsoft 365 set of plugins contains 5 core plugins, and 4 optional plugins, which provide a wide variety of features to enhance your Moodle instance.

* '''Microsoft 365 Local Plugin''' (local_office365)
** This is a shell plugin which has dependencies on the current version of each of the 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''OpenID Connect Authentication Plugin''' (auth_oidc)
** This plugin allows users to log in to Moodle using their Microsoft 365 accounts.
** Users with existing Moodle accounts can switch to using this authentication 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.
* '''Microsoft 365 support plugin''' (local_o365)
** This plugin provides most of the Microsoft 365 integration back-end. It provides shared code to communicate with Microsoft 365, and powers the calendar sync.
** Features
*** Calendar sync from/to Outlook.
**** Users can sync site events, course events, assignment due dates, and their personal Moodle calendar to their Outlook calendar.
*** User Sync and Matching
**** Users can be synced from Azure AD, or matched with existing users.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Microsoft 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Microsoft 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Microsoft 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Microsoft 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### This domain name does not need to be publicly accessible (i.e. internet-wide), but does need to be accessible to users of your Moodle instance. So, for example, you can use a intranet-only domain name.

=== Prepare your Microsoft 365 account for single sign-on with your Moodle installation ===
You will need an Azure subscription. If you do not have one, you can create one by visiting [http://azure.microsoft.com/en-us/pricing/free-trial/ Microsoft Azure Sign Up].

To use Moodle with Microsoft 365 for SSO, you must configure Microsoft Azure to manage your Microsoft 365 Microsoft Azure Active Directory. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need it later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="9" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Microsoft 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Microsoft 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
|-
| '''MailboxSettings.Read'''
| '''Read all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
|-
| '''MailboxSettings.ReadWrite'''
| '''Read and write all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| rowspan="16" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Microsoft 365, and to access Microsoft 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Microsoft 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Microsoft 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''MailboxSettings.Read'''
| '''Read user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| '''MailboxSettings.ReadWrite'''
| '''Read and write user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Microsoft 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Microsoft 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## Choose the method you want to use to connect to Microsoft 365. Unless you have a special reason to use the System API user, choose '''Application access'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''Admin consent:''' Every time you change a '''Requires admin''' permission in Azure, you will need an administrator to provide consent to use the permission. Clicking the '''Provide admin consent''' button will take you to a log in screen on Microsoft 365. An administrator will have to log in, and then will be given the option to approve the new permissions.
## '''Azure AD Tenant:''' This is the domain name that identifies your Microsoft 365 subscription, for example "contoso.onmicrosoft.com". If you know it, enter it in this box, if not, click the "Detect" button to attempt to detect the correct value.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

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

=== Switch the user to use OpenID Connect authentication ===
With this method, the user will log in to Moodle using their Microsoft 365 account credentials.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== Link a Moodle user to a Microsoft 365 user===
Users in Moodle can also be linked to Microsoft 365 users without changing the Moodle user's authentication method. Users will be able to log in as they always have, and still use all the Microsoft 365 features.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Microsoft 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# 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 Microsoft 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 '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# This user is now connected to the Microsoft 365 user.

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

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

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

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

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

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.

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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Microsoft 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to a Microsoft 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Microsoft 365 user, only a group will be created.

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

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

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Microsoft 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Microsoft 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

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

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

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

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

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

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

How to use user restrictions:
# 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

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

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

Using this flow:
# 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.
# The user is redirected to Microsoft 365 to log in.
# Once successfully logged in, the user is redirected back to Moodle where the Moodle login takes place transparently.

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

Using this flow:
# The user enters their Microsoft 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Microsoft 365 for verification.
# If the credentials are verified, the user is logged in to Moodle.

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

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

== Connecting existing Moodle users to Microsoft 365 without changing login method ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# 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 Microsoft 365 user's credentials you'd like to connect to the Moodle user you are logged in as.
## '''NOTE:''' If you're already logged in to Microsoft 365, you will not have to enter your credentials on the Microsoft 365 login page. This Microsoft 365 account will be linked to the Moodle account. Ensure you are logged in to the correct account, or log out of Microsoft 365 first to show the Microsoft 365 login screen.
# If login was successful, you will be brought back to the '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# The Moodle account is now linked to the Microsoft 365 account and can use Microsoft 365 features as that user.
# The Moodle user's login method will not change, the user will log in to Moodle as they always have.

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

== Downloading and linking files ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# Start as a user connected to Microsoft 365 and who has access to modify a course.
# Turn on editing for the course and choose "Add an activity or resource" for the section of the course you want to add the document.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# You should see the file embedded into the page.

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

= Notes on special release =
== 3.8.0.4 and 3.9.1 release==
3.8.0.4 and 3.9.1 release of the plugins on 29 September 2020 introduced improvements on SSO integration for Moodle in Teams as well as Single Sign Off support, but requires additional actions from Moodle and Azure admins.
=== Moodle and Teams SSO integration ===
The new releases is capable of getting a user token from either Teams desktop/mobile app or Teams web app, and attempt to log in as the user in the Moodle Teams tab. In order for it to work, changes in 3 sections are required.
==== Download updated manifest file ====
# Login to Moodle as site administrator.
# Go to "Microsoft 365 Integration" page in the site admin section.
# Go to "Teams Settings" tab.
# Verify settings on the page, note that two new settings are added in this release:
## '''Microsoft app ID for the Moodle Teams app''': This is used in the "ID" field of [https://docs.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema Teams app manifest file], which is essentially a self generated app ID to identify itself. It should be set to the default value in most use cases, otherwise it may affect upgrading of the Teams app. The only scenario a custom value is to be set for this setting is when there are multiple Moodle sites in the organisation, and they all need to be integrated with Teams, thus each site will require a separate Teams app. If custom value is required, please use [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7 powershell] or [https://www.guidgenerator.com/ external tools] to generate valid ones.
## '''Teams app name''': This allows you to give a custom name, rather than the default "Moodle", to the Moodle Teams app created. It can be useful if you have multiple Moodle sites in your organisation, and each creating a separate Moodle app for Teams integration.
# Once settings are verified, save changes, go back to the tab, and click the "Download manifest file" button to download the new manifest file for the upgraded app.
==== Update Moodle app in Teams ====
# As a tenant admin, go to Teams.
# Go to "Apps" page to manage apps.
# From the menu on the left, click on the link "Built for YOUR ORGANISATION". This should list all custom apps uploaded for your tenant.
# Locate the previous Moodle app, click the options button on the card for more options, and click "update". This should open a file picker.
# Select the new manifest file downloaded from Moodle.
Note that as long as the '''Microsoft app ID for the Moodle Teams app''' setting is not changed, this should be recognised as an app upgrade, rather than uploading a new app. This means that the app will be kept in all existing Teams that have it installed, and all existing Moodle tabs will keep working.
==== Update Azure app settings ====
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Microsoft 365 integration, and click its name.
# Under '''Manage''', select '''Expose an API'''.
# Select the "Set" link to generate the Application ID URI in the form of api://{AppID}. Insert your fully qualified domain name (with a forward slash "/" appended to the end) between the double forward slashes and the GUID. The entire ID should have the form of: api://fully-qualified-domain-name.com/{AppID}. e.g. api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000.
# If you get errors when selecting the "Set" link, it may be because the '''Supported account types''' setting of your app is set to a value rather than the one with "single tenant". Try updating this value to get it working.
# Select the "Add a scope" button. In the panel that opens:
## enter "access_as_user" as the "Scope name".
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to be "Teams can access the user’s profile".
## Set "Admin consent description" to be "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to be "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to be "Enable Teams to call this app’s APIs with the same rights as the user".
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
# In the Authorized client applications section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
## 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
## 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Under '''Manage''' then '''API permissions''', ensure the following permissions are added under "Microsoft Graph" > "Delegated permissions":
## User.Read (enabled by default)
## email
## offline_access
## OpenId
## profile
# Under '''Manage''' then '''Authentication''', ensure the following boxes are checked for "implicit grant":
## ID Token
## Access Token.

==== Known limitations ====
It is a known issue that if an Microsoft 365 user has never login to Moodle either, her first attempt to SSO from Teams to Moodle will not work silently. Instead, the user will need to click a button from the prompt to login.

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

In order for this to work, configuration changes in two places are required:
==== Moodle settings change ====
# Sign in Moodle as site admin.
# Go to "Microsoft 365 Integration" page in the site admin section.
# Go to "Advanced" tab.
# Enable "Single sign off".
# Save changes.
==== Azure app settings change ====
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Microsoft 365 integration, and click its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the root URL of your Moodle site (wwwroot) as an entry.

== 3.8.0.5 and 3.9.2 release==
3.8.0.5 and 3.9.2 release of the plugins on 18 November 2020 added support for synching the default timezone preference of the user in Outlook to Moodle. This requires the following permission to be granted for the Azure app:
# '''Delegated permissions'''
## '''MailboxSettings.Read'''
## '''MailboxSettings.ReadWrite'''
# '''Application permissions'''
## '''MailboxSettings.Read'''
## '''MailboxSettings.ReadWrite'''

=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]]

Office365

2020-11-18T15:08:37Z

Enovationdevteam: /* 3.8.0.4 and 3.9.1 release */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [http://azure.microsoft.com/en-us/pricing/free-trial/ 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. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need it later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="9" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
|-
| '''MailboxSettings.Read'''
| '''Read all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
|-
| '''MailboxSettings.ReadWrite'''
| '''Read and write all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| rowspan="16" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''MailboxSettings.Read'''
| '''Read user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| '''MailboxSettings.ReadWrite'''
| '''Read and write user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:
* '''Create accounts in Moodle for users in Azure AD''': This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.
* '''Update all accounts in Moodle for users in Azure AD''': This will update all users in Moodle from each user in the linked Azure AD.
* '''Delete previously synced accounts in Moodle when they are deleted from Azure AD''': This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!
* '''Match preexisting Moodle users with same-named accounts in Azure AD''': This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are insensitive and ignore the 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.
* '''Assign users to application during sync''': The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.
* '''Sync Office 365 profile photos to Moodle in cron job''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.
* '''Sync Office 365 profile photos to Moodle on login''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.
* '''Perform a full sync each run''': By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
* '''Match Azure usernames to Moodle emails instead of Moodle usernames during the sync''': Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.

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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.

===Other advanced settings===
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Office 365 as well.
* '''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.
* '''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 Administration > 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.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

= Notes on special release =
== 3.8.0.4 and 3.9.1 release==
3.8.0.4 and 3.9.1 release of the plugins on 29 September 2020 introduced improvements on SSO integration for Moodle in Teams as well as Single Sign Off support, but requires additional actions from Moodle and Azure admins.
=== Moodle and Teams SSO integration ===
The new releases is capable of getting a user token from either Teams desktop/mobile app or Teams web app, and attempt to log in as the user in the Moodle Teams tab. In order for it to work, changes in 3 sections are required.
==== Download updated manifest file ====
# Login to Moodle as site administrator.
# Go to "Microsoft Office 365 Integration" page in the site admin section.
# Go to "Teams Settings" tab.
# Verify settings on the page, note that two new settings are added in this release:
## '''Microsoft app ID for the Moodle Teams app''': This is used in the "ID" field of [https://docs.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema Teams app manifest file], which is essentially a self generated app ID to identify itself. It should be set to the default value in most use cases, otherwise it may affect upgrading of the Teams app. The only scenario a custom value is to be set for this setting is when there are multiple Moodle sites in the organisation, and they all need to be integrated with Teams, thus each site will require a separate Teams app. If custom value is required, please use [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7 powershell] or [https://www.guidgenerator.com/ external tools] to generate valid ones.
## '''Teams app name''': This allows you to give a custom name, rather than the default "Moodle", to the Moodle Teams app created. It can be useful if you have multiple Moodle sites in your organisation, and each creating a separate Moodle app for Teams integration.
# Once settings are verified, save changes, go back to the tab, and click the "Download manifest file" button to download the new manifest file for the upgraded app.
==== Update Moodle app in Teams ====
# As a tenant admin, go to Teams.
# Go to "Apps" page to manage apps.
# From the menu on the left, click on the link "Built for YOUR ORGANISATION". This should list all custom apps uploaded for your tenant.
# Locate the previous Moodle app, click the options button on the card for more options, and click "update". This should open a file picker.
# Select the new manifest file downloaded from Moodle.
Note that as long as the '''Microsoft app ID for the Moodle Teams app''' setting is not changed, this should be recognised as an app upgrade, rather than uploading a new app. This means that the app will be kept in all existing Teams that have it installed, and all existing Moodle tabs will keep working.
==== Update Azure app settings ====
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Office 365 integration, and click its name.
# Under '''Manage''', select '''Expose an API'''.
# Select the "Set" link to generate the Application ID URI in the form of api://{AppID}. Insert your fully qualified domain name (with a forward slash "/" appended to the end) between the double forward slashes and the GUID. The entire ID should have the form of: api://fully-qualified-domain-name.com/{AppID}. e.g. api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000.
# If you get errors when selecting the "Set" link, it may be because the '''Supported account types''' setting of your app is set to a value rather than the one with "single tenant". Try updating this value to get it working.
# Select the "Add a scope" button. In the panel that opens:
## enter "access_as_user" as the "Scope name".
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to be "Teams can access the user’s profile".
## Set "Admin consent description" to be "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to be "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to be "Enable Teams to call this app’s APIs with the same rights as the user".
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
# In the Authorized client applications section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
## 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
## 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Under '''Manage''' then '''API permissions''', ensure the following permissions are added under "Microsoft Graph" > "Delegated permissions":
## User.Read (enabled by default)
## email
## offline_access
## OpenId
## profile
# Under '''Manage''' then '''Authentication''', ensure the following boxes are checked for "implicit grant":
## ID Token
## Access Token.

==== Known limitations ====
It is a known issue that if an Office 365 user has never login to Moodle either, her first attempt to SSO from Teams to Moodle will not work silently. Instead, the user will need to click a button from the prompt to login.

=== Single Sign Off ===
When an Office 365 authenticated user clicks the Moodle log out button, it is possible to log the user out from Office 365 at the same time.

In order for this to work, configuration changes in two places are required:
==== Moodle settings change ====
# Sign in Moodle as site admin.
# Go to "Microsoft Office 365 Integration" page in the site admin section.
# Go to "Advanced" tab.
# Enable "Single sign off".
# Save changes.
==== Azure app settings change ====
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Office 365 integration, and click its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the root URL of your Moodle site (wwwroot) as an entry.

== 3.8.0.5 and 3.9.2 release==
3.8.0.5 and 3.9.2 release of the plugins on 18 November 2020 added support for synching the default timezone preference of the user in Outlook to Moodle. This requires the following permission to be granted for the Azure app:
# '''Delegated permissions'''
## '''MailboxSettings.Read'''
## '''MailboxSettings.ReadWrite'''
# '''Application permissions'''
## '''MailboxSettings.Read'''
## '''MailboxSettings.ReadWrite'''

=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]]

Office365

2020-11-18T15:02:55Z

Enovationdevteam: /* Configure application */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [http://azure.microsoft.com/en-us/pricing/free-trial/ 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. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need it later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="9" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
|-
| '''MailboxSettings.Read'''
| '''Read all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
|-
| '''MailboxSettings.ReadWrite'''
| '''Read and write all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| rowspan="16" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''MailboxSettings.Read'''
| '''Read user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| '''MailboxSettings.ReadWrite'''
| '''Read and write user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:
* '''Create accounts in Moodle for users in Azure AD''': This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.
* '''Update all accounts in Moodle for users in Azure AD''': This will update all users in Moodle from each user in the linked Azure AD.
* '''Delete previously synced accounts in Moodle when they are deleted from Azure AD''': This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!
* '''Match preexisting Moodle users with same-named accounts in Azure AD''': This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are insensitive and ignore the 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.
* '''Assign users to application during sync''': The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.
* '''Sync Office 365 profile photos to Moodle in cron job''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.
* '''Sync Office 365 profile photos to Moodle on login''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.
* '''Perform a full sync each run''': By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
* '''Match Azure usernames to Moodle emails instead of Moodle usernames during the sync''': Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.

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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.

===Other advanced settings===
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Office 365 as well.
* '''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.
* '''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 Administration > 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.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

= Notes on special release =
== 3.8.0.4 and 3.9.1 release==
3.8.0.4 and 3.9.1 release of the plugins on 29 September 2020 introduced improvements on SSO integration for Moodle in Teams as well as Single Sign Off support, but requires additional actions from Moodle and Azure admins.
=== Moodle and Teams SSO integration ===
The new releases is capable of getting a user token from either Teams desktop/mobile app or Teams web app, and attempt to log in as the user in the Moodle Teams tab. In order for it to work, changes in 3 sections are required.
==== Download updated manifest file ====
# Login to Moodle as site administrator.
# Go to "Microsoft Office 365 Integration" page in the site admin section.
# Go to "Teams Settings" tab.
# Verify settings on the page, note that two new settings are added in this release:
## '''Microsoft app ID for the Moodle Teams app''': This is used in the "ID" field of [https://docs.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema Teams app manifest file], which is essentially a self generated app ID to identify itself. It should be set to the default value in most use cases, otherwise it may affect upgrading of the Teams app. The only scenario a custom value is to be set for this setting is when there are multiple Moodle sites in the organisation, and they all need to be integrated with Teams, thus each site will require a separate Teams app. If custom value is required, please use [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7 powershell] or [https://www.guidgenerator.com/ external tools] to generate valid ones.
## '''Teams app name''': This allows you to give a custom name, rather than the default "Moodle", to the Moodle Teams app created. It can be useful if you have multiple Moodle sites in your organisation, and each creating a separate Moodle app for Teams integration.
# Once settings are verified, save changes, go back to the tab, and click the "Download manifest file" button to download the new manifest file for the upgraded app.
==== Update Moodle app in Teams ====
# As a tenant admin, go to Teams.
# Go to "Apps" page to manage apps.
# From the menu on the left, click on the link "Built for YOUR ORGANISATION". This should list all custom apps uploaded for your tenant.
# Locate the previous Moodle app, click the options button on the card for more options, and click "update". This should open a file picker.
# Select the new manifest file downloaded from Moodle.
Note that as long as the '''Microsoft app ID for the Moodle Teams app''' setting is not changed, this should be recognised as an app upgrade, rather than uploading a new app. This means that the app will be kept in all existing Teams that have it installed, and all existing Moodle tabs will keep working.
==== Update Azure app settings ====
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Office 365 integration, and click its name.
# Under '''Manage''', select '''Expose an API'''.
# Select the "Set" link to generate the Application ID URI in the form of api://{AppID}. Insert your fully qualified domain name (with a forward slash "/" appended to the end) between the double forward slashes and the GUID. The entire ID should have the form of: api://fully-qualified-domain-name.com/{AppID}. e.g. api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000.
# If you get errors when selecting the "Set" link, it may be because the '''Supported account types''' setting of your app is set to a value rather than the one with "single tenant". Try updating this value to get it working.
# Select the "Add a scope" button. In the panel that opens:
## enter "access_as_user" as the "Scope name".
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to be "Teams can access the user’s profile".
## Set "Admin consent description" to be "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to be "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to be "Enable Teams to call this app’s APIs with the same rights as the user".
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
# In the Authorized client applications section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
## 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
## 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Under '''Manage''' then '''API permissions''', ensure the following permissions are added under "Microsoft Graph" > "Delegated permissions":
## User.Read (enabled by default)
## email
## offline_access
## OpenId
## profile
# Under '''Manage''' then '''Authentication''', ensure the following boxes are checked for "implicit grant":
## ID Token
## Access Token.

==== Known limitations ====
It is a known issue that if an Office 365 user has never login to Moodle either, her first attempt to SSO from Teams to Moodle will not work silently. Instead, the user will need to click a button from the prompt to login.

=== Single Sign Off ===
When an Office 365 authenticated user clicks the Moodle log out button, it is possible to log the user out from Office 365 at the same time.

In order for this to work, configuration changes in two places are required:
==== Moodle settings change ====
# Sign in Moodle as site admin.
# Go to "Microsoft Office 365 Integration" page in the site admin section.
# Go to "Advanced" tab.
# Enable "Single sign off".
# Save changes.
==== Azure app settings change ====
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Office 365 integration, and click its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the root URL of your Moodle site (wwwroot) as an entry.

=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]]

Office365

2020-10-06T14:30:48Z

Enovationdevteam: /* Configure application */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [http://azure.microsoft.com/en-us/pricing/free-trial/ 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. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need it later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="7" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| rowspan="14" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:
* '''Create accounts in Moodle for users in Azure AD''': This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.
* '''Update all accounts in Moodle for users in Azure AD''': This will update all users in Moodle from each user in the linked Azure AD.
* '''Delete previously synced accounts in Moodle when they are deleted from Azure AD''': This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!
* '''Match preexisting Moodle users with same-named accounts in Azure AD''': This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are insensitive and ignore the 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.
* '''Assign users to application during sync''': The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.
* '''Sync Office 365 profile photos to Moodle in cron job''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.
* '''Sync Office 365 profile photos to Moodle on login''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.
* '''Perform a full sync each run''': By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
* '''Match Azure usernames to Moodle emails instead of Moodle usernames during the sync''': Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.

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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.

===Other advanced settings===
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Office 365 as well.
* '''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.
* '''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 Administration > 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.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

= Notes on special release =
== 3.8.0.4 and 3.9.1 release==
3.8.0.4 and 3.9.1 release of the plugins on 29 September 2020 introduced improvements on SSO integration for Moodle in Teams as well as Single Sign Off support, but requires additional actions from Moodle and Azure admins.
=== Moodle and Teams SSO integration ===
The new releases is capable of getting a user token from either Teams desktop/mobile app or Teams web app, and attempt to log in as the user in the Moodle Teams tab. In order for it to work, changes in 3 sections are required.
==== Download updated manifest file ====
# Login to Moodle as site administrator.
# Go to "Microsoft Office 365 Integration" page in the site admin section.
# Go to "Teams Settings" tab.
# Verify settings on the page, note that two new settings are added in this release:
## '''Microsoft app ID for the Moodle Teams app''': This is used in the "ID" field of [https://docs.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema Teams app manifest file], which is essentially a self generated app ID to identify itself. It should be set to the default value in most use cases, otherwise it may affect upgrading of the Teams app. The only scenario a custom value is to be set for this setting is when there are multiple Moodle sites in the organisation, and they all need to be integrated with Teams, thus each site will require a separate Teams app. If custom value is required, please use [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7 powershell] or [https://www.guidgenerator.com/ external tools] to generate valid ones.
## '''Teams app name''': This allows you to give a custom name, rather than the default "Moodle", to the Moodle Teams app created. It can be useful if you have multiple Moodle sites in your organisation, and each creating a separate Moodle app for Teams integration.
# Once settings are verified, save changes, go back to the tab, and click the "Download manifest file" button to download the new manifest file for the upgraded app.
==== Update Moodle app in Teams ====
# As a tenant admin, go to Teams.
# Go to "Apps" page to manage apps.
# From the menu on the left, click on the link "Built for YOUR ORGANISATION". This should list all custom apps uploaded for your tenant.
# Locate the previous Moodle app, click the options button on the card for more options, and click "update". This should open a file picker.
# Select the new manifest file downloaded from Moodle.
Note that as long as the '''Microsoft app ID for the Moodle Teams app''' setting is not changed, this should be recognised as an app upgrade, rather than uploading a new app. This means that the app will be kept in all existing Teams that have it installed, and all existing Moodle tabs will keep working.
==== Update Azure app settings ====
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Office 365 integration, and click its name.
# Under '''Manage''', select '''Expose an API'''.
# Select the "Set" link to generate the Application ID URI in the form of api://{AppID}. Insert your fully qualified domain name (with a forward slash "/" appended to the end) between the double forward slashes and the GUID. The entire ID should have the form of: api://fully-qualified-domain-name.com/{AppID}. e.g. api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000.
# If you get errors when selecting the "Set" link, it may be because the '''Supported account types''' setting of your app is set to a value rather than the one with "single tenant". Try updating this value to get it working.
# Select the "Add a scope" button. In the panel that opens:
## enter "access_as_user" as the "Scope name".
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to be "Teams can access the user’s profile".
## Set "Admin consent description" to be "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to be "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to be "Enable Teams to call this app’s APIs with the same rights as the user".
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
# In the Authorized client applications section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
## 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
## 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Under '''Manage''' then '''API permissions''', ensure the following permissions are added under "Microsoft Graph" > "Delegated permissions":
## User.Read (enabled by default)
## email
## offline_access
## OpenId
## profile
# Under '''Manage''' then '''Authentication''', ensure the following boxes are checked for "implicit grant":
## ID Token
## Access Token.

==== Known limitations ====
It is a known issue that if an Office 365 user has never login to Moodle either, her first attempt to SSO from Teams to Moodle will not work silently. Instead, the user will need to click a button from the prompt to login.

=== Single Sign Off ===
When an Office 365 authenticated user clicks the Moodle log out button, it is possible to log the user out from Office 365 at the same time.

In order for this to work, configuration changes in two places are required:
==== Moodle settings change ====
# Sign in Moodle as site admin.
# Go to "Microsoft Office 365 Integration" page in the site admin section.
# Go to "Advanced" tab.
# Enable "Single sign off".
# Save changes.
==== Azure app settings change ====
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Office 365 integration, and click its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the root URL of your Moodle site (wwwroot) as an entry.

=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]]

Office365

2020-10-02T10:36:55Z

Enovationdevteam: /* Single Sign Off */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [http://azure.microsoft.com/en-us/pricing/free-trial/ 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. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="7" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| rowspan="14" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:
* '''Create accounts in Moodle for users in Azure AD''': This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.
* '''Update all accounts in Moodle for users in Azure AD''': This will update all users in Moodle from each user in the linked Azure AD.
* '''Delete previously synced accounts in Moodle when they are deleted from Azure AD''': This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!
* '''Match preexisting Moodle users with same-named accounts in Azure AD''': This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are insensitive and ignore the 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.
* '''Assign users to application during sync''': The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.
* '''Sync Office 365 profile photos to Moodle in cron job''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.
* '''Sync Office 365 profile photos to Moodle on login''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.
* '''Perform a full sync each run''': By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
* '''Match Azure usernames to Moodle emails instead of Moodle usernames during the sync''': Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.

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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.

===Other advanced settings===
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Office 365 as well.
* '''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.
* '''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 Administration > 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.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

= Notes on special release =
== 3.8.0.4 and 3.9.1 release==
3.8.0.4 and 3.9.1 release of the plugins on 29 September 2020 introduced improvements on SSO integration for Moodle in Teams as well as Single Sign Off support, but requires additional actions from Moodle and Azure admins.
=== Moodle and Teams SSO integration ===
The new releases is capable of getting a user token from either Teams desktop/mobile app or Teams web app, and attempt to log in as the user in the Moodle Teams tab. In order for it to work, changes in 3 sections are required.
==== Download updated manifest file ====
# Login to Moodle as site administrator.
# Go to "Microsoft Office 365 Integration" page in the site admin section.
# Go to "Teams Settings" tab.
# Verify settings on the page, note that two new settings are added in this release:
## '''Microsoft app ID for the Moodle Teams app''': This is used in the "ID" field of [https://docs.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema Teams app manifest file], which is essentially a self generated app ID to identify itself. It should be set to the default value in most use cases, otherwise it may affect upgrading of the Teams app. The only scenario a custom value is to be set for this setting is when there are multiple Moodle sites in the organisation, and they all need to be integrated with Teams, thus each site will require a separate Teams app. If custom value is required, please use [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7 powershell] or [https://www.guidgenerator.com/ external tools] to generate valid ones.
## '''Teams app name''': This allows you to give a custom name, rather than the default "Moodle", to the Moodle Teams app created. It can be useful if you have multiple Moodle sites in your organisation, and each creating a separate Moodle app for Teams integration.
# Once settings are verified, save changes, go back to the tab, and click the "Download manifest file" button to download the new manifest file for the upgraded app.
==== Update Moodle app in Teams ====
# As a tenant admin, go to Teams.
# Go to "Apps" page to manage apps.
# From the menu on the left, click on the link "Built for YOUR ORGANISATION". This should list all custom apps uploaded for your tenant.
# Locate the previous Moodle app, click the options button on the card for more options, and click "update". This should open a file picker.
# Select the new manifest file downloaded from Moodle.
Note that as long as the '''Microsoft app ID for the Moodle Teams app''' setting is not changed, this should be recognised as an app upgrade, rather than uploading a new app. This means that the app will be kept in all existing Teams that have it installed, and all existing Moodle tabs will keep working.
==== Update Azure app settings ====
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Office 365 integration, and click its name.
# Under '''Manage''', select '''Expose an API'''.
# Select the "Set" link to generate the Application ID URI in the form of api://{AppID}. Insert your fully qualified domain name (with a forward slash "/" appended to the end) between the double forward slashes and the GUID. The entire ID should have the form of: api://fully-qualified-domain-name.com/{AppID}. e.g. api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000.
# If you get errors when selecting the "Set" link, it may be because the '''Supported account types''' setting of your app is set to a value rather than the one with "single tenant". Try updating this value to get it working.
# Select the "Add a scope" button. In the panel that opens:
## enter "access_as_user" as the "Scope name".
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to be "Teams can access the user’s profile".
## Set "Admin consent description" to be "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to be "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to be "Enable Teams to call this app’s APIs with the same rights as the user".
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
# In the Authorized client applications section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
## 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
## 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Under '''Manage''' then '''API permissions''', ensure the following permissions are added under "Microsoft Graph" > "Delegated permissions":
## User.Read (enabled by default)
## email
## offline_access
## OpenId
## profile
# Under '''Manage''' then '''Authentication''', ensure the following boxes are checked for "implicit grant":
## ID Token
## Access Token.

==== Known limitations ====
It is a known issue that if an Office 365 user has never login to Moodle either, her first attempt to SSO from Teams to Moodle will not work silently. Instead, the user will need to click a button from the prompt to login.

=== Single Sign Off ===
When an Office 365 authenticated user clicks the Moodle log out button, it is possible to log the user out from Office 365 at the same time.

In order for this to work, configuration changes in two places are required:
==== Moodle settings change ====
# Sign in Moodle as site admin.
# Go to "Microsoft Office 365 Integration" page in the site admin section.
# Go to "Advanced" tab.
# Enable "Single sign off".
# Save changes.
==== Azure app settings change ====
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Office 365 integration, and click its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the root URL of your Moodle site (wwwroot) as an entry.

=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]]

Office365

2020-10-02T10:36:42Z

Enovationdevteam: /* Single Sign Off */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [http://azure.microsoft.com/en-us/pricing/free-trial/ 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. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="7" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| rowspan="14" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:
* '''Create accounts in Moodle for users in Azure AD''': This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.
* '''Update all accounts in Moodle for users in Azure AD''': This will update all users in Moodle from each user in the linked Azure AD.
* '''Delete previously synced accounts in Moodle when they are deleted from Azure AD''': This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!
* '''Match preexisting Moodle users with same-named accounts in Azure AD''': This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are insensitive and ignore the 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.
* '''Assign users to application during sync''': The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.
* '''Sync Office 365 profile photos to Moodle in cron job''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.
* '''Sync Office 365 profile photos to Moodle on login''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.
* '''Perform a full sync each run''': By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
* '''Match Azure usernames to Moodle emails instead of Moodle usernames during the sync''': Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.

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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.

===Other advanced settings===
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Office 365 as well.
* '''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.
* '''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 Administration > 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.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

= Notes on special release =
== 3.8.0.4 and 3.9.1 release==
3.8.0.4 and 3.9.1 release of the plugins on 29 September 2020 introduced improvements on SSO integration for Moodle in Teams as well as Single Sign Off support, but requires additional actions from Moodle and Azure admins.
=== Moodle and Teams SSO integration ===
The new releases is capable of getting a user token from either Teams desktop/mobile app or Teams web app, and attempt to log in as the user in the Moodle Teams tab. In order for it to work, changes in 3 sections are required.
==== Download updated manifest file ====
# Login to Moodle as site administrator.
# Go to "Microsoft Office 365 Integration" page in the site admin section.
# Go to "Teams Settings" tab.
# Verify settings on the page, note that two new settings are added in this release:
## '''Microsoft app ID for the Moodle Teams app''': This is used in the "ID" field of [https://docs.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema Teams app manifest file], which is essentially a self generated app ID to identify itself. It should be set to the default value in most use cases, otherwise it may affect upgrading of the Teams app. The only scenario a custom value is to be set for this setting is when there are multiple Moodle sites in the organisation, and they all need to be integrated with Teams, thus each site will require a separate Teams app. If custom value is required, please use [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7 powershell] or [https://www.guidgenerator.com/ external tools] to generate valid ones.
## '''Teams app name''': This allows you to give a custom name, rather than the default "Moodle", to the Moodle Teams app created. It can be useful if you have multiple Moodle sites in your organisation, and each creating a separate Moodle app for Teams integration.
# Once settings are verified, save changes, go back to the tab, and click the "Download manifest file" button to download the new manifest file for the upgraded app.
==== Update Moodle app in Teams ====
# As a tenant admin, go to Teams.
# Go to "Apps" page to manage apps.
# From the menu on the left, click on the link "Built for YOUR ORGANISATION". This should list all custom apps uploaded for your tenant.
# Locate the previous Moodle app, click the options button on the card for more options, and click "update". This should open a file picker.
# Select the new manifest file downloaded from Moodle.
Note that as long as the '''Microsoft app ID for the Moodle Teams app''' setting is not changed, this should be recognised as an app upgrade, rather than uploading a new app. This means that the app will be kept in all existing Teams that have it installed, and all existing Moodle tabs will keep working.
==== Update Azure app settings ====
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Office 365 integration, and click its name.
# Under '''Manage''', select '''Expose an API'''.
# Select the "Set" link to generate the Application ID URI in the form of api://{AppID}. Insert your fully qualified domain name (with a forward slash "/" appended to the end) between the double forward slashes and the GUID. The entire ID should have the form of: api://fully-qualified-domain-name.com/{AppID}. e.g. api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000.
# If you get errors when selecting the "Set" link, it may be because the '''Supported account types''' setting of your app is set to a value rather than the one with "single tenant". Try updating this value to get it working.
# Select the "Add a scope" button. In the panel that opens:
## enter "access_as_user" as the "Scope name".
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to be "Teams can access the user’s profile".
## Set "Admin consent description" to be "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to be "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to be "Enable Teams to call this app’s APIs with the same rights as the user".
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
# In the Authorized client applications section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
## 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
## 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Under '''Manage''' then '''API permissions''', ensure the following permissions are added under "Microsoft Graph" > "Delegated permissions":
## User.Read (enabled by default)
## email
## offline_access
## OpenId
## profile
# Under '''Manage''' then '''Authentication''', ensure the following boxes are checked for "implicit grant":
## ID Token
## Access Token.

==== Known limitations ====
It is a known issue that if an Office 365 user has never login to Moodle either, her first attempt to SSO from Teams to Moodle will not work silently. Instead, the user will need to click a button from the prompt to login.

=== Single Sign Off ===
When an Office 365 authenticated user clicks the Moodle log out button, it is possible to log the users out from Office 365 at the same time.

In order for this to work, configuration changes in two places are required:
==== Moodle settings change ====
# Sign in Moodle as site admin.
# Go to "Microsoft Office 365 Integration" page in the site admin section.
# Go to "Advanced" tab.
# Enable "Single sign off".
# Save changes.
==== Azure app settings change ====
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Office 365 integration, and click its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the root URL of your Moodle site (wwwroot) as an entry.

=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]]

Office365

2020-09-28T22:04:39Z

Enovationdevteam:

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [http://azure.microsoft.com/en-us/pricing/free-trial/ 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. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="7" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| rowspan="14" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:
* '''Create accounts in Moodle for users in Azure AD''': This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.
* '''Update all accounts in Moodle for users in Azure AD''': This will update all users in Moodle from each user in the linked Azure AD.
* '''Delete previously synced accounts in Moodle when they are deleted from Azure AD''': This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!
* '''Match preexisting Moodle users with same-named accounts in Azure AD''': This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are insensitive and ignore the 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.
* '''Assign users to application during sync''': The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.
* '''Sync Office 365 profile photos to Moodle in cron job''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.
* '''Sync Office 365 profile photos to Moodle on login''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.
* '''Perform a full sync each run''': By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
* '''Match Azure usernames to Moodle emails instead of Moodle usernames during the sync''': Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.

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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.

===Other advanced settings===
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Office 365 as well.
* '''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.
* '''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 Administration > 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.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

= Notes on special release =
== 3.8.0.4 and 3.9.1 release==
3.8.0.4 and 3.9.1 release of the plugins on 29 September 2020 introduced improvements on SSO integration for Moodle in Teams as well as Single Sign Off support, but requires additional actions from Moodle and Azure admins.
=== Moodle and Teams SSO integration ===
The new releases is capable of getting a user token from either Teams desktop/mobile app or Teams web app, and attempt to log in as the user in the Moodle Teams tab. In order for it to work, changes in 3 sections are required.
==== Download updated manifest file ====
# Login to Moodle as site administrator.
# Go to "Microsoft Office 365 Integration" page in the site admin section.
# Go to "Teams Settings" tab.
# Verify settings on the page, note that two new settings are added in this release:
## '''Microsoft app ID for the Moodle Teams app''': This is used in the "ID" field of [https://docs.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema Teams app manifest file], which is essentially a self generated app ID to identify itself. It should be set to the default value in most use cases, otherwise it may affect upgrading of the Teams app. The only scenario a custom value is to be set for this setting is when there are multiple Moodle sites in the organisation, and they all need to be integrated with Teams, thus each site will require a separate Teams app. If custom value is required, please use [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7 powershell] or [https://www.guidgenerator.com/ external tools] to generate valid ones.
## '''Teams app name''': This allows you to give a custom name, rather than the default "Moodle", to the Moodle Teams app created. It can be useful if you have multiple Moodle sites in your organisation, and each creating a separate Moodle app for Teams integration.
# Once settings are verified, save changes, go back to the tab, and click the "Download manifest file" button to download the new manifest file for the upgraded app.
==== Update Moodle app in Teams ====
# As a tenant admin, go to Teams.
# Go to "Apps" page to manage apps.
# From the menu on the left, click on the link "Built for YOUR ORGANISATION". This should list all custom apps uploaded for your tenant.
# Locate the previous Moodle app, click the options button on the card for more options, and click "update". This should open a file picker.
# Select the new manifest file downloaded from Moodle.
Note that as long as the '''Microsoft app ID for the Moodle Teams app''' setting is not changed, this should be recognised as an app upgrade, rather than uploading a new app. This means that the app will be kept in all existing Teams that have it installed, and all existing Moodle tabs will keep working.
==== Update Azure app settings ====
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Office 365 integration, and click its name.
# Under '''Manage''', select '''Expose an API'''.
# Select the "Set" link to generate the Application ID URI in the form of api://{AppID}. Insert your fully qualified domain name (with a forward slash "/" appended to the end) between the double forward slashes and the GUID. The entire ID should have the form of: api://fully-qualified-domain-name.com/{AppID}. e.g. api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000.
# If you get errors when selecting the "Set" link, it may be because the '''Supported account types''' setting of your app is set to a value rather than the one with "single tenant". Try updating this value to get it working.
# Select the "Add a scope" button. In the panel that opens:
## enter "access_as_user" as the "Scope name".
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to be "Teams can access the user’s profile".
## Set "Admin consent description" to be "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to be "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to be "Enable Teams to call this app’s APIs with the same rights as the user".
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
# In the Authorized client applications section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
## 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
## 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Under '''Manage''' then '''API permissions''', ensure the following permissions are added under "Microsoft Graph" > "Delegated permissions":
## User.Read (enabled by default)
## email
## offline_access
## OpenId
## profile
# Under '''Manage''' then '''Authentication''', ensure the following boxes are checked for "implicit grant":
## ID Token
## Access Token.

==== Known limitations ====
It is a known issue that if an Office 365 user has never login to Moodle either, her first attempt to SSO from Teams to Moodle will not work silently. Instead, the user will need to click a button from the prompt to login.

=== Single Sign Off ===
When an Office 365 authenticate users clicks the Moodle log out button, it is possible to log the users out from Office 365 at the same time.

In order for this to work, configuration changes in two places are required:
==== Moodle settings change ====
# Sign in Moodle as site admin.
# Go to "Microsoft Office 365 Integration" page in the site admin section.
# Go to "Advanced" tab.
# Enable "Single sign off".
# Save changes.
==== Azure app settings change ====
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Office 365 integration, and click its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the root URL of your Moodle site (wwwroot) as an entry.

=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]]

Office365

2020-09-28T20:53:19Z

Enovationdevteam: /* FAQ */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [http://azure.microsoft.com/en-us/pricing/free-trial/ 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. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="7" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| rowspan="14" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:
* '''Create accounts in Moodle for users in Azure AD''': This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.
* '''Update all accounts in Moodle for users in Azure AD''': This will update all users in Moodle from each user in the linked Azure AD.
* '''Delete previously synced accounts in Moodle when they are deleted from Azure AD''': This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!
* '''Match preexisting Moodle users with same-named accounts in Azure AD''': This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are insensitive and ignore the 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.
* '''Assign users to application during sync''': The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.
* '''Sync Office 365 profile photos to Moodle in cron job''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.
* '''Sync Office 365 profile photos to Moodle on login''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.
* '''Perform a full sync each run''': By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
* '''Match Azure usernames to Moodle emails instead of Moodle usernames during the sync''': Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.

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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.

===Other advanced settings===
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Office 365 as well.
* '''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.
* '''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 Administration > 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.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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]]

Office365

2020-09-28T20:50:15Z

Enovationdevteam: /* Add Teams Moodle app ID back to Moodle */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [http://azure.microsoft.com/en-us/pricing/free-trial/ 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. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="7" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| rowspan="14" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:
* '''Create accounts in Moodle for users in Azure AD''': This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.
* '''Update all accounts in Moodle for users in Azure AD''': This will update all users in Moodle from each user in the linked Azure AD.
* '''Delete previously synced accounts in Moodle when they are deleted from Azure AD''': This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!
* '''Match preexisting Moodle users with same-named accounts in Azure AD''': This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are insensitive and ignore the 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.
* '''Assign users to application during sync''': The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.
* '''Sync Office 365 profile photos to Moodle in cron job''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.
* '''Sync Office 365 profile photos to Moodle on login''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.
* '''Perform a full sync each run''': By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
* '''Match Azure usernames to Moodle emails instead of Moodle usernames during the sync''': Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.

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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.

===Other advanced settings===
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Office 365 as well.
* '''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.
* '''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 Administration > 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.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

=FAQ=
==How will cookie changes in Chrome version 80 affect Teams integration?==
The stable release of the Google Chrome web browser (build 80, scheduled for release on February 4, 2020) features a change in how cookies are handled. This will include two changes:
* Cookies without a '''SameSite''' attribute will be treated as SameSite=Lax.
* Cookies with '''SameSite=None''' must also specify '''Secure''', meaning they require a secure context.
The changes are explained in [https://web.dev/samesite-cookies-explained/ here] and [https://blog.chromium.org/2019/10/developers-get-ready-for-new.html here]

Moodle and Microsoft Teams integration will be affected by this change, because the integration requires embedding Moodle pages in Teams. There is [https://tracker.moodle.org/browse/MDL-67175 an open item] in Moodle tracker about this change in general, but the code change proposed in the tracker item didn't get integrated in time for the last minor Moodle upgrade before Chrome 80 release date. As a result, all sites using Moodle and Microsoft Teams integration feature are strongly suggested to apply the patches proposed in the [https://tracker.moodle.org/browse/MDL-67175 tracker item] so that users with Chrome 80 can keep using Moodle tabs in Teams after upgrade.
* Patches are provided for all Moodle versions that are supported for core feature and security issues, i.e. 3.5, 3.6, 3.7 and 3.8.
* Patches are only required before this is integrated into the next Moodle minor release of the Moodle versions, which is scheduled at March 9th, 2020.
* After the next Moodle minor release, the patch should be removed as it would be integration into core Moodle code.

=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]]

Office365

2020-09-28T20:49:42Z

Enovationdevteam: /* Teams Settings */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [http://azure.microsoft.com/en-us/pricing/free-trial/ 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. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="7" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| rowspan="14" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:
* '''Create accounts in Moodle for users in Azure AD''': This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.
* '''Update all accounts in Moodle for users in Azure AD''': This will update all users in Moodle from each user in the linked Azure AD.
* '''Delete previously synced accounts in Moodle when they are deleted from Azure AD''': This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!
* '''Match preexisting Moodle users with same-named accounts in Azure AD''': This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are insensitive and ignore the 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.
* '''Assign users to application during sync''': The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.
* '''Sync Office 365 profile photos to Moodle in cron job''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.
* '''Sync Office 365 profile photos to Moodle on login''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.
* '''Perform a full sync each run''': By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
* '''Match Azure usernames to Moodle emails instead of Moodle usernames during the sync''': Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.

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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.

===Other advanced settings===
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Office 365 as well.
* '''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.
* '''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 Administration > 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.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

=== Add Teams Moodle app ID back to Moodle ===
After Moodle app is added to Teams, you can go to "Teams Moodle app" tab, and follow steps on the page to set Teams Moodle app ID in Moodle. This will allow Moodle to automatically add The Teams Moodle app to the Teams created from the sync, and create a new Moodle tab in the general channel of the newly create Team, linking to the Moodle course page.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

=FAQ=
==How will cookie changes in Chrome version 80 affect Teams integration?==
The stable release of the Google Chrome web browser (build 80, scheduled for release on February 4, 2020) features a change in how cookies are handled. This will include two changes:
* Cookies without a '''SameSite''' attribute will be treated as SameSite=Lax.
* Cookies with '''SameSite=None''' must also specify '''Secure''', meaning they require a secure context.
The changes are explained in [https://web.dev/samesite-cookies-explained/ here] and [https://blog.chromium.org/2019/10/developers-get-ready-for-new.html here]

Moodle and Microsoft Teams integration will be affected by this change, because the integration requires embedding Moodle pages in Teams. There is [https://tracker.moodle.org/browse/MDL-67175 an open item] in Moodle tracker about this change in general, but the code change proposed in the tracker item didn't get integrated in time for the last minor Moodle upgrade before Chrome 80 release date. As a result, all sites using Moodle and Microsoft Teams integration feature are strongly suggested to apply the patches proposed in the [https://tracker.moodle.org/browse/MDL-67175 tracker item] so that users with Chrome 80 can keep using Moodle tabs in Teams after upgrade.
* Patches are provided for all Moodle versions that are supported for core feature and security issues, i.e. 3.5, 3.6, 3.7 and 3.8.
* Patches are only required before this is integrated into the next Moodle minor release of the Moodle versions, which is scheduled at March 9th, 2020.
* After the next Moodle minor release, the patch should be removed as it would be integration into core Moodle code.

=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]]

Office365

2020-09-28T20:40:02Z

Enovationdevteam: /* User Sync */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [http://azure.microsoft.com/en-us/pricing/free-trial/ 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. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="7" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| rowspan="14" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:
* '''Create accounts in Moodle for users in Azure AD''': This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.
* '''Update all accounts in Moodle for users in Azure AD''': This will update all users in Moodle from each user in the linked Azure AD.
* '''Delete previously synced accounts in Moodle when they are deleted from Azure AD''': This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!
* '''Match preexisting Moodle users with same-named accounts in Azure AD''': This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are insensitive and ignore the 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.
* '''Assign users to application during sync''': The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.
* '''Sync Office 365 profile photos to Moodle in cron job''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.
* '''Sync Office 365 profile photos to Moodle on login''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.
* '''Perform a full sync each run''': By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
* '''Match Azure usernames to Moodle emails instead of Moodle usernames during the sync''': Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.

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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.

===Other advanced settings===
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Office 365 as well.
* '''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.
* '''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 Administration > 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.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in Team linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

=FAQ=
==How will cookie changes in Chrome version 80 affect Teams integration?==
The stable release of the Google Chrome web browser (build 80, scheduled for release on February 4, 2020) features a change in how cookies are handled. This will include two changes:
* Cookies without a '''SameSite''' attribute will be treated as SameSite=Lax.
* Cookies with '''SameSite=None''' must also specify '''Secure''', meaning they require a secure context.
The changes are explained in [https://web.dev/samesite-cookies-explained/ here] and [https://blog.chromium.org/2019/10/developers-get-ready-for-new.html here]

Moodle and Microsoft Teams integration will be affected by this change, because the integration requires embedding Moodle pages in Teams. There is [https://tracker.moodle.org/browse/MDL-67175 an open item] in Moodle tracker about this change in general, but the code change proposed in the tracker item didn't get integrated in time for the last minor Moodle upgrade before Chrome 80 release date. As a result, all sites using Moodle and Microsoft Teams integration feature are strongly suggested to apply the patches proposed in the [https://tracker.moodle.org/browse/MDL-67175 tracker item] so that users with Chrome 80 can keep using Moodle tabs in Teams after upgrade.
* Patches are provided for all Moodle versions that are supported for core feature and security issues, i.e. 3.5, 3.6, 3.7 and 3.8.
* Patches are only required before this is integrated into the next Moodle minor release of the Moodle versions, which is scheduled at March 9th, 2020.
* After the next Moodle minor release, the patch should be removed as it would be integration into core Moodle code.

=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]]

Office365

2020-09-28T20:39:49Z

Enovationdevteam: /* User Sync */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [http://azure.microsoft.com/en-us/pricing/free-trial/ 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. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="7" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| rowspan="14" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:
* '''Create accounts in Moodle for users in Azure AD''': This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.
* '''Update all accounts in Moodle for users in Azure AD''': This will update all users in Moodle from each user in the linked Azure AD.
* '''Delete previously synced accounts in Moodle when they are deleted from Azure AD''': This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!
* '''Match preexisting Moodle users with same-named accounts in Azure AD''': This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are insensitive and ignore the 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.
* '''Assign users to application during sync''': The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.
* '''Sync Office 365 profile photos to Moodle in cron job''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.
* '''Sync Office 365 profile photos to Moodle on login''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.
* '''Perform a full sync each run''': By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
* '''Match Azure usernames to Moodle emails instead of Moodle usernames during the sync''': Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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 colume 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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.

===Other advanced settings===
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Office 365 as well.
* '''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.
* '''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 Administration > 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.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in Team linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

=FAQ=
==How will cookie changes in Chrome version 80 affect Teams integration?==
The stable release of the Google Chrome web browser (build 80, scheduled for release on February 4, 2020) features a change in how cookies are handled. This will include two changes:
* Cookies without a '''SameSite''' attribute will be treated as SameSite=Lax.
* Cookies with '''SameSite=None''' must also specify '''Secure''', meaning they require a secure context.
The changes are explained in [https://web.dev/samesite-cookies-explained/ here] and [https://blog.chromium.org/2019/10/developers-get-ready-for-new.html here]

Moodle and Microsoft Teams integration will be affected by this change, because the integration requires embedding Moodle pages in Teams. There is [https://tracker.moodle.org/browse/MDL-67175 an open item] in Moodle tracker about this change in general, but the code change proposed in the tracker item didn't get integrated in time for the last minor Moodle upgrade before Chrome 80 release date. As a result, all sites using Moodle and Microsoft Teams integration feature are strongly suggested to apply the patches proposed in the [https://tracker.moodle.org/browse/MDL-67175 tracker item] so that users with Chrome 80 can keep using Moodle tabs in Teams after upgrade.
* Patches are provided for all Moodle versions that are supported for core feature and security issues, i.e. 3.5, 3.6, 3.7 and 3.8.
* Patches are only required before this is integrated into the next Moodle minor release of the Moodle versions, which is scheduled at March 9th, 2020.
* After the next Moodle minor release, the patch should be removed as it would be integration into core Moodle code.

=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]]

Office365

2020-09-28T20:39:32Z

Enovationdevteam: /* User Sync */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [http://azure.microsoft.com/en-us/pricing/free-trial/ 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. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="7" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| rowspan="14" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:
* '''Create accounts in Moodle for users in Azure AD''': This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.
* '''Update all accounts in Moodle for users in Azure AD''': This will update all users in Moodle from each user in the linked Azure AD.
* '''Delete previously synced accounts in Moodle when they are deleted from Azure AD''': This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!
* '''Match preexisting Moodle users with same-named accounts in Azure AD''': This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are insensitive and ignore the 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.
* '''Assign users to application during sync''': The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.
* '''Sync Office 365 profile photos to Moodle in cron job''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.
* '''Sync Office 365 profile photos to Moodle on login''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.
* '''Perform a full sync each run''': By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
* '''Match Azure usernames to Moodle emails instead of Moodle usernames during the sync''': Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.

===Other advanced settings===
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Office 365 as well.
* '''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.
* '''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 Administration > 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.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in Team linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

=FAQ=
==How will cookie changes in Chrome version 80 affect Teams integration?==
The stable release of the Google Chrome web browser (build 80, scheduled for release on February 4, 2020) features a change in how cookies are handled. This will include two changes:
* Cookies without a '''SameSite''' attribute will be treated as SameSite=Lax.
* Cookies with '''SameSite=None''' must also specify '''Secure''', meaning they require a secure context.
The changes are explained in [https://web.dev/samesite-cookies-explained/ here] and [https://blog.chromium.org/2019/10/developers-get-ready-for-new.html here]

Moodle and Microsoft Teams integration will be affected by this change, because the integration requires embedding Moodle pages in Teams. There is [https://tracker.moodle.org/browse/MDL-67175 an open item] in Moodle tracker about this change in general, but the code change proposed in the tracker item didn't get integrated in time for the last minor Moodle upgrade before Chrome 80 release date. As a result, all sites using Moodle and Microsoft Teams integration feature are strongly suggested to apply the patches proposed in the [https://tracker.moodle.org/browse/MDL-67175 tracker item] so that users with Chrome 80 can keep using Moodle tabs in Teams after upgrade.
* Patches are provided for all Moodle versions that are supported for core feature and security issues, i.e. 3.5, 3.6, 3.7 and 3.8.
* Patches are only required before this is integrated into the next Moodle minor release of the Moodle versions, which is scheduled at March 9th, 2020.
* After the next Moodle minor release, the patch should be removed as it would be integration into core Moodle code.

=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]]

Office365

2020-09-28T20:33:51Z

Enovationdevteam: /* Advanced settings */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [http://azure.microsoft.com/en-us/pricing/free-trial/ 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. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="7" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| rowspan="14" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:

==== Create accounts in Moodle for users in Azure AD ====
This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.

==== Update all accounts in Moodle for users in Azure AD ====
This will update all users in Moodle from each user in the linked Azure AD.

==== Delete previously synced accounts in Moodle when they are deleted from Azure AD ====
This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!

==== Match preexisting Moodle users with same-named accounts in Azure AD ====
This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are 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.

==== Assign users to application during sync ====

The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.

==== Sync Office 365 profile photos to Moodle in cron job ====

User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.

==== Sync Office 365 profile photos to Moodle on login ====

User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.

==== Perform a full sync each run ====

By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.

==== Match Azure usernames to moodle emails instead of moodle usernames during the sync ====

Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.

===Other advanced settings===
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Office 365 as well.
* '''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.
* '''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 Administration > 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.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

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

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in Team linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

=FAQ=
==How will cookie changes in Chrome version 80 affect Teams integration?==
The stable release of the Google Chrome web browser (build 80, scheduled for release on February 4, 2020) features a change in how cookies are handled. This will include two changes:
* Cookies without a '''SameSite''' attribute will be treated as SameSite=Lax.
* Cookies with '''SameSite=None''' must also specify '''Secure''', meaning they require a secure context.
The changes are explained in [https://web.dev/samesite-cookies-explained/ here] and [https://blog.chromium.org/2019/10/developers-get-ready-for-new.html here]

Moodle and Microsoft Teams integration will be affected by this change, because the integration requires embedding Moodle pages in Teams. There is [https://tracker.moodle.org/browse/MDL-67175 an open item] in Moodle tracker about this change in general, but the code change proposed in the tracker item didn't get integrated in time for the last minor Moodle upgrade before Chrome 80 release date. As a result, all sites using Moodle and Microsoft Teams integration feature are strongly suggested to apply the patches proposed in the [https://tracker.moodle.org/browse/MDL-67175 tracker item] so that users with Chrome 80 can keep using Moodle tabs in Teams after upgrade.
* Patches are provided for all Moodle versions that are supported for core feature and security issues, i.e. 3.5, 3.6, 3.7 and 3.8.
* Patches are only required before this is integrated into the next Moodle minor release of the Moodle versions, which is scheduled at March 9th, 2020.
* After the next Moodle minor release, the patch should be removed as it would be integration into core Moodle code.

=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]]

Office365

2020-09-28T15:29:46Z

Enovationdevteam: /* Configure application */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [http://azure.microsoft.com/en-us/pricing/free-trial/ 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. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="7" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| rowspan="14" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:

==== Create accounts in Moodle for users in Azure AD ====
This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.

==== Update all accounts in Moodle for users in Azure AD ====
This will update all users in Moodle from each user in the linked Azure AD.

==== Delete previously synced accounts in Moodle when they are deleted from Azure AD ====
This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!

==== Match preexisting Moodle users with same-named accounts in Azure AD ====
This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are 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.

==== Assign users to application during sync ====

The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.

==== Sync Office 365 profile photos to Moodle in cron job ====

User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.

==== Sync Office 365 profile photos to Moodle on login ====

User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.

==== Perform a full sync each run ====

By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.

==== Match Azure usernames to moodle emails instead of moodle usernames during the sync ====

Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.

=====Cleanup OpenID Connect Tokens=====
If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors.

====Advanced settings====
=====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.
=====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 Administration > 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.

====Legacy settings====
===== 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 ======
# Visit the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft Office 365 Integration).
# 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.
## This should be the entire URL to the SharePoint site - for example: '''https://contoso.sharepoint.com/moodle'''.
## This site must be accessible to the '''System API user'''
# When you are done typing in the URL, the URL will be checked for suitability.
## If the valid is invalid, you will see a red box and the text "This is not a usable SharePoint site."
## 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.
## 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.
# Click '''Save changes''' at the bottom of the settings page.
# 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.'''.
# The SharePoint Link is set up during the Moodle cron, so ensure your Moodle cron is set up and running.

====Preview features====
=====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.

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in Team linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

=FAQ=
==How will cookie changes in Chrome version 80 affect Teams integration?==
The stable release of the Google Chrome web browser (build 80, scheduled for release on February 4, 2020) features a change in how cookies are handled. This will include two changes:
* Cookies without a '''SameSite''' attribute will be treated as SameSite=Lax.
* Cookies with '''SameSite=None''' must also specify '''Secure''', meaning they require a secure context.
The changes are explained in [https://web.dev/samesite-cookies-explained/ here] and [https://blog.chromium.org/2019/10/developers-get-ready-for-new.html here]

Moodle and Microsoft Teams integration will be affected by this change, because the integration requires embedding Moodle pages in Teams. There is [https://tracker.moodle.org/browse/MDL-67175 an open item] in Moodle tracker about this change in general, but the code change proposed in the tracker item didn't get integrated in time for the last minor Moodle upgrade before Chrome 80 release date. As a result, all sites using Moodle and Microsoft Teams integration feature are strongly suggested to apply the patches proposed in the [https://tracker.moodle.org/browse/MDL-67175 tracker item] so that users with Chrome 80 can keep using Moodle tabs in Teams after upgrade.
* Patches are provided for all Moodle versions that are supported for core feature and security issues, i.e. 3.5, 3.6, 3.7 and 3.8.
* Patches are only required before this is integrated into the next Moodle minor release of the Moodle versions, which is scheduled at March 9th, 2020.
* After the next Moodle minor release, the patch should be removed as it would be integration into core Moodle code.

=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]]

Office365

2020-09-28T15:29:17Z

Enovationdevteam: /* Configure application */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [http://azure.microsoft.com/en-us/pricing/free-trial/ 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. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="7" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''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
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:

==== Create accounts in Moodle for users in Azure AD ====
This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.

==== Update all accounts in Moodle for users in Azure AD ====
This will update all users in Moodle from each user in the linked Azure AD.

==== Delete previously synced accounts in Moodle when they are deleted from Azure AD ====
This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!

==== Match preexisting Moodle users with same-named accounts in Azure AD ====
This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are 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.

==== Assign users to application during sync ====

The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.

==== Sync Office 365 profile photos to Moodle in cron job ====

User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.

==== Sync Office 365 profile photos to Moodle on login ====

User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.

==== Perform a full sync each run ====

By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.

==== Match Azure usernames to moodle emails instead of moodle usernames during the sync ====

Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.

=====Cleanup OpenID Connect Tokens=====
If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors.

====Advanced settings====
=====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.
=====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 Administration > 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.

====Legacy settings====
===== 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 ======
# Visit the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft Office 365 Integration).
# 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.
## This should be the entire URL to the SharePoint site - for example: '''https://contoso.sharepoint.com/moodle'''.
## This site must be accessible to the '''System API user'''
# When you are done typing in the URL, the URL will be checked for suitability.
## If the valid is invalid, you will see a red box and the text "This is not a usable SharePoint site."
## 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.
## 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.
# Click '''Save changes''' at the bottom of the settings page.
# 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.'''.
# The SharePoint Link is set up during the Moodle cron, so ensure your Moodle cron is set up and running.

====Preview features====
=====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.

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in Team linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

=FAQ=
==How will cookie changes in Chrome version 80 affect Teams integration?==
The stable release of the Google Chrome web browser (build 80, scheduled for release on February 4, 2020) features a change in how cookies are handled. This will include two changes:
* Cookies without a '''SameSite''' attribute will be treated as SameSite=Lax.
* Cookies with '''SameSite=None''' must also specify '''Secure''', meaning they require a secure context.
The changes are explained in [https://web.dev/samesite-cookies-explained/ here] and [https://blog.chromium.org/2019/10/developers-get-ready-for-new.html here]

Moodle and Microsoft Teams integration will be affected by this change, because the integration requires embedding Moodle pages in Teams. There is [https://tracker.moodle.org/browse/MDL-67175 an open item] in Moodle tracker about this change in general, but the code change proposed in the tracker item didn't get integrated in time for the last minor Moodle upgrade before Chrome 80 release date. As a result, all sites using Moodle and Microsoft Teams integration feature are strongly suggested to apply the patches proposed in the [https://tracker.moodle.org/browse/MDL-67175 tracker item] so that users with Chrome 80 can keep using Moodle tabs in Teams after upgrade.
* Patches are provided for all Moodle versions that are supported for core feature and security issues, i.e. 3.5, 3.6, 3.7 and 3.8.
* Patches are only required before this is integrated into the next Moodle minor release of the Moodle versions, which is scheduled at March 9th, 2020.
* After the next Moodle minor release, the patch should be removed as it would be integration into core Moodle code.

=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]]

Office365

2020-09-28T15:27:02Z

Enovationdevteam: /* Add a user to the app */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [http://azure.microsoft.com/en-us/pricing/free-trial/ 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. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections:
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="7" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''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
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|-
| '''offline_access'''
| Maintain access to data you have given it access to
|-
| '''email'''
| View users' email address
|-
| '''profile'''
| View users' basic profile
|}
When you're done, click '''Add permissions''' at bottom of the page.
## Click the "Grant admin consent for YOUR ORGANISATION NAME" link.

=== Enter Azure application credentials into Moodle ===
# 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:

==== Create accounts in Moodle for users in Azure AD ====
This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.

==== Update all accounts in Moodle for users in Azure AD ====
This will update all users in Moodle from each user in the linked Azure AD.

==== Delete previously synced accounts in Moodle when they are deleted from Azure AD ====
This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!

==== Match preexisting Moodle users with same-named accounts in Azure AD ====
This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are 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.

==== Assign users to application during sync ====

The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.

==== Sync Office 365 profile photos to Moodle in cron job ====

User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.

==== Sync Office 365 profile photos to Moodle on login ====

User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.

==== Perform a full sync each run ====

By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.

==== Match Azure usernames to moodle emails instead of moodle usernames during the sync ====

Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.

=====Cleanup OpenID Connect Tokens=====
If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors.

====Advanced settings====
=====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.
=====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 Administration > 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.

====Legacy settings====
===== 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 ======
# Visit the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft Office 365 Integration).
# 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.
## This should be the entire URL to the SharePoint site - for example: '''https://contoso.sharepoint.com/moodle'''.
## This site must be accessible to the '''System API user'''
# When you are done typing in the URL, the URL will be checked for suitability.
## If the valid is invalid, you will see a red box and the text "This is not a usable SharePoint site."
## 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.
## 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.
# Click '''Save changes''' at the bottom of the settings page.
# 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.'''.
# The SharePoint Link is set up during the Moodle cron, so ensure your Moodle cron is set up and running.

====Preview features====
=====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.

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in Team linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

=FAQ=
==How will cookie changes in Chrome version 80 affect Teams integration?==
The stable release of the Google Chrome web browser (build 80, scheduled for release on February 4, 2020) features a change in how cookies are handled. This will include two changes:
* Cookies without a '''SameSite''' attribute will be treated as SameSite=Lax.
* Cookies with '''SameSite=None''' must also specify '''Secure''', meaning they require a secure context.
The changes are explained in [https://web.dev/samesite-cookies-explained/ here] and [https://blog.chromium.org/2019/10/developers-get-ready-for-new.html here]

Moodle and Microsoft Teams integration will be affected by this change, because the integration requires embedding Moodle pages in Teams. There is [https://tracker.moodle.org/browse/MDL-67175 an open item] in Moodle tracker about this change in general, but the code change proposed in the tracker item didn't get integrated in time for the last minor Moodle upgrade before Chrome 80 release date. As a result, all sites using Moodle and Microsoft Teams integration feature are strongly suggested to apply the patches proposed in the [https://tracker.moodle.org/browse/MDL-67175 tracker item] so that users with Chrome 80 can keep using Moodle tabs in Teams after upgrade.
* Patches are provided for all Moodle versions that are supported for core feature and security issues, i.e. 3.5, 3.6, 3.7 and 3.8.
* Patches are only required before this is integrated into the next Moodle minor release of the Moodle versions, which is scheduled at March 9th, 2020.
* After the next Moodle minor release, the patch should be removed as it would be integration into core Moodle code.

=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]]

Office365

2020-09-28T15:26:36Z

Enovationdevteam: /* Configuration */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [http://azure.microsoft.com/en-us/pricing/free-trial/ 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. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

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

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

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

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections:
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="7" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''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
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|-
| '''offline_access'''
| Maintain access to data you have given it access to
|-
| '''email'''
| View users' email address
|-
| '''profile'''
| View users' basic profile
|}
When you're done, click '''Add permissions''' at bottom of the page.
## Click the "Grant admin consent for YOUR ORGANISATION NAME" link.

===== Add a user to the app =====
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section.
# Click on the '''Enterprise applications''' from '''Manage''' section on the left.
# Click on the App you created for Moodle. Note this page lists all applications of all types, so make sure the right one is chosen in case there are applications with duplicate names.
# Click '''Users and groups''' under the '''Manage''' section.
# Add users to your application using the '''Add user''' button. Eventually all users who need to access Moodle from Office365 need to be added here. If the amount of users is large, they can be put into a group and added together.

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 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:

==== Create accounts in Moodle for users in Azure AD ====
This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.

==== Update all accounts in Moodle for users in Azure AD ====
This will update all users in Moodle from each user in the linked Azure AD.

==== Delete previously synced accounts in Moodle when they are deleted from Azure AD ====
This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!

==== Match preexisting Moodle users with same-named accounts in Azure AD ====
This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are 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.

==== Assign users to application during sync ====

The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.

==== Sync Office 365 profile photos to Moodle in cron job ====

User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.

==== Sync Office 365 profile photos to Moodle on login ====

User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.

==== Perform a full sync each run ====

By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.

==== Match Azure usernames to moodle emails instead of moodle usernames during the sync ====

Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.

=====Cleanup OpenID Connect Tokens=====
If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors.

====Advanced settings====
=====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.
=====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 Administration > 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.

====Legacy settings====
===== 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 ======
# Visit the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft Office 365 Integration).
# 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.
## This should be the entire URL to the SharePoint site - for example: '''https://contoso.sharepoint.com/moodle'''.
## This site must be accessible to the '''System API user'''
# When you are done typing in the URL, the URL will be checked for suitability.
## If the valid is invalid, you will see a red box and the text "This is not a usable SharePoint site."
## 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.
## 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.
# Click '''Save changes''' at the bottom of the settings page.
# 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.'''.
# The SharePoint Link is set up during the Moodle cron, so ensure your Moodle cron is set up and running.

====Preview features====
=====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.

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in Team linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

=FAQ=
==How will cookie changes in Chrome version 80 affect Teams integration?==
The stable release of the Google Chrome web browser (build 80, scheduled for release on February 4, 2020) features a change in how cookies are handled. This will include two changes:
* Cookies without a '''SameSite''' attribute will be treated as SameSite=Lax.
* Cookies with '''SameSite=None''' must also specify '''Secure''', meaning they require a secure context.
The changes are explained in [https://web.dev/samesite-cookies-explained/ here] and [https://blog.chromium.org/2019/10/developers-get-ready-for-new.html here]

Moodle and Microsoft Teams integration will be affected by this change, because the integration requires embedding Moodle pages in Teams. There is [https://tracker.moodle.org/browse/MDL-67175 an open item] in Moodle tracker about this change in general, but the code change proposed in the tracker item didn't get integrated in time for the last minor Moodle upgrade before Chrome 80 release date. As a result, all sites using Moodle and Microsoft Teams integration feature are strongly suggested to apply the patches proposed in the [https://tracker.moodle.org/browse/MDL-67175 tracker item] so that users with Chrome 80 can keep using Moodle tabs in Teams after upgrade.
* Patches are provided for all Moodle versions that are supported for core feature and security issues, i.e. 3.5, 3.6, 3.7 and 3.8.
* Patches are only required before this is integrated into the next Moodle minor release of the Moodle versions, which is scheduled at March 9th, 2020.
* After the next Moodle minor release, the patch should be removed as it would be integration into core Moodle code.

=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]]

Office365

2020-09-28T14:42:32Z

Enovationdevteam: /* Plugins & Features */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= Plugins & Features =
The Office 365 set of plugins contains 5 core plugins, and 4 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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. It 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.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** 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 Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Office 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Office 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

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

* '''Office 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [[http://azure.microsoft.com/en-us/pricing/free-trial/ Microsoft Azure Sign Up]]

To use Moodle with Office 365 for SSO, you must [https://manage.windowsazure.com configure Microsoft Azure] to manage your Office 365 Microsoft Azure Active Directory:
# Create a new Active Directory.
# Select Use existing directory.
# Select '''I am ready to be signed out now''' and click the check mark.
# Sign in with your Office 365 subscription credentials.
# Click '''Continue'''.
# 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 ===
The easiest way to register application in Azure is to run the PowerShell script downloaded from the plugin configuration page. Go to '''Site Administration > Plugins > Local plugins > Microsoft Office 365 Integration''', it's the '''Download PowerShell Script''' button in the '''Setup''' tab. You should only follow the manual process if you are unable to setup the AzureAd app via PowerShell script.

The manual steps are:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

=== Configure application ===
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click on the App you created for Moodle.
## You may need to change the dropdown from "My apps" to "All apps"
# Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
# Click on the display name of the App to open its settings.
# From the menu on the left, go to '''Certificates & secrets''' link in '''Manage''' section.
# Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
# Configure '''Azure Activity Directory Graph''' Permissions
## Click the '''API permissions''' link in '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''', then choose '''Azure Active Directory Graph''' from '''Supported legacy APIs''' section.
## Click the checkbox for '''User.Read''' permissions in each of the "Delegated" permissions sections.
# Configure '''Microsoft Graph''' Permissions
## Click the '''API permissions''' link in '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''', then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections:
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="7" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''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
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Add a user to the app ===
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section.
# Click on the '''Enterprise applications''' from '''Manage''' section on the left.
# Click on the App you created for Moodle. Note this page lists all applications of all types, so make sure the right one is chosen in case there are applications with duplicate names.
# Click '''Users and groups''' under the '''Manage''' section.
# Add users to your application using the '''Add user''' button. Eventually all users who need to access Moodle from Office365 need to be added here. If the amount of users is large, they can be put into a group and added together.

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 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:

==== Create accounts in Moodle for users in Azure AD ====
This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.

==== Update all accounts in Moodle for users in Azure AD ====
This will update all users in Moodle from each user in the linked Azure AD.

==== Delete previously synced accounts in Moodle when they are deleted from Azure AD ====
This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!

==== Match preexisting Moodle users with same-named accounts in Azure AD ====
This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are 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.

==== Assign users to application during sync ====

The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.

==== Sync Office 365 profile photos to Moodle in cron job ====

User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.

==== Sync Office 365 profile photos to Moodle on login ====

User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.

==== Perform a full sync each run ====

By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.

==== Match Azure usernames to moodle emails instead of moodle usernames during the sync ====

Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.

=====Cleanup OpenID Connect Tokens=====
If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors.

====Advanced settings====
=====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.
=====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 Administration > 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.

====Legacy settings====
===== 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 ======
# Visit the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft Office 365 Integration).
# 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.
## This should be the entire URL to the SharePoint site - for example: '''https://contoso.sharepoint.com/moodle'''.
## This site must be accessible to the '''System API user'''
# When you are done typing in the URL, the URL will be checked for suitability.
## If the valid is invalid, you will see a red box and the text "This is not a usable SharePoint site."
## 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.
## 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.
# Click '''Save changes''' at the bottom of the settings page.
# 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.'''.
# The SharePoint Link is set up during the Moodle cron, so ensure your Moodle cron is set up and running.

====Preview features====
=====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.

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in Team linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

=FAQ=
==How will cookie changes in Chrome version 80 affect Teams integration?==
The stable release of the Google Chrome web browser (build 80, scheduled for release on February 4, 2020) features a change in how cookies are handled. This will include two changes:
* Cookies without a '''SameSite''' attribute will be treated as SameSite=Lax.
* Cookies with '''SameSite=None''' must also specify '''Secure''', meaning they require a secure context.
The changes are explained in [https://web.dev/samesite-cookies-explained/ here] and [https://blog.chromium.org/2019/10/developers-get-ready-for-new.html here]

Moodle and Microsoft Teams integration will be affected by this change, because the integration requires embedding Moodle pages in Teams. There is [https://tracker.moodle.org/browse/MDL-67175 an open item] in Moodle tracker about this change in general, but the code change proposed in the tracker item didn't get integrated in time for the last minor Moodle upgrade before Chrome 80 release date. As a result, all sites using Moodle and Microsoft Teams integration feature are strongly suggested to apply the patches proposed in the [https://tracker.moodle.org/browse/MDL-67175 tracker item] so that users with Chrome 80 can keep using Moodle tabs in Teams after upgrade.
* Patches are provided for all Moodle versions that are supported for core feature and security issues, i.e. 3.5, 3.6, 3.7 and 3.8.
* Patches are only required before this is integrated into the next Moodle minor release of the Moodle versions, which is scheduled at March 9th, 2020.
* After the next Moodle minor release, the patch should be removed as it would be integration into core Moodle code.

=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]]

Office365

2020-09-28T14:36:34Z

Enovationdevteam: /* Requirements */

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams
|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 =
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.5 or above. The plugins are available for Moodle versions 2.7 are above. Features available in each version, and the support status vary.

= 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 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''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_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

== 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 [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 =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Office 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

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

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 ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/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.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any 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.
### 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 [[http://azure.microsoft.com/en-us/pricing/free-trial/ Microsoft Azure Sign Up]]

To use Moodle with Office 365 for SSO, you must [https://manage.windowsazure.com configure Microsoft Azure] to manage your Office 365 Microsoft Azure Active Directory:
# Create a new Active Directory.
# Select Use existing directory.
# Select '''I am ready to be signed out now''' and click the check mark.
# Sign in with your Office 365 subscription credentials.
# Click '''Continue'''.
# 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 ===
The easiest way to register application in Azure is to run the PowerShell script downloaded from the plugin configuration page. Go to '''Site Administration > Plugins > Local plugins > Microsoft Office 365 Integration''', it's the '''Download PowerShell Script''' button in the '''Setup''' tab. You should only follow the manual process if you are unable to setup the AzureAd app via PowerShell script.

The manual steps are:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

=== Configure application ===
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click on the App you created for Moodle.
## You may need to change the dropdown from "My apps" to "All apps"
# Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
# Click on the display name of the App to open its settings.
# From the menu on the left, go to '''Certificates & secrets''' link in '''Manage''' section.
# Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need later.
# Configure '''Azure Activity Directory Graph''' Permissions
## Click the '''API permissions''' link in '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''', then choose '''Azure Active Directory Graph''' from '''Supported legacy APIs''' section.
## Click the checkbox for '''User.Read''' permissions in each of the "Delegated" permissions sections.
# Configure '''Microsoft Graph''' Permissions
## Click the '''API permissions''' link in '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''', then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections:
{| class="nicetable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="7" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Office 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''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
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Office 365, and to access Office 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Office 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Office 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Office 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Office 365 (required for all integration).
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Add a user to the app ===
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section.
# Click on the '''Enterprise applications''' from '''Manage''' section on the left.
# Click on the App you created for Moodle. Note this page lists all applications of all types, so make sure the right one is chosen in case there are applications with duplicate names.
# Click '''Users and groups''' under the '''Manage''' section.
# Add users to your application using the '''Add user''' button. Eventually all users who need to access Moodle from Office365 need to be added here. If the amount of users is large, they can be put into a group and added together.

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 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 Office 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft Office 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## 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'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''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.
## '''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.
## '''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/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== 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.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== 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.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Office 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
# 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.

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

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

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

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

There are several options that affect user sync:

==== Create accounts in Moodle for users in Azure AD ====
This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their 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.

==== Update all accounts in Moodle for users in Azure AD ====
This will update all users in Moodle from each user in the linked Azure AD.

==== Delete previously synced accounts in Moodle when they are deleted from Azure AD ====
This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!

==== Match preexisting Moodle users with same-named accounts in Azure AD ====
This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are 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.

==== Assign users to application during sync ====

The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.

==== Sync Office 365 profile photos to Moodle in cron job ====

User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.

==== Sync Office 365 profile photos to Moodle on login ====

User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.

==== Perform a full sync each run ====

By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.

==== Match Azure usernames to moodle emails instead of moodle usernames during the sync ====

Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# 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.

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

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

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

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

==== Teams vs Group ====
Microsoft Teams share the same base with Office 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to an Office 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Office 365 user, only a group will be created.

== Advanced settings ==
=== 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.

=====Cleanup OpenID Connect Tokens=====
If your users are experiencing problems logging in using their Office 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors.

====Advanced settings====
=====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.
=====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 Administration > 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.

====Legacy settings====
===== 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 ======
# Visit the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft Office 365 Integration).
# 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.
## This should be the entire URL to the SharePoint site - for example: '''https://contoso.sharepoint.com/moodle'''.
## This site must be accessible to the '''System API user'''
# When you are done typing in the URL, the URL will be checked for suitability.
## If the valid is invalid, you will see a red box and the text "This is not a usable SharePoint site."
## 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.
## 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.
# Click '''Save changes''' at the bottom of the settings page.
# 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.'''.
# The SharePoint Link is set up during the Moodle cron, so ensure your Moodle cron is set up and running.

====Preview features====
=====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.

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in Team linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Office 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Office 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft Office 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft Office 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft Office 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft Office 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

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

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

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

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

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the 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)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== 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:
# 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.
# The user is redirected to Office 365 to log in.
# 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:
# The user enters their Office 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Office 365 for verification.
# 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.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# Click the '''Office 365 Login'' link under '''Office 365 Features'''
# 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.
## '''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.
# The Moodle account will now use Office 365 to log in. '''The previous login method will not work.'''
# 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 ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Office 365''' link in the Microsoft block.
# You will be brought to the '''Office 365 / Moodle Control Panel'''.
# 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.
## '''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 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 ==
# 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".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''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.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## 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.
## 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.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

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

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

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

# 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.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# 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"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# 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 [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.

=FAQ=
==How will cookie changes in Chrome version 80 affect Teams integration?==
The stable release of the Google Chrome web browser (build 80, scheduled for release on February 4, 2020) features a change in how cookies are handled. This will include two changes:
* Cookies without a '''SameSite''' attribute will be treated as SameSite=Lax.
* Cookies with '''SameSite=None''' must also specify '''Secure''', meaning they require a secure context.
The changes are explained in [https://web.dev/samesite-cookies-explained/ here] and [https://blog.chromium.org/2019/10/developers-get-ready-for-new.html here]

Moodle and Microsoft Teams integration will be affected by this change, because the integration requires embedding Moodle pages in Teams. There is [https://tracker.moodle.org/browse/MDL-67175 an open item] in Moodle tracker about this change in general, but the code change proposed in the tracker item didn't get integrated in time for the last minor Moodle upgrade before Chrome 80 release date. As a result, all sites using Moodle and Microsoft Teams integration feature are strongly suggested to apply the patches proposed in the [https://tracker.moodle.org/browse/MDL-67175 tracker item] so that users with Chrome 80 can keep using Moodle tabs in Teams after upgrade.
* Patches are provided for all Moodle versions that are supported for core feature and security issues, i.e. 3.5, 3.6, 3.7 and 3.8.
* Patches are only required before this is integrated into the next Moodle minor release of the Moodle versions, which is scheduled at March 9th, 2020.
* After the next Moodle minor release, the patch should be removed as it would be integration into core Moodle code.

=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]]