Merge branch 'sh-mailroom-microsoft-graph-docs' into 'master'

Add documentation for configuring Microsoft Graph with MailRoom

See merge request gitlab-org/gitlab!59084

doc/administration/incoming_email.md

@@ -615,3 +615,59 @@ incoming_email:
     # Whether the IMAP server uses SSL
     ssl: true
 ```
+
+#### Microsoft Graph
+
+> Introduced in [GitLab 13.11](https://gitlab.com/gitlab-org/gitlab/-/issues/214900).
+
+GitLab can read incoming email using the Microsoft Graph API instead of
+IMAP. Because [Microsoft is deprecating IMAP usage with Basic Authentication](https://techcommunity.microsoft.com/t5/exchange-team-blog/announcing-oauth-2-0-support-for-imap-and-smtp-auth-protocols-in/ba-p/1330432), the Microsoft Graph API will soon be required for new Microsoft Exchange Online
+mailboxes.
+
+To configure GitLab for Microsoft Graph, you will need to register an
+OAuth2 application in your Azure Active Directory that has the
+`Mail.ReadWrite` permission for all mailboxes. See the [MailRoom step-by-step guide](https://github.com/tpitale/mail_room/#microsoft-graph-configuration)
+and [Microsoft instructions](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
+for more details.
+
+Record the following when you configure your OAuth2 application:
+
+- Tenant ID for your Azure Active Directory
+- Client ID for your OAuth2 application
+- Client secret your OAuth2 application
+
+##### Restrict mailbox access
+
+For MailRoom to work as a service account, the application you create
+in Azure Active Directory requires that you set the `Mail.ReadWrite` property
+to read/write mail in *all* mailboxes.
+
+To mitigate security concerns, we recommend configuring an application access
+policy which limits the mailbox access for all accounts, as described in
+[Microsoft documentation](https://docs.microsoft.com/en-us/graph/auth-limit-mailbox-access).
+
+This example for Omnibus GitLab assumes you're using the following mailbox: `incoming@example.onmicrosoft.com`:
+
+##### Configure Microsoft Graph
+
+```ruby
+gitlab_rails['incoming_email_enabled'] = true
+
+# The email address including the `%{key}` placeholder that will be replaced
+# to reference the item being replied to. The placeholder can be omitted, but if
+# present, it must appear in the "user" part of the address (before the `@`).
+gitlab_rails['incoming_email_address'] = "incoming+%{key}@example.onmicrosoft.com"
+
+# Email account username
+gitlab_rails['incoming_email_email'] = "incoming@example.onmicrosoft.com"
+
+gitlab_rails['incoming_email_inbox_method'] = 'microsoft_graph'
+gitlab_rails['incoming_email_inbox_options'] = {
+   'tenant_id': '<YOUR-TENANT-ID>',
+   'client_id': '<YOUR-CLIENT-ID>',
+   'client_secret': '<YOUR-CLIENT-SECRET>',
+   'poll_interval': 60  # Optional
+}
+```
+
+The Microsoft Graph API is not yet supported in source installations. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/326169) for more details.

doc/user/project/service_desk.md

@@ -183,7 +183,7 @@ always use separate mailboxes. This is important, because emails picked from
 `service_desk_email` mailbox are processed by a different worker and it would
 not recognize `incoming_email` emails.
 
-To configure a custom email address for Service Desk, add the following snippets to your configuration file:
+To configure a custom email address for Service Desk with IMAP, add the following snippets to your configuration file:
 
 - Example for installations from source:
 
@@ -236,6 +236,38 @@ As a result, a new Service Desk issue is created from this email in the `mygroup
 The configuration options are the same as for configuring
 [incoming email](../../administration/incoming_email.md#set-it-up).
 
+#### Microsoft Graph
+
+> Introduced in [GitLab 13.11](https://gitlab.com/gitlab-org/gitlab/-/issues/214900)
+
+Service Desk can be configured to read Microsoft Exchange Online mailboxes with the Microsoft
+Graph API instead of IMAP. Follow the [documentation in the incoming e-mail section for setting up an OAuth2 application for Microsoft Graph](../../administration/incoming_email.md#microsoft-graph).
+
+- Example for Omnibus GitLab installations:
+
+  ```ruby
+  gitlab_rails['service_desk_email_enabled'] = true
+
+  gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com"
+
+  gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com"
+
+  gitlab_rails['service_desk_email_mailbox_name'] = "inbox"
+
+  gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log"
+
+  gitlab_rails['service_desk_inbox_method'] = 'microsoft_graph'
+
+  gitlab_rails['service_desk_inbox_options'] = {
+   'tenant_id': '<YOUR-TENANT-ID>',
+   'client_id': '<YOUR-CLIENT-ID>',
+   'client_secret': '<YOUR-CLIENT-SECRET>',
+   'poll_interval': 60  # Optional
+  }
+  ```
+
+The Microsoft Graph API is not yet supported in source installations. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/326169) for more details.
+
 ## Using Service Desk
 
 You can use Service Desk to [create an issue](#as-an-end-user-issue-creator) or [respond to one](#as-a-responder-to-the-issue).