Fixes #733 - Add M365 Graph channel guide

channels/email/accounts/account-setup.rst

@@ -27,7 +27,8 @@ The import process does things you might not expect:
 
    **Microsoft 365 users:**
       To add a Microsoft 365 account, create a dedicated
-      :doc:`Microsoft 365 channel </channels/microsoft365/accounts/account-setup>`.
+      :doc:`Microsoft 365 IMAP Email channel </channels/microsoft365/accounts>` or
+      :doc:`Microsoft 365 Graph Email channel </channels/microsoft365-graph/accounts>`.
 
 Basic
 -----

channels/email/index.rst

@@ -29,7 +29,9 @@ Control how Zammad **sends and receives email**.
    At this moment Zammad supports XOAUTH for the following providers:
 
       * :ref:`Google <migrate-channel>`
-      * :doc:`Microsoft 365 (formerly Office 365) </channels/microsoft365/accounts/migrate-from-email-channel>`
+      * Microsoft 365 (formerly Office 365)
+        * `Microsoft 365 IMAP Email </channels/microsoft365/accounts/migrate-from-email-channel>` (formerly Microsoft 365)
+        * `Microsoft 365 Graph Email </channels/microsoft365-graph/index/>`
 
    Use above links to use the migration option instead of removing and re-adding
    the channels. This will save precious time for something else!
@@ -43,6 +45,8 @@ Control how Zammad **sends and receives email**.
    (Self-hosted users may have already completed this step
    during new system setup.)
 
+   .. start-after-accounts
+
 :doc:`🗂️ Filters <filters>`
    **Make sure new tickets show up in the right place**
    with automated, if-this-then-that rules for all incoming email.

channels/google/index.rst

@@ -1,5 +1,5 @@
-Google
-======
+Google Email
+============
 
 .. toctree::
    :hidden:
@@ -12,7 +12,7 @@ Google
    settings
    email-headers
 
-Connect a Gmail or G Suite account to Zammad.
+Connect a Google Email account to Zammad.
 
 .. figure:: /images/channels/google/panel.png
    :alt: Google channel settings panel

channels/microsoft365-graph/accounts.rst

@@ -0,0 +1,163 @@
+Accounts
+========
+
+You can connect to user and shared mailboxes in your M365 environment.
+Follow the steps below and skip not applicable parts.
+
+First Steps
+-----------
+
+- Check your FQDN under *Settings > System > Fully Qualified Domain Name* in the
+  admin interface of Zammad. If it is not correct, change it now. Otherwise the
+  setup of the channel will fail.
+- Go to *Channels > Microsoft 365 Graph Email* and click on
+  **Connect Microsoft 365 App**. Copy the provided callback URL.
+
+Configuration
+----------------
+
+Go to Microsoft's `Entra admin center <https://entra.microsoft.com/#home>`_ and
+log in as an administrator (at least application administrator permission is
+required).
+
+Create App
+^^^^^^^^^^
+
+.. figure:: /images/channels/microsoft365-graph/register-app.png
+  :align: center
+  :alt: Screenshot shows Entra admin center with application registration screen.
+
+- Create a new app by going to *Applications > App registrations* and select
+  **New registration**.
+- Enter a fitting name and select an account type. Supported types are:
+
+  - Accounts in this organizational directory only (Single tenant)
+  - Accounts in any organizational directory (Multitenant)
+
+- Under "Redirect URI", select "Web" as platform and paste your already copied
+  callback URL from Zammad.
+- Click on **Register**.
+
+
+.. figure:: /images/channels/microsoft365-graph/app-overview.png
+  :align: center
+  :alt: Screenshot shows Entra admin center with application overview screen.
+
+- In the overview screen, copy the "Application (client) ID", switch to Zammad
+  and paste it in the "Client ID" field in the pop up.
+- Only required for single tenant setup: copy the "Directory (tenant) ID" and
+  paste it in the "Tenant UUID/Name" field in Zammad.
+
+Create Secret
+^^^^^^^^^^^^^
+
+.. figure:: /images/channels/microsoft365-graph/secret.png
+  :align: center
+  :alt: Screenshot shows Entra admin center with client secret screen.
+
+- In Entra, go to "Certificates & secrets" and add a secret by clicking the
+  **New client secret** button.
+- Enter a description, set an expiry duration and click **Add**.
+- Copy the string under "Value", this is the secret. Paste it to Zammad
+  in the "Client Secret" field.
+
+Configure API Permissions
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. figure:: /images/channels/microsoft365-graph/api-permissions.png
+  :align: center
+  :alt: Screenshot shows Entra admin center with api permission screen.
+
+- Go to "API permissions" and **Add a permission**.
+- Select "Microsoft Graph" and "Delegated permissions".
+- Add the following permissions:
+
+  - ``offline_access``
+  - ``openid``
+  - ``profile``
+  - ``Mail.ReadWrite``
+  - ``Mail.Send``
+  - ``Mail.ReadWrite.Shared``
+  - ``Mail.Send.Shared``
+
+Save it by clicking the **Add permissions** button.
+
+Additional Steps for Shared Mailboxes
+-------------------------------------
+
+If you want to fetch email from a shared mailbox, you have to perform additional
+steps:
+
+- Log in to the `Exchange admin center <https://admin.exchange.microsoft.com>`_.
+- Go to *Recipients > Mailboxes*, select the mailbox and click on **Mailboxes
+  delegation**.
+- Under "Send as", click on **Edit** and **Add members**. Search and select the
+  user from which you want to access the mailbox and **Save** it.
+- Do the same for "Read and manage (Full Access)".
+
+
+Configure the Channel in Zammad
+-------------------------------
+
+App Configuration
+^^^^^^^^^^^^^^^^^
+
+.. figure:: /images/channels/microsoft365-graph/connect-app-dialog.png
+  :align: center
+  :alt: Screenshot shows Zammad's app configuration dialog.
+
+If you followed this guide, you already should have pasted your app information.
+If not, here is a short summary:
+
+- In Zammad's channel configuration, click on **Configure App**.
+- Enter your app details:
+
+  - Client ID: *Application (client) ID*
+  - Client Secret: *Value* from client secret
+  - Tenant UUID/Name: *Directory (tenant) ID* (not required for shared mailboxes)
+- Click on **Submit**.
+
+Add Account
+^^^^^^^^^^^
+
+Now you can add your account to Zammad. Do so by clicking the **Add account**
+button in the top right corner. Select the correct mailbox type. In case you
+selected "Shared Mailbox", you have to enter the email address of the shared
+mailbox. Confirm by clicking the **Authenticate** button, enter your credentials
+and confirm the requested permissions by clicking the **Accept** button.
+
+.. figure:: /images/channels/microsoft365-graph/add-account-dialog.png
+  :align: center
+  :alt: Screenshot shows Zammad's dialog for account configuration.
+
+After that, Zammad will ask you to assign a destination group. Select a group
+which should (initially) handle the incoming tickets of this channel. You can
+also specify a folder from which Zammad should fetch emails from. If you do so,
+make sure that the emails are routed to this folder somehow. Otherwise you won't
+receive tickets. Leave it empty to fetch all emails from the inbox. Finally,
+choose if fetched emails should remain on the server or not and confirm by
+clicking the **Save** button.
+
+Now your channel is ready and can be used! If something doesn't work, have
+a look at the :doc:`common errors section <common-errors>`, where you can
+find common errors related to the M365 configuration.
+
+
+Re-Authenticate
+^^^^^^^^^^^^^^^
+
+If your token got invalid, you have to replace the token due to other reasons,
+you want to use a shared mailbox with another user, you can use the
+**Re-Authenticate** button.
+
+In case you are using an user mailbox, the new user has to match the
+existing one, otherwise it will result in a user mismatch error. In this case,
+you should delete the channel and add a new account.
+
+Request Admin Consent
+^^^^^^^^^^^^^^^^^^^^^
+
+It is possible to request the permissions via admin consent. In this case
+Zammad will request necessary permissions for you from your admin, and then your
+admin (if it's not the same user as you) can accept them on Microsoft side.
+Trigger this process via the **Request Admin Consent** button in Zammad.

channels/microsoft365-graph/common-errors.rst

@@ -0,0 +1,46 @@
+Common Errors
+=============
+
+Here you can find some common errors in M365 context. Also have a look at
+the general
+:doc:`M365 documentation </channels/microsoft365-graph/index>` for
+the configuration and the
+:doc:`common errors mentioned in the M365 IMAP channel <../microsoft365/common-errors>`, if
+your error is not covered here.
+
+.. hint::
+  If you try to fix a problem, make sure to remove the account after the fix first
+  and re-add it then again.
+
+Problem with User Mailbox
+-------------------------
+
+``MailboxNotEnabledForRESTAPI``
+  *The mailbox is either inactive, soft-deleted, or is hosted on-premise.*
+
+Possible reasons:
+
+- The user has no access to the mailbox.
+- The account has no mailbox at all (user mailboxes).
+
+Either grant the user access to the mailbox or assign them a license and create
+a mailbox for this user.
+
+Problem with User Permissions
+-----------------------------
+
+``ErrorItemNotFound``
+  *The specified object was not found in the store., Default folder Root not found.*
+
+Indicates that the user has no delegation permissions for the mailbox.
+Make sure that the permissions are set correctly or consider using another
+account.
+
+Problem with Shared Mailbox
+---------------------------
+
+``ErrorInvalidUser``
+  *The requested user '\*' is invalid.*
+
+Possible reason could be that the shared mailbox you provided is wrong.
+Check if the provided shared mailbox email address is correct.

channels/microsoft365-graph/email-headers.rst

@@ -0,0 +1,8 @@
+.. note::
+
+   Header based actions in Microsoft 365 channels work in the same way as
+   in email channels.
+   This is why the section has been adopted verbatim from
+   :doc:`here </channels/email/email-headers>`.
+
+.. include:: /channels/email/email-headers.rst

channels/microsoft365-graph/filters.rst

@@ -0,0 +1,7 @@
+.. note::
+
+   Filters in Microsoft 365 channels work in the same way as in email channels.
+   This is why the section has been adopted verbatim from
+   :doc:`here </channels/email/filters>`.
+
+.. include:: /channels/email/filters.rst

channels/microsoft365-graph/filters/system-filters.rst

@@ -0,0 +1,7 @@
+.. note::
+
+   System Filters in Microsoft 365 channels work in the same way as in email
+   channels. This is why the section has been adopted verbatim from
+   :doc:`here </channels/email/filters/system-filters>`.
+
+.. include:: /channels/email/filters/system-filters.rst

channels/microsoft365-graph/index.rst

@@ -0,0 +1,35 @@
+Microsoft 365 Graph Email
+=========================
+
+.. toctree::
+   :hidden:
+
+   accounts
+   filters
+   signatures
+   settings
+   email-headers
+   common-errors
+
+Connect a Microsoft 365 account (formerly "Office 365") via Graph API to Zammad.
+
+.. figure:: /images/channels/microsoft365-graph/panel.png
+   :alt: Email settings panel
+   :align: center
+
+.. note:: Microsoft 365 channels are a specialized kind of
+   :doc:`📨 email channel </channels/email/index>`.
+
+   This documentation part does not cover
+   :doc:`🗝 user authentication </settings/security/third-party/microsoft>`.
+
+   If you're already familiar with email channels,
+   you can skip most of this - but **watch out for the “Accounts” section**,
+   which has a few extra quirks due to Microsoft's strict security measures.
+
+.. include:: /channels/email/index.rst
+   :start-after: .. start-after-migration
+   :end-before: Extra Options for Self-Hosted Users
+
+:doc:`🛟 Common M365 errors </channels/microsoft365/common-errors>`
+   Here you can find common errors and how to fix them.

channels/microsoft365-graph/settings.rst

@@ -0,0 +1,7 @@
+.. note::
+
+   Settings in Microsoft 365 channels work in the same way as in email channels.
+   This is why the section has been adopted verbatim from
+   :doc:`here </channels/email/settings>`.
+
+.. include:: /channels/email/settings.rst

channels/microsoft365-graph/signatures.rst

@@ -0,0 +1,7 @@
+.. note::
+
+   Signatures in Microsoft 365 channels work in the same way as in email channels.
+   This is why the section has been adopted verbatim from
+   :doc:`here </channels/email/signatures>`.
+
+.. include:: /channels/email/signatures.rst

channels/microsoft365/common-errors.rst

@@ -1,4 +1,4 @@
-Common errors
+Common Errors
 =============
 
 Here you can find some common errors in M365 context. Also have a look at

channels/microsoft365/index.rst

@@ -1,5 +1,5 @@
-Microsoft 365
-=============
+Microsoft 365 IMAP Email
+========================
 
 .. toctree::
    :hidden:
@@ -11,7 +11,7 @@ Microsoft 365
    email-headers
    common-errors
 
-Connect a Microsoft 365 account (formerly “Office 365”) to Zammad.
+Connect a Microsoft 365 account (formerly "Office 365") via IMAP to Zammad.
 
 .. figure:: /images/channels/microsoft365/panel.png
    :alt: Email settings panel

index.rst

@@ -44,6 +44,7 @@ Zammad Admin Documentation
    channels/chat
    channels/google/index
    channels/microsoft365/index
+   channels/microsoft365-graph/index
    channels/sms
    channels/twitter-x/twitter
    channels/facebook