microsoft_graph_mailer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 12632ade885e197f206aa7cbdaa9be6770820b9a47de70eeaf092f606928c911
+  data.tar.gz: 409fee6a54f49282b55cb8384a3d4e279e747de350fae421438b19fd43624a28
+SHA512:
+  metadata.gz: 156c69eebea594d1aa1a554155cc4fb82aeeca74085fe8bd87f90e66f01a88a041ce0044a3ddbcff05cd4175394b825bc51a2a97d9910454a4e6b122e5b07761
+  data.tar.gz: 2ed8b199e9f26d0629f78a153c857fe13b1645a99515c3f21c3db9527503f293b933d47429d01e0df277a82a2f0da6ba469ee1720999e674dc14ccba8a1693fa

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 GitLab B.V.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/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"
+}
+```

data/lib/microsoft_graph_mailer/client.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "oauth2"
+
+module MicrosoftGraphMailer
+  class Client
+    attr_accessor :user_id, :tenant, :client_id, :client_secret, :azure_ad_endpoint, :graph_endpoint
+
+    def initialize(user_id:, tenant:, client_id:, client_secret:, azure_ad_endpoint:, graph_endpoint:)
+      @user_id = user_id
+      @tenant = tenant
+      @client_id = client_id
+      @client_secret = client_secret
+      @azure_ad_endpoint = azure_ad_endpoint
+      @graph_endpoint = graph_endpoint
+    end
+
+    def send_mail(message_in_mime_format)
+      # https://docs.microsoft.com/en-us/graph/api/user-sendmail
+      token.post(
+        send_mail_url,
+        headers: { "Content-type" => "text/plain" },
+        body: Base64.encode64(message_in_mime_format)
+      )
+    end
+
+    private
+
+    def token
+      # https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow
+      OAuth2::Client.new(
+        client_id,
+        client_secret,
+        site: azure_ad_endpoint,
+        token_url: "/#{tenant}/oauth2/v2.0/token"
+      ).client_credentials.get_token({ scope: scope })
+    end
+
+    def scope
+      "#{graph_endpoint}/.default"
+    end
+
+    def base_url
+      "#{graph_endpoint}/v1.0/users/#{user_id}"
+    end
+
+    def send_mail_url
+      "#{base_url}/sendMail"
+    end
+  end
+end

data/lib/microsoft_graph_mailer/delivery.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "client"
+
+module MicrosoftGraphMailer
+  class Delivery
+    attr_reader :microsoft_graph_settings
+
+    def initialize(microsoft_graph_settings)
+      @microsoft_graph_settings = microsoft_graph_settings
+
+      [:user_id, :tenant, :client_id, :client_secret].each do |setting|
+        unless microsoft_graph_settings[setting]
+          raise MicrosoftGraphMailer::ConfigurationError, "'#{setting}' is missing"
+        end
+      end
+
+      @microsoft_graph_settings[:azure_ad_endpoint] ||= "https://login.microsoftonline.com"
+      @microsoft_graph_settings[:graph_endpoint] ||= "https://graph.microsoft.com"
+    end
+
+    def deliver!(message)
+      # https://github.com/mikel/mail/pull/872
+      if message[:bcc]
+        previous_message_bcc_include_in_headers = message[:bcc].include_in_headers
+        message[:bcc].include_in_headers = true
+      end
+
+      message_in_mime_format = message.encoded
+
+      client = MicrosoftGraphMailer::Client.new(
+        user_id: microsoft_graph_settings[:user_id],
+        tenant: microsoft_graph_settings[:tenant],
+        client_id: microsoft_graph_settings[:client_id],
+        client_secret: microsoft_graph_settings[:client_secret],
+        azure_ad_endpoint: microsoft_graph_settings[:azure_ad_endpoint],
+        graph_endpoint: microsoft_graph_settings[:graph_endpoint]
+      )
+
+      response = client.send_mail(message_in_mime_format)
+
+      raise MicrosoftGraphMailer::DeliveryError unless response.status == 202
+
+      response
+    ensure
+      message[:bcc].include_in_headers = previous_message_bcc_include_in_headers if message[:bcc]
+    end
+  end
+end

data/lib/microsoft_graph_mailer/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "delivery"
+
+module MicrosoftGraphMailer
+  class Railtie < Rails::Railtie
+    ActiveSupport.on_load(:action_mailer) do
+      add_delivery_method :microsoft_graph, MicrosoftGraphMailer::Delivery
+    end
+  end
+end

data/lib/microsoft_graph_mailer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MicrosoftGraphMailer
+  VERSION = "0.1.0"
+end

data/lib/microsoft_graph_mailer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "microsoft_graph_mailer/delivery"
+require_relative "microsoft_graph_mailer/railtie" if defined?(Rails::Railtie)
+require_relative "microsoft_graph_mailer/version"
+
+module MicrosoftGraphMailer
+  class Error < StandardError
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class DeliveryError < Error
+  end
+end

metadata

@@ -0,0 +1,143 @@
+--- !ruby/object:Gem::Specification
+name: microsoft_graph_mailer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Bogdan Denkovych
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-09-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.4.4
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.4.4
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.11.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.11.0
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.18.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.18.1
+description: 
+email:
+- bdenkovych@gitlab.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/microsoft_graph_mailer.rb
+- lib/microsoft_graph_mailer/client.rb
+- lib/microsoft_graph_mailer/delivery.rb
+- lib/microsoft_graph_mailer/railtie.rb
+- lib/microsoft_graph_mailer/version.rb
+homepage: https://gitlab.com/gitlab-org/gitlab/-/tree/master/vendor/gems/microsoft_graph_mailer
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://gitlab.com/gitlab-org/gitlab/-/tree/master/vendor/gems/microsoft_graph_mailer
+  source_code_uri: https://gitlab.com/gitlab-org/gitlab/-/tree/master/vendor/gems/microsoft_graph_mailer
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.22
+signing_key: 
+specification_version: 4
+summary: Allows delivery of emails using Microsoft Graph API with OAuth 2.0 client
+  credentials flow
+test_files: []