This article helps you integrate your Microsoft Defender for Endpoint installation with the Expel Workbench.

Step 1: Enable Console Access

Option 1: Basic AAD Permissions

The simplest way to grant Expel access to the Microsoft Defender for Endpoint console is with basic AAD permissions.

Note

If the tenant is using RBAC (Role-Based Access Control) to manage permissions in Microsoft Defender for Endpoint, basic permissions won’t be an option for that tenant. Use Option 2 in this case.

You have 2 permission levels for basic AAD access. Expel prefers full access but can still operate with read-only access. However, some of our capabilities are limited.

Access Level

Description

Full access

Users with full access can log in, view all system information and resolve alerts, submit files for deep analysis, and download the onboarding package. To assign full access rights, add the users to all these Directory roles:

  • Security administrator

  • Security operator

  • Security reader

Read only access

Users with read-only access can log in, view all alerts, and related information. They can't change alert states, submit files for deep analysis or perform any state-changing operations. To assign read-only access rights, add the users to the Security Reader AAD built-in role.

Note

In addition to the Security Reader role, the Security Operator role is also required to view EDR alerts within your Microsoft Defender for Endpoint console. If only granted the Security Reader role, we may not be able to view all of your alerts and may have limited investigate and monitoring capabilities for your device(s).

Option 2: Role-Based Access Control (RBAC) Permissions

To more granularly control what permissions Expel has in Microsoft Defender for Endpoint, use RBAC permissions.
Note
Enabling RBAC in Microsoft Defender for Endpoint may have an unintended consequence if you were previously using basic permissions. Users who were previously granted read-only access (Security Reader role) are denied access until they are added to a Microsoft Defender for Endpoint role.
  1. From the Microsoft 365 Defender portal, navigate to Permissions > Microsoft 365 Defender, and then create the new role for Expel.
  2. On the role creation page, fill out the required fields:
    • Role name: name the role you’re creating.
    • Description: describe what this role is for.
    • Permissions: select the permissions to grant to Expel.
      • Required Permissions:
        • View Data (all)
        • Security operations
        • Threat and vulnerability management
        • Alerts investigation
      • Recommended Permissions:
        • Active remediation actions (all)
        • Security operations
        • Threat and vulnerability management
        • Remediation handling
        • Threat and vulnerability management
        • Exception handling
        • Live response capabilities (advanced)
      • Permissions not Required:
        • Manage security settings
  3. Click Save.

Step 2: Generate API Credentials

To integrate Microsoft Defender for Endpoint with Expel, we need to create secure credentials to the API. You have 2 options for enabling API access:

  1. Enable the Expel Defender for Endpoint Integration Enterprise Application within Azure.
  2. Create a custom Azure Microsoft Entra ID Application.

Usually enabling the Enterprise Application is the recommended approach. The second option is offered for cases where the absolute minimum permissions are required. In either case, the table shows the required items to be obtained during this step:

 

Description

Azure Directory (tenant) ID

A unique identifier for your Azure instance. Expel needs this information to route our API requests to the right place.

Application (client) ID (Option 2 only)

A unique identifier for the application you create that grants Expel the access it needs to your Azure instance.

Application (client) Secret (Option 2 only)

The API secret that allows Expel to authenticate as the created application to your Azure instance.

Option 1: Enable Defender for Endpoint Enterprise Application (Preferred)

  1. As an Administrator, navigate to the Expel Admin Consent Page.
  2. Review and accept requested permissions.
  3. The Expel Defender for Endpoint Integration app appears under Enterprise Applications. Review properties and ensure that all permissions are properly granted.
  4. Note the Directory (Tenant) ID when viewing the Expel Defender for Endpoint Integration application for use in later steps.

Option 2: Create a Custom Microsoft Entra ID Application

  1. As an Azure administrator, log in to the Azure Portal.
  2. Navigate to App registrations and click + New registration.
  3. Fill in the application details.
    We recommend the following:
    • Name: Expel Defender for Endpoint Integration.
    • Supported account types: accounts in this organizational directory only (first option).
  4. After you fill out the fields, click Register to create the new application
  5. Navigate to the application registration created, and open API permissions. Click Add permissions.
  6. On the next screen, select APIs my organization uses tab and search for WindowsDefenderATP.
  7. Click WindowsDefenderATP.
  8. On the next screen, select Application permissions and then Add permissions.
  9. On the next screen, select the required permissions below and select Add permissions.
    • Required Permissions:
      •  WindowsDefenderATP
        • AdvancedQuery.Read.All
        • Alert.Read.All
        • File.Read.All
        • Ip.Read.All
        • Machine.CollectForensics
        • Machine.Read.All
        • Score.Read.All
        • SecurityConfiguration.Read.All
        • SecurityRecommendation.Read.All
        • Software.Read.All
        • Url.Read.All
        • User.Read.All
        • Vulnerability.Read.All
      • Microsoft Graph
        • User.Read
        • User.Read.All
    • Optional Permissions:
      These additional permissions are only needed if using auto remediations.
      • WindowsDefenderATP
        • Machine.Isolate
        • Ti.ReadWrite
        • Ti.ReadWrite.All
      • Microsoft Graph
        • User.ReadWrite.All
  10. Grant admin consent to the application.
  11. Navigate to Certificates & secrets and click + New client secret. The client secret only appears once; make a note of the value before navigating away from the page.

Step 3: Configure the Technology in Workbench

Now that we have the correct access configured and noted the credentials, we can integrate your tech with Workbench.

  1. Log in to Workbench.
  2. In the side menu, navigate to Organization Settings > Security Devices.
  3. Select the Add Security Device button.
  4. In the search box, type “Defender” and then select the Microsoft Defender for Endpoint integration.
  5. Complete the fields as follows:
    • Name - enter a name that might help you more easily identify this integration, such as “CompanyName Defender”; this name will display in Workbench under the Name column, and is a text string that you can filter on
    • Location - enter the location of your server
    • Directory (tenant) ID - enter the Directory (tenant) ID from Step 2
    • Application (client) ID - enter the Application (client) ID from Step 2
    • App (client) secret - enter the Application (client) Secret from Step 2
  6. Your device should be created successfully within a few seconds. A few reminders:
    • After your connection is healthy, it will take some time for your device to begin polling and receiving data.
    • To check on the status, click on the downward arrow for your device in the first column and choose View details. You can then scroll to the Connection section to see if your device is fully connected.
    • Polling will happen first; data will be received after that. You must refresh the page to see updates.
    • If your device does not begin polling within 15 minutes, and does not begin receiving data within 30 minutes, contact our support team for help.