Microsoft Graph API Integration

Overview

Integrating with Microsoft Graph API can provide a wealth of user contextual attributes, insights and risks, which can substantially enrich the data provided to the OutThink platform. This information can be used to positively contribute to OutThink’s Human Risk Intelligence processes, and provide enhanced insights and recommendations for employees and/or department/organization level decision making.

It is important to ensure that automatic user synchronization has been set-up between OutThink and your Microsoft Entra ID (Azure AD) instance before configuring access to Graph API. This ensures that OutThink and your Microsoft Azure tenant are correlated in terms of user identities. You can read more about this here.

The following permissions will be required on your Microsoft Azure Tenant to undertake the actions undertaken in this article:

• Application Developer
  Required to create an application registration in the Microsoft Azure Portal.
  
• Global Administrator, Privileged Role Administrator or a custom directory role that includes the permission to Grant Admin Consent to the application.

You will also need to be an OutThink administrator, with access to your tenancy via the Command Centre at https://cc.outthink.io.

---

Create New Registration

• Login to the Microsoft Azure Portal, and search for App Registrations.
• Click + New Registration and enter an appropriate name for this application.
  Set the Supported Account Type to Accounts in this organizational directory only.
  Click Register.

• In the App Registrations page, select the new application you just created.
• Under Manage on the left menu, select Certificates & secrets, and click the + New client secret button.

• Add a relevant Description for the secret, and choose an appropriate Expiry period.
  Whenever this secret expires, a new secret will need to be created, so it is recommended to select a period long enough that this does not present a management overhead.
• Copy the secret Value to a secure location. You will need this later.
• The next step is to define the Graph API permissions that this application will be configured to use. Select API permissions on the left menu, then click + Add a permission.

• On the fly-out that appears, select Microsoft Graph under the Microsoft APIs tab, then select Application permissions.

• Under Select Permissions check the permissions that you would like to include in the app, according to the details below. When finished, hit the Add permissions button.

What permissions should be granted?

You have the flexibility to grant OutThink specific permissions to enhance your users’ data within the platform according to your requirements. You can independently add permissions to access detailed data points, which you’ll later need to activate within the platform integration (details provided below).

EMPLOYEE BASIC INFORMATION

• Users.Read.All
  Enriches the user’s data with:
  – Avatars: customize the user profile with their official Microsoft profile picture.
  – Managers: Identify users who have employees reporting to them directly. Administrators can target managers with leadership training, and assess managers’ contribution to security culture
  – Line Manager information: Identify the line manager for each employee. This enables administrators to generate reports on specific teams and take appropriate escalation actions.

• People.Read.All
  Enriches the user’s data with:
  – Relevant colleagues: collect the people most relevant colleagues based on communication, collaboration patterns and business relationships. This is designed to detect human lateral movement

SECURITY AND ACCESS

• DeviceManagementManagedDevice.Read.All
  Enriches the user’s data with:
  – Device at risk: detect potential high-risk users and their devices, empowering administrators to take immediate action.

• AuditLog.ReadAll
  Enriches the user’s data with:
  – Sign-In failures: identify users with a higher than normal authentication failure rate. Makes it easy for administrators to segment these users and support them with targeted training.
  – Remote workers: identify users who frequently work in different locations, for easier risk management.
• Directory.ReadAll
  Enriches the user’s data with:
  – Administrator role: identify users with administrative privileges and adjust their risk score based on their access level and behavior.

OUT OF OFFICE AND TRAVEL

• Mailbox.Setting.Read
  Enriches the user’s data with:
  – Working hours: correlate user activity in trainings and simulations with working hours.
  – Out of office: analyze the contribution of OOO status to the number of compromised simulation users and adjust reports accordingly.
• Calendars.ReadBasic.All
  Enriches the user’s data with:
  Upcoming travels: Identify users who are about to travel, for easier risk management.
  

EMAIL BEHAVIORS

** Outthink platform does not read any content on customer emails, just read permissions on email metadata and sender domains.

• Mail.ReadBasic.All
  Enriches the user’s data with:
  – Email fatigue: identify users facing very high levels of email communication, with the attendant elevated phishing risk.
  – Frequent Cloud Service Users: identify the users who most frequently use cloud services, for easier risk management.
  – Frequent Social Media Users: identify the users who most frequently use social media, for easier risk management.

Full list of permissions here:

User.Read.All
People.Read.All
Directory.Read.All
AuditLog.Read.All
MailboxSettings.Read
Mail.ReadBasic.All
DeviceManagementManagedDevices.Read.All
Calendars.ReadBasic.All

For example:

Grant Admin Consent

• As a final step in the application setup, you will need to Grant admin consent for your application. Click the “Grant admin consent for {organisation}” button, as shown below, and confirm.
  If you do not have privileges to grant tenant-wide admin consent for this application, you can instead construct a URL and send to your tenant administrator, as detailed here.

Command Center Configuration

Navigate to the Settings > Organization Management section of the Command Centre, select the relevant Organization on the left hand side, then select the Integrations tab on the right. Directly under the title Microsoft Graph API, ensure the following three fields are correctly populated:

Tenant ID – The Directory Id of your Entra ID Tenant. Refer here for assistance in finding this value.
Client ID – The Application (client) ID of the App Registration created in the previous section. This can be found in the Overview section of the new App Registration.
Client Secret – The secret value copied and stored from the previous section.

Finally, hit Save changes at the bottom of the screen. Please be aware that it may take up to 24 hours for data from your Entra ID tenant to be ingested and processed.

Was this helpful?

YesNo

2 / 0