Learn how to access valuable insights from Microsoft Defender for Endpoint using the documented Microsoft Defender API and automate workflows beyond just simple administration.

We have covered how to manage access to the Microsoft Defender for Endpoint Security Centre portal. You access the portal through a browser to manage the Microsoft Defender for Endpoint settings, investigate alerts, and other various tasks.

However, sometimes you want to facilitate access through the Microsoft Defender APIs. The Microsoft Defender API will enable you to automate workflows and innovate based on Microsoft Defender for Endpoint capabilities. Think about an application that connects to the Microsoft Defender for Endpoint APIs to pull alerts, and trigger workflows once certain conditions are met. For that, we need first to authenticate to the service before consuming the Microsoft Defender API. In this section, we are going to cover how to manage access through the Microsoft Defender API.

Read other parts here:

P1: Microsoft Defender for Endpoint – Architecture

P2: MS Defender for Security Strategy & Role of AI

P3: MS Defender for Endpoint – Threat and Vulnerability Management (TVM)

P4: MS Defender for Endpoint – Attack Surface Reduction ASR

P5: Microsoft Defender Antivirus Internal Mechanics

P6: Microsoft Defender Endpoint Detection & Response (EDR)

Microsoft Defender API – Security context

When accessing the APIs, you can’t just enter a username and a password in your application to authenticate to the API. What happen if your password gets expired? How can you rotate the password of that account for better security?

In the old days, we used to create service accounts to run our on-premises applications and then grant that service account the needed rights and permissions to do its job. Managed service accounts then were introduced, and they have an automatically managed, complex password that removes the requirement of manually dealing with password rotation and security. However, both requires Active Directory to work.

In the cloud, we have the same requirements. We need to authenticate to a service using some sort of credentials or secrets, and we don’t need to worry about password complexity, rotation, or dependency on Active Directory.

Instead of using Active Directory as the authentication service, in the cloud it makes sense to leverage Azure Active Directory for that purpose. Azure Active Directory has a similar concept to the service account called Azure AD Applications. When you register an application in Azure AD, you get an Application ID (similar to usernames) and Application Secrets (similar to passwords).

Therefore, to access the Microsoft Defender for Endpoint APIs, we need a security context. For that, we register an application in Azure AD, and we get an Application ID and a secret that will be used later to complete the authentication process.

Authentication Protocol

Now that we have a security context, let’s pick an authentication protocol that works with the Microsoft Defender for Endpoint APIs. Of course, we can’t use Kerberos for that. In the cloud, we use modern authentication that works well with cloud services. One of those modern authentication protocols is OAuth 2.

First, why is OAuth 2 too important? This is the latest version of an industry standard framework to automate application access. With Oauth2, Microsoft Defender for Endpoint has not only been able to expand the available APIs, but also improve in user experience with rich functionality and ease of API management.

Azure AD becomes the central authentication and authorization body that facilitate accessing the APIs by the client application. Azure AD needs to know about the two entities:

• The client application: which is accomplished by registering an app in Azure AD and acquiring an application ID and a secret.
• The target service which is Microsoft Defender for Endpoint APIs. Azure AD already integrates with Microsoft Defender for Endpoint and maintains a list of Microsoft Defender for Endpoint permissions.

The basic overview of the workflow for Auth 2.0 happens as described next:

• First, we register the client application in Azure AD and grant it a list of Microsoft Defender for Endpoint permissions. 
• Next, the client app in this flow will contact Azure AD and present an Application ID and a secret to identify itself. 
• Azure AD will then return a token to the client app that contains a list of roles that maps to the Microsoft Defender for Endpoint permissions granted earlier to the client app in Azure AD.
• The client application will then present that access token to the Microsoft Defender for Endpoint APIs to complete the authentication and authorization process.

With this model, the client ID and secret no longer have to be provided for each API call. After the initial authorization, the issued token can be used for multiple calls until the configured expiration time, at which point the client credentials are provided again for a new token. Furthermore, with Azure AD as the authentication service, you get extensive logging on all application registration events and authentication traffic.

Authentication context

We have established the following facts so far:

• Azure AD is the authentication service for accessing the Microsoft Defender for Endpoint.
• OAuth 2 is used for the authorization flow.
• We need to register an application in Azure AD that represents our service or application that needs access to the APIs.
• By registering an application in Azure AD, we get an Application ID and a secret.
• In Azure AD, we define what permissions that application will have on the Microsoft Defender for Endpoint service (for example reading alerts)
• We use the Application ID and secret to request a token from Azure AD that contains our roles or permissions (allowed actions through the API).
• We present that token to the API to consume its services.

Finally, you can access the Microsoft Defender for Endpoint using the registered app in two contexts:

• Application context (Recommended): Used by apps that run without a signed-in user present. for example, apps that run as background services or daemons.
• User context: Used to perform actions in the API on behalf of a user.

Since it is recommended to use the application context when accessing the Microsoft Defender for Endpoint APIs, we will be focusing on that in the following section. 

Note: to learn more on how to access the Microsoft Defender API using the user context, please refer to Microsoft Documentations here.

Example: Accessing the APIs using a PowerShell script

In this section, we will create a PowerShell script that represent any application or service that needs to access the Microsoft Defender for Endpoint APIs. The PowerShell script will simply connect to the API and read the latest alerts from the Microsoft Defender for Endpoint service.

To that, we will be performing the following:

1. In Azure AD will:
   1. Create an Azure AD application: this represents the PowerShell script identity.
   1. Generate a secret for that application.
   1. Assign (Read All Alerts) Microsoft Defender for Endpoint permission to that app.
2. From our machine, we will write a script that will do the following:
   1. Connect to Azure AD using the Application ID and secret.
   1. Get an access token.
   1. We will validate that token for demonstration purposes.
   1. We will use that token to connect to the API and read alerts.

Login to Azure Active Directory and navigate to App registrations > New registration.

In the registration form:

• Choose a name for your application.
• Supported account types: pick “Accounts in this organizational directory only”.
• Redirect URI:  the type should be Web. The URL is optional so you can skip it.
• Click Register.

Now that we have defined an application that represent our PowerShell script, go to the Overview section, and take a note of the Directory (tenant) ID and the Application (client) ID. You will need them later in the PowerShell script.

Now, let’s go to Certificates and Secrets section to generate a secret for our application. Under Client secrets, click New client secret.  Give your secret a description and an expiry period.

Copy the generated secret value now as you won’t be able to access it later. Together, the Tenant ID, Application ID and the secret, are all what you need in your PowerShell script to request an access token from Azure AD.

So far, we have registered an app in Azure AD that represents our PowerShell script, and we have an application ID and a secret that represents a username and a password in traditional attention flows.

Let’s move to the authorization part. We need to grant our application permissions in Microsoft Defender for Endpoint. We do it from Azure AD and not from the Microsoft Defender for Endpoint service. Since Azure AD knows about the Microsoft Defender for Endpoint service already, it maintains a list of permissions that are relevant to the Microsoft Defender for Endpoint service.

For that, let’s go to API Permissions > Add permission > APIs my organization uses > type WindowsDefenderATP and click on WindowsDefenderATP

Note: WindowsDefenderATP does not appear in the original list. You need to start writing its name in the text box to see it appear.

Since our script will only need to query alerts through the APIs, then Under Application permissions, pick Alerts.ReadAll permission and then click Add Permissions.

Finally, don’t forget to Grant Admin Consent for the permission to be granted to the application.

Now, we have a registered application, an application ID and a secret, and we have given the application the Alert.ReadAll permission on the Microsoft Defender for Endpoint service. Let’s move to our machine and configure our PowerShell Script.

Remember that we need to do two things with our PowerShell script:

1. Connect to Azure AD and provide the Tenant ID, Application ID and secret to get an access token.
2. Connect to the Microsoft Defender for Endpoint, provide the access token to authenticate, and ask the API to return a list of alerts.

For the first part, I am going to run a dedicated script (Get-Token.ps1) to get an access token from Azure AD. You can find the script here in Microsoft documentation. You just need to provide values for the Tenant ID, Application ID and secret. The script will ask Azure AD for a token and will return a JSON Web Token (JWT) that can’t be read by humans.

For demonstration purpose, let’s copy the output JWT and go to https://jwt.ms/, past the token to decode it and look for the “roles” section. Find the Alert.Read.All role. 

Now that we have an access token, we can then create a second PowerShell script that calls the first one to get a token, and then use the returned JWT to connect to the Microsoft Defender for Endpoint API and get the past 48 hours Alerts.  The script can be found at Microsoft documentation here. Save this script in the same folder you saved the previous Get-Token.ps1 script for the script to work.

Since we are using Azure AD for authentication, you get a complete audit trail for the application service principal by going to Azure AD> Sign-ins.

Partner access through Microsoft Defender for Endpoint APIs

If you are a partner and you want to manage the Microsoft Defender for Endpoint instance of your customer, you can get programmatic access the Microsoft Defender for Endpoint on behalf of your customers.

There are few modifications that must be done to facilitate such authorization flow.

• As a partner, go to your Azure AD tenant, and register an application in your Azure AD tenant the same way described in the previous sections. During the registration process, make sure to choose Accounts in any organizational directory (Any Azure AD directory – Multitenant under Supported account types. Take note of Your Partner Application ID.

• Assign Microsoft Defender for Endpoint permissions as needed to your application in your Azure AD tenant and don’t forget to click on Grant consent for the new permission to take effect.
•  Create a secret. Take a note of the Application secret.
• Now, we need to add our partner application to the customer’s Azure AD tenant. To do so, ask your customer to login to his Azure AD using a Global Administrator account and click the following consent link. Make sure to replace PartnerApplicationIDwith the Application ID for the application we’ve created in the partner’s tenant.

https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=PartnerApplicationID&response_type=code&sso_reload=true

• The rest of the flow is the same. Your application (PowerShell script for example) need to request an access token by providing the following information:
  • Application ID = Partner Application ID
  • Secret = Partner Application Secret.
  • Tenant ID = Customer’s Azure AD tenant ID (not your partner’s tenant ID)

Once you have obtained the token, you can use it to access the customer’s Microsoft Defender for Endpoint API

About this Microsoft Defender for Endpoint Blog Series

During the years, I have worked with many security and Infrastructure services, and I usually don’t find good information in the web on how a product or service works. For me to master a service, I need to learn how it thinks, the internal mechanics, and even how the product group who designed it really thought about different features.

So, I started blogging years back to reflect my understanding and help others find useful information that is not found elsewhere on the internet (at least in one place) and direct from my experience.

This blog series is written after careful consideration and will help you imagine how Defender for Endpoint works from the bottom up. I rarely have time to blog these days, so I might not update the blog on new features. However, the content here will give the information you need to build on top.

CREDITS Big thanks to my friend and fellow Microsoft MVP and RD: Ahmad Nabil who helped me put such content and the Microsoft 365 Security for IT PRO book family who helped in reviewing and editing this chapter. Newer version of the book is available here with updated content and valuable content about other Microsoft 365 security services. Download the new book here.