You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
25
18
19
+
API access requires [OAuth2.0 authentication](/azure/active-directory/develop/active-directory-v2-protocols-oauth-code).
26
20
27
-
**Applies to:**
21
+
## Prerequisites
28
22
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)
23
+
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*.
32
24
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)]
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
25
+
## Step 1: Create an app in Azure
58
26
59
27
1. Sign in to the [Azure portal](https://portal.azure.com).
3. In the registration form, choose a name for your application, and then select **Register**.
33
+
4. Choose a name for your application, and then select **Register**.
66
34
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**.
35
+
5. In your application page, go to *Manage > Api Permissions > Add permission > APIs my organization uses*.
68
36
69
-
> [!NOTE]
70
-
> `WindowsDefenderATP` does not appear in the original list. Start writing its name in the text box to see it appear.
37
+
6. In the *Request API permissions* page, search for **WindowsDefenderATP** and select it.
71
38
72
-
:::image type="content" source="../media/add-permission.png" alt-text="The API permissions pane" lightbox="../media/add-permission.png":::
39
+
7. Select the type of permissions you require, and then select **Add permissions**.
73
40
74
-
Select**Application permissions**\>**Alert.Read.All**, and then select **Add permissions**.
41
+
***Delegated permissions**- Sign in with your app as if you were a user.
75
42
76
-
:::image type="content" source="../media/application-permissions.png" alt-text="The application permission information pane" lightbox="../media/application-permissions.png":::
43
+
***Application permissions** - Access the API as a service.
77
44
78
-
5. Select appropriate permissions. `Read All Alerts` is only an example. Here are some examples:
45
+
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:
79
46
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.
47
+
* To [run advanced queries](run-advanced-query-api.md), select *Run advanced queries*.
83
48
84
-
5. Select **Grant consent**.
49
+
* To [isolate a device](isolate-machine.md), select *Isolate machine*.
50
+
9. Select **Add permission**.
85
51
86
-
> [!NOTE]
87
-
> Every time you add a permission, you must select **Grant consent** for the new permission to take effect.
52
+
## Step 2: Add a secret to your app
88
53
89
-
:::image type="content" source="../media/grant-consent.png" alt-text="The grant permissions page" lightbox="../media/grant-consent.png":::
54
+
1. From the application page, select *Certificates & secrets* > *New client secret*.
90
55
91
-
6. To add a secret to the application, select **Certificates & secrets**, add a description to the secret, and then select **Add**.
56
+
2. In the *Add a client secret* pane, add a description and expiration date.
92
57
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.
4. Copy the **Value** of the secret you created. You won't be able to retrieve this value after you leave the page.
97
61
98
-
7. Write down your application ID and your tenant ID. On your application page, go to **Overview** and copy the following.
62
+
5. From your app's *overview* page, copy the **Application (client) ID** and **Directory (tenant) ID**. You need this ID to authenticate your app.
99
63
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":::
64
+
7. Write down your application ID and your tenant ID. On your application page, go to **Overview**and copy the following.
101
65
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:
66
+
## Multitenant apps
103
67
104
-
1. Go to **Authentication**, and add `https://portal.azure.com` as the **Redirect URI**.
68
+
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.
105
69
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.
70
+
1. In your Azure app page, go to **Manage > Authentication**.
107
71
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.
72
+
2.**Add a platform**.
109
73
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.
74
+
3. From the *Configure platforms* pane, select **Web**.
111
75
112
-
The consent link is formed as follows:
76
+
4. Add `https://portal.azure.com` to **Redirect URIs** and select **Configure**.
3. From the *Supported account types* options, select **Accounts in any organizational directory** and select **Save**.
117
79
118
-
Where `00000000-0000-0000-0000-000000000000` is replaced with your application ID.
80
+
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.
119
81
82
+
Here's how to form the consent link. Replace `00000000-0000-0000-0000-000000000000` with your app ID.
120
83
121
-
**Done!** You have successfully registered an application! See examples below for token acquisition and validation.
For more information on Microsoft Entra tokens, see the [Microsoft Entra tutorial](/azure/active-directory/develop/active-directory-v2-protocols-oauth-client-creds).
90
+
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).
126
91
127
-
### Use PowerShell
92
+
#[PowerShell](#tab/PowerShell)
128
93
129
94
```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.
95
+
# This script acquires the App Context Token and stores it in the variable $token for later use.
96
+
# Paste your Tenant ID, App ID, and App Secret (App key) into the quotes below.
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.
1. Copyandpastethetokenyougotinthepreviousstepinto [JWT](https://jwt.ms) in order to decode it.
145
+
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.
0 commit comments