Merge pull request #99 from Azure-Samples/updateDocAfterKCAFix

Update README.md now that KCA works for MSA

Author: jmprieur

2. Web API now calls Microsoft Graph/README-incremental-instructions.md

@@ -7,16 +7,15 @@ client: .NET Desktop (WPF)
 service: ASP.NET Core Web API, Microsoft Graph
 endpoint: AAD v2.0
 ---
-# ASP.NET Core 2.1 Web API calling Microsoft Graph, itself called from a WPF application using Azure AD V2
+# ASP.NET Core Web API calling Microsoft Graph, itself called from a WPF application using Microsoft identity platform
 
-![Build badge](https://identitydivision.visualstudio.com/_apis/public/build/definitions/a7934fdd-dcde-4492-a406-7fad6ac00e17/497/badge)
+[![Build status](https://identitydivision.visualstudio.com/IDDP/_apis/build/status/AAD%20Samples/.NET%20client%20samples/active-directory-dotnet-native-aspnetcore-v2)](https://identitydivision.visualstudio.com/IDDP/_build/latest?definitionId=516)
 
 > The sample in this folder is part of a multi-phase tutorial. This folder is about the second phase named **Web API now calls Microsoft Graph**.
 > The first phase is available from [1. Desktop app calls Web API](../1.%20Desktop%20app%20calls%20Web%20API).
 >
 > This article [README-incremental-instructions.md](README-incremental-instructions.md) builds on top of the README.md of the first part. If you want to see the full instructions on how to configure the sample, see [README.md](README.md)
 
-> At that time, the Azure AD v2.0 endpoint does not yet completely support the on-behalf-of flow for users signing-in with a Microsoft Personal account. Limitations are called out in the [Current limitations](#Current-limitations) section
 
 ## About this sample
 
@@ -29,7 +28,7 @@ endpoint: AAD v2.0
 - [How to run this sample](#How-to-run-this-sample)
   - [Step 1:  Clone or download this repository](#step-1--clone-or-download-this-repository)
   - [Step 2:  Register the sample with your Azure Active Directory tenant](#step-2--register-the-sample-with-your-azure-active-directory-tenant)
-  - [Step 3:  Configure the sample to use your Azure AD tenant](#step-3--configure-the-sample-to-use-your-azure-ad-tenant)
+  - [Step 3:  Configure the sample code to use your Azure AD tenant](#step-3--configure-the-sample-code-to-use-your-azure-ad-tenant)
   - [Step 4:  Run the sample](#step-4-run-the-sample)
   - [Troubleshooting](#Troubleshooting)
   - [Current limitations](#Current-limitations)
@@ -76,6 +75,8 @@ There are two projects in this sample. Each needs to be separately registered in
   - **automatically** creates the Azure AD applications and related objects (passwords, permissions, dependencies) for you
   - modify the Visual Studio projects' configuration files.
 
+  > Note however that the automation will not, at this point, allow you to sign-in with a personal Microsoft account. If you want to allow sign in with personal Microsoft accounts, use the manual instructions. 
+
 #### Using scripts
 
 If you want to use this automation:
@@ -95,14 +96,13 @@ If you want to use this automation:
       - in the manifest, search for **"accessTokenAcceptedVersion"**, and replace **null** by **2**. This property lets Azure AD know that the Web API accepts v2.0 tokens
       - search for **signInAudience** and make sure it's set to **AzureADandPersonalMicrosoftAccount**
       - Select **Save**
-   1. In the **Authentication** page for the *TodoListService-v2* application, check the `urn:ietf:wg:oauth:2.0:oob` reply URI so that the client can propose incremental consent to the user for the Web API when needed.
-   1. In tthe application registration page for the *TodoListClient-v2* application, select the **Manifest** section:
+   1. In the application registration page for the *TodoListClient-v2* application, select the **Manifest** section:
       - search for **signInAudience** and make sure it's set to **AzureADandPersonalMicrosoftAccount**
       - Select **Save**
 
    > Tip: Get directly to the app registration portal page for a give app, you can navigate to the links provided in the [AppCreationScripts\createdApps.html](AppCreationScripts\createdApps.html). This file is generated by the scripts during the app registration and configuration.
 
-1. Open the Visual Studio solution and click start
+5. Open the Visual Studio solution and click start
 
 If you don't want to use this automation, follow the steps below
 
@@ -112,7 +112,7 @@ These instructions only show the differences with the first part.
 
 #### Register the service app (TodoListService)
 
-1. In **App registrations (Preview)** page, find the *TodoListService-2* app
+1. In **App registrations** page, find the *TodoListService-2* app
 1. From the **Certificates & secrets** page, in the **Client secrets** section, choose **New client secret**:
    - Type a key description (of instance `app secret`),
    - Select a key duration of either **In 1 year**, **In 2 years**, or **Never Expires**.
@@ -123,32 +123,34 @@ These instructions only show the differences with the first part.
    - Click the **Add a permission** button and then,
    - Ensure that the **Microsoft APIs** tab is selected
    - In the *Commonly used Microsoft APIs* section, click on **Microsoft Graph**
-   - In the **Delegated permissions** section, ensure that the right permissions are checked: **User.Read**. Use the search box if necessary.
+   - In the **Delegated permissions** section, ensure that the right permissions are checked: **User.Read** and **offline_access**. Use the search box if necessary.
    - Select the **Add permissions** button
-   - [Optional] if you are a tenant admin, and agree to grant the admin consent to the web api, select **Grant admin consent for {your tenant domain}**.
-1. [Otherwise] If you have not granted admin consent to the Web API in the previous optional step, select **Authentication** in the list of pages and there:
-   - Check the `urn:ietf:wg:oauth:2.0:oob` Redirect URI checkbox. This is so that the client can propose incremental consent to the user for the downstream web apis used by our *TodoListService-v2* Web API.
-   - Select **Save**
+   - [Optional] if you are a tenant admin, and agree to grant the admin consent to the web api, select **Grant admin consent for {your tenant domain}**. If you don't do
+    it, users will be presented a consent screen enabling them to consent to using the web api. The consent screen will also mention the permissions required by the web api itself.
 1. [Optional] Select the **Manifest** section and:
    - in the manifest, search for **"accessTokenAcceptedVersion"**, and see that its value is **2**. This property lets Azure AD know that the Web API accepts v2.0 tokens
    - Select **Save**
 
-> Important: it's up to the Web API to decide which version of token (v1.0 or v2.0) it accepts. Then when clients request a token for your Web API using the v2.0 endpoint, they'll get a token which version is accepted by the Web API. The code validating the tokens in this sample was written to accept both versions.
+   > Important: it's up to the Web API to decide which version of token (v1.0 or v2.0) it accepts. Then when clients request a token for your Web API using the Microsoft identity platform endpoint, they'll get a token which version is accepted by the Web API. The code validating the tokens in this sample was written to accept both versions.
 
 #### Register the client app (TodoListClient)
 
 Nothing more to do more here. All was done in the first part
 
 ### Step 3:  Configure the sample to use your Azure AD tenant
 
-By default the sample is configured to enable users to sign in with any work and school accounts (AAD) accounts.
-This constrain is ensured by `ida:Tenant` in `TodoListClient\App.Config` having the value `organizations`.
+By default the sample is configured to enable users to sign in with any work and school accounts (AAD) or personal Microsoft accounts.
+This constraint is ensured by `ida:Tenant` in `TodoListClient\App.Config` having the value `common`.
 
 #### Configure the TodoListService C# project
 
 1. Open the solution in Visual Studio.
 1. In the *TodoListService-v2* project, open the `appsettings.json` file.
 1. Find the `ClientSecret` property and replace the existing value with the key you saved during the creation of the `TodoListService-v2` app, in the Azure portal.
+   > Note
+   > In chapter 1, the protected Web API did not call any downstrream API. In this chapter it does, and thus
+   > it needs to acquire s token, and becomes a confidential client. Therefore it needs to prove its identity to
+   > Azure AD through a client secret (or a certificate)
 
 #### Configure the TodoListClient C# project
 
@@ -158,12 +160,9 @@ Nothing more to do more here. All was done in the first part
 
 Clean the solution, rebuild the solution, and run it
 
-### Current limitations
+### Alternative architecture
 
-The on-behalf-of flow works for Microsoft Personal accounts, but the consent is not yet rolled-up in the client for the user to consent to the Web API calling the downstream API (here Microsoft Graph). To make this work, the suggestion is:
-
-- either to use the same client ID in the Client and the Service. This way the consent for the service will appear in the client.
-- or to provide a protected page on the Web API (which therefore also becomes a Web app) so that the user can have an interaction
+This part of the sample uses different client ID for the client and the service and uses the on-behalf-of flow. If you are the author of both the client and the service, you might alternatively want to use the same client ID in the Client and the Service. This approach is described in the third part of the tutorial [3.-Web-api-call-Microsoft-graph-for-personal-accounts](../3.-Web-api-call-Microsoft-graph-for-personal-accounts)
 
 ## How was the code created
 
@@ -196,36 +195,32 @@ Update `Startup.cs` file:
 
   ```csharp
   services.AddProtectedWebApi(Configuration)
-          .AddProtectedApiCallsWebApis(Configuration, new string[] { "user.read" })
+          .AddProtectedApiCallsWebApis(Configuration)
           .AddInMemoryTokenCaches();
   ```
 
   `AddProtectedWebApi` does the following:
   - add the **Jwt**BearerAuthenticationScheme (Note the replacement of BearerAuthenticationScheme by **Jwt**BearerAuthenticationScheme)
-  - set the authority to be the Microsoft identity platform v2.0 identity
+  - set the authority to be the Microsoft identity platform identity
   - sets the audiences to validate
   - register an issuer validator that accepts issuers to be in the Microsoft identity platform clouds.
-  - 
 
-  Here is an idea of the code: 
+  Here is an idea of the code (in the `WebApiServiceCollectionExtensions.cs` file)
 
   ```csharp
   services.AddAuthentication(AzureADDefaults.JwtBearerAuthenticationScheme)
           .AddAzureADBearer(options => configuration.Bind("AzureAd", options));
 
-  services.AddSession();
-
   // Added
   services.Configure<JwtBearerOptions>(AzureADDefaults.JwtBearerAuthenticationScheme, options =>
   {
-    // This is an Azure AD v2.0 Web API
+    // This is an Microsoft identity platform Web API
     options.Authority += "/v2.0";
 
     // The valid audiences are both the Client ID (options.Audience) and api://{ClientID}
     options.TokenValidationParameters.ValidAudiences = new string[]
     {
-     options.Audience,
-      $"api://{options.Audience}" 
+          options.Audience,  $"api://{options.Audience}"
     };
 
     // Instead of using the default validation (validating against a single tenant
@@ -236,7 +231,7 @@ Update `Startup.cs` file:
   });
   ```
 
-  The services that are added are:
+  The .NET Core "services" that are added are:
 
   - a token acquisition service leveraging MSAL.NET
   - an in memory token cache
@@ -252,29 +247,22 @@ Update `Startup.cs` file:
     // so that it can be used from the controllers.
     options.Events = new JwtBearerEvents();
 
-    // Subscribing to OnTokenValidated to add the token to the cache using the OnBehalfOf flow
+    // Subscribing to OnTokenValidated to verify that the token has at least the Scope, scp or roles claims
     options.Events.OnTokenValidated = async context =>
     {
-     var tokenAcquisition = context.HttpContext.RequestServices.GetRequiredService<ITokenAcquisition>();
-     var scopes = new string[] { "user.read" };
-     context.Success();
+        // This check is required to ensure that the Web API only accepts tokens from tenants where it has been consented and provisioned.
+        if (!context.Principal.Claims.Any(x => x.Type == ClaimConstants.Scope)
+        && !context.Principal.Claims.Any(y => y.Type == ClaimConstants.Scp)
+        && !context.Principal.Claims.Any(y => y.Type == ClaimConstants.Roles))
+        {
+            throw new UnauthorizedAccessException("Neither scope or roles claim was found in the bearer token.");
+        }
 
-     // Adds the token to the cache, and also handles the incremental consent and claim challenges
-     tokenAcquisition.AddAccountToCacheFromJwt(context, scopes);
-     await Task.FromResult(0);
+        await Task.FromResult(0);
     };
   });
   ```
 
-- At the beginning of the `Configure` method, insert `app.UseSession()`. This code ensures that the session exists for the session-based token cache to work properly.
-
-  ```CSharp
-  public void Configure(IApplicationBuilder app, IHostingEnvironment env)
-  {
-    app.UseSession();
-    ...
-  ```
-
 ### Modify the TodoListController.cs file to add information to the todo item about its owner
 
 In the `TodoListController.cs` file, the Post() action was modified
@@ -312,7 +300,7 @@ This method is the following. It:
         }
         catch (MsalUiRequiredException ex)
         {
-            tokenAcquisition.ReplyForbiddenWithWwwAuthenticateHeader(HttpContext, scopes, ex);
+            tokenAcquisition.ReplyForbiddenWithWwwAuthenticateHeader(scopes, ex);
             return string.Empty;
         }
     }
@@ -332,23 +320,21 @@ This sample uses the `ReplyForbiddenWithWwwAuthenticateHeader` method of the `To
   - the scopes to request
   - the claims (for conditional access, MFA etc ...)
 
-The code for this method is available in [Microsoft.Identity.Web\Client\TokenAcquisition.cs L394-L427](https://github.com/Azure-Samples/active-directory-dotnet-native-aspnetcore-v2/blob/2e5d34aedabbf20b583580a661433ad4b00bb035/Microsoft.Identity.Web/Client/TokenAcquisition.cs#L394-L427)
+The code for this method is available in [Microsoft.Identity.Web\Client\TokenAcquisition.cs L457-L493](https://github.com/Azure-Samples/active-directory-dotnet-native-aspnetcore-v2/blob/4f9a9bc7f08e79f1a3e908cb513c59f1976470da/Microsoft.Identity.Web/TokenAcquisition.cs#L457-L493)
 
 #### On the client side
 
 On the client side, when it calls the Web API and receives a 403 with a www-Authenticate header, the client will call the `HandleChallengeFromWebApi` method, which will
 
 - extract from the www-Authenticate header
-  - the client ID
-  - the scopes
-  - the claims
-- Create a new `PublicClientApplication` (as the client is here a desktop app), and call `AcquireTokenAsync` method to ask the user to consent.
+  - the consent URi
+- Navigate to the consent URI provided by the Web API.
 
-The code for `HandleChallengeFromWebApi` method is available from [TodoListClient\MainWindow.xaml.cs L180-L206](https://github.com/Azure-Samples/active-directory-dotnet-native-aspnetcore-v2/blob/9be6d8b3705ada352caa9a47be0a5add8389b6f6/2.%20Web%20API%20now%20calls%20Microsoft%20Graph/TodoListClient/MainWindow.xaml.cs#L180-L206)
+The code for `HandleChallengeFromWebApi` method is available from [TodoListClient\MainWindow.xaml.cs L162-197](https://github.com/Azure-Samples/active-directory-dotnet-native-aspnetcore-v2/blob/4f9a9bc7f08e79f1a3e908cb513c59f1976470da/2.%20Web%20API%20now%20calls%20Microsoft%20Graph/TodoListClient/MainWindow.xaml.cs#L162-L197)
 
 ## How to deploy this sample to Azure
 
-See section [How to deploy this sample to Azure](../1.%20Desktop%20app%20calls%20Web%20API/README.md#How-to-deploy-this-sample-to-Azure) in the first part of this tutorial, as the deployment is exactly the same.
+See section [How to deploy this sample to Azure](../1.%20Desktop%20app%20calls%20Web%20API/README.md#How-to-deploy-this-sample-to-Azure) in the first part of this tutorial, as the deployment is the same.
 
 ## Community Help and Support
 
@@ -370,19 +356,22 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
 
 For more information, visit the following links:
 
-- To lean more about the application registration, visit:
+- to learn more about the scenario, see [Scenario: Web app that calls web APIs](https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-web-app-call-api-overview)
+
+- to learn more about Microsoft.Identity.Web, see [Microsoft.Identity.Web/README.md](../Microsoft.Identity.Web/README.md)
+
+- To learn more about the application registration, visit:
 
-  - [Quickstart: Register an application with the Microsoft identity platform (Preview)](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
-  - [Quickstart: Configure a client application to access web APIs (Preview)](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-access-web-apis)
-  - [Quickstart: Quickstart: Configure an application to expose web APIs (Preview)](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis)
+  - [Quickstart: Register an application with the Microsoft identity platform](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
+  - [Quickstart: Configure a client application to access web APIs](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-access-web-apis)
+  - [Quickstart: Quickstart: Configure an application to expose web APIs](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis)
 
 - To learn more about the code, visit [Conceptual documentation for MSAL.NET](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki#conceptual-documentation) and in particular:
-  - [Acquiring tokens with authorization codes on web apps](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/Acquiring-tokens-with-authorization-codes-on-web-apps)
-  - [Customizing Token cache serialization](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/token-cache-serialization)
+  - [Acquiring tokens with the on-behalf-of flow](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/on-behalf-of)
 
-- Articles about the Azure AD V2 endpoint [http://aka.ms/aaddevv2](http://aka.ms/aaddevv2), with a focus on:
-  - [Azure Active Directory v2.0 and OAuth 2.0 On-Behalf-Of flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-on-behalf-of)
+- Articles about the Microsoft identity platform endpoint [http://aka.ms/aaddevv2](http://aka.ms/aaddevv2), with a focus on:
+  - [identity platform and OAuth 2.0 On-Behalf-Of flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-on-behalf-of)
 
-- [Introduction to Identity on ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/security/authentication/identity?view=aspnetcore-2.1&tabs=visual-studio%2Caspnetcore2x)
+- [Introduction to Identity on ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/security/authentication/identity?view=aspnetcore-2.2&tabs=visual-studio%2Caspnetcore2x)
   - [AuthenticationBuilder](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.authentication.authenticationbuilder?view=aspnetcore-2.0)
-  - [Azure Active Directory with ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/security/authentication/azure-active-directory/?view=aspnetcore-2.1)
+  - [Azure Active Directory with ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/security/authentication/azure-active-directory/?view=aspnetcore-2.2)