Enabling Tines for Microsoft Graph security automation

NOTE: This blog was created using an old version of the Microsoft Application Registration Portal. For new instructions, please follow our new guide here.

If your organization leverages Office 365, Microsoft Graph provides programmatic access to a wealth of data that 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, organizational 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 “My applications” page, choose “Add an app”.

Enter an application name and press “Create”:

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”.

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:</tenant-name>

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’.

Step 2 – Creating a Tines credential 

Next, we now need to create a Tines credential that corresponds to the application we’ve just registered. We will use this credential in our Action’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 to 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:

Oauth url: https://login.microsoftonline.com//oauth2/v2.0/authorize
Oauth token url: https://login.microsoftonline.com//oauth2/v2.0/token

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:

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.

Step 3 – Creating a Tines Action 

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

Graph Explorer is a very useful tool for understanding how to interact with the data in Graph. Using 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:

https://graph.microsoft.com/v1.0/me/messages

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

{
  "url": "https://graph.microsoft.com/v1.0/me/messages",
  "method": "get",
  "headers": {
    "Authorization": "Bearer {% credential Ms_graph %}"
  },
  "expected_update_period_in_days": "1"
}

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

Summary 

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 to refocus on higher-impact activities.

References 

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

NOTE: This blog was created using an old version of the Microsoft Application Registration Portal. For new instructions, please follow our new guide here.

*We recently updated our terminology. Our "agents" are now known as "Actions," but some visuals might not reflect this.*