OAuth/OIDC and .NET terminology

mmacy · web-flow · commit 9f94868e568e · 2022-09-28T10:22:53.000-07:00
Couple of tweaks to get crisp on auth concepts and one fix for .NET (using _directive_ instead of using statement). cc: @tamram
diff --git a/articles/storage/common/storage-auth-aad-app.md b/articles/storage/common/storage-auth-aad-app.md
@@ -1,13 +1,13 @@
 ---
 title: Authorize access to blob or queue data from a native or web application
 titleSuffix: Azure Storage
-description: Use Azure Active Directory to authenticate from within a client application, acquire an OAuth 2.0 token, and authorize requests to Azure Blob storage and Queue storage.
+description: Use Azure Active Directory to authenticate from within a client application, acquire an OAuth 2.0 access token, and authorize requests to Azure Blob storage and Queue storage.
 services: storage
 author: tamram
 
 ms.service: storage
 ms.topic: how-to
-ms.date: 10/11/2021
+ms.date: 09/28/2022
 ms.author: tamram
 ms.subservice: common
 ms.custom: "devx-track-csharp"
@@ -19,28 +19,28 @@ A key advantage of using Azure Active Directory (Azure AD) with Azure Blob stora
 
 This article shows how to configure your native application or web application for authentication with the Microsoft identity platform using a sample application that is available for download. The sample application features .NET, but other languages use a similar approach. For more information about the Microsoft identity platform, see [Microsoft identity platform overview](../../active-directory/develop/v2-overview.md).
 
-For an overview of the OAuth 2.0 code grant flow, see [Authorize access to Azure Active Directory web applications using the OAuth 2.0 code grant flow](../../active-directory/develop/v2-oauth2-auth-code-flow.md).
+For an overview of the OAuth 2.0 authorization code flow, see [Authorize access to Azure Active Directory web applications using the OAuth 2.0 code grant flow](../../active-directory/develop/v2-oauth2-auth-code-flow.md).
 
 ## About the sample application
 
-The sample application provides an end-to-end experience that shows how to configure a web application for authentication with Azure AD in a local development environment. To view and run the sample application, first clone or download it from [GitHub](https://github.com/Azure-Samples/storage-dotnet-azure-ad-msal). Then follow the steps outlined in the article to configure an Azure app registration and update the application for your environment.
+The sample application provides an end-to-end experience that shows how to configure a web application for authentication with Azure AD in a local development environment. To view and run the sample application, first clone or download it from [GitHub](https://github.com/Azure-Samples/storage-dotnet-azure-ad-msal). Then follow the steps outlined in the article to configure an Azure AD app registration and update the application for your environment.
 
 ## Assign a role to an Azure AD security principal
 
 To authenticate a security principal from your Azure Storage application, first configure Azure role-based access control (Azure RBAC) settings for that security principal. Azure Storage defines built-in roles that encompass permissions for containers and queues. When the Azure role is assigned to a security principal, that security principal is granted access to that resource. For more information, see [Assign an Azure role for access to blob data](../blobs/assign-azure-role-data-access.md).
 
 ## Register your application with an Azure AD tenant
 
-The first step in using Azure AD to authorize access to storage resources is registering your client application with an Azure AD tenant from the [Azure portal](https://portal.azure.com). When you register your client application, you supply information about the application to Azure AD. Azure AD then provides a client ID (also called an *application ID*) that you use to associate your application with Azure AD at runtime. To learn more about the client ID, see [Application and service principal objects in Azure Active Directory](../../active-directory/develop/app-objects-and-service-principals.md). To register your Azure Storage application, follow the steps shown in [Quickstart: Register an application with the Microsoft identity platform](../../active-directory/develop/quickstart-register-app.md).
+The first step in using Azure AD to authorize access to storage resources is registering your client application in an Azure AD tenant by using the [Azure portal](https://portal.azure.com). When you register your client application, you supply information about the application to Azure AD. Azure AD then provides a client ID (also called an *application ID*) that you use to associate your application with Azure AD at runtime. To learn more about the client ID, see [Application and service principal objects in Azure Active Directory](../../active-directory/develop/app-objects-and-service-principals.md). To register your Azure Storage application, follow the steps shown in [Quickstart: Register an application with the Microsoft identity platform](../../active-directory/develop/quickstart-register-app.md).
 
 The following image shows common settings for registering a web application. Note that in this example, the redirect URI is set to `http://localhost:5000/signin-oidc` for testing the sample application in the development environment. You can modify this setting later under the **Authentication** setting for your registered application in the Azure portal:
 
 :::image type="content" source="media/storage-auth-aad-app/app-registration.png" alt-text="Screenshot showing how to register your storage application with Azure AD":::
 
 > [!NOTE]
-> If you register your application as a native application, you can specify any valid URI for the **Redirect URI**. For native applications, this value does not have to be a real URL. For web applications, the redirect URI must be a valid URI, because it specifies the URL to which tokens are provided.
+> If you register your application as a native application, you can specify any valid URI for the **Redirect URI**. For native applications, this value does not have to be a real URL. For web applications, the redirect URI must be a valid URI because it specifies the URL to which tokens are provided.
 
-After you've registered your application, you'll see the application ID (or client ID) under **Settings**:
+After you've registered your application, you'll see the **Application (client) ID** under **Settings**:
 
 :::image type="content" source="media/storage-auth-aad-app/app-registration-client-id.png" alt-text="Screenshot showing the client ID":::
 
@@ -75,9 +75,11 @@ The application needs a client secret to prove its identity when requesting a to
 
     ![Screenshot showing client secret](media/storage-auth-aad-app/client-secret.png)
 
-### Enable implicit grant flow
+### Enable ID tokens
 
-Next, configure implicit grant flow for your application. Follow these steps:
+Next, tell the identity platform to also ID tokens for the app by enabling the *hybrid flow*. The hybrid flow combines the use of the authorization code grant for obtaining access tokens and OpenID Connect (OIDC) for getting ID tokens.
+
+To enable issuance of ID tokens for the app, follow these steps:
 
 1. Navigate to your app registration in the Azure portal.
 1. In the **Manage** section, select the **Authentication** setting.
@@ -87,7 +89,7 @@ Next, configure implicit grant flow for your application. Follow these steps:
 
 ## Client libraries for token acquisition
 
-Once you have registered your application and granted it permissions to access data in Azure Blob storage or Queue storage, you can add code to your application to authenticate a security principal and acquire an OAuth 2.0 token. To authenticate and acquire the token, you can use either one of the [Microsoft identity platform authentication libraries](../../active-directory/develop/reference-v2-libraries.md) or another open-source library that supports OpenID Connect 1.0. Your application can then use the access token to authorize a request against Azure Blob storage or Queue storage.
+Once you've registered your application and granted it permissions to access data in Azure Blob storage or Queue storage, you can add code to your application to authenticate a security principal and acquire an OAuth 2.0 access token. To authenticate and acquire the access token, you can use one of [Microsoft's open-source authentication libraries](../../active-directory/develop/reference-v2-libraries.md) or another library that supports OAuth 2.0 and OpenID Connect 1.0. Your application can then use the access token to authorize a request against Azure Blob storage or Queue storage.
 
 For a list of scenarios for which acquiring tokens is supported, see the [authentication flows](../../active-directory/develop/msal-authentication-flows.md) section of the [Microsoft Authentication Library (MSAL)](../../active-directory/develop/msal-overview.md) documentation.
 
@@ -97,11 +99,11 @@ To authenticate a security principal with Azure AD, you need to include some wel
 
 ### Azure AD authority
 
-For Microsoft public cloud, the base Azure AD authority is as follows, where *tenant-id* is your Active Directory tenant ID (or directory ID):
+For the Azure public cloud, the base Azure AD authority is as follows, where *tenant-id* is your Active Directory tenant ID (or directory ID):
 
 `https://login.microsoftonline.com/<tenant-id>/`
 
-The tenant ID identifies the Azure AD tenant to use for authentication. It is also referred to as the directory ID. To retrieve the tenant ID, navigate to the **Overview** page for your app registration in the Azure portal, and copy the value from there.
+The tenant ID identifies the Azure AD tenant to use for authentication. It's also referred to as the directory ID. To get the tenant ID, navigate to the **Overview** page for your app registration in the Azure portal and copy the value from there.
 
 ### Azure Storage resource ID
 
@@ -111,7 +113,7 @@ The tenant ID identifies the Azure AD tenant to use for authentication. It is al
 
 The code example shows how to get an access token from Azure AD. The access token is used to authenticate the specified user and then authorize a request to create a block blob. To get this sample working, first follow the steps outlined in the preceding sections.
 
-To request the token, you will need the following values from your app's registration:
+To request the token, you'll need the following values from your app's registration:
 
 - The name of your Azure AD domain. Retrieve this value from the **Overview** page of your Azure Active Directory.
 - The tenant (or directory) ID. Retrieve this value from the **Overview** page of your app registration.
@@ -126,19 +128,19 @@ To run the code sample, create a storage account within the same subscription as
 Next, explicitly assign the **Storage Blob Data Contributor** role to the user account under which you will run the sample code. To learn how to assign this role in the Azure portal, see [Assign an Azure role for access to blob data](../blobs/assign-azure-role-data-access.md).
 
 > [!NOTE]
-> When you create an Azure Storage account, you are not automatically assigned permissions to access data via Azure AD. You must explicitly assign yourself an Azure role for Azure Storage. You can assign it at the level of your subscription, resource group, storage account, or container or queue.
+> When you create an Azure Storage account, you're not automatically assigned permissions to access data via Azure AD. You must explicitly assign yourself an Azure role for Azure Storage. You can assign it at the level of your subscription, resource group, storage account, or container or queue.
 >
 > Prior to assigning yourself a role for data access, you will be able to access data in your storage account via the Azure portal because the Azure portal can also use the account key for data access. For more information, see [Choose how to authorize access to blob data in the Azure portal](../blobs/authorize-data-operations-portal.md).
 
 ### Create a web application that authorizes access to Blob storage with Azure AD
 
-When your application accesses Azure Storage, it does so on the user's behalf, meaning that blob or queue resources are accessed using the permissions of the user who is logged in. To try this code example, you need a web application that prompts the user to sign in using an Azure AD identity. You can create your own, or use the sample application provided by Microsoft.
+When your application accesses Azure Storage, it does so on the user's behalf, meaning that blob or queue resources are accessed using the permissions of the user who is logged in. To try this code example, you need a web application that prompts the user to sign in using an Azure AD identity. You can create your own or use the sample application provided by Microsoft.
 
-A completed sample web application that acquires a token and uses it to create a blob in Azure Storage is available on [GitHub](https://aka.ms/aadstorage). Reviewing and running the completed sample may be helpful for understanding the code examples. For instructions about how to run the completed sample, see the section titled [View and run the completed sample](#view-and-run-the-completed-sample).
+A completed sample web application that acquires an access token and uses it to create a blob in Azure Storage is available on [GitHub](https://aka.ms/aadstorage). Reviewing and running the completed sample may be helpful for understanding the following code examples. For instructions about how to run the completed sample, see the section titled [View and run the completed sample](#view-and-run-the-completed-sample).
 
-#### Add references and using statements
+#### Add assembly references and using directives
 
-From Visual Studio, install the Azure Storage client library. From the **Tools** menu, select **NuGet Package Manager**, then **Package Manager Console**. Type the following commands into the console window to install the necessary packages from the Azure Storage client library for .NET:
+In Visual Studio, install the Azure Storage client library. From the **Tools** menu, select **NuGet Package Manager**, then **Package Manager Console**. Type the following commands into the console window to install the necessary packages from the Azure Storage client library for .NET:
 
 # [.NET v12 SDK](#tab/dotnet)
 
@@ -147,7 +149,7 @@ Install-Package Azure.Storage.Blobs
 Install-Package Microsoft.Identity.Web -Version 0.4.0-preview
 ```
 
-Next, add the following using statements to the HomeController.cs file:
+Next, add the following using directives to the HomeController.cs file:
 
 ```csharp
 using Microsoft.Identity.Web; //MSAL library for getting the access token
@@ -161,7 +163,7 @@ Install-Package Microsoft.Azure.Storage.Blob
 Install-Package Microsoft.Identity.Web -Version 0.4.0-preview //or a later version
 ```
 
-Next, add the following using statements to the HomeController.cs file:
+Next, add the following using directives to the HomeController.cs file:
 
 ```csharp
 using Microsoft.Identity.Client; //MSAL library for getting the access token
@@ -214,9 +216,9 @@ private static async Task<string> CreateBlob(string accessToken)
 ---
 
 > [!NOTE]
-> To authorize blob and queue operations with an OAuth 2.0 token, you must use HTTPS.
+> To authorize blob and queue operations with an OAuth 2.0 access token, you must use HTTPS.
 
-In the example above, the .NET client library handles the authorization of the request to create the block blob. Azure Storage client libraries for other languages also handle the authorization of the request for you. However, if you are calling an Azure Storage operation with an OAuth token using the REST API, then you'll need to construct the **Authorization** header by using the OAuth token.
+In the example above, the .NET client library handles the authorization of the request to create the block blob. Azure Storage client libraries for other languages also handle the authorization of the request for you. However, if you're calling an Azure Storage operation with an OAuth access token using the REST API, then you'll need to construct the **Authorization** header by using the OAuth token.
 
 To call Blob and Queue service operations using OAuth access tokens, pass the access token in the **Authorization** header using the **Bearer** scheme, and specify a service version of 2017-11-09 or higher, as shown in the following example:
 
@@ -245,7 +247,7 @@ public async Task<IActionResult> Blob()
 }
 ```
 
-Consent is the process of a user granting authorization to an application to access protected resources on their behalf. The Microsoft identity platform supports incremental consent, meaning that a security principal can request a minimum set of permissions initially and add permissions over time as needed. When your code requests an access token, specify the scope of permissions that your app needs. For more information about incremental consent, see [Incremental and dynamic consent](../../active-directory/azuread-dev/azure-ad-endpoint-comparison.md#incremental-and-dynamic-consent).
+Consent is the process of a user granting authorization to an application to access protected resources on their behalf. The Microsoft identity platform supports incremental consent, meaning that an application can request a minimum set of permissions initially and request more permissions over time as needed. When your code requests an access token, specify the scope of permissions that your app needs. For more information about incremental consent, see [Incremental and dynamic consent](../../active-directory/azuread-dev/azure-ad-endpoint-comparison.md#incremental-and-dynamic-consent).
 
 ## View and run the completed sample
 
