Microsoft 365 / Microsoft Defender

This is a combined document for enabling the Dropzone AI Data Source and Alert Source for Microsoft 365 / Microsoft Defender services.

The Data Source is named "Entra ID / Exchange Online / Microsoft Defender".

The Alert Source is named "Exchange Online / Microsoft Defender".

The Dropzone AI platform integrates with Entra ID, Exchange Online, and Microsoft Defender via the Microsoft Graph API. This document describes how to set up API credentials and install them into the Dropzone platform.

Integration Overview

To enable these integrations you will perform the following actions:

  • Register a new application in Microsoft Entra Admin Center

  • Create API credentials

  • Enable Dropzone Certificate Credentials

  • Enable necessary permissions on the application

  • Install the credentials into your Dropzone tenant (Data Source and Alert Source)

  • Select integration parameters, such as which alert types to sync

Register Dropzone Application in Microsoft Entra Admin Center

Microsoft's documentation for registering an application is available at https://learn.microsoft.com/en-us/graph/auth-register-app-v2

  • On the "Register an application" page:

    • Name: "Dropzone AI"

    • Supported account types: "Accounts in this organizational directory only"

    • Leave "Redirect URI" as-is

    • Click "Register" to complete registering the application

Once registered, you will find yourself at the Application Overview of the new app you just created.

Record the "Application (client) ID" and "Directory (tenant) ID" for use later in the Dropzone UI where they are called "Client ID" and "Tenant ID" respectively.

Create Client API Credentials

Microsoft's documentation for creating client credentials for an application is available at https://learn.microsoft.com/en-us/graph/auth-register-app-v2#add-credentials

From the Application overview page, click "Manage" > "Certificates & Secrets":

  • Click the "Client secrets" tab

  • Click the "+ New client secret" button

  • "Add a client secret" will pop from the side

    • Description: "Dropzone AI Integration Key"

    • Expires: Custom

    • Start: today's date

    • End: today + 2 years

Your Dropzone integration will stop working when the client secret expires. Consider setting a calendar reminder to update the key prior to expiration.

  • Click "Add" to finish adding client secret to the application

  • Record the "Value" for use later in the Dropzone UI where it is called "Client Secret"

This value is not shown after you leave this page - be sure to record it immediately.

Set Application Permissions

Setting the application permissions is done in two sections:

  • Microsoft Graph Permissions

  • Windows Defender ATP - Live Response

Setting Microsoft Graph Permissions

  • Return to the Application Overview for our new application

  • Click "API Permissions"

  • Click "Add a permission"

  • Select "Microsoft Graph"

  • Select "Application Permissions"

The table below lists the permissions we'll be adding and how they're used by the Dropzone platform.

Permission
Purpose
Used By

AuditLog.Read.All

Retrieve audit information such as user MFA and administrator access status, for alert investigation and chat.

Data Source Integration

Directory.Read.All

Retrieve directory information such as users, group membership, directory roles, etc, for alert investigation and chat.

Data Source Integration

Mail.Read

Retrieve phishing emails for analysis; Retrieve phishing alerts in some configurations

Alert Source and Data Source Integrations

ThreatHunting.Read.All

Investigating Microsoft Defender alerts

Alert Source Integration

SecurityAlert.Read.All

Pulling Microsoft Defender alerts

Alert Source Integration

SecurityIncident.Read.All

Pulling Microsoft Defender alerts

Alert Source Integration

ThreatSubmission.Read.All

Pulling Phishing Alerts

Alert Source Integration

For each Permission listed above

  • Type it in the "Select Permissions" box to filter the list

  • Expand the section that starts with the permission name by clicking the ">" icon

  • Click the checkbox

    • Do not click the "Add permissions" button yet!

  • Repeat for the all the permissions in the list

  • Click "Add permissions" once done selecting all the permissions

You should now see the permissions, similar to the following:

  • Click "Grant admin consent for <your_company>"

  • Click "Yes" to confirm

Now you should see all the required permissions from the table above listed with a green check mark:

Enable Microsoft Cloud Apps Security

The following permissions are required to query investigations from Microsoft Cloud Apps. When enabled, Dropzone is able to analyze cloud apps events.

  • Return to the Application Overview for our new application

  • Click "API Permissions"

  • Click "Add a permission"

  • Click "APIs my organization uses"

  • Type "Microsoft Cloud App Security" in the search bar

  • Click "Microsoft Cloud App Security"

  • Click "Application permissions"

We will add the following permissions:

Permission
Purpose

investigation.read

Read Cloud App investigations

For each Permission string listed above:

  • Type it in the "Select Permissions" box to filter the list

  • Expand the section that starts with the permission name by clicking the ">" icon

  • Click the checkbox

    • Do not click the "Add permissions" button yet!

  • Repeat for the all the permissions in the list

  • Click "Add permissions" once done selecting all the permissions

  • Click "Grant admin consent for <your_company>"

  • Click "Yes" to confirm

You should now see the new permissions with a green check mark

Enable Windows Defender ATP - Live Response

The following permissions are required to extract quarantined files from Defender alerts. When enabled, Dropzone is able to independently analyze the files which will improve conclusion accuracy.

  • Return to the Application Overview for our new application

  • Click "API Permissions"

  • Click "Add a permission"

  • Click "APIs my organization uses"

  • Type "WindowsDefenderATP" in the search bar

  • Click WindowsDefenderATP

  • Click "Application permissions"

We will add the following permissions:

Permission
Purpose

File.Read.All

Read file details

Library.Manage

Extract quarantined files for analysis

Machine.LiveResponse

Extract quarantined files for analysis

Machine.Read.All

Read machine details

For each Permission string listed above:

  • Type it in the "Select Permissions" box to filter the list

  • Expand the section that starts with the permission name by clicking the ">" icon

  • Click the checkbox

    • Do not click the "Add permissions" button yet!

  • Repeat for the all the permissions in the list

  • Click "Add permissions" once done selecting all the permissions

  • Click "Grant admin consent for <your_company>"

  • Click "Yes" to confirm

You should now see the new permissions with a green check mark

Enable Dropzone Certificate Credentials

Some Dropzone actions use x509 certificate based authentication, for example retrieving quarantined emails during phishing analysis. In this section we will set up the Dropzone certificate as trusted by Microsoft.

Each Dropzone tenant uses a unique Dropzone certificate for maximum security.

  • Return to the Application Overview for our new application

  • Click Manage > Certificates & Secrets

  • Click Certificates and Upload Certificate

  • Select the certificate file you downloaded from the Dropzone UI earlier

  • For description use "Dropzone AI"

You should now see the cert in the UI, including a 'thumbprint' (a cryptographic hash of the certificate.)

Enable Office 365 Exchange Online Management

This section walks you through enabling Office 365 Exchange Online Management, specifically to support retrieving quarantined emails during phishing analysis.

Be sure you've already installed the Dropzone certificate as explained earlier in this document.

Enable Office 365 Exchange Online Mangament Permissions in Entra ID

Please follow these steps to add these permissions to our application in Entra ID

  • Return to the Application Overview for our new application

  • Click "API Permissions"

  • Click "Add a permission"

  • Select "APIs my organization uses"

  • Search for "Office 365 Exchange Online" and click on it

  • Select "Application Permissions"

  • Expand "Exchange" and check Exchange.ManageAsApp

  • Click "Add permissions" at the bottom of the screen

You should now see the permissions, similar to the following:

  • Click "Grant admin consent for <your_company>"

  • Click "Yes" to confirm

Create and Authorize Service Account

Next we need to run PowerShell commands to grant permissions. You may use whatever PowerShell environment you prefer. The examples below were performed using Azure's interactive Cloud Shell. You may find some of the Microsoft Azure Documentation useful.

  • Connect to Entra ID and get information about the application we configured. The value for the -AppID parameter is the "Application (Client) ID" you recorded earlier

    PowerShell 7.4.5
    
    # Connect to "AzureAD"
    PS /home/wbagg> <b>Connect-AzureAD</b>
    VERBOSE: Authenticating to Azure ...
    VERBOSE: Building your Azure drive ...
    Loading personal and system profiles took 8788ms.
    
    # Run the following to get the object-id of our application, replacing
    # application-id with the actual Application (Client) ID of our new app
    #
    #    PS /home/wbagg> <b>Get-AzADServicePrincipal -AppID "<application-id>" | Select-Object DisplayName, AppId, Id | Format-List
    # 
    # For example:
    PS /home/wbagg> <b>Get-AzADServicePrincipal -AppID aaaaaaaa-1111-2222-3333-444444444444 | Select-Object DisplayName, AppId, Id | Format-List
    
    DisplayName : Dropzone AI
    AppId       : aaaaaaaa-1111-2222-3333-444444444444
    Id          : 44726f70-7a6f-6e65-5761-734865726521
    
  • Note this Id field which we'll use in the next command, which we refer to as the object-spid (Service Principal ID)

  • Connect to Exchange Online and Create an Exchange Online Service Principal for our Application

# Connect to ExchangeOnline
PS /home/wbagg> Connect-ExchangeOnline

# Run the following to create the service principal, replacing
# application-id and object-spid from the earlier values
#
#    PS /home/wbagg> New-ServicePrincipal -AppId "<application-id>" -ObjectId "<object-spid>" -DisplayName "Dropzone AI"
#
# for example
PS /home/wbagg> New-ServicePrincipal -AppId "aaaaaaaa-1111-2222-3333-444444444444" -ObjectId "44726f70-7a6f-6e65-5761-734865726521" -DisplayName "Dropzone AI"

DisplayName    ObjectId                               AppId
-----------    --------                               -----
Dropzone AI    44726f70-7a6f-6e65-5761-734865726521   aaaaaaaa-1111-2222-3333-444444444444
  • Lastly, we assign Transport Hygiene Exchange Role to our Application

# Run the following to enable the Transport Hygiene role, replacing the
# application-id with the actual Application (Client) ID of our new app
#
#    PS /> New-ManagementRoleAssignment -App "application-id" -Role "Transport Hygiene"
#
PS /> New-ManagementRoleAssignment -App "aaaaaaaa-1111-2222-3333-444444444444" -Role "Transport Hygiene"

Name                           Role                RoleAssigneeName       RoleAssigneeType   AssignmentMethod   EffectiveUserName
----                           ----                ----------------       ----------------   ----------------   -----------------
Transport Hygiene-44726f70...  Transport Hygiene   ba0efd83-6465-48a...   ServicePrincipal   Direct

Gather Organization ID

  • In the domain list you'll find one that ends in .onmicrosoft.com. Record this domain for use later in the Dropzone UI where it is called "Organization ID"

Gather Cloud Apps Information

Record the "API URL" for use later in the Dropzone UI where it is called "Portal URL".

Enable The Dropzone Data Source Integration

The Data source integration allows Dropzone AI to interact with Entra ID, Exchange Online, and Microsoft Defender to gather information for use in investigation analysis and interactive chat.

You'll need the following information:

Dropzone Field
Source

Client ID

The "Application (client) ID" from the Application Overview

Tenant ID

The "Directory (tenant) ID" from the Application Overview

Client Secret

The client secret "value" from the client secret page

Portal URL

Defender Cloud Apps API URL

To enable the Data Source integration, do the following:

  • Navigate to your Dropzone AI tenant home page e.g. https://mycompany.dropzone.ai

  • Click System > Integrations

  • Click "Data Sources" in the top left corner

  • Find the "Entra ID" / "Exchange Online" / "Microsoft Defender" tile and click "Connect"

  • Input the Client ID, Tenant ID, and Client Secret, and the Cloud Apps Portal URL

  • If you wish to enable Live Response capability, check the "Use LiveResponse" box

  • Click "Test & Save" to finish

If you have any errors engage your Dropzone AI support representative.

Enable The Dropzone Alert Source Integration

The Alert source integration allows Dropzone AI to pull alerts from Exchange Online and Microsoft Defender for investigation.

You'll need the following information:

Dropzone Field
Source

Client ID

The "Application (client) ID" from the Application Overview

Tenant ID

The "Directory (tenant) ID" from the Application Overview

Client Secret

The client secret "value" from the client secret page

To enable the Alert Source integration, do the following:

  • Navigate to your Dropzone AI tenant home page e.g. https://mycompany.dropzone.ai

  • Click System > Integrations

  • Click on "Alert Sources" in the top left corner

  • Find the "Exchange Online" / "Microsoft Defender" tile and click "Connect"

  • Input the Client ID, Tenant ID, and Client Secret

  • Check the alert sources you want to ingest

If you are enabling the PowerShell API integration to retrieve quarantined emails for phishing analysis

  • Find the section "PowerShell API Configuration (Advanced)"

  • Click "Enable PowerShell API"

  • Enter the Organization ID you saved earlier (ends in .onmicrosoft.com)

  • Click "Test & Save" to finish

You should begin ingesting alerts immediately.

If you have any errors engage your Dropzone AI support representative.

Last updated

Was this helpful?