Generate API Credentials for Integrating Microsoft Defender for Endpoint with Xshield platform using Terraform

1. Overview

This document helps you generate the API credentials in the Microsoft Defender for Endpoint platform to enable secure programmatic access. These credentials are required for integrating Microsoft Defender for Endpoint with the Xshield platform.

To ease setup, we provide this Terraform script that automates the full configuration process. Customers may run this script or follow manual steps described in

1. Microsoft Defender API credentials- Generate API Credentials on Microsoft Defender
2. Azure Storage Account and Azure Storage Queue - Generate Azure Storage Account and Azure Storage Queue

---

2. Quick Start: Terraform Automation

To simplify setup, ColorTokens provides a Terraform automation script that configures all necessary Azure and Microsoft Defender for Endpoint settings for integration with the Xshield platform.

You do not need to write any code. Just follow the instructions below to download, install, and run the automation script.

2.1 Summary of the Terraform Script

🛠 The Terraform script automates the following tasks:

Task	Purpose / Why This Step is Required
Register Entra Application	To create an identity for Xshield in Azure AD to authenticate with Microsoft Defender for Endpoint APIs.
Generate Client Secret	Required for secure programmatic access; acts as a password for the registered application.
Assign API Permissions	Grants the necessary access rights (like Machine.Read.All) to allow Xshield to query Defender APIs.
Create Storage Account	Acts as the destination where Defender will send raw telemetry events like DeviceNetworkEvents.
Create Storage Queue	Queue stores event notifications (triggers) for new data blobs uploaded by Defender.
Configure Event Subscription	Automatically forwards notifications to the queue when new telemetry blobs are created in storage.
Assign IAM Role - 'Storage Blob Data Reader'	Allows the Entra application to read blobs from the storage account (for retrieving event data).
Assign IAM Role - 'Storage Queue Data Message Processor'	Allows Xshield (via the Entra app) to read and process messages from the queue (event triggers).
Retrieve Storage Account Resource ID	Needed to configure Defender’s Streaming API and tie it to the correct storage account.

---

2.2 Install Terraform (One-Time Step) and Download Terraform Script

Terraform is an open-source automation tool used to configure cloud infrastructure. You only need to install it once.

For Linux / macOS:

sudo apt update && sudo apt install -y wget unzip
wget https://releases.hashicorp.com/terraform/1.8.5/terraform_1.8.5_linux_amd64.zip
unzip terraform_1.8.5_linux_amd64.zip
sudo mv terraform /usr/local/bin/
terraform -version

For Windows:

1. Download from: https://releases.hashicorp.com/terraform/1.8.5/terraform_1.8.5_windows_amd64.zip

2. Extract the ZIP file.

3. Move terraform.exe to C:\terraform\

4. Add C:\terraform\ to your System Environment PATH

5. Verify installation:

terraform -version

---

2.3 Download and Unzip the Terraform Script provided by ColorTokens

1. Open a terminal or PowerShell window
2. Run the following command (replace artifacts-url appropriately based on the cluster you are using):

wget https://<artifacts-url>/edr-microsoft-defender/msdefenderterraform.zip

Artifact URL Mapping by Domain

Xshield Tenant Domain	Artifact URL
ng.colortokens.com	https://artifacts.ng.colortokens.com
bom.colortokens.com	https://artifacts.bom.colortokens.com
fra.colortokens.com	https://artifacts.fra.colortokens.com
syd.colortokens.com	https://artifacts.syd.colortokens.com

3. Unzip the script. Install unzip package on the lab VM, if not already installed:

    sudo apt update
    sudo apt install unzip

    unzip msdefenderterraform.zip

You will get:

• main.tf
• terraform.tfvars
• variables.tf
• outputs.tf

---

2.4 Steps to Run Terraform Script

1. Prepare the following values and populate them in the terraform.tfvars file:

subscription_id      = "<your_subscription_id>"
location             = "<location>"
resource_group_name  = "<resource_group_name>"
storage_account_name = "<unique_storage_account_name>"
queue_name           = "<storage_queue_name>"
app_name             = "<entra_application_name>"
auto_admin_consent   = true

note

• storage_account_name must be globally unique.
• Set auto_admin_consent = true to automatically grant API permissions.
• Admin Azure credentials are required to execute this script.

2. Open a terminal and run below command to login to Azure:

   az login

3. Initialize and apply the configuration:

   terraform init     # to initialise configuration
   terraform plan     # to create a plan
   terraform apply    # to create resources

4. After successful deployment, retrieve the output values:

   terraform output                  # to see all the created resources (except client_secret)
   terraform output client_secret    # to get the client secret

5. Use the provided output values (client_id, tenant_id, client_secret, storage_account_name, and queue_name) to configure the integration in the Xshield platform.

6. Copy and store the value provided in the output variable storage_account_id to configure Defender XDR Streaming API in the next step.

---

3. Configure Defender Telemetry Export via Streaming API

Microsoft Defender for XDR collects various telemetry events from machines onboarded to Defender for Endpoint. The Xshield platform requires access only to events in the DeviceNetworkEvents table to provide network visibility.

⚠️ IMPORTANT NOTE: Xshield only requires DeviceNetworkEvents. While configuring the Streaming API to export data to Blob Storage, make sure to select only DeviceNetworkEvents under the Devices section of Event Types.

1. Go to Defender for Endpoint > Settings

   

2. Select Microsoft Defender XDR

   

3. Select Streaming API > +Add. Provide:

   • A value for name
   • Select Forward events to Azure Storage
   • Under Storage account Resource ID, enter the Resource ID of the Storage Account copied in the previous step (JSON View)
   • Under Event Types, select Devices > DeviceNetworkEvents
   • Click Submit

   

4. The Streaming API is now Setup successfully.

   

⚠️ Note:

This configuration will:

• Export only: DeviceNetworkEvents
• A container named insights-logs-advancedhunting-devicenetworkevents will be created automatically in the storage account.
• Blobs will be stored in this container. ✅ Verify that blobs are being generated in the container before proceeding to the next steps. It can take upto 30 minutes for the first blob to appear in the storage container.

Once the above steps are completed, you may configure the integration in Xshield platform.

---

4. Activate Integration in Xshield

In the Xshield platform:

1. Navigate to Integrations > EDR > Microsoft Defender for Endpoint

2. Enter the following:

   • Tenant ID
   • Client ID
   • Client Secret
   • Storage Account Name
   • Storage Queue Name

3. Click Test and then Save

Done! Integration is now active. Device discovery and telemetry will begin flowing from MDE to Xshield.

---

5. References and Support

• Register Entra Application Register Entra Application
• Create Client Secrets Create Client Secrets
• Streaming API Setup Streaming API Setup
• Event Subscription for Blob Notifications Event Subscription for Blob Notifications

For assistance, please contact ColorTokens Support.