Additional distributed token cache guidance (#35546)

Author: guardrex

aspnetcore/blazor/security/blazor-web-app-with-entra.md

@@ -611,7 +611,6 @@ Example:
   "ResponseType": "code",
   "TenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
 },
-...
 "DownstreamApi": {
   "BaseUrl": "https://localhost:7277",
   "Scopes": [ "api://11112222-bbbb-3333-cccc-4444dddd5555/Weather.Get" ]
@@ -763,15 +762,89 @@ The following example shows how to use [Azure Blob Storage and Azure Key Vault](
 
 [!INCLUDE[](~/includes/package-reference.md)]
 
-Configure Azure Blob Storage to maintain the encrypted keys and protect them with Azure Key Vault. In the following example, the `{BLOB URI WITH SAS TOKEN}` placeholder is the full URI where the key file should be stored with the SAS token as a query string parameter, and the `{KEY IDENTIFIER}` placeholder is the key vault key identifier used for key encryption:
+Configure Azure Blob Storage to maintain the encrypted keys and protect them with Azure Key Vault. The following code is typically implemented at the same time that a [production distributed token cache provider](xref:performance/caching/distributed) is implemented. Other options, both within Azure and outside of Azure, are available for managing Data Protection keys across multiple app instances, but the sample app demonstrates how to use Azure services.
+
+The <xref:Microsoft.Extensions.Azure.AzureEventSourceLogForwarder> service in the following example requires the [`Microsoft.Extensions.Azure` NuGet package](https://www.nuget.org/packages/Microsoft.Extensions.Azure) and a `using` statement at the top of the `Program` file for the <xref:Microsoft.Extensions.Azure?displayProperty=fullName> namespace.
+
+[!INCLUDE[](~/includes/package-reference.md)]
 
 ```csharp
+builder.Services.TryAddSingleton<AzureEventSourceLogForwarder>();
+
 builder.Services.AddDataProtection()
     .PersistKeysToAzureBlobStorage(new Uri("{BLOB URI WITH SAS TOKEN}"))
     .ProtectKeysWithAzureKeyVault(new Uri("{KEY IDENTIFIER}"), new DefaultAzureCredential());
 ```
 
-For more information on using a shared Data Protection key ring, see <xref:host-and-deploy/web-farm#data-protection> and <xref:security/data-protection/configuration/overview>.
+* `{BLOB URI WITH SAS TOKEN}`: The full URI where the key file should be stored with the SAS (shared access signature) token as a query string parameter. The URI is generated by Azure Storage when you request a SAS after creating a container. The container name in the following example is `data-protection`, and the storage account name is `contoso`. The key file is named `keys.xml`. When you create the SAS, use the following permissions: `Read`, `Write`, `Delete`, `List`, and `Create`.
+
+  Example: :::no-loc text="https://contoso.blob.core.windows.net/data-protection/keys.xml?sp={PERMISSIONS}&st={START DATETIME}&se={EXPIRATION DATETIME}&spr=https&sv={STORAGE VERSION DATE}&sr=c&sig={TOKEN}":::
+
+  > [!TIP]
+  > If you run the app once without enabling the code that calls <xref:Microsoft.AspNetCore.DataProtection.AzureDataProtectionBuilderExtensions.ProtectKeysWithAzureKeyVault%2A>, the Data Protection key file (`keys.xml`) is automatically generated in Azure Blob Storage for you. After you've verified the file's presence in Azure Blob Storage with the Storage Browser in the Entra or Azure portal, enable the call to <xref:Microsoft.AspNetCore.DataProtection.AzureDataProtectionBuilderExtensions.ProtectKeysWithAzureKeyVault%2A>.
+
+* `{KEY IDENTIFIER}`: Azure Key Vault key identifier used for key encryption. The key vault name is `contoso` in the following example, and an access policy allows the application to access the key vault with `Get`, `Wrap Key`, and `Unwrap Key` permissions. The example key name is `data-protection`. The version of the key for the `{KEY VERSION}` placeholder is obtained from the key in the Entra or Azure Portal after it's created.
+
+  Example: :::no-loc text="https://contoso.vault.azure.net/keys/data-protection/{KEY VERSION}":::
+
+To configure the app with app settings, add the following to the app settings file:
+
+```json
+"DistributedTokenCache": {
+    "DisableL1Cache": false,
+    "L1CacheSizeLimit": 524288000,
+    "Encrypt": true,
+    "SlidingExpirationInHours": 1
+  },
+"DataProtection": {
+  "BlobUriWithSasToken": "https://contoso.blob.core.windows.net/data-protection/keys.xml?sp={PERMISSIONS}&st={START DATETIME}&se={EXPIRATION DATETIME}&spr=https&sv={STORAGE VERSION DATE}&sr=c&sig={TOKEN}",
+  "KeyIdentifier": "https://contoso.vault.azure.net/keys/data-protection/{KEY VERSION}"
+}
+```
+
+Make the following changes in the `Program` file:
+
+```diff
+builder.Services.Configure<MsalDistributedTokenCacheAdapterOptions>(
+    options =>
+    {
++       var config = builder.Configuration.GetSection("DistributedTokenCache");
+
+-       options.DisableL1Cache = false;
++       options.DisableL1Cache = config.GetValue<bool>("DisableL1Cache");
+
+-       options.L1CacheOptions.SizeLimit = 500 * 1024 * 1024;
++       options.L1CacheOptions.SizeLimit = config.GetValue<long>("L1CacheSizeLimit");
+
+-       options.Encrypt = true;
++       options.Encrypt = config.GetValue<bool>("Encrypt");
+
+-       options.SlidingExpiration = TimeSpan.FromHours(1);
++       options.SlidingExpiration = 
++           TimeSpan.FromHours(config.GetValue<int>("SlidingExpirationInHours"));
+    });
+
+- builder.Services.AddDataProtection()
+-   .PersistKeysToAzureBlobStorage(new Uri("{BLOB URI WITH SAS TOKEN}"))
+-   .ProtectKeysWithAzureKeyVault(new Uri("{KEY IDENTIFIER}"), new DefaultAzureCredential());
+
++ var config = builder.Configuration.GetSection("DataProtection");
+
++ builder.Services.AddDataProtection()
++   .PersistKeysToAzureBlobStorage(
++       new Uri(config.GetValue<string>("BlobUriWithSasToken") ??
++       throw new Exception("Missing Blob URI")))
++   .ProtectKeysWithAzureKeyVault(
++       new Uri(config.GetValue<string>("KeyIdentifier") ?? 
++       throw new Exception("Missing Key Identifier")), 
++       new DefaultAzureCredential());
+```
+
+For more information on using a shared Data Protection key ring and key storage providers, see the following resources:
+
+* <xref:host-and-deploy/web-farm#data-protection>
+* <xref:security/data-protection/configuration/overview>
+* <xref:security/data-protection/implementation/key-storage-providers>
 
 ## Redirect to the home page on logout