Merge pull request #333 from Azure-Samples/tibre/addNugetReview

Readme updates for new Microsoft.Identity.Web nuget package

Author: Tiago Brenck

1-WebApp-OIDC/1-2-AnyOrg/README-1-1-to-1-2.md

@@ -64,14 +64,12 @@ In the `Startup.cs` file, in the `ConfigureServices` method, after `services.Add
     {
     ...
     // Sign-in users with the Microsoft identity platform
-    services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
-        .AddSignIn("AzureAd", Configuration, options => Configuration.Bind("AzureAd", options));
-
-    // Restrict users to specific belonging to specific tenants
-    services.Configure<OpenIdConnectOptions>(AzureADDefaults.OpenIdScheme, options =>
+    services.AddSignIn(Configuration, options =>
     {
+        Configuration.Bind("AzureAd", options);
+        // Restrict users to specific belonging to specific tenants
         options.TokenValidationParameters.IssuerValidator = ValidateSpecificIssuers;
-    });
+    }, options => Configuration.Bind("AzureAd", options));
    ...
 ```
 

1-WebApp-OIDC/1-3-AnyOrgOrPersonal/README.md

@@ -43,8 +43,8 @@ There is one project in this sample. To register it, you can:
   3. Run the following script to create and configure your Azure AD application and configure the code of the sample application as well.
 
      ```PowerShell
-     cd .\AppCreationScripts\ 
-   .\Configure.ps1
+     cd .\AppCreationScripts\   
+     .\Configure.ps1
      ```
 
    > Other ways of running the scripts are described in [App Creation Scripts](./AppCreationScripts/AppCreationScripts.md)

1-WebApp-OIDC/1-5-B2C/README.md

@@ -83,8 +83,7 @@ Your web application registration should include the following information:
     "Instance": "https://<your-tenant-name>.b2clogin.com",
     "ClientId": "<web-app-application-id>",
     "Domain": "<your-b2c-domain>",
-    "CallbackPath": "/signin/B2C_1_sign_up_in",
-    "SignedOutCallbackPath": "/signout/B2C_1_sign_up_in",
+    "SignedOutCallbackPath": "/signout/<your-sign-up-in-policy>",
     "SignUpSignInPolicyId": "<your-sign-up-in-policy>"
   }
 }
@@ -112,16 +111,16 @@ If your web site needs to be accessed from users using iOS 12, you probably want
 This sample does NOT use MSAL as it only signs-in users (it does not call a Web API). It uses the built-in ASP.NET Core middleware. MSAL is used for fetching access  for accessing protected APIs (not shown here), as well as ID tokens. For logging-in purposes, it is sufficient to obtain an ID Token, and the middleware is capable of doing this on its own.
 
 #### Where is the Account controller?
-The `AccountController.cs` used in this sample is part of the built-in .NET Core authentication controllers found in the NuGet package `Microsoft.AspNetCore.Authentication.AzureADB2C.UI`, and you can find its implementation [here](https://github.com/aspnet/AspNetCore/blob/master/src/Azure/AzureAD/Authentication.AzureADB2C.UI/src/Areas/AzureADB2C/Controllers/AccountController.cs). If you want to customize the **Sign-in**, **Sign-up** or **Sign-out** actions, you are encouraged to create your own controller.
+The `AccountController.cs` used in this sample is part of `Microsoft.Identity.Web.UI` NuGet package, and you can find its implementation [here](https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.UI/Areas/MicrosoftIdentity/Controllers/AccountController.cs). If you want to customize the **Sign-in**, **Sign-up** or **Sign-out** actions, you are encouraged to create your own controller.
 
 #### B2C middlerware
-This sample shows how to use the OpenID Connect ASP.NET Core middleware to sign in users from a single Azure AD B2C tenant. The middleware is initialized in the `Startup.cs` file by passing the default authentication scheme and `AzureADB2COptions.cs` options. The options are read from the `appsettings.json` file. The middleware takes care of:
+This sample shows how to use the OpenID Connect ASP.NET Core middleware to sign in users from a single Azure AD B2C tenant. The middleware is initialized in the `Startup.cs` file by passing the default authentication scheme and `OpenIdConnectOptions.cs` options. The options are read from the `appsettings.json` file. The middleware takes care of:
 
 - Requesting OpenID Connect sign-in using the policy from the `appsettings.json` file.
 - Processing OpenID Connect sign-in responses by validating the signature and issuer in an incoming JWT, extracting the user's claims, and putting the claims in `ClaimsPrincipal.Current`.
 - Integrating with the session cookie ASP.NET Core middleware to establish a session for the user.
 
-You can trigger the middleware to send an OpenID Connect sign-in request by decorating a class or method with the `[Authorize]` attribute or by issuing a challenge (see the [AccountController.cs](https://github.com/aspnet/AspNetCore/blob/master/src/Azure/AzureAD/Authentication.AzureADB2C.UI/src/Areas/AzureADB2C/Controllers/AccountController.cs) file which is part of ASP.NET Core).
+You can trigger the middleware to send an OpenID Connect sign-in request by decorating a class or method with the `[Authorize]` attribute or by issuing a challenge (see the [AccountController.cs](https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.UI/Areas/MicrosoftIdentity/Controllers/AccountController.cs) file).
 
 Here is the middleware example:
 

1-WebApp-OIDC/1-6-SignOut/README.md

@@ -28,22 +28,21 @@ The sign out button is exposed in `Views\Shared\_LoginPartial.cshtml` and only d
 {
     <ul class="nav navbar-nav navbar-right">
         <li class="navbar-text">Hello @User.GetDisplayName()!</li>
-        <li><a asp-area="AzureAD" asp-controller="Account" asp-action="SignOut">Sign out</a></li>
+        <li><a asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignOut">Sign out</a></li>
     </ul>
 }
 else
 {
     <ul class="nav navbar-nav navbar-right">
-        <li><a asp-area="AzureAD" asp-controller="Account" asp-action="SignIn">Sign in</a></li>
+        <li><a asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignIn">Sign in</a></li>
     </ul>
 }
 ```
 
 ### `Signout()` action of the `AccountController`
 
-Pressing the **Sign out** button on the web app, triggers the `SignOut` action on the `Account` controller. In previous versions of the ASP.NET core templates, this controller
-was embedded with the Web App, but this is no longer the case as it's now part of the ASP.NET Core framework itself. The code for the `AccountController` is available from the ASP.NET core repository at
-from <https://github.com/aspnet/AspNetCore/blob/master/src/Azure/AzureAD/Authentication.AzureAD.UI/src/Areas/AzureAD/Controllers/AccountController.cs>, and what it does is:
+Pressing the **Sign out** button on the web app, triggers the `SignOut` action on the `Account` controller. The code for the `AccountController` is available at [Microsoft.Identity.Web repository]
+(https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.UI/Areas/MicrosoftIdentity/Controllers/AccountController.cs), and what it does is:
 
 - set an openid redirect URI to `/Account/SignedOut` so that the controller is called back when Azure AD has performed the sign out
 - call `Signout()`, which lets the OpenId connect middleware contact the Microsoft identity platform `logout` endpoint which:
@@ -56,44 +55,18 @@ from <https://github.com/aspnet/AspNetCore/blob/master/src/Azure/AzureAD/Authent
 The ASP.NET Core OpenIdConnect middleware enables your app to intercept the call to the Microsoft identity platform logout endpoint by providing an OpenIdConnect event named `OnRedirectToIdentityProviderForSignOut`.
 
 ```CSharp
-public static IServiceCollection AddSignIn(this IServiceCollection services,
-                                                            IConfiguration configuration)
+services.Configure<OpenIdConnectOptions>(OpenIdConnectDefaults.AuthenticationScheme, options =>
 {
-    services.Configure<OpenIdConnectOptions>(AzureADDefaults.OpenIdScheme, options =>
+    options.Events.OnRedirectToIdentityProviderForSignOut = async context =>
     {
-        options.Authority = options.Authority + "/v2.0/";
-        
-        options.Events.OnRedirectToIdentityProviderForSignOut = async context =>
-        {
-            //Your logic here
-        };
-    }
-}
+        //Your logic here
+    };
+});
 ```
 
 ### Clearing the token cache
 
-Your application can also intercept the logout event, for instance to clear the entry of the token cache associated with the account that signed out. We'll see in the second part of this tutorial (about the Web app calling a Web API), that the web app will store access tokens for the user in a cache. Intercepting the logout callback enables your web application to remove the user from the token cache. This is illustrated in the `AddWebAppCallsProtectedWebApi()` method of [StartupHelper.cs L137-143](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/blob/b87a1d859ff9f9a4a98eb7b701e6a1128d802ec5/Microsoft.Identity.Web/StartupHelpers.cs#L137-L143)
-
-```CSharp
-public static IServiceCollection AddWebAppCallsProtectedWebApi(this IServiceCollection services, IEnumerable<string> initialScopes)
-{
-    services.AddTokenAcquisition();
-
-    services.Configure<OpenIdConnectOptions>(AzureADDefaults.OpenIdScheme, options =>
-    {
-     ...
-        // Handling the sign-out: removing the account from MSAL.NET cache
-        options.Events.OnRedirectToIdentityProviderForSignOut = async context =>
-        {
-            // Remove the account from MSAL.NET token cache
-            var _tokenAcquisition = context.HttpContext.RequestServices.GetRequiredService<ITokenAcquisition>();
-            await _tokenAcquisition.RemoveAccount(context);
-        };
-    });
-    return services;
-}
-```
+Your application can also intercept the logout event, for instance to clear the entry of the token cache associated with the account that signed out. We'll see in the second part of this tutorial (about the Web app calling a Web API), that the web app will store access tokens for the user in a cache. Intercepting the logout callback enables your web application to remove the user from the token cache. This is illustrated in the `AddWebAppCallsProtectedWebApi()` method of [WebAppServiceCollectionExtensions.cs](https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web/WebAppServiceCollectionExtensions.cs#L202-L208)
 
 ### Single Sign-Out
 

2-WebApp-graph-user/2-3-Multi-Tenant/README.md

@@ -56,7 +56,7 @@ The application puts forward a scenario where a SaaS application invites the adm
 
 To run this sample:
 
-> Pre-requisites: Install .NET Core 2.2 or later (for example for Windows) by following the instructions at [.NET and C# - Get Started in 10 Minutes](https://www.microsoft.com/net/core). In addition to developing on Windows, you can develop on [Linux](https://www.microsoft.com/net/core#linuxredhat), [Mac](https://www.microsoft.com/net/core#macos), or [Docker](https://www.microsoft.com/net/core#dockercmd).
+> Pre-requisites: Install .NET Core 3.1 or later (for example for Windows) by following the instructions at [.NET and C# - Get Started in 10 Minutes](https://www.microsoft.com/net/core). In addition to developing on Windows, you can develop on [Linux](https://www.microsoft.com/net/core#linuxredhat), [Mac](https://www.microsoft.com/net/core#macos), or [Docker](https://www.microsoft.com/net/core#dockercmd).
 
 Ideally, you would want to have two Azure AD tenants so you can test all the aspects of this multi-tenant sample. For more information on how to get an Azure AD tenant, see [How to get an Azure AD tenant](https://azure.microsoft.com/documentation/articles/active-directory-howto-tenant/).
 
@@ -210,8 +210,7 @@ These steps are encapsulated in the [Microsoft.Identity.Web](..\..\Microsoft.Ide
 In order to be able to sign-in users from multiple tenants, the [/common endpoint](https://docs.microsoft.com/azure/active-directory/develop/howto-convert-app-to-be-multi-tenant#update-your-code-to-send-requests-to-common) must be used. In the sample, this endpoint is used as a result of setting the value for `TenantId` as `organizations` on the `appsettings.json` file, and configuring the middleware to read the values from it.
 
 ```csharp
-services.AddAuthentication(AzureADDefaults.AuthenticationScheme)
-                .AddAzureAD(options => configuration.Bind(configSectionName, options));
+services.AddSignIn(Configuration);
 ```
 
  You can read about the various endpoints of the Microsoft Identity Platform [here](https://docs.microsoft.com/azure/active-directory/develop/active-directory-v2-protocols#endpoints).
@@ -256,7 +255,7 @@ options.TokenValidationParameters.IssuerValidator = AadIssuerValidator.GetIssuer
 To extend this validation to only Azure AD tenants registered in the application database, the event handler `OnTokenValidated` was configured to grab the `tenantId` from the token claims and check if it has an entry on the database. If it doesn't, a custom exception `UnauthorizedTenantException` is thrown, canceling the authentication, and the user is redirected to the `UnauthorizedTenant` view. At this stage, the user is not authenticated in the application.
 
 ```csharp
-services.Configure<OpenIdConnectOptions>(AzureADDefaults.OpenIdScheme, options =>
+services.Configure<OpenIdConnectOptions>(OpenIdConnectDefaults.AuthenticationScheme, options =>
 {
     options.Events.OnTokenValidated = async context => 
     {
@@ -296,7 +295,7 @@ If you want to read more about data architecture on multi-tenant apps, please re
 
 ### Acquiring Access token for Microsoft Graph for each tenant
 
-If a multi-tenant app needs to acquire an access token for Microsoft Graph to be able to read data from the signed user's tenant, the token must be issued from their tenanted authority and not from the tenant where the SaaS application is registered. This feature is being showed on the **Edit** action result on `todoListController.cs`.
+If a multi-tenant app needs to acquire an access token for Microsoft Graph to be able to read data from the signed user's tenant, the token must be issued from their tenanted authority and not from the tenant where the SaaS application is registered. This feature is being showed on the **Edit** action result on `TodoListController.cs`.
 
 ```csharp
 var userTenant = User.GetTenantId();

4-WebApp-your-API/4-1-MyOrg/README.md

@@ -123,7 +123,7 @@ As a first step you'll need to:
    - Select **Add a scope**
    - accept the proposed Application ID URI (api://{clientId}) by selecting **Save and Continue**
    - Enter the following parameters
-     - for **Scope name** use `user_impersonation`
+     - for **Scope name** use `access_as_user`
      - Keep **Admins and users** for **Who can consent**
      - in **Admin consent display name** type `Access TodoListService-aspnetcore-webapi as a user`
      - in **Admin consent description** type `Accesses the TodoListService-aspnetcore-webapi Web API as a user`
@@ -189,7 +189,7 @@ Note: if you had used the automation to setup your application mentioned in [Ste
 1. Find the app key `TenantId` and replace the existing value with your Azure AD tenant ID.
 1. Find the app key `ClientId` and replace the existing value with the application ID (clientId) of the `TodoListClient-aspnetcore-webapi` application copied from the Azure portal.
 1. Find the app key `ClientSecret` and replace the existing value with the key you saved during the creation of the `TodoListClient-aspnetcore-webapi` app, in the Azure portal.
-1. Find the app key `TodoListScope` and replace the existing value with Scope if you changed the name from `api://<client id>/user_impersonation`.
+1. Find the app key `TodoListScope` and replace the existing value with Scope if you changed the name from `api://<client id>/access_as_user`.
 1. Find the app key `TodoListBaseAddress` and replace the existing value with the base address of the TodoListService-aspnetcore-webapi project (or use the default `https://localhost:44351`).
 
 ### Step 4: Run the sample
@@ -205,7 +205,7 @@ This behavior is expected as you are not authenticated. The client application w
 
 Explore the sample by signing in into the TodoList client, adding items to the To Do list. If you stop the application without signing out, the next time you run the application, you won't be prompted to sign in again.
 
-NOTE: Remember, the To-Do list is stored in memory in this `TodoListService` app. Each time you run the projects, your To-Do list will get emptied.
+> NOTE: Remember, the To-Do list is stored in memory in this `TodoListService` app. Each time you run the projects, your To-Do list will get emptied.
 
 > Did the sample not work for you as expected? Did you encounter issues trying this sample? Then please reach out to us using the [GitHub Issues](../../../issues) page.