Commit 24e67427 authored by Stan Hu's avatar Stan Hu

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

Add documentation for configuring Microsoft Graph with MailRoom

See merge request gitlab-org/gitlab!59084
parents c21a079c 4304d511
......@@ -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.
......@@ -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).
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment