Skip to content

Commit eb617d9

Browse files
m365-skilling-repo-management[bot]m365-skilling-repo-management[bot]
authored
Merge pull request #5033 from MicrosoftDocs/main
[AutoPublish] main to live - 09/14 01:31 PDT | 09/14 14:01 IST
2 parents c178323 + 0d24400 commit eb617d9

File tree

2 files changed

+76
-150
lines changed

2 files changed

+76
-150
lines changed

‎defender-endpoint/api/exposed-apis-create-app-webapp.md‎

Lines changed: 72 additions & 150 deletions
Original file line numberDiff line numberDiff line change
@@ -1,134 +1,98 @@
11
---
22
title: Create an app to access Microsoft Defender for Endpoint without a user
3-
ms.reviewer:
4-
description: Learn how to design a web app to get programmatic access to Microsoft Defender for Endpoint without a user.
3+
description: Learn how to grant a web app access to Microsoft Defender for Endpoint without a user.
54
ms.service: defender-endpoint
6-
ms.author: bagol
7-
author: batamig
8-
ms.localizationpriority: medium
9-
ms.date: 03/21/2025
10-
manager: bagol
11-
audience: ITPro
12-
ms.collection:
13-
- m365-security
14-
- tier3
15-
- must-keep
16-
ms.topic: reference
5+
ms.author: kesharab
6+
author: KesemSharabi
7+
ms.date: 09/08/2025
8+
ms.topic: how-to
179
ms.subservice: reference
18-
ms.custom: api
10+
ms.appliesTo: Microsoft Defender for Business and Microsoft Defender for Endpoint Plans 1 and 2
1911
search.appverid: met150
2012
---
2113

2214
# Create an app to access Microsoft Defender for Endpoint without a user
2315

24-
[!INCLUDE [Microsoft Defender XDR rebranding](../../includes/microsoft-defender.md)]
16+
When [using APIs](apis-intro.md), you might need access to Microsoft Defender for Endpoint without a user. For example, you might want to create a service that runs in the background and interacts with Defender for Endpoint on behalf of your organization. In this case, you need to create an application that can access Defender for Endpoint without a user.
2517

18+
API access requires [OAuth2.0 authentication](/azure/active-directory/develop/active-directory-v2-protocols-oauth-code).
2619

27-
**Applies to:**
20+
## Prerequisites
2821

29-
- [Microsoft Defender for Endpoint Plan 1](../microsoft-defender-endpoint.md)
30-
- [Microsoft Defender for Endpoint Plan 2](../microsoft-defender-endpoint.md)
31-
- [Microsoft Defender for Business](/defender-business)
22+
Having the [Microsoft Entra role](/entra/identity/role-based-access-control/manage-roles-portal?tabs=admin-center) for creating an app in Azure. For example, *Application Administrator*.
3223

33-
> [!IMPORTANT]
34-
> Advanced hunting capabilities are not included in Defender for Business.
35-
36-
37-
> Want to experience Microsoft Defender for Endpoint? [Sign up for a free trial.](https://go.microsoft.com/fwlink/p/?linkid=2225630)
38-
39-
[!include[Microsoft Defender for Endpoint API URIs for US Government](../../includes/microsoft-defender-api-usgov.md)]
40-
41-
[!include[Improve request performance](../../includes/improve-request-performance.md)]
42-
43-
This page describes how to create an application to get programmatic access to Defender for Endpoint without a user. If you need programmatic access to Defender for Endpoint on behalf of a user, see [Get access with user context](exposed-apis-create-app-nativeapp.md). If you are not sure which access you need, see [Get started](apis-intro.md).
44-
45-
Microsoft Defender for Endpoint 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 Defender for Endpoint capabilities. The API access requires OAuth2.0 authentication. For more information, see [OAuth 2.0 Authorization Code Flow](/azure/active-directory/develop/active-directory-v2-protocols-oauth-code).
46-
47-
In general, you'll need to take the following steps to use the APIs:
48-
- Create a Microsoft Entra application.
49-
- Get an access token using this application.
50-
- Use the token to access Defender for Endpoint API.
51-
52-
This article explains how to create a Microsoft Entra application, get an access token to Microsoft Defender for Endpoint, and validate the token.
53-
54-
> [!IMPORTANT]
55-
> Microsoft recommends that you use roles with the fewest permissions. This helps improve security for your organization. Global Administrator is a highly privileged role that should be limited to emergency scenarios when you can't use an existing role.
56-
57-
## Create an app
24+
## Step 1: Create an app in Azure
5825

5926
1. Sign in to the [Azure portal](https://portal.azure.com).
6027

61-
2. Navigate to **Microsoft Entra ID** \> **App registrations** \> **New registration**.
28+
2. Search for **App registrations** and navigate to *App registrations*.
6229

63-
:::image type="content" source="../media/atp-azure-new-app2.png" alt-text="The application registration pane" lightbox="../media/atp-azure-new-app2.png":::
30+
3. Select **New registration**.
6431

65-
3. In the registration form, choose a name for your application, and then select **Register**.
32+
4. Choose a name for your application, and then select **Register**.
6633

67-
4. To enable your app to access Defender for Endpoint and assign it **'Read all alerts'** permission, on your application page, select **API Permissions** \> **Add permission** \> **APIs my organization uses** >, type **WindowsDefenderATP**, and then select **WindowsDefenderATP**.
34+
5. In your application page, go to *Manage > Api Permissions > Add permission > APIs my organization uses*.
6835

69-
> [!NOTE]
70-
> `WindowsDefenderATP` does not appear in the original list. Start writing its name in the text box to see it appear.
36+
6. In the *Request API permissions* page, search for **WindowsDefenderATP** and select it.
7137

72-
:::image type="content" source="../media/add-permission.png" alt-text="The API permissions pane" lightbox="../media/add-permission.png":::
38+
7. Select the type of permissions you require, and then select **Add permissions**.
7339

74-
Select **Application permissions** \> **Alert.Read.All**, and then select **Add permissions**.
40+
* **Delegated permissions** - Sign in with your app as if you were a user.
7541

76-
:::image type="content" source="../media/application-permissions.png" alt-text="The application permission information pane" lightbox="../media/application-permissions.png":::
42+
* **Application permissions** - Access the API as a service.
7743

78-
5. Select appropriate permissions. `Read All Alerts` is only an example. Here are some examples:
44+
8. Select the appropriate permissions for your app. To determine which permission you need, look at the *Permissions* section in the API you're calling. Here are two examples:
7945

80-
- To [run advanced queries](run-advanced-query-api.md), select the `Run advanced queries` permission.
81-
- To [isolate a device](isolate-machine.md), select the `Isolate machine` permission.
82-
- To determine which permission you need, look at the **Permissions** section in the API you are interested to call.
46+
* To [run advanced queries](run-advanced-query-api.md), select *Run advanced queries*.
8347

84-
5. Select **Grant consent**.
48+
* To [isolate a device](isolate-machine.md), select *Isolate machine*.
49+
9. Select **Add permission**.
8550

86-
> [!NOTE]
87-
> Every time you add a permission, you must select **Grant consent** for the new permission to take effect.
51+
## Step 2: Add a secret to your app
8852

89-
:::image type="content" source="../media/grant-consent.png" alt-text="The grant permissions page" lightbox="../media/grant-consent.png":::
53+
1. From the application page, select *Certificates & secrets* > *New client secret*.
9054

91-
6. To add a secret to the application, select **Certificates & secrets**, add a description to the secret, and then select **Add**.
55+
2. In the *Add a client secret* pane, add a description and expiration date.
9256

93-
> [!NOTE]
94-
> After you select **Add**, select **copy the generated secret value**. You won't be able to retrieve this value after you leave.
57+
3. Select **Add**.
9558

96-
:::image type="content" source="../media/webapp-create-key2.png" alt-text="The create application option" lightbox="../media/webapp-create-key2.png":::
59+
4. Copy the **Value** of the secret you created. You won't be able to retrieve this value after you leave the page.
9760

98-
7. Write down your application ID and your tenant ID. On your application page, go to **Overview** and copy the following.
61+
5. From your app's *overview* page, copy the **Application (client) ID** and **Directory (tenant) ID**. You need this ID to authenticate your app.
9962

100-
:::image type="content" source="../media/app-and-tenant-ids.png" alt-text="The created app and tenant IDs" lightbox="../media/app-and-tenant-ids.png":::
63+
7. Write down your application ID and your tenant ID. On your application page, go to **Overview** and copy the following.
10164

102-
8. **For Microsoft Defender for Endpoint Partners only**. Set your app to be multi-tenanted (available in all tenants after consent). This is **required** for third-party apps (for example, if you create an app that is intended to run in multiple customers' tenant). This is **not required** if you create a service that you want to run in your tenant only (for example, if you create an application for your own usage that will only interact with your own data). To set your app to be multi-tenanted, follow these steps:
65+
## Multitenant apps
10366

104-
1. Go to **Authentication**, and add `https://portal.azure.com` as the **Redirect URI**.
67+
Microsoft Defender for Endpoint partners need to set their apps to be multi-tenanted. Set your app to be a multitenant app if you're planning to create an app that will run in multiple customers' tenants.
10568

106-
2. On the bottom of the page, under **Supported account types**, select the **Accounts in any organizational directory** application consent for your multi-tenant app.
69+
1. In your Azure app page, go to **Manage > Authentication**.
10770

108-
You need your application to be approved in each tenant where you intend to use it. This is because your application interacts Defender for Endpoint on behalf of your customer.
71+
2. **Add a platform**.
10972

110-
You (or your customer if you are writing a third-party app) need to select the consent link and approve your app. The consent should be done with a user who has administrative privileges in Active Directory.
73+
3. From the *Configure platforms* pane, select **Web**.
11174

112-
The consent link is formed as follows:
75+
4. Add `https://portal.azure.com` to **Redirect URIs** and select **Configure**.
11376

114-
```https
115-
https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
116-
```
77+
3. From the *Supported account types* options, select **Accounts in any organizational directory** and select **Save**.
11778

118-
Where `00000000-0000-0000-0000-000000000000` is replaced with your application ID.
79+
Once you run your app, you need it to be approved in each tenant where you intend to use it. This is because your application interacts with Defender for Endpoint on behalf of your customer. You or your customer, will need to select the consent link and approve your app. Give consent with a user who has admin privileges.
11980

81+
Here's how to form the consent link. Replace `00000000-0000-0000-0000-000000000000` with your app ID.
12082

121-
**Done!** You have successfully registered an application! See examples below for token acquisition and validation.
83+
```https
84+
https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
85+
```
12286

12387
## Get an access token
12488

125-
For more information on Microsoft Entra tokens, see the [Microsoft Entra tutorial](/azure/active-directory/develop/active-directory-v2-protocols-oauth-client-creds).
89+
This section lists a few methods for getting your app's [access token](/entra/identity-platform/v2-oauth2-client-creds-grant-flow#get-a-token).
12690

127-
### Use PowerShell
91+
# [PowerShell](#tab/PowerShell)
12892

12993
```powershell
130-
# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
131-
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.
94+
# This script acquires the App Context Token and stores it in the variable $token for later use.
95+
# Paste your Tenant ID, App ID, and App Secret (App key) into the quotes below.
13296
13397
$tenantId = '' ### Paste your tenant ID here
13498
$appId = '' ### Paste your Application ID here
@@ -147,105 +111,63 @@ $token = $authResponse.access_token
147111
$token
148112
```
149113

150-
### Use C#:
151-
152-
The following code was tested with NuGet Microsoft.Identity.Client 3.19.8.
153-
154-
> [!IMPORTANT]
155-
> The [Microsoft.IdentityModel.Clients.ActiveDirectory](https://www.nuget.org/packages/Microsoft.IdentityModel.Clients.ActiveDirectory) NuGet package and Azure AD Authentication Library (ADAL) have been deprecated. No new features have been added since June 30, 2020. We strongly encourage you to upgrade, see the [migration guide](/azure/active-directory/develop/msal-migration) for more details.
156-
157-
1. Create a new console application.
158-
159-
1. Install NuGet [Microsoft.Identity.Client](https://www.nuget.org/packages/Microsoft.Identity.Client/).
114+
# [Python](#tab/Python)
160115

161-
1. Add the following:
116+
[Get token using Python](run-advanced-query-sample-python.md#get-token).
162117

163-
```csharp
164-
using Microsoft.Identity.Client;
165-
```
118+
# [Curl](#tab/Curl)
166119

167-
1. Copy and paste the following code in your app (don't forget to update the three variables: ```tenantId, appId, appSecret```):
120+
The following procedure assumes that Curl for Windows is already installed on your computer.
168121

169-
```csharp
170-
string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
171-
string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
172-
string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place!
173-
const string authority = "https://login.microsoftonline.com";
174-
const string audience = "https://api.securitycenter.microsoft.com";
175-
176-
IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();
177-
178-
List<string> scopes = new List<string>() { $"{audience}/.default" };
179-
180-
AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();
181-
182-
string token = authResult.AccessToken;
183-
```
122+
1. Open a command prompt, and set `CLIENT_ID` to your Azure application ID.
184123

185-
### Use Python
124+
2. Set `CLIENT_SECRET` to your Azure application secret.
186125

187-
See [Get token using Python](run-advanced-query-sample-python.md#get-token).
126+
3. Set `TENANT_ID` to the Azure tenant ID of the customer that wants to use your app to access Defender for Endpoint.
188127

189-
### Use Curl
128+
4. Run the following command:
190129

191-
> [!NOTE]
192-
> The following procedure assumes that Curl for Windows is already installed on your computer.
130+
```console
131+
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
132+
```
193133

194-
1. Open a command prompt, and set `CLIENT_ID` to your Azure application ID.
134+
The answer resembles the following code snippet:
195135

196-
1. Set `CLIENT_SECRET` to your Azure application secret.
136+
```console
137+
{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
197138

198-
1. Set `TENANT_ID` to the Azure tenant ID of the customer that wants to use your app to access Defender for Endpoint.
199139

200-
1. Run the following command:
140+
---
201141

202-
```console
203-
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
204-
```
205-
206-
You get an answer that resembles the following code snippet:
207-
208-
```console
209-
{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
210-
```
211-
212142
## Validate the token
213143

214-
Ensure that you got the correct token:
215-
216-
1. Copy and paste the token you got in the previous step into [JWT](https://jwt.ms) in order to decode it.
144+
Follow the process in this section to ensure that you got the correct token. You can send more than one request with the same token. The token expires in an hour.
217145

218-
1. Validate that you get a roles claim with the desired permissions.
146+
1. Copy and paste [your token](#get-an-access-token) into [JWT](https://jwt.ms) to decode it.
219147

220-
In the following image, you can see a decoded token acquired from an app with permissions to all of Microsoft Defender for Endpoint's roles:
221-
222-
:::image type="content" source="../media/webapp-decoded-token.png" alt-text="The token details portion" lightbox="../media/webapp-decoded-token.png":::
148+
2. Validate that you get a roles claim with the desired permissions.
223149

224150
## Use the token to access Microsoft Defender for Endpoint API
225151

226-
1. Choose the API you want to use. For more information, see [Supported Defender for Endpoint APIs](exposed-apis-list.md).
152+
1. Choose the [API](exposed-apis-list.md) you want to use.
227153

228-
1. Set the authorization header in the `http` request you send to `Bearer {token}` (Bearer is the authorization scheme).
154+
2. Set the authorization header in the `http` request you send to `Bearer {token}`. *Bearer* is the authorization scheme.
229155

230-
1. The expiration time of the token is one hour. You can send more than one request with the same token.
156+
### Example
231157

232-
The following is an example of sending a request to get a list of alerts **using C#**:
158+
This example sends a request to get a list of alerts using C#.
233159

234160
```csharp
235161
var httpClient = new HttpClient();
236-
237162
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");
238-
239163
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
240-
241164
var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
242-
243-
// Do something useful with the response
244165
```
245166

246167
## See also
247168

248-
- [Supported Microsoft Defender for Endpoint APIs](exposed-apis-list.md)
249-
- [Access Microsoft Defender for Endpoint on behalf of a user](exposed-apis-create-app-nativeapp.md)
169+
* [Get access with user context](exposed-apis-create-app-nativeapp.md)
170+
171+
* [Supported Microsoft Defender for Endpoint APIs](exposed-apis-list.md)
250172

251-
[!INCLUDE [Microsoft Defender for Endpoint Tech Community](../../includes/defender-mde-techcommunity.md)]
173+
* [Access Microsoft Defender for Endpoint on behalf of a user](exposed-apis-create-app-nativeapp.md)

‎defender-endpoint/defender-endpoint-false-positives-negatives.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -315,6 +315,10 @@ In general, you shouldn't need to define exclusions for Microsoft Defender Antiv
315315

316316
You can submit entities, such as files and fileless detections, to Microsoft for analysis. Microsoft security researchers analyze all submissions, and their results help inform Defender for Endpoint threat protection capabilities. When you sign in at the submission site, you can track your submissions.
317317

318+
### Submit hashes for analysis
319+
320+
To investigate hashes, use the https://aka.ms/wdsi web portal. A maximum of 100 hashes can be submitted. The source of the Indicator of Compromise (IOC), must be provided. This can be a blog post, security article, or any other relevant source.
321+
318322
### Submit a file for analysis
319323

320324
If you have a file that was either wrongly detected as malicious or was missed, follow these steps to submit the file for analysis.

0 commit comments

Comments
 (0)