Skip to main content

How to integrate Microsoft Defender account?

Overview​

To authenticate with Microsoft Defender (Defender for Endpoint / Defender XDR), you will need to provide the following information from Azure / Microsoft Entra ID:

  • Tenant (Directory) ID
  • Application (Client) ID
  • Client Secret or Certificate (recommended for production)
  • API Base URL (Defender Endpoint APIs use https://api.securitycenter.microsoft.com)

The app must be granted the necessary Application permissions with admin consent for the Defender API.

Step 1: Sign in to Azure Portal​

  1. Go to the Azure Portal
  2. Sign in with an account that has rights to register applications and grant admin consent (Tenant admin or a role with app management rights)

Step 2: Register a New Application​

  1. In the Azure portal, navigate to: Microsoft Entra ID → App registrations → New registration
  2. Fill in the following details:
    • Name: Enter a meaningful name (e.g., "Unizo - Microsoft Defender Connector")
    • Supported account types: Select Accounts in this organizational directory only (Single tenant) for internal use
    • Redirect URI: Leave blank for service-to-service authentication
Microsoft Defender App Registration
Fill in the application registration details
  1. Click Register

Step 3: Add Credentials (Client Secret)​

  1. In your registered app, navigate to: Certificates & secrets
  2. Under Client secrets, click New client secret
  3. Add a description and select expiry period
  4. Click Add
  5. Copy the secret value immediately - it's shown only once

Important:

  • Store the secret securely in a secrets manager or key vault
  • For production environments, consider using certificates instead of secrets

Step 4: Configure API Permissions​

  1. In your app, navigate to: API permissions → Add a permission

  2. Select APIs my organization uses

  3. Search for and select WindowsDefenderATP (Microsoft Defender for Endpoint)

  4. Select Application permissions (not Delegated permissions)

  5. Choose the minimum required permissions for your integration:

    Essential Permissions for EDR/XDR Integration:

    • Alert.Read.All - Read all alerts
    • Alert.ReadWrite.All - Read and update alerts
    • Machine.Read.All - Read machine/device inventory
    • Machine.ReadWrite.All - Read and update machine information
    • Vulnerability.Read.All - Read vulnerability information
    • AdvancedQuery.Read.All - Run advanced queries
    • Score.Read.All - Read secure score data

  6. Click Add permissions

  7. Click Grant admin consent for [Your Tenant] - this requires tenant admin privileges

Note: Without admin consent, application permissions will not be usable

Step 5: Copy Tenant ID, Client ID and Client Secret​

From your registered app, collect the following values:

  1. Tenant ID: Azure AD → Overview → Directory (Tenant) ID
  2. Client ID: App registration → Overview → Application (Client) ID
  3. Client Secret: The value you copied in Step 3
Application Overview - Client ID and Tenant ID

Copy the Application (Client) ID and Directory (Tenant) ID from the Overview page

  1. API Base URL:
    • Global: https://api.securitycenter.microsoft.com
    • US Government: https://api-gcc.securitycenter.microsoft.com
    • US Government High: https://api-gcc-high.securitycenter.microsoft.com
    • For XDR regional endpoints:
      • US: https://us.api.security.microsoft.com
      • EU: https://eu.api.security.microsoft.com
      • UK: https://uk.api.security.microsoft.com