Merge pull request #3240 from fracaron/feature/microsoft-graph-mailer

Add Microsoft Graph Mailer support

Author: sachilles

README.md

@@ -23,6 +23,7 @@
         - [External Redis Server](#external-redis-server)
         - [Linking to Redis Container](#linking-to-redis-container)
     - [Mail](#mail)
+        - [Microsoft Graph Mailer](#microsoft-graph-mailer)
         - [Reply by email](#reply-by-email)
     - [SSL](#ssl)
         - [Generation of a Self Signed Certificate](#generation-of-a-self-signed-certificate)
@@ -437,6 +438,26 @@ docker run --name gitlab -d \
 
 Please refer the [Available Configuration Parameters](#available-configuration-parameters) section for the list of SMTP parameters that can be specified.
 
+##### Microsoft Graph Mailer
+
+As Microsoft is retiring basic authentication for SMTP AUTH on Exchange Online, mail delivery via SMTP using a Microsoft 365 mailbox is no longer viable for many tenants. The image supports GitLab's native Microsoft Graph Mailer, which sends emails via the Microsoft Graph API using OAuth 2.0 client credentials.
+
+To enable it, register an application in Azure AD, grant it the `Mail.Send` **Application** permission (not Delegated), and have an administrator consent to it. Then start the container with:
+
+```bash
+docker run --name gitlab -d \
+    --env 'MICROSOFT_GRAPH_MAILER_ENABLED=true' \
+    --env 'MICROSOFT_GRAPH_MAILER_USER_ID=00000000-0000-0000-0000-000000000000' \
+    --env 'MICROSOFT_GRAPH_MAILER_TENANT=contoso.onmicrosoft.com' \
+    --env 'MICROSOFT_GRAPH_MAILER_CLIENT_ID=11111111-1111-1111-1111-111111111111' \
+    --env 'MICROSOFT_GRAPH_MAILER_CLIENT_SECRET=YOUR_CLIENT_SECRET' \
+    --env 'GITLAB_EMAIL=sender@contoso.com' \
+    --volume /srv/docker/gitlab/gitlab:/home/git/data \
+    sameersbn/gitlab:18.11.0
+```
+
+`MICROSOFT_GRAPH_MAILER_USER_ID` is the Object ID of the Microsoft 365 user whose mailbox will be used, and `GITLAB_EMAIL` must be that user's primary email address. `SMTP_ENABLED` should stay at its default (`false`) when Graph Mailer is used. Please refer the [Available Configuration Parameters](#available-configuration-parameters) section for the list of Microsoft Graph Mailer parameters that can be specified.
+
 ##### Reply by email
 
 Since version `8.0.0` GitLab adds support for commenting on issues by replying to emails.
@@ -2019,6 +2040,34 @@ Specify the `ca_path` parameter for SMTP email configuration. Defaults to `/home
 
 Specify the `ca_file` parameter for SMTP email configuration. Defaults to `/home/git/data/certs/ca.crt`.
 
+##### `MICROSOFT_GRAPH_MAILER_ENABLED`
+
+Enable mail delivery via Microsoft Graph API. Defaults to `false`. When enabled, emails are sent using OAuth 2.0 client credentials via the Microsoft Graph `sendMail` endpoint instead of SMTP. Requires an Azure App Registration with the `Mail.Send` Application permission granted and admin-consented. When both `SMTP_ENABLED` and `MICROSOFT_GRAPH_MAILER_ENABLED` are `false`, GitLab mail delivery is disabled.
+
+##### `MICROSOFT_GRAPH_MAILER_USER_ID`
+
+The Object ID (GUID) of the Microsoft 365 user to send mail as. This must match the user whose mailbox the emails are sent from. `GITLAB_EMAIL` should match the primary email address of this user.
+
+##### `MICROSOFT_GRAPH_MAILER_TENANT`
+
+The Azure AD tenant ID (GUID) or tenant domain (e.g. `contoso.onmicrosoft.com`).
+
+##### `MICROSOFT_GRAPH_MAILER_CLIENT_ID`
+
+The Application (client) ID from the Azure App Registration.
+
+##### `MICROSOFT_GRAPH_MAILER_CLIENT_SECRET`
+
+The client secret value from the Azure App Registration.
+
+##### `MICROSOFT_GRAPH_MAILER_AZURE_AD_ENDPOINT`
+
+Azure AD authority endpoint used to obtain an access token. Defaults to `https://login.microsoftonline.com`. Override for sovereign clouds (e.g. `https://login.microsoftonline.us` for Azure Government).
+
+##### `MICROSOFT_GRAPH_MAILER_GRAPH_ENDPOINT`
+
+Microsoft Graph API endpoint. Defaults to `https://graph.microsoft.com`. Override for sovereign clouds (e.g. `https://graph.microsoft.us` for Azure Government).
+
 ##### `IMAP_ENABLED`
 
 Enable mail delivery via IMAP. Defaults to `true` if `IMAP_USER` is defined, else defaults to `false`.

assets/runtime/config/gitlabhq/gitlab.yml

@@ -170,6 +170,24 @@ production: &base
     ## Disable jQuery and CSS animations
     # disable_animations: true
 
+  #start-microsoft-graph-mailer
+  # Allows delivery of emails using Microsoft Graph API with OAuth 2.0 client credentials flow.
+  microsoft_graph_mailer:
+    enabled: {{MICROSOFT_GRAPH_MAILER_ENABLED}}
+    # The unique identifier for the user. To use Microsoft Graph on behalf of the user.
+    user_id: "{{MICROSOFT_GRAPH_MAILER_USER_ID}}"
+    # The directory tenant the application plans to operate against, in GUID or domain-name format.
+    tenant: "{{MICROSOFT_GRAPH_MAILER_TENANT}}"
+    # The application ID that's assigned to your app. You can find this information in the portal where you registered your app.
+    client_id: "{{MICROSOFT_GRAPH_MAILER_CLIENT_ID}}"
+    # The client secret that you generated for your app in the app registration portal.
+    client_secret: "{{MICROSOFT_GRAPH_MAILER_CLIENT_SECRET}}"
+    # Defaults to "https://login.microsoftonline.com".
+    azure_ad_endpoint: "{{MICROSOFT_GRAPH_MAILER_AZURE_AD_ENDPOINT}}"
+    # Defaults to "https://graph.microsoft.com".
+    graph_endpoint: "{{MICROSOFT_GRAPH_MAILER_GRAPH_ENDPOINT}}"
+  #end-microsoft-graph-mailer
+
   ## Reply by email
   # Allow users to comment on issues and merge requests by replying to notification emails.
   # For documentation on how to set this up, see http://doc.gitlab.com/ce/administration/reply_by_email.html

assets/runtime/env-defaults

@@ -362,7 +362,17 @@ if [[ -n ${SMTP_USER} ]]; then
   SMTP_AUTHENTICATION=${SMTP_AUTHENTICATION:-login}
 fi
 SMTP_ENABLED=${SMTP_ENABLED:-false}
-GITLAB_EMAIL_ENABLED=${GITLAB_EMAIL_ENABLED:-${SMTP_ENABLED}}
+MICROSOFT_GRAPH_MAILER_ENABLED=${MICROSOFT_GRAPH_MAILER_ENABLED:-false}
+MICROSOFT_GRAPH_MAILER_USER_ID=${MICROSOFT_GRAPH_MAILER_USER_ID:-}
+MICROSOFT_GRAPH_MAILER_TENANT=${MICROSOFT_GRAPH_MAILER_TENANT:-}
+MICROSOFT_GRAPH_MAILER_CLIENT_ID=${MICROSOFT_GRAPH_MAILER_CLIENT_ID:-}
+MICROSOFT_GRAPH_MAILER_CLIENT_SECRET=${MICROSOFT_GRAPH_MAILER_CLIENT_SECRET:-}
+MICROSOFT_GRAPH_MAILER_AZURE_AD_ENDPOINT=${MICROSOFT_GRAPH_MAILER_AZURE_AD_ENDPOINT:-https://login.microsoftonline.com}
+MICROSOFT_GRAPH_MAILER_GRAPH_ENDPOINT=${MICROSOFT_GRAPH_MAILER_GRAPH_ENDPOINT:-https://graph.microsoft.com}
+if [[ ${SMTP_ENABLED} == true || ${MICROSOFT_GRAPH_MAILER_ENABLED} == true ]]; then
+  GITLAB_EMAIL_ENABLED=${GITLAB_EMAIL_ENABLED:-true}
+fi
+GITLAB_EMAIL_ENABLED=${GITLAB_EMAIL_ENABLED:-false}
 GITLAB_EMAIL=${GITLAB_EMAIL:-${SMTP_USER}}
 GITLAB_EMAIL_REPLY_TO=${GITLAB_EMAIL_REPLY_TO:-${GITLAB_EMAIL}}
 GITLAB_EMAIL_SUBJECT_SUFFIX=${GITLAB_EMAIL_SUBJECT_SUFFIX:-}

assets/runtime/functions

@@ -473,6 +473,24 @@ gitlab_configure_mail_delivery() {
   fi
 }
 
+gitlab_configure_microsoft_graph_mailer() {
+  if [[ ${MICROSOFT_GRAPH_MAILER_ENABLED} == true ]]; then
+    echo "Configuring gitlab::microsoft_graph_mailer..."
+    exec_as_git sed -i "/#start-microsoft-graph-mailer/d" ${GITLAB_CONFIG}
+    exec_as_git sed -i "/#end-microsoft-graph-mailer/d" ${GITLAB_CONFIG}
+    update_template ${GITLAB_CONFIG} \
+      MICROSOFT_GRAPH_MAILER_ENABLED \
+      MICROSOFT_GRAPH_MAILER_USER_ID \
+      MICROSOFT_GRAPH_MAILER_TENANT \
+      MICROSOFT_GRAPH_MAILER_CLIENT_ID \
+      MICROSOFT_GRAPH_MAILER_CLIENT_SECRET \
+      MICROSOFT_GRAPH_MAILER_AZURE_AD_ENDPOINT \
+      MICROSOFT_GRAPH_MAILER_GRAPH_ENDPOINT
+  else
+    exec_as_git sed -i "/#start-microsoft-graph-mailer/,/#end-microsoft-graph-mailer/d" ${GITLAB_CONFIG}
+  fi
+}
+
 gitlab_configure_mailroom() {
   if [[ ${IMAP_ENABLED} == true ]]; then
     echo "Configuring gitlab::incoming_email..."
@@ -2041,6 +2059,7 @@ configure_gitlab() {
   gitlab_configure_mattermost
   gitlab_configure_project_features
   gitlab_configure_mail_delivery
+  gitlab_configure_microsoft_graph_mailer
   gitlab_configure_mailroom
   gitlab_configure_oauth
   gitlab_configure_ldap