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

• As an Admin, go to to Entra home - https://entra.microsoft.com/#home

• From the left sidebar, go to Identity > Applications > App registrations

• Click New registration

Registering the Dropzone AI Application

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

Application Overview Page

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":

Application Certificates & Secrets Page

• 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

Add a client secret

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

Copy the Client Secret Value

• 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

  • https://entra.microsoft.com

  • Applications > App Registration > All Applications > Dropzone AI

• Click "API Permissions"

• Click "Add a permission"

• Select "Microsoft Graph"

Select the Microsoft Graph API

• Select "Application Permissions"

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

Example - setting User.Read.All MSGraph Permission

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

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

(Example - this screenshot does not show all permissions you may need.)

• Click "Grant admin consent for <your_company>"

Grant admin consent

• Click "Yes" to confirm

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

(Example - this screenshot does not show all permissions you may need.)

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

  • https://entra.microsoft.com

  • Applications > App Registration > All Applications > Dropzone AI

• Click "API Permissions"

• Click "Add a permission"

• Click "APIs my organization uses"

APIs my organization uses

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

Microsoft Cloud App Security

• 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>"

Grant consent

• 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

  • https://entra.microsoft.com

  • Applications > App Registration > All Applications > Dropzone AI

• Click "API Permissions"

• Click "Add a permission"

• Click "APIs my organization uses"

APIs my organization uses

• Type "WindowsDefenderATP" in the search bar

WindowsDefenderATP

• 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>"

Grant consent

• Click "Yes" to confirm

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

(Example - this screenshot does not show all permissions you may need.)

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

  • https://entra.microsoft.com

  • Applications > App Registration > All Applications > Dropzone AI

• Click Manage > Certificates & Secrets

Certificates & Secrets

• Click Certificates and Upload Certificate

Upload Certificate

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

• For description use "Dropzone AI"

Upload Certificate File

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

Certificate installed

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

  • https://entra.microsoft.com

  • Applications > App Registration > All Applications > Dropzone AI

• Click "API Permissions"

• Click "Add a permission"

• Select "APIs my organization uses"

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

Office 365 Exchange Online

• Select "Application Permissions"

Select Application Permissions

• Expand "Exchange" and check Exchange.ManageAsApp

Office 365 Exchange Online

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

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

(Example - this screenshot does not show all permissions you may need.)

• Click "Grant admin consent for <your_company>"

Grant admin consent

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

• Open your powershell environment

  • For example go to https://portal.azure.com and click on the Cloud Shell icon

Azure Cloud Shell Icon

• 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

• As an Admin, go to to Entra home - https://entra.microsoft.com/#home

• In the left navigation, select Manage > Custom domain names

Azure Custom Domain Names

• 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"

Azure Custom Domain Names List

Gather Cloud Apps Information

• Go to https://security.microsoft.com/

• In the left navigation, select Settings

• Select Cloud Apps

Defender Cloud Apps API URL

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

Integrations Dropdown

• Click "Data Sources" in the top left corner

Select the "Data Sources" button

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

The Microsoft Data Source Tile

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

Fill out the Data Source details

• 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

Integrations Dropdown

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

Select the "Alert Sources" button

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

The Microsoft Alert Source Tile

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

• Check the alert sources you want to ingest

Configure the Alert Source

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)

Configure PowerShell

• Click "Test & Save" to finish

You should begin ingesting alerts immediately.

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