Merge branch 'master' of https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2

Author: Kalyan Krishna

.gitignore

@@ -101,3 +101,6 @@
 /2-WebApp-graph-user/2-4-Sovereign-Call-MSGraph/bin/Release/netcoreapp2.2
 /Microsoft.Identity.Web.Test/bin/Release/netcoreapp2.2
 /Microsoft.Identity.Web.Test/obj
+/4-WebApp-your-API/4-2-B2C/.vs
+/4-WebApp-your-API/4-2-B2C/Client/obj
+/4-WebApp-your-API/4-2-B2C/TodoListService/obj

2-WebApp-graph-user/2-2-TokenCache/Startup.cs

@@ -51,8 +51,7 @@ public void ConfigureServices(IServiceCollection services)
             // and chosen token cache implementation
             services.AddMicrosoftIdentityPlatformAuthentication(Configuration)
                     .AddMsal(Configuration, new string[] { Constants.ScopeUserRead })
-                    .AddSqlAppTokenCache(msalSqlTokenCacheOptions)
-                    .AddSqlPerUserTokenCache(msalSqlTokenCacheOptions);
+                    .AddSqlTokenCaches(msalSqlTokenCacheOptions);
 
 
             // Add Graph

3-WebApp-multi-APIs/README.md

@@ -189,6 +189,8 @@ insert
 
 ## Troubleshooting
 
+To access Azure Resource Management (ARM), you'll need a work or school account (AAD account) and an Azure subscription. If your Azure subscription is for a Microsoft personal account, just create a new user in your directory, and use this user to run the sample
+
 OpenIdConnectProtocolException: Message contains error: 'invalid_client', error_description: 'AADSTS650052: The app needs access to a service (\"https://*.blob.core.windows.net\") that your organization \"*tenantname*.onmicrosoft.com\" has not subscribed to or enabled. Contact your IT Admin to review the configuration of your service subscriptions.
 this is because the AzureStorage API was not registered as an API used by your Web App
 
@@ -198,4 +200,4 @@ You can learn more about the tokens by looking at the following articles in MSAL
 
 - The [Authorization code flow](https://aka.ms/msal-net-authorization-code), which is used, after the user signed-in with Open ID Connect, in order to get a token and cache it for a later use. See [TokenAcquisition L 107](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/blob/f99e913cc032e16c59b748241111e97108e87918/Extensions/TokenAcquisition.cs#L107) for details of this code
 - [AcquireTokenSilent](https://aka.ms/msal-net-acquiretokensilent ), which is used by the controller to get an access token for the downstream API. See [TokenAcquisition L 168](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/blob/f99e913cc032e16c59b748241111e97108e87918/Extensions/TokenAcquisition.cs#L168) for details of this code
-- [Token cache serialization](msal-net-token-cache-serialization)
+- [Token cache serialization](msal-net-token-cache-serialization)

4-WebApp-your-API/README.md

@@ -417,6 +417,10 @@ In the left-hand navigation pane, select the **Azure Active Directory** service,
 > NOTE: Remember, the To Do list is stored in memory in this TodoListService sample. Azure Web Sites will spin down your web site if it is inactive, and your To Do list will get emptied.
 Also, if you increase the instance count of the web site, requests will be distributed among the instances. To Do will, therefore, not be the same on each instance.
 
+## Next steps
+
+If you're interested in the Web API calling a downstream API, you might want to have a look at the [ASP.NET Core Web API tutorial](https://github.com/Azure-Samples/active-directory-dotnet-native-aspnetcore-v2), in chapter 2 [2. Web API now calls Microsoft Graph/](https://github.com/Azure-Samples/active-directory-dotnet-native-aspnetcore-v2/tree/master/2.%20Web%20API%20now%20calls%20Microsoft%20Graph). The client is a desktop app there, whereas you have a Web App, but apart from that all the app registration steps apply.
+
 ## Community Help and Support
 
 Use [Stack Overflow](http://stackoverflow.com/questions/tagged/msal) to get support from the community.

6-Deploy-to-Azure/README.md

@@ -52,7 +52,84 @@ In the left-hand navigation pane, select the **Azure Active Directory** service,
 
 Secure key management is essential to protect data in the cloud. Use [Azure Key Vault](https://azure.microsoft.com/en-ca/services/key-vault/) to encrypt keys and small secrets like passwords that use keys stored in hardware security modules (HSMs).
 
-You can follow [this sample](https://github.com/Azure-Samples/app-service-msi-keyvault-dotnet) as a guide on how to use Azure KeyVault from App Service with Managed Service Identity (MSI).
+Use [this sample](https://github.com/Azure-Samples/app-service-msi-keyvault-dotnet) as a guide on how to use Azure Key Vault from App Service with Managed Service Identity (MSI).
+
+## MSAL token cache on distributed environments
+
+The samples in this tutorial have their token cache providers configured for apps running on a single machine. On a production environment, these apps could be deployed in many machines for scalability purpose, so the token cache provider needs to be configured accordingly for this distributed architecture.
+
+These are the necessary changes for each cache provider option:
+
+### In memory
+
+If you want to use in memory cache, use this configuration on `Startup.cs`:
+
+```csharp
+services.AddDistributedTokenCaches()
+.AddDistributedMemoryCache();
+```
+
+### Redis
+
+If you want to use a distributed Redis cache, use this configuration on `Startup.cs`:
+
+```csharp
+services.AddDistributedTokenCaches()
+.AddStackExchangeRedisCache(options =>
+{
+    options.Configuration = "<your_redis_primary_connection_string_here>";
+    options.InstanceName = "<your_redis_instance_name>";
+});
+```
+
+### SQL Server
+
+There are two options for distributed SQL cache:
+
+- [using .Net Core distributed cache extensions](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/distributed?view=aspnetcore-2.2)
+- [configuring DataProtection for distributed environments](https://docs.microsoft.com/en-us/aspnet/core/security/data-protection/configuration/overview?view=aspnetcore-2.2)
+
+#### If you want to use .Net Core distributed cache extensions
+
+Create the cache database by running the CLI (change the parameters according to your configurations)
+
+```csharp
+dotnet sql-cache create "<your DB connection string>" dbo <cacheTableName>
+```
+
+Then use this configuration on `Startup.cs`:
+
+```csharp
+services.AddDistributedTokenCaches()
+.AddDistributedSqlServerCache(options =>
+{
+    options.ConnectionString = "<your_sql_connection_string_here>";
+    options.SchemaName = "dbo";
+    options.TableName = "<your_cache_table_name_here>";
+});
+```
+
+#### If you want to configure `DataProtection` for distributed environments
+
+You have to configure the key ring storage to a centralized location. It could be in [Azure Key Vault](https://azure.microsoft.com/services/key-vault/) or on a [UNC share](https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-dfsc/149a3039-98ce-491a-9268-2f5ddef08192).
+
+> **Note**: If you change the key persistence location, the system no longer automatically encrypts keys at rest. It is recommended that you use one of the ProtectKeysWith* methods listed [in this doc](https://docs.microsoft.com/en-us/aspnet/core/security/data-protection/configuration/overview?view=aspnetcore-2.2).
+
+For Azure Key Vault, configure the system with [PersistKeysToAzureBlobStorage](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.dataprotection.azuredataprotectionbuilderextensions.persistkeystoazureblobstorage?view=aspnetcore-2.2) (also consider using [ProtectKeysWithAzureKeyVault](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.dataprotection.azuredataprotectionbuilderextensions.protectkeyswithazurekeyvault)) in the `Startup` class:
+
+```csharp
+services.AddDataProtection()
+.PersistKeysToAzureBlobStorage("<storage account connection or uri>");
+```
+
+> **Note**: Your app must have **Unwrap Key** and **Wrap Key** permissions to the Azure Key Vault.
+
+For UNC share, configure the system with [PersistKeysToFileSystem](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.dataprotection.dataprotectionbuilderextensions.persistkeystofilesystem) (also consider using [ProtectKeysWithCertificate](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.dataprotection.dataprotectionbuilderextensions.protectkeyswithcertificate?view=aspnetcore-2.2)) in the `Startup` class:
+
+```csharp
+services.AddDataProtection()
+.PersistKeysToFileSystem(new DirectoryInfo(@"\\server\share\directory\"));
+```
 
 ## Community Help and Support
 

Microsoft.Identity.Web/Microsoft.Identity.Web.csproj

@@ -57,6 +57,6 @@
     <PackageReference Include="Microsoft.AspNetCore.Authentication.AzureAD.UI" Version="2.2.0" />
     <PackageReference Include="Microsoft.AspNetCore.Authentication.AzureADB2C.UI" Version="2.2.0" />
     <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="2.2.0" />
-    <PackageReference Include="Microsoft.Identity.Client" Version="4.5.1" />
+    <PackageReference Include="Microsoft.Identity.Client" Version="4.6.0" />
   </ItemGroup>
 </Project>

Microsoft.Identity.Web/TokenAcquisition.cs

@@ -29,8 +29,7 @@ public class TokenAcquisition : ITokenAcquisition
         private readonly AzureADOptions _azureAdOptions;
         private readonly ConfidentialClientApplicationOptions _applicationOptions;
 
-        private readonly IMsalAppTokenCacheProvider _appTokenCacheProvider;
-        private readonly IMsalUserTokenCacheProvider _userTokenCacheProvider;
+        private readonly IMsalTokenCacheProvider _tokenCacheProvider;
 
         private IConfidentialClientApplication application;
         private readonly IHttpContextAccessor _httpContextAccessor;
@@ -42,20 +41,18 @@ public class TokenAcquisition : ITokenAcquisition
         /// This constructor is called by ASP.NET Core dependency injection
         /// </summary>
         /// <param name="configuration"></param>
-        /// <param name="appTokenCacheProvider">The App token cache provider</param>
+        /// <param name="tokenCacheProvider">The App token cache provider</param>
         /// <param name="userTokenCacheProvider">The User token cache provider</param>
         public TokenAcquisition(
-            IMsalAppTokenCacheProvider appTokenCacheProvider,
-            IMsalUserTokenCacheProvider userTokenCacheProvider,
+            IMsalTokenCacheProvider tokenCacheProvider,
             IHttpContextAccessor httpContextAccessor,
             IOptions<AzureADOptions> azureAdOptions,
             IOptions<ConfidentialClientApplicationOptions> applicationOptions)
         {
             _httpContextAccessor = httpContextAccessor;
             _azureAdOptions = azureAdOptions.Value;
             _applicationOptions = applicationOptions.Value;
-            _appTokenCacheProvider = appTokenCacheProvider;
-            _userTokenCacheProvider = userTokenCacheProvider;
+            _tokenCacheProvider = tokenCacheProvider;
         }
 
         /// <summary>
@@ -283,7 +280,7 @@ public async Task RemoveAccountAsync(RedirectContext context)
             if (account != null)
             {
                 await app.RemoveAsync(account).ConfigureAwait(false);
-                _userTokenCacheProvider?.ClearAsync().ConfigureAwait(false);
+                _tokenCacheProvider?.ClearAsync().ConfigureAwait(false);
             }
         }
 
@@ -326,8 +323,8 @@ private IConfidentialClientApplication BuildConfidentialClientApplication()
                 .Build();
 
             // Initialize token cache providers
-            _appTokenCacheProvider?.InitializeAsync(app.AppTokenCache);
-            _userTokenCacheProvider?.InitializeAsync(app.UserTokenCache);
+            _tokenCacheProvider?.InitializeAsync(app.AppTokenCache);
+            _tokenCacheProvider?.InitializeAsync(app.UserTokenCache);
 
             return app;
         }

Microsoft.Identity.Web/TokenCacheProviders/Distributed/DistributedTokenCacheAdapterExtension.cs

@@ -29,7 +29,7 @@ public static IServiceCollection AddDistributedAppTokenCache(
             this IServiceCollection services)
         {
             services.AddDistributedMemoryCache();
-            services.AddSingleton<IMsalAppTokenCacheProvider, MsalAppDistributedTokenCacheProvider>();
+            services.AddSingleton<IMsalTokenCacheProvider, MsalDistributedTokenCacheAdapter>();
             return services;
         }
 
@@ -42,7 +42,7 @@ public static IServiceCollection AddDistributedUserTokenCache(
         {
             services.AddDistributedMemoryCache();
             services.AddHttpContextAccessor();
-            services.AddSingleton<IMsalUserTokenCacheProvider, MsalPerUserDistributedTokenCacheProvider>();
+            services.AddSingleton<IMsalTokenCacheProvider, MsalDistributedTokenCacheAdapter>();
             return services;
         }
     }