gitlab-org--gitlab-foss/vendor/gems/microsoft_graph_mailer

microsoft_graph_mailer

This gem allows delivery of emails using Microsoft Graph API with OAuth 2.0 client credentials flow.

The reason for this gem

See https://gitlab.com/groups/gitlab-org/-/epics/8259.

Installation

Add this line to your application's Gemfile:

gem 'microsoft_graph_mailer'

And then execute:

bundle

Or install it yourself as:

gem install microsoft_graph_mailer

Settings

To use the Microsoft Graph API to send mails, you will need to create an application in the Azure Active Directory. See the Microsoft instructions for more details:

1. Sign in to the Azure portal.
2. Search for and select Azure Active Directory.
3. Under Manage, select App registrations > New registration.
4. Enter a Name for your application, such as MicrosoftGraphMailer. Users of your app might see this name, and you can change it later.
5. If Supported account types is listed, select the appropriate option.
6. Leave Redirect URI blank. This is not needed.
7. Select Register.
8. Under Manage, select Certificates & secrets.
9. Under Client secrets, select New client secret, and enter a name.
10. Under Expires, select Never, unless you plan on updating the credentials every time it expires.
11. Select Add. Record the secret value in a safe location for use in a later step.
12. Under Manage, select API Permissions > Add a permission. Select Microsoft Graph.
13. Select Application permissions.
14. Under the Mail node, select Mail.Send. Then select Add permissions.
15. If User.Read is listed in the permission list, you can delete this.
16. Click Grant admin consent for these permissions.

• user_id - The unique identifier for the user. To use Microsoft Graph on behalf of the user.
• tenant - The directory tenant the application plans to operate against, in GUID or domain-name format.
• client_id - The application ID that's assigned to your app. You can find this information in the portal where you registered your app.
• client_secret - The client secret that you generated for your app in the app registration portal.

Usage

require "microsoft_graph_mailer"

microsoft_graph_mailer = MicrosoftGraphMailer::Delivery.new(
  {
    user_id: "YOUR-USER-ID",
    tenant: "YOUR-TENANT-ID",
    client_id: "YOUR-CLIENT-ID",
    client_secret: "YOUR-CLIENT-SECRET-ID"
    # Defaults to "https://login.microsoftonline.com".
    azure_ad_endpoint: "https://login.microsoftonline.us",
    # Defaults to "https://graph.microsoft.com".
    graph_endpoint: "https://graph.microsoft.us"
  }
)

message = Mail.new do
  from "about@gitlab.com"
  to "to@example.com"
  subject "GitLab Mission"

  html_part do
    content_type "text/html; charset=UTF-8"
    body "It is GitLab's mission to make it so that <strong>everyone can contribute</strong>."
  end
end

microsoft_graph_mailer.deliver!(message)

Usage with ActionMailer

ActionMailer::Base.delivery_method = :microsoft_graph

ActionMailer::Base.microsoft_graph_settings = {
  user_id: "YOUR-USER-ID",
  tenant: "YOUR-TENANT-ID",
  client_id: "YOUR-CLIENT-ID",
  client_secret: "YOUR-CLIENT-SECRET-ID"
  # Defaults to "https://login.microsoftonline.com".
  azure_ad_endpoint: "https://login.microsoftonline.us",
  # Defaults to "https://graph.microsoft.com".
  graph_endpoint: "https://graph.microsoft.us"
}