Combining Microsoft Graph and Flow for Better Office 365 Adminstration

By Gustavo Velez (gustavo@gavd.net)

Leveraging the Power of the Graph

The Microsoft Graph API offers a fast and easy way to find and modify Office 365 data. Combining the Graph with Microsoft Flow makes it possible to automate the steps in a task. Some impressive results can be created even by people who don’t have a programming background.

The Microsoft Graph API is a unified programmatic RESTful interface for all the components of Office 365. Via a single REST endpoint. Microsoft Graph API provides access to objects such as users, groups, mail, messages, notes, tasks, calendar, and Office Graph. Data can be retrieved from multiple Microsoft cloud services such as Exchange, OneDrive, SharePoint, OneNote, Planner and Azure Active Directory. One of the Microsoft Graph components is the Security API, an interface and schema used to integrate security solutions from Microsoft and other vendors.

Office 365 Flow

Microsoft Flow is the automation engine in Office 365. A flow is a workflow that combines tasks and data from multiple Office 365 applications and services to get work done. To create a flow, the user specifies what action should take place when a specific event occurs. No programming experience is required.

Once a flow is built, it can be managed on the desktop or through a mobile device. Flow integrates out-of-the-box with many Office 365 services and apps, including SharePoint, Power BI, PowerApps, and Dynamics 365, but can be extended to reach other systems.

Putting Graph and Flow Together

After a tenant is up and running, it’s good to know the current state of the Office 365 services consumed by users. But monitoring services and taking any necessary actions can be a boring and tiresome activity. This kind of repetitive work can be automated using tools as Flow and Graph. And, because the creation of flows can be done by non-programmers, a flow can be quickly built by administrators.

In this article, we will use the Office 365 Secure Score as an example. Secure Score is a self-assessment tool to test the security level of an Office 365 tenant and generates an assessment of how well the tenant is protected against the risk of a security breach or attack. Secure Score is available in the Security & Compliance Center or this link. Click the Improvement actions tab to see recommendations to improve tenant security and increase the tenant’s Secure Score (Figure 1).

Viewing improvement actions for Secure Score
Figure 1: Viewing improvement actions for Secure Score

Our aim is to get the recommendations using the Microsoft Graph Security API. The idea is to generate a weekly report containing security recommendations and email it to the administrator.

First Step: Register an application in Azure Active Directory

Because Flow communicates with Graph as an “external” component, it needs to be authenticated and authorized to get information from Office 365. This is done by registering the application in the Azure AD and assigning the app the needed permissions. The first step is to open the Azure Active Directory portal and select “App registrations” and then “New registration” (Figure 2). Give the app a name, select the account type and leave the Redirect URL empty.

Registering an Azure AD app
Figure 2: Registering an Azure AD app

After the app is registered, note the “Application (client) ID” and “Directory (tenant) ID” values (Figure 3) because these data are used later in the process.

Noting important app data
Figure 3: Noting important app data

Next, grant the registration permissions to access the Graph, selecting the option “API Permissions” on the left side menu. Click on “Add permissions”, then “Microsoft Graph” and, in the new window, “Application permissions”. Because we will use the “Secure Scores” of the Security API, scroll down in the window, open the “Security” section, and select the option “SecurityEvents.Read.All” (Figure 4). Always the lowest possible access level for any app you register. Save the changes.

Selecting permissions for the app
Figure 4: Selecting the Secure Score permissions for the app

Remember to grant the permissions assigned to the application using the button in the “Grant consent” section (Figure 5).

Granting consent for the permissions
Figure 5: Granting consent for the app to receive permissions

The next step is to create a secret that allows the application to run without any user credentials. Select “Certificates and secrets” on the menu at the left side, and then click the button “New client secret.” A popup window will start asking for how long the secret will be valid: one, two years, or never expires. Select one of the options and generate the secret. Make a note of the secret along with the Client and Tenant IDs (Figure 6).

Viewing the client secret for the app
Figure 6: Viewing the client secret for the app

Creating the Flow

It is now time to create the Flow and get the information required. Open https://flow.microsoft.com and go to “My flows”. Select “+ New” and “Scheduled – from blank.. Assign a name to the Flow and select how often, and when, it will start (Figure 7).

Creating a new scheduled Flow
Figure 7: Creating a new scheduled Flow

The Flow designer starts. The “Recurrence” step should be already populated using the information in Figure 7. Use the “+ New step” button to create a “Initialize variable” step to contain the first value needed (the Client ID) to use the Azure AD registration, giving it a name, selecting “String” as “Type”, and copying its value into the Flow. Repeat the operation to add two variables for the Tenant ID and the Secret (Figure 8).

Creating Flow variables for the Graph app
Figure 8: Creating Flow variables for the Graph app

Add a new variable to contain the filter for the query to Graph. This is necessary because URLs in Flow don’t allow to use whitespaces, and Graph doesn’t understand the convention to use “_x020_” to encrypt the spaces. The value for the variable will be “?$filter=userImpact eq ‘High'” (Figure 9).

Adding a filter for the Graph app
Figure 9: Adding a filter for the Graph app

Now add a new step to the Flow, this time of type “HTTP” to send the request to Graph. This activity requires a “Premium” account for Flow (Plan 1 or Plan 2). In the step, click on the “Show advanced options”. In the “Authentication” box select “Active Directory oAuth”. Configure the options using the following values:

    null
  • Method: GET
  • URI: We’ll explain this in a little while.
  • Authentication: Active Directory OAuth
  • Authority: https://login.microsoft.com
  • Tenant: use the variable with the directory id
  • Audience: https://graph.microsoft.com
  • Client ID: use the viable with the application id
  • Credential Type: Secret
  • Secret: use the secret variable

For the URI you can use any of the multiple queries possible to approach the Graph Security API. In this example we are using this:

https://graph.microsoft.com/v1.0/security/secureScoreControlProfiles?$filter=userImpact eq ‘High’

Because the query is filtered to get a similar response as the response given by the Office 365 user interface (User Impact High), we are using a combination of the string for the query and the value of the variable for the filter (Figure 10).

Inserting the Graph URI into the Flow
Figure 10: Inserting the Graph URI into the Flow

Save the Flow and run it because we need the output for the next step. From the output result window of the Flow, copy the “Body” response (Figure 11).

Checking the Graph response
Figure 11: Checking the Graph response

The Graph response is in JSON form, and it contains a plethora of data. We are interested in only the Title (that contains the description of the issue) and Remediation fields. Return to the Flow and open it for editing. Add a new action of the type “Parse JSON” at the end of the flow to extract the needed data. Use the “Body” of the HTTP query output as “Content” and click on the “Use sample payload to generate schema.” Flow opens a pop-up window where you can paste the result of the query run (Figure 11). Flow will generate the schema for the parser and create objects for each item in the response automatically (Figure 12).

Flow creates objects from the Graph JSON response
Figure 12: Flow creates objects from the Graph JSON response

The parser presents the data as text without any formatting. To create something that a user can read, add a new step in the Flow of the type “Create HTTP table”. For the data source (“From” field) select the “value” tag of the parser and select “Custom” in “Columns”. Create two columns, one called “Title” that uses the “title” object created for the parser, and other called “Remediation” for the “remediation” object (Figure 13).

Creating a HTML table in Flow
Figure 13: Creating a HTML table in Flow

Save and run the Flow again. Open the result and in the Table step you will see the data that we want to have, rendered in the correct format (Figure 14).

Examining the Secure Score Information Retrieved from the Graph
Figure 14: Examining the Secure Score Information Retrieved from the Graph

To send a message to the system administrator with the query results, add finally a “Send an email notification” step to the Flow. Use the “Output” of the table for the Body of the Email (Figure 15).

Creating an email notification in the Flow
Figure 15: Creating an email notification in the Flow

Save the Flow and run it manually. An Email will be received in a couple of seconds with the recommendations found by Graph (Figure 16).

The email with Secure Score information as received by the admin
Figure 16: The email with Secure Score information as received by the admin

From now on, the Flow will run automatically each month based on the configured schedule.

Conclusions

The Microsoft Graph offers a unified way to approach and interact with Office 365. At the other side of the equation, Flow allows us to use Graph, not only to get information from Office 365 but also to take decisions and make modifications if necessary. Both systems combined give the administrators of Office 365 a powerful tool to automate monitoring and maintenance activities.


Gustavo writes Chapter 23 of the Office 365 for IT Pros eBook, where he discusses the finer points of Microsoft Flow and PowerApps. If you haven’t tried to create anything with Flow, you might be surprised at what’s possible.

Advertisements

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.