diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-09-20 02:18:09 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-09-20 02:18:09 +0300 |
commit | 6ed4ec3e0b1340f96b7c043ef51d1b33bbe85fde (patch) | |
tree | dc4d20fe6064752c0bd323187252c77e0a89144b /vendor/gems/microsoft_graph_mailer/README.md | |
parent | 9868dae7fc0655bd7ce4a6887d4e6d487690eeed (diff) |
Add latest changes from gitlab-org/gitlab@15-4-stable-eev15.4.0-rc42
Diffstat (limited to 'vendor/gems/microsoft_graph_mailer/README.md')
-rw-r--r-- | vendor/gems/microsoft_graph_mailer/README.md | 104 |
1 files changed, 104 insertions, 0 deletions
diff --git a/vendor/gems/microsoft_graph_mailer/README.md b/vendor/gems/microsoft_graph_mailer/README.md new file mode 100644 index 00000000000..dd9dfecfc56 --- /dev/null +++ b/vendor/gems/microsoft_graph_mailer/README.md @@ -0,0 +1,104 @@ +# microsoft_graph_mailer + +This gem allows delivery of emails using [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/api/user-sendmail) with [OAuth 2.0 client credentials flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow). + +## The reason for this gem + +See [https://gitlab.com/groups/gitlab-org/-/epics/8259](https://gitlab.com/groups/gitlab-org/-/epics/8259). + +## Installation + +Add this line to your application's Gemfile: + +```ruby +gem 'microsoft_graph_mailer' +``` + +And then execute: + +```shell +bundle +``` + +Or install it yourself as: + +```shell +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](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) for more details: + +1. Sign in to the [Azure portal](https://portal.azure.com). +1. Search for and select `Azure Active Directory`. +1. Under `Manage`, select `App registrations` > `New registration`. +1. Enter a `Name` for your application, such as `MicrosoftGraphMailer`. Users of your app might see this name, and you can change it later. +1. If `Supported account types` is listed, select the appropriate option. +1. Leave `Redirect URI` blank. This is not needed. +1. Select `Register`. +1. Under `Manage`, select `Certificates & secrets`. +1. Under `Client secrets`, select `New client secret`, and enter a name. +1. Under `Expires`, select `Never`, unless you plan on updating the credentials every time it expires. +1. Select `Add`. Record the secret value in a safe location for use in a later step. +1. Under `Manage`, select `API Permissions` > `Add a permission`. Select `Microsoft Graph`. +1. Select `Application permissions`. +1. Under the `Mail` node, select `Mail.Send`. Then select Add permissions. +1. If `User.Read` is listed in the permission list, you can delete this. +1. 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 + +```ruby +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 + +```ruby +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" +} +``` |