Microsoft Defender for Endpoint

You can start virus scans, stop execution of malicious code, manage isolation of network resources, get security recommendations in your Microsoft Defender for Endpoint  tenant, and trigger workflows on new security alerts with the Microsoft Defender for Endpoint plugin for Automation (InsightConnect) .

To use the Microsoft Defender for Endpoint plugin, you must create an application in your Azure Active Directory and then configure the connection in Automation (InsightConnect). For more information on the functionality of the Microsoft Defender for Endpoint plugin, see the Extension Library listing .

Prerequisites

When you create an application in Azure Active Directory, you must assign specific API permissions. The required permissions depend on the actions your application will perform.

Make sure your application has the following minimum permissions:

• Machine.Read.All
• Alert.ReadWrite.All
• Alert.Read.All

Some actions need extra permissions beyond the ones listed above. To find out which permissions are required for specific actions, refer to the permissions section for the actions in Microsoft’s documentation: https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/exposed-apis-list .

Create an application in Azure Active Directory

1. Log in to Azure Portal  with a user that has the Global Administrator role.
2. Click Azure Active Directory > App Registrations > New Registration.
3. Name your application in a way that indicates its purpose and helps you keep track of it.
4. Under Supported account types, select Accounts in this organizational directory only.
5. Click Register.
6. Now that your application is created, assign permissions to enable it to access Microsoft Defender for Endpoint. To do this, click API Permissions > Add a permission.
7. On the APIs my organization uses tab, search for and select WindowsDefenderATP.
8. Click Application permissions and select the appropriate permissions required for your intended actions, as explained in the Prerequisites section, then click Add permissions.
9. Grant administrator consent to the permissions selected. Every time you add a permission, you must select Grant consent for the new permission to take effect.
10. Now that you’ve configured your application, add an application secret to it by clicking Certificates & secrets > New client secret.
11. Enter a description that indicates its purpose, select an expiration, and click Add.
    • Microsoft recommends that you set an expiration value of less than 12 months.
12. Save the secret value that’s generated in a temporary text file. You won’t be able to retrieve this value after you leave this screen.
13. Go to Overview and record your Application ID and your Directory ID values in a temporary text file.

Configure the Microsoft Defender for Endpoint Connection in Automation (InsightConnect)

Now that you’ve created your application in Azure Active Directory, you can configure the Microsoft Defender for Endpoint connection in Automation (InsightConnect) to use the plugin.

1. In Automation (InsightConnect), open the connection configuration for the Microsoft Defender for Endpoint plugin. You can do this when selecting the Microsoft Defender for Endpoint plugin during a workflow building session or by creating the connection independently by choosing Plugins & Tools from the Settings tab on the left menu. On the Plugins & Tools page, select the Connections tab and click Add Connection in the upper-right corner.
2. Configure the connection for the Microsoft Defender for Endpoint plugin. Give the connection a unique and identifiable name, select where the plugin should run, and choose the Microsoft Windows Defender for Endpoint plugin from the list. If it’s not available, then import the plugin from the Installed Plugins tab.
3. Configure your Microsoft Defender for Endpoint credentials. In the Secret Key field, create a credential and paste in the Microsoft Defender for Endpoint Application Secret that you copied earlier. In addition, add the Application ID and Directory ID you copied earlier.

Test in Progress

Save the connection, and the connection test will attempt to authenticate to your Azure Active Directory Microsoft Defender for Endpoint application. A blue circle on the Connection tile indicates that the Connection test is in progress.

Success

If there is no circle, the connection succeeded and you’re ready to begin orchestrating your processes with Microsoft Defender for Endpoint.

Failed

A red circle indicates that the connection test failed. If this occurs, check your connection details (including the Application Secret, Application ID and Directory ID) before trying again.

The log may contain useful troubleshooting information. Click the ellipsis at the right side of the plugin and click View to see a list of your recent connection tests.

Under the Test Status tab, expand the dropdown for the test that encountered an error to view its log.