msgraph-api

Msgraph::Api

Client to connect to Microsoft's Graph API (Office365). As Microsoft will discontinue support for basic auth on IMAP, POP3, EWS,... we sought for a way to access exchange mail servers using modern APIs and state of the art authentication. Microsofts recommendation for this is Microsoft Graph API, and there is already a basic implementation that enables ActionMailer to use this API by Gitlab's microsoft_graph_mailer gem (Excellent work, thanks!). This gem is using microsoft_graph_mailer as a basis to build an API to access exchange mail servers not only for sending APIs but also for receiving and managing messages. Still this gem integrates with ActionMailer the same way microsoft_graph_mailer does.

Authentication is based on Azure AD's OAuth2 method. In order to login you need to register an application in Azure AD, with appropriate permissions. For OAuth2 access you will also need to create a client secret.

Installation

Add this line to your application's Gemfile:

gem 'msgraph-api'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install msgraph-api

Usage

require "msgraph/api"

settings = {
  user_id: "<user id in azure AD>"
  tenant: "<tenant id in azure>"
  client_id: "<client id of the registered app>"
  client_secret: "<secret token of the registered app>"
}

client = Msgraph::Api.open(settings)

puts "My name is #{client.me.display_name}."
puts "I live in Greenwhich."
puts "I have #{client.me.messages.size} mails."
puts "'#{client.me.mail_folders.last.messages.first.subject}' is my first mail in last folder."
puts "'#{client.me.mail_folders.find("<unique id">).display_name}' is directly accessible, too."

Fields of MS Graph API's responses are mapped to appropriate methods. Naming of those methods adheres to ruby conventions, e.g. a displayName attribute will be accessible by a getter named display_name. The client implements lazy loading, that is, actual requests are executed only when an attribute is being accessed. So be aware that find(<id>) may return a valid object, but still it may raise an error later when an attribute is being read. Maybe the ID passed as parameter is invalid. This is because the actual request to MS Graph API is triggered by the later read access. As long as no attribute is being accessed, the only attribute of the object in this example will remain ID passed as parameter to find().

Microsoft provides an extraordinary tool for testing queries to MS Graph API in https://developer.microsoft.com/de-de/graph/graph-explorer, which is also very adequate for looking up fields in responses.

Contributing

Bug reports and pull requests are welcome on Gitlab at https://gitlab.com/digitalwerk/community/gems/msgraph-api.