Skip to main content


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!

Step 1: Enable console access

  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 Azure Active Directory (AAD).

    Azure_active_directory (2).png
  3. Under Manage, select Users.

  4. Select New guest user.

  5. On the New user page, select Invite user, fill out the email address (, 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.


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


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. Assigning full access rights requires adding the users to the Security Administrator or Global Administrator AAD built-in roles.

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. Assigning read only access rights requires adding the users to the Security Reader AAD built-in role.

Screen Shot 2021-03-05 at 12.48.19 PM.png

Option 2: Role-based Access Control (RBAC) permissions

To more granularly control what permissions Expel has in Microsoft Defender for Endpoint, use RBAC permissions.


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. Navigate to the Microsoft Defender for Endpoint console and open Settings > Permissions > Roles. Click + Add role to create a new role for Expel.

    Screen Shot 2021-03-05 at 12.48.49 PM.png
  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

          Screen Shot 2021-03-05 at 12.49.19 PM.png

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 Active Directory (AD) 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


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 Azure ADapplication

  1. As an Azure administrator, log in to the Azure Portal.

  2. Navigate to Azure Active Directory > App registrations and click + New registration.

  3. On the next screen, create a name for the application and click Register.

  4. Navigate to the application registration created, and open API permissions. Click Add permissions.

  5. On the next screen, select APIs my organization uses tab and search for WindowsDefenderATP.

  6. Click WindowsDefenderATP.

  7. On the next screen, select Application permissions and then Add permissions.

    Screen Shot 2021-03-05 at 12.50.30 PM.png
  8. 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.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

  9. Grant admin consent to the application.

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


    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, login to

  2. Type Security Code from Google Authenticator (two-factor authentication).

  3. On the console page, navigate to Settings and click Security Devices.

  4. At the top of the page, click Add Security Device.

    This is the default image for Add Security Device
  5. Search for and select Microsoft Defender for Endpoint.

    • For Name type what you want to name the Microsoft Defender for Endpoint.

    • For Location type Microsoft Cloud.

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

    • For the AppID, type Application (client) ID fromStep 2, Option 2.

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