Merge pull request #221892 from MicrosoftDocs/main

12/19 AM Publish

Author: huypub

articles/active-directory/develop/includes/web-app/quickstart-aspnet-core.md

@@ -9,29 +9,29 @@ ms.service: active-directory
 ms.subservice: develop
 ms.topic: quickstart
 ms.workload: identity
-ms.date: 11/22/2021
+ms.date: 12/19/2022
 ms.author: jmprieur
 ms.custom: "devx-track-csharp, aaddev, identityplatformtop40, scenarios:getting-started, languages:aspnet-core"
 #Customer intent: As an application developer, I want to know how to write an ASP.NET Core web app that can sign in personal Microsoft accounts and work/school accounts from any Azure Active Directory instance,  then access their data in Microsoft Graph on their behalf.
 ---
 
-In this quickstart, you download and run a code sample that demonstrates how an ASP.NET Core web app can sign in users from any Azure Active Directory (Azure AD) organization.  
+The following quickstart uses a ASP.NET Core web app code sample to demonstrate how to sign in users from any Azure Active Directory (Azure AD) organization.  
 
 See [How the sample works](#how-the-sample-works) for an illustration.
 
 ## Prerequisites
 
-* [Visual Studio](https://visualstudio.microsoft.com/vs/) or [Visual Studio Code](https://code.visualstudio.com/)
-* [.NET Core SDK 3.1+](https://dotnet.microsoft.com/download)
+* [Visual Studio 2022](https://visualstudio.microsoft.com/vs/) or [Visual Studio Code](https://code.visualstudio.com/)
+* [.NET Core SDK 6.0+](https://dotnet.microsoft.com/download)
 
 ## Register and download your quickstart application
 
-#### Step 1: Register your application
-1. Sign in to the <a href="https://portal.azure.com/" target="_blank">Azure portal</a>.
-1. If you have access to multiple tenants, use the **Directories + subscriptions** filter :::image type="icon" source="../../media/common/portal-directory-subscription-filter.png" border="false"::: in the top menu to switch to the tenant in which you want to register the application.
+### Step 1: Register your application
+1. Sign in to the [Azure portal](https://portal.azure.com/).
+1. If access to multiple tenants is available, use the **Directories + subscriptions** filter :::image type="icon" source="../../media/common/portal-directory-subscription-filter.png" border="false"::: in the top menu to switch to the tenant in which to register the application.
 1. Search for and select **Azure Active Directory**.
 1. Under **Manage**, select **App registrations** > **New registration**.
-1. For **Name**, enter a name for your application. For example, enter **AspNetCore-Quickstart**. Users of your app will see this name, and you can change it later.
+1. For **Name**, enter a name for the application.  For example, enter **AspNetCore-Quickstart**. Users of the app will see this name, and can be changed later.
 1. Set the **Redirect URI** type to **Web** and value to `https://localhost:44321/signin-oidc`.
 1. Select **Register**.
 1. Under **Manage**, select **Authentication**.
@@ -43,47 +43,66 @@ See [How the sample works](#how-the-sample-works) for an illustration.
 1. Select **In 1 year** for the secret's expiration.
 1. Select **Add** and immediately record the secret's **Value** for use in a later step. The secret value is *never displayed again* and is irretrievable by any other means. Record it in a secure location as you would any password.
 
-#### Step 2: Download the ASP.NET Core project
+### Step 2: Download the ASP.NET Core project
 
 [Download the ASP.NET Core solution](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/archive/aspnetcore3-1-callsgraph.zip)
 
-[!INCLUDE [active-directory-develop-path-length-tip](../../../../../includes/active-directory-develop-path-length-tip.md)]
+> [!Note]
+> The code sample currently targets ASP.NET Core 3.1. The sample can be updated to use .NET Core 6.0 and is covered in the following steps: [Update the sample code to ASP.NET Core 6.0](#step-4-update-the-sample-code-to-aspnet-core-60)
+This quickstart will be deprecated in the near future and will be updated to use .NET 6.0.
 
-#### Step 3: Configure your ASP.NET Core project
-1. Extract the .zip archive into a local folder near the root of your drive. For example, extract into *C:\Azure-Samples*.
+### Step 3: Configure your ASP.NET Core project
 
-   We recommend extracting the archive into a directory near the root of your drive to avoid errors caused by path length limitations on Windows.
-1. Open the solution in Visual Studio 2019.
-1. Open the *appsettings.json* file and modify the following code:
+1. Extract the *.zip* file to a local folder that's close to the root of the disk to avoid errors caused by path length limitations on Windows. For example, extract to *C:\Azure-Samples*.
+1. Open the solution in the chosen code editor.
+1. In *appsettings.json*, replace the values of `ClientId`, and `TenantId`. The value for the application (client) ID and the directory (tenant) ID, can be found in the app's **Overview** page on the Azure portal.
 
    ```json
    "Domain": "[Enter the domain of your tenant, e.g. contoso.onmicrosoft.com]",
    "ClientId": "Enter_the_Application_Id_here",
    "TenantId": "common",
    ```
 
-   - Replace `Enter_the_Application_Id_here` with the application (client) ID of the application that you registered in the Azure portal. You can find the **Application (client) ID** value on the app's **Overview** page.
-   - Replace `common` with one of the following:
-      - If your application supports **Accounts in this organizational directory only**, replace this value with the directory (tenant) ID (a GUID) or the tenant name (for example, `contoso.onmicrosoft.com`). You can find the **Directory (tenant) ID** value on the app's **Overview** page.
-      - If your application supports **Accounts in any organizational directory**, replace this value with `organizations`.
-      - If your application supports **All Microsoft account users**, leave this value as `common`.
-    - Replace `Enter_the_Client_Secret_Here` with the **Client secret** you created and recorded in an earlier step.
+   - `Enter_the_Application_Id_Here` is the application (client) ID for the registered application.
+   - Replace `Enter_the_Tenant_Info_Here` with one of the following:
+      - If the application supports **Accounts in this organizational directory only**, replace this value with the directory (tenant) ID (a GUID) or tenant name (for example, `contoso.onmicrosoft.com`). The directory (tenant) ID can be found on the app's **Overview** page.
+      - If the application supports **Accounts in any organizational directory**, replace this value with `organizations`.
+      - If the application supports **All Microsoft account users**, leave this value as `common`.
+    - Replace `Enter_the_Client_Secret_Here` with the **Client secret** that was created and recorded in an earlier step.
 
 For this quickstart, don't change any other values in the *appsettings.json* file.
 
-#### Step 4: Build and run the application
+### Step 4: Update the sample code to ASP.NET Core 6.0
 
-Build and run the app in Visual Studio by selecting the **Debug** menu > **Start Debugging**, or by pressing the F5 key.
+To update this code sample to target ASP.NET Core 6.0, follow these steps:
 
-You're prompted for your credentials, and then asked to consent to the permissions that your app requires. Select **Accept** on the consent prompt.
+1. Open WebApp-OpenIDConnect-DotNet.csproj
+1. Remove the following line:
+
+    ```xml
+   <TargetFramework>netcoreapp3.1</TargetFramework>
+   ```
+
+1. Add the following line in its place:
+
+   ```xml
+   <TargetFramework>netcoreapp6.0</TargetFramework>
+   ```
+
+This step will ensure that the sample is targeting the .NET Core 6.0 framework.
+ 
+### Step 5: Build and run the application
+
+Build and run the app in Visual Studio by selecting the **Debug** menu > **Start Debugging**, or by pressing the F5 key. 
+
+A prompt for credentials will appear, and then a request for consent to the permissions that the app requires. Select **Accept** on the consent prompt.
 
 :::image type="content" source="../../media/quickstart-v2-aspnet-core-webapp/webapp-01-consent.png" alt-text="Screenshot of the consent dialog box, showing the permissions that the app is requesting from the user.":::
 
-After consenting to the requested permissions, the app displays that you've successfully logged in using your Azure Active Directory credentials, and you'll see your email address in the "Api result" section of the page. This was extracted using Microsoft Graph.
+After consenting to the requested permissions, the app displays that sign-in has been successful using correct Azure Active Directory credentials. The user's account email address will be displayed in the *API result* section of the page. This was extracted using the Microsoft Graph API.
 
 :::image type="content" source="../../media/quickstart-v2-aspnet-core-webapp-calls-graph/webapp-02-signed-in.png" alt-text="Web browser displaying the running web app and the user signed in":::
 
-
 ## More information
 
 This section gives an overview of the code required to sign in users and call the Microsoft Graph API on their behalf. This overview can be useful to understand how the code works, main arguments, and also if you want to add sign-in to an existing ASP.NET Core application and call Microsoft Graph. It uses [Microsoft.Identity.Web](../../microsoft-identity-web.md), which is a wrapper around [MSAL.NET](../../msal-overview.md).
@@ -130,15 +149,15 @@ The *Microsoft.AspNetCore.Authentication* middleware uses a `Startup` class that
 
 The `AddAuthentication()` method configures the service to add cookie-based authentication. This authentication is used in browser scenarios and to set the challenge to OpenID Connect.
 
-The line that contains `.AddMicrosoftIdentityWebApp` adds Microsoft identity platform authentication to your application. The application is then configured to sign in users based on the following information in the `AzureAD` section of the *appsettings.json* configuration file:
+The line that contains `.AddMicrosoftIdentityWebApp` adds Microsoft identity platform authentication to the application. The application is then configured to sign in users based on the following information in the `AzureAD` section of the *appsettings.json* configuration file:
 
 | *appsettings.json* key | Description                                                                                                                                                          |
 |------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `ClientId`             | Application (client) ID of the application registered in the Azure portal.                                                                                       |
 | `Instance`             | Security token service (STS) endpoint for the user to authenticate. This value is typically `https://login.microsoftonline.com/`, indicating the Azure public cloud. |
 | `TenantId`             | Name of your tenant or the tenant ID (a GUID), or `common` to sign in users with work or school accounts or Microsoft personal accounts.                             |
 
-The `EnableTokenAcquisitionToCallDownstreamApi` method enables your application to acquire a token to call protected web APIs. `AddMicrosoftGraph` enables your controllers or Razor pages to benefit directly the `GraphServiceClient` (by dependency injection) and the `AddInMemoryTokenCaches` methods enables your app to benefit from a token cache.
+The `EnableTokenAcquisitionToCallDownstreamApi` method enables the application to acquire a token to call protected web APIs. `AddMicrosoftGraph` enables the controllers or Razor pages to benefit directly the `GraphServiceClient` (by dependency injection) and the `AddInMemoryTokenCaches` methods enables your app to benefit from a token cache.
 
 The `Configure()` method contains two important methods, `app.UseAuthentication()` and `app.UseAuthorization()`, that enable their named functionality. Also in the `Configure()` method, you must register Microsoft Identity Web routes with at least one call to `endpoints.MapControllerRoute()` or a call to `endpoints.MapControllers()`:
 
@@ -157,7 +176,7 @@ app.UseEndpoints(endpoints =>
 
 ### Protect a controller or a controller's method
 
-You can protect a controller or its methods by applying the `[Authorize]` attribute to the controller's class or one or more of its methods. This `[Authorize]` attribute restricts access by allowing only authenticated users. If the user isn't already authenticated, an authentication challenge can be started to access the controller. In this quickstart, the scopes are read from the configuration file:
+The controller or its methods can be protected by applying the `[Authorize]` attribute to the controller's class or one or more of its methods. This `[Authorize]` attribute restricts access by allowing only authenticated users. If the user isn't already authenticated, an authentication challenge can be started to access the controller. In this quickstart, the scopes are read from the configuration file:
 
 ```csharp
 [AuthorizeForScopes(ScopeKeySection = "DownstreamApi:Scopes")]
@@ -174,7 +193,7 @@ public async Task<IActionResult> Index()
 
 ## Next steps
 
-The GitHub repo that contains the ASP.NET Core code sample referenced in this quickstart includes instructions and more code samples that show you how to:
+The following GitHub repository contains the ASP.NET Core code sample referenced in this quickstart and more samples that show how to achieve the following:
 
 - Add authentication to a new ASP.NET Core web application.
 - Call Microsoft Graph, other Microsoft APIs, or your own web APIs.