If your organisation leverages Office 365, Microsoft Graph provides programmatic access to a wealth of data which can be used to better inform decision making during threat detection and response. In this post, we explore how to enable Tines for Microsoft Graph security automation. So that you can use information such as Outlook emails, organisational structure, advanced threat analytics and more in your security automation program.

Step 1 – Getting an app ID and secret for use in Microsoft Graph

Authenticating for Microsoft Graph security automation

We will authenticate to Microsoft Graph using an app ID and secret. To get these, we need to register a new application in the Microsoft Application Registration portal. Sign in with your Microsoft credentials.

From the the “My applications” page, choose “Add an app”.

Enter an application name and press “Create”:

Microsoft Application Registration Portal - Name your app for Microsoft Graph Security Automation

From the application registration page, create a new application secret using the “Generate new password” button. Take note of the generated secret (you only see it once) and the application id, we will need these when creating a Tines credential later.

Selecting the Microsoft Graph platform

Under “Platforms” choose “Add Platform”. Select “Web”.

Microsoft Application Registration Portal - What platform for Microsoft Graph Security Automation

Finding your Tines OAuth2 callback URL for Microsoft Graph secure access

We now need to specify where Microsoft Graph should send authentication responses for this application. Under “Redirect URLs”, enter the Tines Oauth2.0 callback URL for your Tines tenant. This takes the form https://<tenant-name>.tines.io/oauth2/callback and is available from the “Create credential” page under the Oauth2.0 type in your tenant. Mine is shown below:

Creating a Tines OAuth2 credential for Microsoft Graph Security Automation

Finally, we need to define the permissions this application should have, this is also referred to as the OAuth2.0 scopes. Permissions include everything from creating tasks to sending emails. A full list of permissions is available in the Microsoft Graph docs.

It is best security practice to provide the application with the minimum amount of permissions necessary to perform its required task(s).

In our example, we want to read Outlook emails using Tines, so we’ll include the Mail.read permission under “Delegated permissions”. A sample configuration is shown below. Press ‘save’.

Microsoft Application Registration Portal - complete example of Microsoft Graph Security Automation

 

Step 2 – Creating a Tines credential

Next, we now need to create a Tines credential which corresponds to the application we’ve just registered. We will use this credential in our agent’s to access Microsoft Graph security data. From your Tines tenant, choose “Credentials” and “New Credential”. From the “Type” dropdown, choose OAuth2.0. Give your credential a name, I used “Ms_graph”, but you can use whatever makes sense in your situation.

Under “client id” and “client secret” in the “Create credential” page, enter the “application id” and “application secret” from the application you just registered in Step 1.

Under scope, we’ll enter a space separated list of the permissions we used when registering the Graph application. That is: Mail.read and User.read. Additionally, we will include the offline_access scope. This scope will allow Tines request fresh access tokens as necessary.

From the “Grant type” dropdown, choose “authorization_code”.

Under “Oauth url” and “Oauth token url”, we need to tell Tines where to request authorization and access tokens. For Microsoft Graph, these URLs take the following form:

 

Though, there are a number of ways to determine your office 365 tenant id, the simplest is probably to use the whatismytenantid.com service, which uses some sort of voodoo to retrieve the id from your domain name. Plug your tenant ID into the above URLs.

Having entered all the required information into the “Create credential” page, it should look similar to the below:

Tines - example OAuth2 credential for Microsoft Graph Security Automation

When you select “Save credential”, Tines will redirect to a Microsoft account consent page, where you will be asked to authorize the application’s access to your account.

After accepting the request, Microsoft will securely redirect you to Tines.

Tines OAuth2 consent flow for Microsoft Graph Security Automation

Credential auth flow

Step 3 – Creating a Tines agent

We now have everything we need to connect Tines and Microsoft Graph. So, we’ll now use a standard Tines HTTP Request Agent to read emails from an Outlook account.

The Graph Explorer is a very useful tool for understanding how to interact with the data in Graph. Using the Graph Explorer, we can read Microsoft Graph security data. In addition, we can see that in order to read Outlook messages, we need to send a GET request to the following URL:

As such, we will create a HTTP Request with the following Options block:

Consequently When this agent runs, Tines will replace the credential widget ({% credential Ms_graph %}) with a valid access token. The event emitted by this agent will contain emails from my Outlook inbox. For example:

Tines - Event generated by Microsoft Graph Security Automation

Sumary

In conclusion, Microsoft Graph exposes an extraordinarily rich repository of data and capabilities. By using the Tines advanced security automation platform to automate interaction with Graph, security analysts can automate their Microsoft Graph security tasks, and perform more thorough threat detection and response. Of course, all while simultaneously freeing up analyst resources and allowing them refocus on higher-impact activities.

References

Microsoft Graph quickstart guide: https://developer.microsoft.com/en-us/graph/quick-start