Merge branch 'main' into QuarRR-chrisda

Author: chrisda

defender-endpoint/api/exposed-apis-create-app-partners.md

@@ -6,7 +6,7 @@ ms.service: defender-endpoint
 ms.author: siosulli
 author: siosulli
 ms.localizationpriority: medium
-ms.date: 01/25/2023
+ms.date: 06/28/2024
 manager: deniseb
 audience: ITPro
 ms.collection: 
@@ -46,13 +46,19 @@ Microsoft Defender for Endpoint exposes much of its data and actions through a s
 
 In general, you need to take the following steps to use the APIs:
 
-- Create a **multi-tenant** Microsoft Entra application.
-- Get authorized(consent) by your customer administrator for your application to access Defender for Endpoint resources it needs.
-- Get an access token using this application.
-- Use the token to access Microsoft Defender for Endpoint API.
+1. Create a multi-tenant Microsoft Entra application.
+
+2. Get authorized(consent) by your customer administrator for your application to access Defender for Endpoint resources it needs.
+
+3. Get an access token using this application.
+
+4. Use the token to access Microsoft Defender for Endpoint API.
 
 The following steps guide you how to create a Microsoft Entra application, get an access token to Microsoft Defender for Endpoint and validate the token.
 
+> [!IMPORTANT]
+> 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.
+
 ## Create the multitenant app
 
 1. Sign in to your [Azure tenant](https://portal.azure.com) with user that has **Global Administrator** role.
@@ -75,34 +81,34 @@ The following steps guide you how to create a Microsoft Entra application, get a
 
    - On your application page, select **API Permissions** \> **Add permission** \> **APIs my organization uses** > type **WindowsDefenderATP** and select on **WindowsDefenderATP**.
 
-   - Note that *WindowsDefenderATP* doesn't appear in the original list. Start writing its name in the text box to see it appear.
+   - `WindowsDefenderATP` doesn't appear in the original list. Start writing its name in the text box to see it appear.
 
      :::image type="content" source="../media/add-permission.png" alt-text="The Add a permission option" lightbox="../media/add-permission.png":::
 
 ### Request API permissions
 
-To determine which permission you need, review the **Permissions** section in the API you're interested to call. For instance:
+To determine which permission you need, review the **Permissions** section in the API you want to call. For instance:
 
-- To [run advanced queries](run-advanced-query-api.md), select 'Run advanced queries' permission
-- To [isolate a device](isolate-machine.md), select 'Isolate machine' permission
+- To [run advanced queries](run-advanced-query-api.md), select the **Run advanced queries** permission.
+- To [isolate a device](isolate-machine.md), select the **Isolate machine** permission.
 
-In the following example we use **'Read all alerts'** permission:
+In the following example we use **Read all alerts** permission:
 
 1. Choose **Application permissions** \> **Alert.Read.All** > select on **Add permissions**
 
    :::image type="content" source="../media/application-permissions.png" alt-text="The option that allows to add a permission" lightbox="../media/application-permissions.png":::
 
 2. Select **Grant consent**
 
-   - **Note**: Every time you add permission you must select on **Grant consent** for the new permission to take effect.
+   - Every time you add permission you must select on **Grant consent** for the new permission to take effect.
 
    :::image type="content" source="../media/grant-consent.png" alt-text="The option that allows consent to be granted" lightbox="../media/grant-consent.png":::
 
 3. Add a secret to the application.
 
    - Select **Certificates & secrets**, add description to the secret and select **Add**.
 
-    **Important**: After you select **Add**, make sure to copy the generated secret value. You won't be able to retrieve it after you leave!
+    After you select **Add**, make sure to copy the generated secret value. You won't be able to retrieve it after you leave!
 
      :::image type="content" source="../media/webapp-create-key2.png" alt-text="The create app key" lightbox="../media/webapp-create-key2.png":::
 
@@ -124,9 +130,9 @@ In the following example we use **'Read all alerts'** permission:
    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 Application ID
+   Where `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 customer's tenant and consent the application.
+   After selecting the consent link, sign in as the Global Administrator of the customer's tenant and consent the application.
 
    :::image type="content" source="../media/app-consent-partner.png" alt-text="The Accept button" lightbox="../media/app-consent-partner.png":::
 
@@ -136,7 +142,7 @@ In the following example we use **'Read all alerts'** permission:
 
 ## Get an access token example
 
-**Note:** To get access token on behalf of your customer, use the customer's tenant ID on the following token acquisitions.
+To get access token on behalf of your customer, use the customer's tenant ID on the following token acquisitions.
 
 For more information on Microsoft Entra token, see [Microsoft Entra tutorial](/azure/active-directory/develop/active-directory-v2-protocols-oauth-client-creds).
 
@@ -166,61 +172,63 @@ return $token
 
 ### Using C#
 
-> The below code was tested with Nuget Microsoft.Identity.Client
-
 > [!IMPORTANT]
-> 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.
+> 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. To upgrade, see the [migration guide](/azure/active-directory/develop/msal-migration).
+
+1. Create a new Console Application.
 
-- Create a new Console Application
-- Install NuGet [Microsoft.Identity.Client](https://www.nuget.org/packages/Microsoft.Identity.Client/)
-- Add the below using
+2. Install NuGet [Microsoft.Identity.Client](https://www.nuget.org/packages/Microsoft.Identity.Client/).
 
-    ```console
+3. Add the following using code:
+
+   ```console
     using Microsoft.Identity.Client;
-    ```
+   ```
 
-- Copy/Paste the below code in your application (don't forget to update the three variables: `tenantId`, `appId`, and `appSecret`)
+   This code was tested with NuGet `Microsoft.Identity.Client`.
 
-    ```csharp
-    string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
-    string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
-    string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place! 
-    const string authority = https://login.microsoftonline.com;
-    const string audience = https://api.securitycenter.microsoft.com;
+4. Copy/Paste the following code in your application (don't forget to update the three variables: `tenantId`, `appId`, and `appSecret`).
 
-    IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();
+   ```csharp
+   string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
+   string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
+   string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place! 
+   const string authority = https://login.microsoftonline.com;
+   const string audience = https://api.securitycenter.microsoft.com;
 
-    List<string> scopes = new List<string>() { $"{audience}/.default" };
+   IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();
 
-    AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();
+   List<string> scopes = new List<string>() { $"{audience}/.default" };
 
-    string token = authResult.AccessToken;
-    ```
+   AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();
+
+   string token = authResult.AccessToken;
+   ```
 
 ### Using Python
 
-Refer to [Get token using Python](run-advanced-query-sample-python.md#get-token).
+See [Get token using Python](run-advanced-query-sample-python.md#get-token).
 
 ### Using Curl
 
 > [!NOTE]
-> The below procedure supposed Curl for Windows is already installed on your computer
+> The following procedure supposed Curl for Windows is already installed on your computer
 
 1. Open a command window.
 
-2. Set CLIENT_ID to your Azure application ID.
+2. Set `CLIENT_ID` to your Azure application ID.
 
-3. Set CLIENT_SECRET to your Azure application secret.
+3. Set `CLIENT_SECRET` to your Azure application secret.
 
-4. Set TENANT_ID to the Azure tenant ID of the customer that wants to use your application to access Microsoft Defender for Endpoint application.
+4. Set `TENANT_ID` to the Azure tenant ID of the customer that wants to use your application to access Microsoft Defender for Endpoint application.
 
 5. Run the following command:
 
    ```curl
    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
    ```
 
-   You get an answer of the form:
+   You get an answer that resembles the following code snippet:
 
    ```console
    {"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
@@ -232,21 +240,22 @@ Confirm you received a correct token.
 
 1. Copy/paste into [JWT](https://jwt.ms) the token you get in the previous step in order to decode it.
 
-2. Confirm you get a 'roles' claim with the desired permissions.
+2. Confirm you get a roles claim with the appropriate permissions.
 
    In the following screenshot, you can see a decoded token acquired from an Application with multiple permissions to  Microsoft Defender for Endpoint:
 
+   :::image type="content" source="../media/webapp-decoded-token.png" alt-text="The token validation page" lightbox="../media/webapp-decoded-token.png":::
+
    The "tid" claim is the tenant ID the token belongs to.
 
-   :::image type="content" source="../media/webapp-decoded-token.png" alt-text="The token validation page" lightbox="../media/webapp-decoded-token.png":::
 
 ## Use the token to access Microsoft Defender for Endpoint API
 
 1. Choose the API you want to use. For more information, see [Supported Microsoft Defender for Endpoint APIs](exposed-apis-list.md).
 
-2. Set the Authorization header in the Http request you send to "Bearer {token}" (Bearer is the Authorization scheme). The Expiration time of the token is 1 hour (you can send more than one request with the same token).
+2. Set the Authorization header in the Http request you send to `Bearer {token}` (Bearer is the Authorization scheme). The Expiration time of the token is one hour (you can send more than one request with the same token).
 
-   Here's an example of sending a request to get a list of alerts **using C#**
+   Here's an example of sending a request to get a list of alerts using C#:
 
    ```csharp
    var httpClient = new HttpClient();