mirror of
https://github.com/MicrosoftDocs/windows-itpro-docs.git
synced 2025-05-12 13:27:23 +00:00
Update application creation to align with Azure's new pages.
This commit is contained in:
Ben Alfasi
parent
0293c749fd
commit
a04e2e332f
@ -1,5 +1,5 @@
|
||||
---
|
||||
title: Advanced Hunting API
|
||||
title: Hello World
|
||||
ms.reviewer:
|
||||
description: Use this API to run advanced queries
|
||||
keywords: apis, supported apis, advanced hunting, query
|
||||
@ -33,65 +33,47 @@ It only takes 5 minutes done in two steps:
|
||||
- Use examples: only requires copy/paste of a short PowerShell script
|
||||
|
||||
### Do I need a permission to connect?
|
||||
For the App registration stage, you must have a Global administrator role in your Azure Active Directory (Azure AD) tenant.
|
||||
For the Application registration stage, you must have a **Global administrator** role in your Azure Active Directory (Azure AD) tenant.
|
||||
|
||||
### Step 1 - Create an App in Azure Active Directory
|
||||
|
||||
1. Log on to [Azure](https://portal.azure.com) with your Global administrator user.
|
||||
1. Log on to [Azure](https://portal.azure.com) with your **Global administrator** user.
|
||||
|
||||
2. Navigate to **Azure Active Directory** > **App registrations** > **New application registration**.
|
||||
2. Navigate to **Azure Active Directory** > **App registrations** > **New registration**.
|
||||
|
||||
|
||||
|
||||
|
||||
3. In the registration form, enter the following information, then click **Create**.
|
||||
3. In the registration form, choose a name for your application and then click **Register**.
|
||||
|
||||
- **Name:** Choose your own name.
|
||||
- **Application type:** Web app / API
|
||||
- **Redirect URI:** `https://127.0.0.1`
|
||||
4. Allow your Application to access Microsoft Defender ATP and assign it 'Read all alerts' permission:
|
||||
|
||||
|
||||
|
||||
4. Allow your App to access Microsoft Defender ATP and assign it 'Read all alerts' permission:
|
||||
|
||||
- Click **Settings** > **Required permissions** > **Add**.
|
||||
|
||||
|
||||
|
||||
- Click **Select an API** > **WindowsDefenderATP**, then click **Select**.
|
||||
- On your application page, click **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.
|
||||
|
||||
|
||||
- Choose **Application permissions** > **Alert.Read.All** > Click on **Add permissions**
|
||||
|
||||
- Click **Select permissions** > **Read all alerts** > **Select**.
|
||||
|
||||
|
||||
|
||||
- Click **Grant consent**
|
||||
|
||||
- Click **Done**
|
||||
**Note**: Every time you add permission you must click on **Grant consent** for the new permission to take effect.
|
||||
|
||||
|
||||
|
||||
|
||||
- Click **Grant permissions**
|
||||
5. Add a secret to the application.
|
||||
|
||||
**Note**: Every time you add permission you must click on **Grant permissions**.
|
||||
- Click **Certificates & secrets**, add description to the secret and click **Add**.
|
||||
|
||||
|
||||
**Important**: After click Add, **copy the generated secret value**. You won't be able to retrieve after you leave!
|
||||
|
||||
5. Create a key for your App:
|
||||
|
||||
|
||||
- Click **Keys**, type a key name and click **Save**.
|
||||
6. Write down your application ID and your tenant ID:
|
||||
|
||||
|
||||
- On your application page, go to **Overview** and copy the following:
|
||||
|
||||
6. Write down your App ID and your Tenant ID:
|
||||
|
||||
- App ID:
|
||||
|
||||
|
||||
|
||||
- Tenant ID: Navigate to **Azure Active Directory** > **Properties**
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Done! You have successfully registered an application!
|
||||
@ -106,8 +88,8 @@ Done! You have successfully registered an application!
|
||||
# Paste below your Tenant ID, App ID and App Secret (App key).
|
||||
|
||||
$tenantId = '' ### Paste your tenant ID here
|
||||
$appId = '' ### Paste your app ID here
|
||||
$appSecret = '' ### Paste your app key here
|
||||
$appId = '' ### Paste your Application ID here
|
||||
$appSecret = '' ### Paste your Application secret here
|
||||
|
||||
$resourceAppIdUri = 'https://api.securitycenter.windows.com'
|
||||
$oAuthUri = "https://login.windows.net/$TenantId/oauth2/token"
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Use Microsoft Defender Advanced Threat Protection APIs
|
||||
ms.reviewer:
|
||||
description: Use the exposed data and actions using a set of progammatic APIs that are part of the Microsoft Intelligence Security Graph.
|
||||
description: Use the exposed data and actions using a set of programmatic APIs that are part of the Microsoft Intelligence Security Graph.
|
||||
keywords: apis, graph api, supported apis, actor, alerts, machine, user, domain, ip, file, advanced hunting, query
|
||||
search.product: eADQiWindows 10XVcnh
|
||||
ms.prod: w10
|
||||
@ -40,7 +40,7 @@ In general, you’ll need to take the following steps to use the APIs:
|
||||
This page explains how to create an AAD application, get an access token to Microsoft Defender ATP and validate the token.
|
||||
|
||||
>[!NOTE]
|
||||
> When accessing Microsoft Defender ATP API on behalf of a user, you will need the correct App permission and user permission.
|
||||
> When accessing Microsoft Defender ATP API on behalf of a user, you will need the correct Application permission and user permission.
|
||||
> If you are not familiar with user permissions on Microsoft Defender ATP, see [Manage portal access using role-based access control](rbac.md).
|
||||
|
||||
>[!TIP]
|
||||
@ -48,60 +48,48 @@ This page explains how to create an AAD application, get an access token to Micr
|
||||
|
||||
## Create an app
|
||||
|
||||
1. Log on to [Azure](https://portal.azure.com) with user that has Global Administrator role.
|
||||
1. Log on to [Azure](https://portal.azure.com) with user that has **Global Administrator** role.
|
||||
|
||||
2. Navigate to **Azure Active Directory** > **App registrations** > **New application registration**.
|
||||
2. Navigate to **Azure Active Directory** > **App registrations** > **New registration**.
|
||||
|
||||
|
||||
|
||||
|
||||
3. In the Create window, enter the following information then click **Create**.
|
||||
3. In the registration from, enter the following information then click **Register**.
|
||||
|
||||
|
||||
|
||||
|
||||
- **Name:** -Your app name-
|
||||
- **Application type:** Native
|
||||
- **Redirect URI:** `https://127.0.0.1`
|
||||
- **Name:** -Your application name-
|
||||
- **Application type:** Public client
|
||||
|
||||
4. Allow your Application to access Microsoft Defender ATP and assign it 'Read alerts' permission:
|
||||
|
||||
4. Click **Settings** > **Required permissions** > **Add**.
|
||||
|
||||
|
||||
|
||||
5. Click **Select an API** > **WindowsDefenderATP**, then click **Select**.
|
||||
- On your application page, click **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.
|
||||
|
||||
|
||||
- Choose **Delegated permissions** > **Alert.Read** > Click on **Add permissions**
|
||||
|
||||
6. Click **Select permissions** > **Check the desired permissions** > **Select**.
|
||||
|
||||
|
||||
**Important note**: You need to select the relevant permissions. 'Read alerts' is only an example!
|
||||
|
||||
>[!IMPORTANT]
|
||||
>You need to select the relevant permissions. 'Read alerts' and 'Collect forensics' are only an example.
|
||||
For instance,
|
||||
|
||||
- To [run advanced queries](run-advanced-query-api.md), select 'Run advanced queries' permission
|
||||
- To [isolate a machine](isolate-machine.md), select 'Isolate machine' permission
|
||||
- To determine which permission you need, please look at the **Permissions** section in the API you are interested to call.
|
||||
|
||||
To determine which permission you need, look at the **Permissions** section in the API you are interested to call.
|
||||
- Click **Grant consent**
|
||||
|
||||
|
||||
**Note**: Every time you add permission you must click on **Grant consent** for the new permission to take effect.
|
||||
|
||||
|
||||
|
||||
7. Click **Done**
|
||||
6. Write down your application ID and your tenant ID:
|
||||
|
||||
|
||||
- On your application page, go to **Overview** and copy the following:
|
||||
|
||||
8. Click **Grant permissions**
|
||||
|
||||
In order to add the new selected permissions to the app, the Admin's tenant must press on the **Grant permissions** button.
|
||||
|
||||
If in the future you will want to add more permission to the app, you will need to press on the **Grant permissions** button again so the changes will take effect.
|
||||
|
||||
|
||||
|
||||
9. Write down your application ID.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Get an access token
|
||||
@ -156,7 +144,7 @@ For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.co
|
||||
Sanity check to make sure you got a correct token:
|
||||
- Copy/paste into [JWT](https://jwt.ms) the token you got in the previous step in order to decode it
|
||||
- Validate you get a 'scp' claim with the desired app permissions
|
||||
- In the screenshot below you can see a decoded token acquired from the app in the tutorial:
|
||||
- In the screen shot below you can see a decoded token acquired from the app in the tutorial:
|
||||
|
||||
|
||||
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Create an app to access Microsoft Defender ATP without a user
|
||||
title: Create an Application to access Microsoft Defender ATP without a user
|
||||
ms.reviewer:
|
||||
description: Use the exposed data and actions using a set of progammatic APIs that are part of the Microsoft Intelligence Security Graph.
|
||||
description: Use the exposed data and actions using a set of programmatic APIs that are part of the Microsoft Intelligence Security Graph.
|
||||
keywords: apis, graph api, supported apis, actor, alerts, machine, user, domain, ip, file, advanced hunting, query
|
||||
search.product: eADQiWindows 10XVcnh
|
||||
ms.prod: w10
|
||||
@ -31,7 +31,7 @@ If you need programmatic access Microsoft Defender ATP on behalf of a user, see
|
||||
|
||||
If you are not sure which access you need, see [Get started](apis-intro.md).
|
||||
|
||||
Microsoft Defender ATP exposes much of its data and actions through a set of programmatic APIs. Those APIs will help you automate workflows and innovate based on Microsoft Defender ATP capabilities. The API access requires OAuth2.0 authentication. For more information, see [OAuth 2.0 Authorization Code Flow](https://docs.microsoft.com/azure/active-directory/develop/active-directory-v2-protocols-oauth-code).
|
||||
Microsoft Defender ATP 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 Defender ATP capabilities. The API access requires OAuth2.0 authentication. For more information, see [OAuth 2.0 Authorization Code Flow](https://docs.microsoft.com/azure/active-directory/develop/active-directory-v2-protocols-oauth-code).
|
||||
|
||||
In general, you’ll need to take the following steps to use the APIs:
|
||||
- Create an AAD application
|
||||
@ -42,33 +42,25 @@ This page explains how to create an AAD application, get an access token to Micr
|
||||
|
||||
## Create an app
|
||||
|
||||
1. Log on to [Azure](https://portal.azure.com) with user that has Global Administrator role.
|
||||
1. Log on to [Azure](https://portal.azure.com) with user that has **Global Administrator** role.
|
||||
|
||||
2. Navigate to **Azure Active Directory** > **App registrations** > **New application registration**.
|
||||
2. Navigate to **Azure Active Directory** > **App registrations** > **New registration**.
|
||||
|
||||
|
||||
|
||||
|
||||
3. In the Create window, enter the following information then click **Create**.
|
||||
3. In the registration form, choose a name for your application and then click **Register**.
|
||||
|
||||
|
||||
4. Allow your Application to access Microsoft Defender ATP and assign it 'Read all alerts' permission:
|
||||
|
||||
- **Name:** Choose your own name.
|
||||
- **Application type:** Web app / API
|
||||
- **Redirect URI:** `https://127.0.0.1`
|
||||
|
||||
4. Click **Settings** > **Required permissions** > **Add**.
|
||||
|
||||
|
||||
|
||||
5. Click **Select an API** > **WindowsDefenderATP**, then click **Select**.
|
||||
- On your application page, click **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.
|
||||
|
||||
|
||||
- Choose **Application permissions** > **Alert.Read.All** > Click on **Add permissions**
|
||||
|
||||
6. Click **Select permissions** > **Check the desired permissions** > **Select**.
|
||||
|
||||
|
||||
**Important note**: You need to select the relevant permissions. 'Run advanced queries' is only an example!
|
||||
**Important note**: You need to select the relevant permissions. 'Read All Alerts' is only an example!
|
||||
|
||||
For instance,
|
||||
|
||||
@ -76,41 +68,37 @@ This page explains how to create an AAD application, get an access token to Micr
|
||||
- To [isolate a machine](isolate-machine.md), select 'Isolate machine' permission
|
||||
- To determine which permission you need, please look at the **Permissions** section in the API you are interested to call.
|
||||
|
||||
|
||||
- Click **Grant consent**
|
||||
|
||||
7. Click **Done**
|
||||
**Note**: Every time you add permission you must click on **Grant consent** for the new permission to take effect.
|
||||
|
||||
|
||||
|
||||
|
||||
8. Click **Grant permissions**
|
||||
5. Add a secret to the application.
|
||||
|
||||
In order to add the new selected permissions to the app, the Admin's tenant must press on the **Grant permissions** button.
|
||||
- Click **Certificates & secrets**, add description to the secret and click **Add**.
|
||||
|
||||
If in the future you will want to add more permission to the app, you will need to press on the **Grant permissions** button again so the changes will take effect.
|
||||
**Important**: After click Add, **copy the generated secret value**. You won't be able to retrieve after you leave!
|
||||
|
||||
|
||||
|
||||
|
||||
9. Click **Keys**, type a key name and click **Save**.
|
||||
6. Write down your application ID and your tenant ID:
|
||||
|
||||
**Important**: After you save, **copy the key value**. You won't be able to retrieve after you leave!
|
||||
- On your application page, go to **Overview** and copy the following:
|
||||
|
||||
|
||||
|
||||
|
||||
10. Write down your application ID.
|
||||
7. **For Microsoft Defender ATP Partners only** - Set your application to be multi-tenanted (available in all tenants after consent)
|
||||
|
||||
|
||||
This is **required** for 3rd party applications (for example, if you create an application that is intended to run in multiple customers tenant).
|
||||
|
||||
11. **For Microsoft Defender ATP Partners only** - Set your application to be multi-tenanted
|
||||
This is **not required** if you create a service that you want to run in your tenant only (i.e. if you create an application for your own usage that will only interact with your own data)
|
||||
|
||||
This is **required** for 3rd party apps (for example, if you create an application that is intended to run in multiple customers tenant).
|
||||
- Go to **Authentication** > Add https://portal.azure.com as **Redirect URI**.
|
||||
|
||||
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)
|
||||
- On the bottom of the page, under **Supported account types**, mark **Accounts in any organizational directory**
|
||||
|
||||
Click **Properties** > **Yes** > **Save**.
|
||||
|
||||
|
||||
|
||||
- Application consent for your multi-tenant App:
|
||||
- Application consent for your multi-tenant Application:
|
||||
|
||||
You need your application to be approved in each tenant where you intend to use it. This is because your application interacts with Microsoft Defender ATP application on behalf of your customer.
|
||||
|
||||
@ -122,7 +110,7 @@ This page explains how to create an AAD application, get an access token to Micr
|
||||
https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
|
||||
```
|
||||
|
||||
where 00000000-0000-0000-0000-000000000000 should be replaced with your Azure application ID
|
||||
where 00000000-0000-0000-0000-000000000000 should be replaced with your Application ID
|
||||
|
||||
|
||||
- **Done!** You have successfully registered an application!
|
||||
@ -139,8 +127,8 @@ For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.co
|
||||
# Paste below your Tenant ID, App ID and App Secret (App key).
|
||||
|
||||
$tenantId = '' ### Paste your tenant ID here
|
||||
$appId = '' ### Paste your app ID here
|
||||
$appSecret = '' ### Paste your app key here
|
||||
$appId = '' ### Paste your Application ID here
|
||||
$appSecret = '' ### Paste your Application key here
|
||||
|
||||
$resourceAppIdUri = 'https://api.securitycenter.windows.com'
|
||||
$oAuthUri = "https://login.windows.net/$TenantId/oauth2/token"
|
||||
@ -158,7 +146,7 @@ return $token
|
||||
|
||||
### Using C#:
|
||||
|
||||
>The below code was tested with nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8
|
||||
>The below code was tested with Nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8
|
||||
|
||||
- Create a new Console Application
|
||||
- Install Nuget [Microsoft.IdentityModel.Clients.ActiveDirectory](https://www.nuget.org/packages/Microsoft.IdentityModel.Clients.ActiveDirectory/)
|
||||
@ -215,7 +203,7 @@ You will get an answer of the form:
|
||||
Sanity check to make sure you got a correct token:
|
||||
- Copy/paste into [JWT](https://jwt.ms) the token you get in the previous step in order to decode it
|
||||
- Validate you get a 'roles' claim with the desired permissions
|
||||
- In the screenshot below you can see a decoded token acquired from an app with permissions to all of Microsoft Defender ATP's roles:
|
||||
- In the screen shot below you can see a decoded token acquired from an Application with permissions to all of Microsoft Defender ATP's roles:
|
||||
|
||||
|
||||
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 84 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 180 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 43 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 43 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 32 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 88 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 5.7 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 16 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 8.9 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 62 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 47 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 33 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 6.9 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 41 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 12 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 44 KiB |
Loading…
x
Reference in New Issue
Block a user