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

Step 1: Enable console access

Note

Expel secures all login information our SOC analysts need about your devices in an MFA password product. Access to this login information is protected using our internal MFA processes. To learn more about the IP addresses all Expel traffic comes from, go here.

  1. Sign in to the Azure portal as a user assigned a limited administrator directory role or the Guest Inviter role.

  2. In the navigation pane, select Microsoft Entra ID.

  3. Under Manage, select Users.

  4. Select New guest user.

  5. On the New user page, select Invite user, fill out the email address (expel_analyst@expel.io), and optionally include a message.

  6. Select Invite to automatically send the invitation to the guest user.

  7. After you send the invitation, the user account is automatically added to the directory as a guest. You have 2 user permission options, Basic AAD Permissions and RBAC Permissions. See instructions for these options below.

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.

Caution

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

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:

Item we need

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 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 all of the required permissions below and click Add permissions. Required permissions are:

    • WindowsDefenderATP

      • AdvancedQuery.Read.All

      • Alert.Read.All

      • File.Read.All

      • Ip.Read.All

      • Machine.CollectForensics

      • Machine.Isolate

      • Machine.Read.All

      • Score.Read.All

      • SecurityConfiguration.Read.All

      • SecurityRecommendation.Read.All

      • Software.Read.All

      • Ti.ReadWrite

      • Ti.ReadWrite.All

      • Url.Read.All

      • User.Read.All

      • Vulnerability.Read.All

    • Microsoft Graph

      • User.Read

      • User.ReadWrite.All

      • User.Read.All

  10. Grant admin consent to the application.

  11. Navigate to Certificates & secrets and click + New client secret.

    Caution

    The client secret only appears 1 time! Make a note of this before navigating away from the page.

Step 3: Configure the technology in Workbench

  1. In a new browser tab, log into https://workbench.expel.io/settings/security-devices?setupIntegration=microsoft_atp. You may be asked to log into Workbench.

  2. Fill out the form like this:

    MSDefenderForEndpoint_AddSecDev.png
    • For Name type what you want to name the connection.

    • For Location type the server location.

    • For Directory (tenant) ID, type the Directory (tenant) ID from Step 2, Option 1, or Step 2, Option 2, depending on the option you selected.

    • For the Application (client) ID, type Application (client) ID from Step 2, Option 2.

    • For App (client) secret, type the Application (client) Secret from Step 2, Option 2.

Tip

This article was accurate at the time of writing, but changes happen. If you find the instructions are outdated, leave a description in the comment field below and let us know!