Merge pull request #134677 from JnHs/jh-batch-rolenote

add note and cleanup topic

Author: Court72

articles/batch/batch-aad-auth.md

@@ -2,13 +2,13 @@
 title: Authenticate Azure Batch services with Azure Active Directory
 description: Batch supports Azure AD for authentication from the Batch service. Learn how to authenticate in one of two ways.
 ms.topic: how-to
-ms.date: 01/28/2020
+ms.date: 10/20/2020
 ms.custom: has-adal-ref
 ---
 
 # Authenticate Batch service solutions with Active Directory
 
-Azure Batch supports authentication with [Azure Active Directory][aad_about] (Azure AD). Azure AD is Microsoft’s multi-tenant cloud based directory and identity management service. Azure itself uses Azure AD to authenticate its customers, service administrators, and organizational users.
+Azure Batch supports authentication with [Azure Active Directory](../active-directory/fundamentals/active-directory-whatis.md) (Azure AD). Azure AD is Microsoft's multi-tenant cloud based directory and identity management service. Azure itself uses Azure AD to authenticate its customers, service administrators, and organizational users.
 
 When using Azure AD authentication with Azure Batch, you can authenticate in one of two ways:
 
@@ -35,10 +35,8 @@ To authenticate with Azure AD, you use this endpoint together with the tenant ID
 > The tenant-specific endpoint is required when you authenticate using a service principal.
 >
 > The tenant-specific endpoint is optional when you authenticate using integrated authentication, but recommended. However, you can also use the Azure AD common endpoint. The common endpoint provides a generic credential gathering interface when a specific tenant is not provided. The common endpoint is `https://login.microsoftonline.com/common`.
->
->
 
-For more information about Azure AD endpoints, see [Authentication Scenarios for Azure AD][aad_auth_scenarios].
+For more information about Azure AD endpoints, see [Authentication vs. authorization]()../active-directory/develop/authentication-vs-authorization.md).
 
 ### Batch resource endpoint
 
@@ -48,17 +46,15 @@ Use the **Azure Batch resource endpoint** to acquire a token for authenticating
 
 ## Register your application with a tenant
 
-The first step in using Azure AD to authenticate is registering your application in an Azure AD tenant. Registering your application enables you to call the Azure [Active Directory Authentication Library][aad_adal] (ADAL) from your code. The ADAL provides an API for authenticating with Azure AD from your application. Registering your application is required whether you plan to use integrated authentication or a service principal.
+The first step in using Azure AD to authenticate is registering your application in an Azure AD tenant. Registering your application enables you to call the Azure [Active Directory Authentication Library](../active-directory/azuread-dev/active-directory-authentication-libraries.md) (ADAL) from your code. The ADAL provides an API for authenticating with Azure AD from your application. Registering your application is required whether you plan to use integrated authentication or a service principal.
 
 When you register your application, you supply information about your application to Azure AD. Azure AD then provides an application ID (also called a *client ID*) that you use to associate your application with Azure AD at runtime. To learn more about the application ID, see [Application and service principal objects in Azure Active Directory](../active-directory/develop/app-objects-and-service-principals.md).
 
-To register your Batch application, follow the steps in the [Adding an Application](../active-directory/develop/quickstart-register-app.md) section in [Integrating applications with Azure Active Directory][aad_integrate]. If you register your application as a Native Application, you can specify any valid URI for the **Redirect URI**. It does not need to be a real endpoint.
+To register your Batch application, follow the steps in the **Register an application** section in [Quickstart: Register an application with the Microsoft identity platform](../active-directory/develop/quickstart-register-app.md). If you register your application as a Native Application, you can specify any valid URI for the **Redirect URI**. It does not need to be a real endpoint.
 
 After you've registered your application, you'll see the application ID:
 
-![Register your Batch application with Azure AD](./media/batch-aad-auth/app-registration-data-plane.png)
-
-For more information about registering an application with Azure AD, see [Authentication Scenarios for Azure AD](../active-directory/develop/authentication-vs-authorization.md).
+![Screenshot of the Application ID shown in the Azure portal.](./media/batch-aad-auth/app-registration-data-plane.png)
 
 ## Get the tenant ID for your Active Directory
 
@@ -68,31 +64,26 @@ The tenant ID identifies the Azure AD tenant that provides authentication servic
 1. Select **Properties**.
 1. Copy the GUID value provided for the **Directory ID**. This value is also called the tenant ID.
 
-![Copy the directory ID](./media/batch-aad-auth/aad-directory-id.png)
+![Screenshot of the Directory ID in the Azure portal.](./media/batch-aad-auth/aad-directory-id.png)
 
 ## Use integrated authentication
 
 To authenticate with integrated authentication, you need to grant your application permissions to connect to the Batch service API. This step enables your application to authenticate calls to the Batch service API with Azure AD.
 
 Once you've registered your application, follow these steps in the Azure portal to grant it access to the Batch service:
 
-1. In the left-hand navigation pane of the Azure portal, choose **All services**. Select **App Registrations**.
-1. Search for the name of your application in the list of app registrations:
-
-    ![Search for your application name](./media/batch-aad-auth/search-app-registration.png)
-
+1. In the Azure portal, choose **All services**, then select **App Registrations**.
+1. Search for the name of your application in the list of app registrations.
 1. Select the application and select **API permissions**.
 1. In the **API permissions** section, select **Add a permission**.
 1. In **Select an API**, search for the Batch API. Search for each of these strings until you find the API:
     1. **Microsoft Azure Batch**
     1. **ddbf3205-c6bd-46ae-8127-60eb93363864** is the ID for the Batch API.
-1. Once you find the Batch API, select it and select **Select**.
+1. Once you find the Batch API, select it and then choose **Select**.
 1. In **Select permissions**, select the check box next to **Access Azure Batch Service** and then select **Add permissions**.
 
 The **API permissions** section now shows that your Azure AD application has access to both Microsoft Graph and the Batch service API. Permissions are granted to Microsoft Graph automatically when you first register your app with Azure AD.
 
-![Grant API permissions](./media/batch-aad-auth/required-permissions-data-plane.png)
-
 ## Use a service principal
 
 To authenticate an application that runs unattended, you use a service principal. After you've registered your application, follow these steps in the Azure portal to configure a service principal:
@@ -106,14 +97,12 @@ When your application authenticates with a service principal, it sends both the
 
 Follow these steps in the Azure portal:
 
-1. In the left-hand navigation pane of the Azure portal, choose **All services**. Select **App Registrations**.
+1. In the Azure portal, choose **All services**. Select **App Registrations**.
 1. Select your application from the list of app registrations.
 1. Select the application and then select **Certificates & secrets**. In the **Client secrets** section, select **New client secret**.
-1. To create a secret, enter a description for the secret. Then select an expirations for the secret of either one year, two years, or no expiration..
+1. To create a secret, enter a description for the secret. Then select an expiration for the secret of either one year, two years, or no expiration.
 1. Select **Add** to create and display the secret. Copy the secret value to a safe place, as you won't be able to access it again after you leave the page.
 
-    ![Create a secret key](./media/batch-aad-auth/secret-key.png)
-
 ### Assign Azure RBAC to your application
 
 To authenticate with a service principal, you need to assign Azure RBAC to your application. Follow these steps:
@@ -152,6 +141,9 @@ You can use a custom role to grant permissions to an Azure AD user, group, or se
 
 Custom roles are for users authenticated by Azure AD, not the Batch account credentials (shared key). Note that the Batch account credentials give full permission to the Batch account. Also note that jobs using autopool require pool-level permissions.
 
+> [!NOTE]
+> Certain role assignments need to be specified in the Action field, whereas others need to be specified in the DataAction field. For more information, see [Azure resource provider operations](../role-based-access-control/resource-provider-operations.md#microsoftbatch).
+
 Here's an example of a custom role definition:
 
 ```json
@@ -188,7 +180,7 @@ Here's an example of a custom role definition:
 }
 ```
 
-For more general information on creating a custom role, see [Azure custom roles](../role-based-access-control/custom-roles.md).
+For more information on creating a custom role, see [Azure custom roles](../role-based-access-control/custom-roles.md).
 
 ### Get the tenant ID for your Azure Active Directory
 
@@ -207,10 +199,7 @@ The code examples in this section show how to authenticate with Azure AD using i
 > [!NOTE]
 > An Azure AD authentication token expires after one hour. When using a long-lived **BatchClient** object, we recommend that you retrieve a token from ADAL on every request to ensure you always have a valid token.
 >
->
-> To achieve this in .NET, write a method that retrieves the token from Azure AD and pass that method to a **BatchTokenCredentials** object as a delegate. The delegate method is called on every request to the Batch service to ensure that a valid token is provided. By default ADAL caches tokens, so a new token is retrieved from Azure AD only when necessary. For more information about tokens in Azure AD, see [Authentication Scenarios for Azure AD][aad_auth_scenarios].
->
->
+> To achieve this in .NET, write a method that retrieves the token from Azure AD and pass that method to a **BatchTokenCredentials** object as a delegate. The delegate method is called on every request to the Batch service to ensure that a valid token is provided. By default ADAL caches tokens, so a new token is retrieved from Azure AD only when necessary. For more information about tokens in Azure AD, see [Security tokens](../active-directory/develop/security-tokens.md).
 
 ### Code example: Using Azure AD integrated authentication with Batch .NET
 
@@ -414,16 +403,8 @@ Use the service principal credentials to open a **BatchServiceClient** object. T
 
 ## Next steps
 
-- To learn more about Azure AD, see the [Azure Active Directory Documentation](../active-directory/index.yml). In-depth examples showing how to use ADAL are available in the [Azure Code Samples](https://azure.microsoft.com/resources/samples/?service=active-directory) library.
-
-- To learn more about service principals, see [Application and service principal objects in Azure Active Directory](../active-directory/develop/app-objects-and-service-principals.md). To create a service principal using the Azure portal, see [Use portal to create Active Directory application and service principal that can access resources](../active-directory/develop/howto-create-service-principal-portal.md). You can also create a service principal with PowerShell or Azure CLI.
-
-- To authenticate Batch Management applications using Azure AD, see [Authenticate Batch Management solutions with Active Directory](batch-aad-auth-management.md).
-
+- Review the [Azure Active Directory Documentation](../active-directory/index.yml). In-depth examples showing how to use ADAL are available in the [Azure Code Samples](https://azure.microsoft.com/resources/samples/?service=active-directory) library.
+- Learn about [Application and service principal objects in Azure Active Directory](../active-directory/develop/app-objects-and-service-principals.md) and [how to create an Azure AD application and service principal that can access resources](../active-directory/develop/howto-create-service-principal-portal.md).
+- Learn about [authenticating Batch Management solutions with Active Directory](batch-aad-auth-management.md).
 - For a Python example of how to create a Batch client authenticated using an Azure AD token, see the [Deploying Azure Batch Custom Image with a Python Script](https://github.com/azurebigcompute/recipes/blob/master/Azure%20Batch/CustomImages/CustomImagePython.md) sample.
 
-[aad_about]: ../active-directory/fundamentals/active-directory-whatis.md "What is Azure Active Directory?"
-[aad_adal]: ../active-directory/azuread-dev/active-directory-authentication-libraries.md
-[aad_auth_scenarios]: ../active-directory/develop/authentication-vs-authorization.md "Authentication Scenarios for Azure AD"
-[aad_integrate]: ../active-directory/develop/quickstart-register-app.md "Integrating Applications with Azure Active Directory"
-[azure_portal]: https://portal.azure.com