Create an app with partner access to Microsoft 365 Defender APIs

Applies to:

• Microsoft 365 Defender

This page describes how to create an Azure Active Directory app that has programmatic access to Microsoft 365 Defender, on behalf of users across multiple tenants. Multi-tenant apps are useful for serving large groups of users.

If you need programmatic access to Microsoft 365 Defender on behalf of a single user, see Create an app to access Microsoft 365 Defender APIs on behalf of a user. If you need access without a user explicitly defined (for example, if you’re writing a background app or daemon), see Create an app to access Microsoft 365 Defender without a user. If you’re not sure which kind of access you need, see Get started.

Microsoft 365 Defender exposes much of its data and actions through a set of programmatic APIs. Those APIs help you automate workflows and make use of Microsoft 365 Defender’s capabilities. This API access requires OAuth2.0 authentication. For more information, see OAuth 2.0 Authorization Code Flow.

In general, you’ll need to take the following steps to use these APIs:

• Create an Azure Active Directory (Azure AD) application.
• Get an access token using this application.
• Use the token to access Microsoft 365 Defender API.

Since this app is multi-tenant, you’ll also need admin consent from each tenant on behalf of its users.

This article explains how to:

• Create a multi-tenant Azure AD application
• Get authorized consent from your user administrator for your application to access the Microsoft 365 Defender that resources it needs.
• Get an access token to Microsoft 365 Defender
• Validate the token

Microsoft 365 Defender exposes much of its data and actions through a set of programmatic APIs. Those APIs will help you automate work flows and innovate based on Microsoft 365 Defender capabilities. The API access requires OAuth2.0 authentication. For more information, see OAuth 2.0 Authorization Code Flow.

In general, you’ll need to take the following steps to use the APIs:

• Create a multi-tenant Azure AD application.
• Get authorized (consent) by your user administrator for your application to access Microsoft 365 Defender resources it needs.
• Get an access token using this application.
• Use the token to access Microsoft 365 Defender API.

The following steps with guide you how to create a multi-tenant Azure AD application, get an access token to Microsoft 365 Defender and validate the token.

Create the multi-tenant app

1. Sign in to Azure as a user with the Global Administrator role.
2. Navigate to Azure Active Directory > App registrations > New registration.

   

3. In the registration form:
   • Choose a name for your application.
   • From Supported account types, select Accounts in any organizational directory (Any Azure AD directory) – Multitenant.
   • Fill out the Redirect URI section. Select type Web and give the redirect URI as https://portal.azure.com.

   After you’re done filling out the form, select wp-signup.php.

   

4. On your application page, select API Permissions > Add permission > APIs my organization uses >, type Microsoft Threat Protection, and select Microsoft Threat Protection. Your app can now access Microsoft 365 Defender.

    Tip

   Microsoft Threat Protection is a former name for Microsoft 365 Defender, and will not appear in the original list. You need to start writing its name in the text box to see it appear.

   

5. Select Application permissions. Choose the relevant permissions for your scenario (for example, Incident.Read.All), and then select Add permissions.

   

    Note

   You need to select the relevant permissions for your scenario. Read all incidents is just an example. To determine which permission you need, please look at the Permissions section in the API you want to call.

   For instance, to run advanced queries, select the ‘Run advanced queries’ permission; to isolate a device, select the ‘Isolate machine’ permission.

6. Select Grant admin consent. Every time you add a permission, you must select Grant admin consent for it to take effect.

   

7. To add a secret to the application, select Certificates & secrets, add a description to the secret, then select Add.

    Tip

   After you select Add, select copy the generated secret value. You won’t be able to retrieve the secret value after you leave.

   

8. Record your application ID and your tenant ID somewhere safe. They’re listed under Overview on your application page.

   

9. Add the application to your user’s tenant.

   Since your application interacts with Microsoft 365 Defender on behalf of your users, it needs be approved for every tenant on which you intend to use it.

   A Global Administrator from your user’s tenant needs to view the consent link and approve your application.

   Consent link is of the form:

   HTTPCopy

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

   The digits 00000000-0000-0000-0000-000000000000 should be replaced with your Application ID.

   After clicking on the consent link, sign in with the Global Administrator of the user’s tenant and consent the application.

   

   You’ll also need to ask your user for their tenant ID. The tenant ID is one of the identifiers used to acquire access tokens.

• Done! You’ve successfully wp-signup.phped an application!
• See examples below for token acquisition and validation.

Get an access token

For more information on Azure AD tokens, see the Azure AD tutorial.

Get an access token using PowerShell

# This code gets the application context token and saves it to a file named "Latest-token.txt" under the current directory.

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"

$authBody = [Ordered] @{
    resource = $resourceAppIdUri
    client_id = $clientId
    client_secret = $appSecret
    grant_type = 'client_credentials'
}

$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token

Out-File -FilePath "./Latest-token.txt" -InputObject $token

return $token

Get an access token using C#

1. Create a new console application.
2. Install NuGet Microsoft.IdentityModel.Clients.ActiveDirectory.
3. Add the following line:
   C#Copy

   using Microsoft.IdentityModel.Clients.ActiveDirectory;
   

4. Copy and paste the following code into your app (don’t forget to update the three variables: tenantId, clientId, appSecret):
   C#Copy

   string tenantId = ""; // Paste your directory (tenant) ID here
   string clientId = ""; // Paste your application (client) ID here
   string appSecret = ""; // Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!
   
   const string authority = "https://login.windows.net";
   const string wdatpResourceId = "https://api.security.microsoft.com";
   
   AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}/");
   ClientCredential clientCredential = new ClientCredential(clientId, appSecret);
   AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, clientCredential).GetAwaiter().GetResult();
   string token = authenticationResult.AccessToken;
   

Get an access token using Python

import json
import urllib.request
import urllib.parse

tenantId = '' # Paste your directory (tenant) ID here
clientId = '' # Paste your application (client) ID here
appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

url = "https://login.windows.net/%s/oauth2/token" % (tenantId)

resourceAppIdUri = 'https://api.security.microsoft.com'

body = {
    'resource' : resourceAppIdUri,
    'client_id' : clientId,
    'client_secret' : appSecret,
    'grant_type' : 'client_credentials'
}

data = urllib.parse.urlencode(body).encode("utf-8")

req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
jsonResponse = json.loads(response.read())
aadToken = jsonResponse["access_token"]

Get an access token using curl

1. Open a command prompt, and set CLIENT_ID to your Azure application ID.
2. Set CLIENT_SECRET to your Azure application secret.
3. Set TENANT_ID to the Azure tenant ID of the user that wants to use your app to access Microsoft 365 Defender.
4. Run the following command:

curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

A successful response will look like this:

{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}

Validate the token

1. Copy and paste the token into the JSON web token validator website, JWT, to decode it.
2. Make sure that the roles claim within the decoded token contains the desired permissions.

In the following image, you can see a decoded token acquired from an app, with Incidents.Read.All, Incidents.ReadWrite.All, and AdvancedHunting.Read.All permissions:

Use the token to access the Microsoft 365 Defender API

1. Choose the API you want to use (incidents, or advanced hunting). For more information, see Supported Microsoft 365 Defender APIs.
2. In the http request you’re about to send, set the authorization header to "Bearer" <token>, Bearer being the authorization scheme, and token being your validated token.
3. The token will expire within one hour. You can send more than one request during this time with the same token.

The following example shows how to send a request to get a list of incidents using C#.

   var httpClient = new HttpClient();
   var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.microsoft.com/api/incidents");

   request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

   var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

Source : Official Microsoft Brand
Editor by : BEST Antivirus KBS Team