Merge pull request #640 from MicrosoftDocs/atp-api-update

Update application creation to align with Azure's new pages.

windows/security/threat-protection/microsoft-defender-atp/api-hello-world.md

@@ -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
@@ -19,10 +19,9 @@ ms.topic: article
 
 # Microsoft Defender ATP API - Hello World 
 
-**Applies to:** 
+**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
-- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
 
-> Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/WindowsForBusiness/windows-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) 
+- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/WindowsForBusiness/windows-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) 
 
 
 ## Get Alerts using a simple PowerShell script
@@ -33,65 +32,57 @@ 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**. 
 
-   ![Image of Microsoft Azure and navigation to application registration](images/atp-azure-new-app.png)
+   ![Image of Microsoft Azure and navigation to application registration](images/atp-azure-new-app2.png)
 
-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. 
+4. Allow your Application to access Microsoft Defender ATP and assign it **'Read all alerts'** permission:
-   - **Application type:** Web app / API
-   - **Redirect URI:** `https://127.0.0.1`
 
-   ![Image of Create application window](images/webapp-create.png)
+   - On your application page, click **API Permissions** > **Add permission** > **APIs my organization uses** > type **WindowsDefenderATP** and click on **WindowsDefenderATP**.
 
-4. Allow your App to access Microsoft Defender ATP and assign it 'Read all alerts' permission:
+   - **Note**: WindowsDefenderATP does not appear in the original list. You need to start writing its name in the text box to see it appear.
 
-   - Click **Settings** > **Required permissions** > **Add**.
+   ![Image of API access and API selection](images/add-permission.png)
 
-     ![Image of new app in Azure](images/webapp-add-permission.png)
+   - Choose **Application permissions** > **Alert.Read.All** > Click on **Add permissions**
 
-   - Click **Select an API** > **WindowsDefenderATP**, then click **Select**.
+   ![Image of API access and API selection](images/application-permissions.png)
 
-     **Note**: WindowsDefenderATP does not appear in the original list. You need to start writing its name in the text box to see it appear.
+   **Important note**: You need to select the relevant permissions. 'Read All Alerts' is only an example!
 
-     ![Image of API access and API selection](images/webapp-add-permission-2.png)
+     For instance,
 
-   - Click **Select permissions** > **Read all alerts** > **Select**.
+     - 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.
 
-     ![Image of API access and API selection](images/webapp-add-permission-readalerts.png)
+5. Click **Grant consent**
 
-   - Click **Done**
+	- **Note**: Every time you add permission you must click on **Grant consent** for the new permission to take effect.
 
-     ![Image of add permissions completion](images/webapp-add-permission-end.png)
+	![Image of Grant permissions](images/grant-consent.png)
 
-   - Click **Grant permissions**
+6. 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**.
 
-     ![Image of Grant permissions](images/webapp-grant-permissions.png)
+    **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:
+    ![Image of create app key](images/webapp-create-key2.png)
 
-   - Click **Keys**, type a key name and click **Save**.
+7. Write down your application ID and your tenant ID:
 
-     ![Image of create app key](images/webapp-create-key.png)
+   - On your application page, go to **Overview** and copy the following:
 
-6. Write down your App ID and your Tenant ID:
+   ![Image of created app id](images/app-and-tenant-ids.png)
-
-   - App ID: 
-
-     ![Image of created app id](images/webapp-app-id1.png)
-
-   - Tenant ID: Navigate to **Azure Active Directory** > **Properties**
-
-     ![Image of create app key](images/api-tenant-id.png)
 
 
 Done! You have successfully registered an application!
@@ -106,8 +97,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
+$appId = '' ### Paste your Application ID here
-$appSecret = '' ### Paste your app key here
+$appSecret = '' ### Paste your Application secret here
 
 $resourceAppIdUri = 'https://api.securitycenter.windows.com'
 $oAuthUri = "https://login.windows.net/$TenantId/oauth2/token"

windows/security/threat-protection/microsoft-defender-atp/exposed-apis-create-app-nativeapp.md

@@ -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
@@ -19,10 +19,9 @@ ms.topic: article
 
 # Use Microsoft Defender ATP APIs
 
-**Applies to:**
+**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
-- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
 
-> Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/en-us/WindowsForBusiness/windows-atp?ocid=docs-wdatp-exposedapis-abovefoldlink)
+- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/en-us/WindowsForBusiness/windows-atp?ocid=docs-wdatp-exposedapis-abovefoldlink)
 
 This page describes how to create an application to get programmatic access to Microsoft Defender ATP on behalf of a user.
 
@@ -40,7 +39,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 +47,50 @@ 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**. 
 
-   ![Image of Microsoft Azure and navigation to application registration](images/atp-azure-new-app.png)
+   ![Image of Microsoft Azure and navigation to application registration](images/atp-azure-new-app2.png)
 
-3. In the Create window, enter the following information then click **Create**.
+3. In the registration from, enter the following information then click **Register**.
 
-   ![Image of Create application window](images/nativeapp-create.png)
+   ![Image of Create application window](images/nativeapp-create2.png)
 
-   - **Name:** -Your app name-
+   - **Name:** -Your application name-
-   - **Application type:** Native
+   - **Application type:** Public client
-   - **Redirect URI:** `https://127.0.0.1`
 
+4. Allow your Application to access Microsoft Defender ATP and assign it 'Read alerts' permission:
 
-4. Click **Settings** > **Required permissions** > **Add**.
+	- On your application page, click **API Permissions** > **Add permission** > **APIs my organization uses** > type **WindowsDefenderATP** and click on **WindowsDefenderATP**.
 
-   ![Image of new app in Azure](images/nativeapp-add-permission.png)
+	- **Note**: WindowsDefenderATP does not appear in the original list. You need to start writing its name in the text box to see it appear.
 
-5. Click **Select an API** > **WindowsDefenderATP**, then click **Select**.
+	![Image of API access and API selection](images/add-permission.png)
 
-   **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**
 
-   ![Image of API access and API selection](images/webapp-add-permission-2.png)
+    ![Image of API access and API selection](images/application-permissions-public-client.png)
 
-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**
 
-     ![Image of select permissions](images/nativeapp-select-permissions.png)
+     **Note**: Every time you add permission you must click on **Grant consent** for the new permission to take effect.
 
+     ![Image of Grant permissions](images/grant-consent.png)
 
-7. Click **Done**
+6. Write down your application ID and your tenant ID:
 
-    ![Image of add permissions completion](images/nativeapp-add-permissions-end.png)
+   - On your application page, go to **Overview** and copy the following:
 
-8. Click **Grant permissions**
+   ![Image of created app id](images/app-and-tenant-ids.png)
-
-	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.
-
-	![Image of Grant permissions](images/webapp-grant-permissions.png)
-
-9. Write down your application ID.
-    
-	![Image of app ID](images/nativeapp-get-appid.png)
 
 
 ## Get an access token
@@ -156,7 +145,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:
 
 ![Image of token validation](images/nativeapp-decoded-token.png)
 

windows/security/threat-protection/microsoft-defender-atp/exposed-apis-create-app-webapp.md

@@ -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
@@ -19,11 +19,9 @@ ms.topic: article
 
 # Create an app to access Microsoft Defender ATP without a user
 
-**Applies to:**
+**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
 
-- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
+- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/en-us/WindowsForBusiness/windows-atp?ocid=docs-wdatp-exposedapis-abovefoldlink)
-
-> Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/en-us/WindowsForBusiness/windows-atp?ocid=docs-wdatp-exposedapis-abovefoldlink)
 
 This page describes how to create an application to get programmatic access to Microsoft Defender ATP without a user.
 
@@ -31,7 +29,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 +40,27 @@ 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**. 
 
-   ![Image of Microsoft Azure and navigation to application registration](images/atp-azure-new-app.png)
+   ![Image of Microsoft Azure and navigation to application registration](images/atp-azure-new-app2.png)
 
-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**.
 
-   ![Image of Create application window](images/webapp-create.png)
+4. Allow your Application to access Microsoft Defender ATP and assign it **'Read all alerts'** permission:
 
-   - **Name:** Choose your own name. 
+   - On your application page, click **API Permissions** > **Add permission** > **APIs my organization uses** > type **WindowsDefenderATP** and click on **WindowsDefenderATP**.
-   - **Application type:** Web app / API
-   - **Redirect URI:** `https://127.0.0.1`
 
-4. Click **Settings** > **Required permissions** > **Add**.
+   - **Note**: WindowsDefenderATP does not appear in the original list. You need to start writing its name in the text box to see it appear.
 
-   ![Image of new app in Azure](images/webapp-add-permission.png)
+   ![Image of API access and API selection](images/add-permission.png)
 
-5. Click **Select an API** > **WindowsDefenderATP**, then click **Select**.
+   - Choose **Application permissions** > **Alert.Read.All** > Click on **Add permissions**
 
-   **Note**: WindowsDefenderATP does not appear in the original list. You need to start writing its name in the text box to see it appear.
+   ![Image of API access and API selection](images/application-permissions.png)
 
-   ![Image of API access and API selection](images/webapp-add-permission-2.png)
+   **Important note**: You need to select the relevant permissions. 'Read All Alerts' is only an example!
-
-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!
 
      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.
 
-     ![Image of select permissions](images/webapp-select-permission.png)
+5. 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.
 
-    ![Image of add permissions completion](images/webapp-add-permission-end.png)
+	![Image of Grant permissions](images/grant-consent.png)
 
-8. Click **Grant permissions**
+6. 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!
 
-    ![Image of Grant permissions](images/webapp-grant-permissions.png)
+    ![Image of create app key](images/webapp-create-key2.png)
 
-9. Click **Keys**, type a key name and click **Save**.
+7. 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:
 
-    ![Image of create app key](images/webapp-create-key.png)
+   ![Image of created app id](images/app-and-tenant-ids.png)
 
-10. Write down your application ID.
+8. **For Microsoft Defender ATP Partners only** - Set your application to be multi-tenanted (available in all tenants after consent)
 
-    ![Image of created app id](images/webapp-app-id1.png)
+    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 Application:
-
-    ![Image of multi tenant](images/webapp-edit-multitenant.png)
-
-    - Application consent for your multi-tenant App:
 
     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
+$appId = '' ### Paste your Application ID here
-$appSecret = '' ### Paste your app key 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:
 
 ![Image of token validation](images/webapp-decoded-token.png)