Merge branch 'documentation-configure-absence-sync' into 'master'

Update the description and screenshots for the configuration of calendar

See merge request Chill-Projet/chill-bundles!608

docs/source/installation/msgraph-configure.rst

@@ -1,13 +1,15 @@
 
-Configure Chill for calendar sync and SSO with Microsoft Graph (Outlook)
-========================================================================
+Configure Chill for calendar and absence synchronisation and SSO with Microsoft Graph (Outlook)
+===============================================================================================
 
 Chill offers the possibility to:
 
 * authenticate users using Microsoft Graph, with relatively small adaptations;
 * synchronize calendar in both ways (`see the user manual for a large description of the feature <https://gitea.champs-libres.be/Chill-project/manuals>`_).
 
-Both can be configured separately (synchronising calendars without SSO, or SSO without calendar). When calendar sync is configured without SSL, the user's email address is the key to associate Chill's users with Microsoft's ones.
+Both can be configured separately (synchronising calendars without SSO, or SSO without calendar).
+
+Please note that the user's email address is the key to associate Chill's users with Microsoft's ones.
 
 Configure SSO
 -------------
@@ -46,7 +48,7 @@ Do not forget to provider user's accesses to your app, using the "Utilisateurs e
 
 You must know have gathered all the required variables for SSO:
 
-.. code-block:: 
+.. code-block::
 
    SAML_BASE_URL=https://test.chill.be # must be
    SAML_ENTITY_ID=https://test.chill.be # must match the one entered
@@ -186,20 +188,27 @@ Configure chill app
 
 
 
-Configure sync
---------------
+Configure sync and calendar access
+----------------------------------
 
-The sync processe might be configured in the same app, or into a different app.
+The purpose of this configuration is the following:
 
-The synchronization processes use Oauth2.0 for authentication and authorization.
+- let user read their calendar and shared calendar within Chill (with the same permissions as the one configured in Outlook / Azure);
+- allow chill instance to write appointment ("Rendez-vous") into their calendar, and invite other users to their appointment;
+- allow chill instance to be notified if an appoint is added or removed by the user within another interface than Chill: if the appointment match another one created in the Chill interface, the date and time are updated in Chill;
+- allow chill instance to read the absence of the user and, if set, mark the user as absent in Chill;
+
+The sync processe might be configured in the same app, or into a different app on the Azure side.
+
+The synchronization processes use Oauth 2.0 / OpenID Connect for authentication and authorization.
 
 .. note::
 
    Two flows are in use:
 
-   * we authenticate "on behalf of a user", to allow users to see their own calendar or other user's calendar into the web interface. 
+   * we authenticate "on behalf of a user", to allow users to see their own calendar or other user's calendar into the web interface.
 
-     Typically, when the page is loaded, Chill first check that an authorization token exists. If not, the user is redirected to Microsoft Azure for authentification and a new token is grabbed (most of the times, this is transparent for users). 
+     Typically, when the page is loaded, Chill first check that an authorization token exists. If not, the user is redirected to Microsoft Azure for authentification and a new token is grabbed (most of the times, this is transparent for users).
 
    * Chill also acts "as a machine", to synchronize calendars with a daemon background.
 
@@ -229,8 +238,9 @@ Some explanation:
 The sync daemon must have write access:
 
 * the daemon must be allowed to read all users and their profile, to establish a link between them and the Chill's users: (:code:`Users.Read.All`);
-* it must also be allowed to read and write into the calendars (:code:`Calendars.ReadWrite.All`)
-* for sending invitation to other users, the permission (:code:`Mail.Send`) must be granted.
+* it must also be allowed to read and write into the calendars (:code:`Calendars.ReadWrite.All`);
+* for sending invitation to other users, the permission (:code:`Mail.Send`) must be granted;
+* and, for reading the absence status of the user and sync it with chill, it must be able to read the mailboxSettings (:code:`MailboxSettings.Read`).
 
 At this step, you might choose to accept those permissions for all users, or let them do it by yourself.
 
@@ -301,7 +311,7 @@ The calendar synchronization is processed using symfony messenger. It seems to b
 
 The association between chill's users and Microsoft's users is done by this cli command:
 
-.. code-block:: 
+.. code-block::
 
    bin/console chill:calendar:msgraph-user-map-subscribe