標記快取序列化

Microsoft.Identity.Web.TokenCache NuGet 套件在 Microsoft.Identity.Web 程式庫中提供權杖快取序列化功能。 該函式庫可整合 ASP.NET Core 與 ASP.NET Classic，其抽象功能可用於驅動其他網頁應用程式或 API 框架。

記憶體內標記快取

以下是一個在 ASP.NET Core 應用程式中啟動類別的ConfigureServices 方法中使用記憶體快取的程式碼範例：

using Microsoft.Identity.Web;

public class Startup
{
 const string scopesToRequest = "user.read";
  
  public void ConfigureServices(IServiceCollection services)
  {
   // code before
   services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
           .AddMicrosoftIdentityWebApp(Configuration)
             .EnableTokenAcquisitionToCallDownstreamApi(new string[] { scopesToRequest })
                .AddInMemoryTokenCaches();
   // code after
  }
  // code after
}

AddInMemoryTokenCaches 如果你要求應用程式專用的代幣，適合在生產環境中使用。 如果你使用使用者代幣，可以考慮使用分散式代幣快取。

ASP.NET Core 網頁應用程式與網頁 API 之間的權杖快取設定程式碼相似。

分散式代幣快取

以下是可能的分散式快取範例：

// or use a distributed Token Cache by adding
   services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
           .AddMicrosoftIdentityWebApp(Configuration)
             .EnableTokenAcquisitionToCallDownstreamApi(new string[] { scopesToRequest }
               .AddDistributedTokenCaches();

// Distributed token caches have a L1/L2 mechanism.
// L1 is in memory, and L2 is the distributed cache
// implementation that you will choose below.
// You can configure them to limit the memory of the 
// L1 cache, encrypt, and set eviction policies.
services.Configure<MsalDistributedTokenCacheAdapterOptions>(options => 
  {
    // Optional: Disable the L1 cache in apps that don't use session affinity
    //                 by setting DisableL1Cache to 'true'.
    options.DisableL1Cache = false;
    
    // Or limit the memory (by default, this is 500 MB)
    options.L1CacheOptions.SizeLimit = 1024 * 1024 * 1024; // 1 GB

    // You can choose if you encrypt or not encrypt the cache
    options.Encrypt = false;

    // And you can set eviction policies for the distributed
    // cache.
    options.SlidingExpiration = TimeSpan.FromHours(1);
  });

// Then, choose your implementation of distributed cache
// -----------------------------------------------------

// good for prototyping and testing, but this is NOT persisted and it is NOT distributed - do not use in production
services.AddDistributedMemoryCache();

// Or a Redis cache
// Requires the Microsoft.Extensions.Caching.StackExchangeRedis NuGet package
services.AddStackExchangeRedisCache(options =>
{
 options.Configuration = "localhost";
 options.InstanceName = "SampleInstance";
});

// You can even decide if you want to repair the connection
// with Redis and retry on Redis failures. 
services.Configure<MsalDistributedTokenCacheAdapterOptions>(options => 
{
  options.OnL2CacheFailure = (ex) =>
  {
    if (ex is StackExchange.Redis.RedisConnectionException)
    {
      // action: try to reconnect or something
      return true; //try to do the cache operation again
    }
    return false;
  };
});

// Or even a SQL Server token cache
// Requires the Microsoft.Extensions.Caching.SqlServer NuGet package
services.AddDistributedSqlServerCache(options =>
{
 options.ConnectionString = _config["DistCache_ConnectionString"];
 options.SchemaName = "dbo";
 options.TableName = "TestCache";
});

// Or an Azure Cosmos DB cache
// Requires the Microsoft.Extensions.Caching.Cosmos NuGet package
services.AddCosmosCache((CosmosCacheOptions cacheOptions) =>
{
    cacheOptions.ContainerName = Configuration["CosmosCacheContainer"];
    cacheOptions.DatabaseName = Configuration["CosmosCacheDatabase"];
    cacheOptions.ClientBuilder = new CosmosClientBuilder(Configuration["CosmosConnectionString"]);
    cacheOptions.CreateIfNotExists = true;
});

欲了解更多資訊，請參閱：

• 分散式快取加密及其他進階選項
• 處理 L2 快取驅逐
• 在 Docker 中設置 Redis 快取
• Troubleshooting

分散式快取的使用在 ASP.NET Core 網頁應用程式教學中，於第 2-2 階段令牌快取中介紹。

建議 .NET 機密用戶端使用Microsoft.Identity.Web（其以 MSAL.NET 為基礎），因為較高層級的 API 能夠開箱即用地處理複雜情境（例如訪客使用者、持續存取評估、持有證明權杖）。 需要存取 Azure API 的應用程式應該使用 Azure SDK，因為它在內部利用 MSAL。

如果你直接使用 MSAL.NET，以下資料會很相關。

可用的快取技術

• 無淘汰機制的記憶體快取
• 具淘汰機制的記憶體快取
• 結合分散式快取與記憶體快取

無驅逐的記憶體快取

.WithCacheOptions(CacheOptions.EnableSharedCacheOptions)用於建置服務對服務應用程式時——AcquireTokenForClient該應用不會針對許多（超過 100,000 個）租戶。

    // Create the confidential client application
    app= ConfidentialClientApplicationBuilder.Create(clientId)
       // Alternatively to the certificate, you can use .WithClientSecret(clientSecret)
       .WithCertificate(cert)
       .WithLegacyCacheCompatibility(false)
       .WithCacheOptions(CacheOptions.EnableSharedCacheOptions)
       .WithAuthority(authority)
       .Build();

WithCacheOptions(CacheOptions.EnableSharedCacheOptions) 使內部 MSAL 令牌快取在 MSAL 用戶端應用程式實例間共享。 共用權杖快取比使用任何權杖快取序列化機制更快，但內部記憶體權杖快取不具備淘汰原則。 現有的代幣會被重新刷新，但為不同使用者、租戶和資源取得代幣，會讓快取相應成長。

具淘汰機制的記憶體快取

將 Microsoft.Identity.Web.TokenCache NuGet 套件新增至你的專案。

以下程式碼說明如何加入帶有驅逐功能的記憶體快取：

using Microsoft.Identity.Web;
using Microsoft.Identity.Client;
using Microsoft.Extensions.DependencyInjection;

public static async Task<AuthenticationResult> GetTokenAsync(string clientId, X509Certificate cert, string authority, string[] scopes)
 {
     // Create the confidential client application
     app= ConfidentialClientApplicationBuilder.Create(clientId)       
       .WithCertificate(cert)
       .WithLegacyCacheCompatibility(false)
       .WithAuthority(authority)
       .Build();

     // Add a static in-memory token cache and set an eviction policy
     app.AddInMemoryTokenCache(services =>
     {
         // Configure the memory cache options
         services.Configure<MemoryCacheOptions>(options =>
         {
              options.SizeLimit = 500 * 1024 * 1024; // in bytes (500 MB)
         });
      });
  }

分散式快取

如果你使用 app.AddDistributedTokenCache，權杖快取會作為 .NET IDistributedCache 實作的轉接器。 所以你可以選擇 SQL Server 快取、Redis 快取、Azure Cosmos DB 快取，或任何實作 IDistributedCache 介面的快取。

為了進行測試，你可以使用 services.AddDistributedMemoryCache()，這是 IDistributedCache 的記憶體內實作。

這是 SQL Server 快取的程式碼：

     // SQL Server token cache
     app.AddDistributedTokenCache(services =>
     {
      services.AddDistributedSqlServerCache(options =>
      {
       
       // Requires to reference Microsoft.Extensions.Caching.SqlServer
       options.ConnectionString = @"Data Source=(localdb)\MSSQLLocalDB;Initial Catalog=TestCache;Integrated Security=True;Connect Timeout=30;Encrypt=False;TrustServerCertificate=False;ApplicationIntent=ReadWrite;MultiSubnetFailover=False";
       options.SchemaName = "dbo";
       options.TableName = "TestCache";

       // You don't want the SQL token cache to be purged before the access token has expired. Usually
       // access tokens expire after 1 hour (but this can be changed by token lifetime policies), whereas
       // the default sliding expiration for the distributed SQL database is 20 mins. 
       // Use a value above 60 mins (or the lifetime of a token in case of longer-lived tokens)
       options.DefaultSlidingExpiration = TimeSpan.FromMinutes(90);
      });
     });

這是 Redis 快取的程式碼：

    // Redis token cache
    app.AddDistributedTokenCache(services =>
    {
      // Requires to reference Microsoft.Extensions.Caching.StackExchangeRedis
       services.AddStackExchangeRedisCache(options =>
       {
         options.Configuration = "localhost";
         options.InstanceName = "Redis";
       });

      // You can even decide if you want to repair the connection
      // with Redis and retry on Redis failures. 
      services.Configure<MsalDistributedTokenCacheAdapterOptions>(options => 
      {
        options.OnL2CacheFailure = (ex) =>
        {
          if (ex is StackExchange.Redis.RedisConnectionException)
          {
            // action: try to reconnect or something
            return true; //try to do the cache operation again
          }
          return false;
        };
      });
    });

這是 Azure Cosmos DB 快取的程式碼：

      // Azure Cosmos DB token cache
      app.AddDistributedTokenCache(services =>
      {
        // Requires to reference Microsoft.Extensions.Caching.Cosmos
        services.AddCosmosCache((CosmosCacheOptions cacheOptions) =>
        {
          cacheOptions.ContainerName = Configuration["CosmosCacheContainer"];
          cacheOptions.DatabaseName = Configuration["CosmosCacheDatabase"];
          cacheOptions.ClientBuilder = new CosmosClientBuilder(Configuration["CosmosConnectionString"]);
          cacheOptions.CreateIfNotExists = true;
        });
       });

欲了解更多分散式快取資訊，請參閱：

• 分散式快取加密與進階選項
• 處理 L2 快取驅逐
• 在 Docker 中設置 Redis 快取
• Troubleshooting

停用舊版代幣快取

MSAL 內部有專門用於與舊有 Microsoft 驗證資源庫（ADAL）快取互動的程式碼。 當 MSAL 和 ADAL 不並用時，舊快取就不會被使用，相關的舊有程式碼也變得不必要。 MSAL 4.25.0 新增了停用舊有 ADAL 快取程式碼並提升快取使用效能的功能。 關於停用舊有快取前後的效能比較，請參見 GitHub 拉取請求 2309。

請像以下程式碼那樣呼叫 .WithLegacyCacheCompatibility(false) 應用程式建構器。

var app = ConfidentialClientApplicationBuilder
	.Create(clientId)
	.WithClientSecret(clientSecret)
	.WithLegacyCacheCompatibility(false)
	.Build();

Samples

• 以下範例是一個 ASP.NET 網頁應用程式：使用 OpenID Connect 登入使用者至 Microsoft 身分識別平台。

在桌面應用程式中，我們建議使用跨平台令牌快取。 MSAL.NET 在名為 Microsoft.Identity.Client.Extensions.MSAL 的獨立程式庫中提供跨平台權杖快取。

參考 NuGet 套件

加上 Microsoft。Identity.Client.Extensions.MSAL NuGet 套件到你的專案。

設定令牌快取

以下範例展示了如何使用跨平台令牌快取：

 var storageProperties =
     new StorageCreationPropertiesBuilder(Config.CacheFileName, Config.CacheDir)
     .WithLinuxKeyring(
         Config.LinuxKeyRingSchema,
         Config.LinuxKeyRingCollection,
         Config.LinuxKeyRingLabel,
         Config.LinuxKeyRingAttr1,
         Config.LinuxKeyRingAttr2)
     .WithMacKeyChain(
         Config.KeyChainServiceName,
         Config.KeyChainAccountName)
     .Build();

 IPublicClientApplication pca = PublicClientApplicationBuilder.Create(clientId)
    .WithAuthority(Config.Authority)
    .WithRedirectUri("http://localhost")  // make sure to register this redirect URI for the interactive login 
    .Build();
    

// This hooks up the cross-platform cache into MSAL
var cacheHelper = await MsalCacheHelper.CreateAsync(storageProperties );
cacheHelper.RegisterCache(pca.UserTokenCache);    

純文字備援模式

跨平台代幣快取允許你將未加密的代幣儲存在 ACL 限制的純文字檔案中。 這在靜態加密失效時非常有用，這種情況偶爾會因環境因素而發生。 您可以使用以下程式碼模式來使用純文字備援模式：

storageProperties =
    new StorageCreationPropertiesBuilder(
        Config.CacheFileName + ".plaintext",
        Config.CacheDir)
    .WithUnprotectedFile()
    .Build();

var cacheHelper = await MsalCacheHelper.CreateAsync(storageProperties).ConfigureAwait(false);

MSAL.NET 預設提供記憶體內的標記快取。 MAUI 行動目標預設提供序列化功能。

如果你想撰寫自己的標記快取序列化器，MSAL.NET 在 .NET Framework 和 .NET Core 子平台上提供自訂的標記快取序列化功能。 存取快取時，會觸發事件。 應用程式可以選擇是序列化或反序列化快取。

在處理使用者的機密用戶端應用程式（如登入使用者並呼叫網頁 API，以及呼叫下游 Web API 的網頁應用程式）中，使用者數量可能很多。 使用者會被並行處理。 基於安全性和效能的考量，建議您為每個使用者序列化一個快取。 序列化事件會根據處理中的使用者身份計算快取金鑰，並為該使用者序列化或反序列化該使用者的標記快取。

請記住，行動平台無法提供自訂序列化功能。 MSAL 已經為這些平台定義了一套安全且效能良好的序列化機制。 然而，.NET 桌面與 .NET Core 應用程式的架構有所不同。 而且 MSAL 無法實作通用的序列化機制。

例如，網站可能會選擇將標記儲存在 Redis 快取中，桌面應用程式則可能將標記存放在加密檔案中。 所以，預設並不提供序列化功能。 若要在 .NET 桌面或 .NET Core 中建立持久的令牌快取應用程式，請自訂序列化。

以下類別與介面用於標記快取序列化：

• ITokenCache 定義了訂閱令牌快取序列化請求的事件，以及以各種格式（MSAL 2.x 與 MSAL 3.x）序列化或反序列化快取的方法。
• TokenCacheCallback 是傳遞給事件的回呼函式，讓你可以處理序列化作業。 它們會以型別為 TokenCacheNotificationArgs 的引數來呼叫。
• TokenCacheNotificationArgs 僅提供應用程式的 ClientId 值，以及可使用該權杖的使用者參考。

策略會因你是為 公開客戶端應用程式 （桌面）或 機密客戶端應用程式 （網頁應用程式、網頁 API、守護程序應用程式）撰寫令牌快取序列化而有所不同。

網頁應用程式或網頁 API（機密客戶端應用程式）的自訂令牌快取

如果你想為機密用戶端應用程式撰寫自己的權杖快取序列化程式，我們建議你繼承 Microsoft.Identity.Web.MsalAbstractTokenCacheProvider，並覆寫 WriteCacheBytesAsync 和 ReadCacheBytesAsync 方法。

權杖快取序列化程式的範例可在 Microsoft.Identity.Web/TokenCacheProviders 中找到。

桌面或行動應用程式（公開客戶端應用程式）的自訂令牌快取

MSAL.NET v2.x 及後續版本提供多種序列化公共用戶端憑證快取的選項。 你只能將快取序列化成 MSAL.NET 格式（統一格式快取在 MSAL 及各平台皆有）。
如何自訂令牌快取序列化，以共享 ADAL.NET 3.x、ADAL.NET 5.x 與 MSAL.NET 之間的單一登入狀態，詳見以下範例：active-directory-dotnet-v1-to-v2。

簡易令牌快取序列化（僅限 MSAL）

以下程式碼是一個為桌面應用程式自訂序列化代幣快取的簡單實作範例。 在這裡，使用者憑證快取是與應用程式同一個資料夾中的檔案。

建置應用程式後，透過呼叫 TokenCacheHelper.EnableSerialization() 方法並傳遞應用程式 UserTokenCache 屬性來啟用序列化。

app = PublicClientApplicationBuilder.Create(ClientId)
    .Build();
TokenCacheHelper.EnableSerialization(app.UserTokenCache);

TokenCacheHelper輔助類別定義為：

static class TokenCacheHelper
 {
  public static void EnableSerialization(ITokenCache tokenCache)
  {
   tokenCache.SetBeforeAccess(BeforeAccessNotification);
   tokenCache.SetAfterAccess(AfterAccessNotification);
  }

  /// <summary>
  /// Path to the token cache. Note that this could be something different, for instance, for MSIX applications:
  /// private static readonly string CacheFilePath =
  /// $"{Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData)}\{AppName}\msalcache.bin";
  /// </summary>
  public static readonly string CacheFilePath = System.Reflection.Assembly.GetExecutingAssembly().Location + ".msalcache.bin3";

  private static readonly object FileLock = new object();


  private static void BeforeAccessNotification(TokenCacheNotificationArgs args)
  {
   lock (FileLock)
   {
    args.TokenCache.DeserializeMsalV3(File.Exists(CacheFilePath)
            ? ProtectedData.Unprotect(File.ReadAllBytes(CacheFilePath),
                                      null,
                                      DataProtectionScope.CurrentUser)
            : null);
   }
  }

  private static void AfterAccessNotification(TokenCacheNotificationArgs args)
  {
   // if the access operation resulted in a cache update
   if (args.HasStateChanged)
   {
    lock (FileLock)
    {
     // reflect changes in the persistent store
     File.WriteAllBytes(CacheFilePath,
                         ProtectedData.Protect(args.TokenCache.SerializeMsalV3(),
                                                 null,
                                                 DataProtectionScope.CurrentUser)
                         );
    }
   }
  }
 }

可供公用用戶端應用程式（適用於在 Windows、Mac 和 Linux 上執行的桌面應用程式）使用的產品等級、以檔案為基礎的權杖快取序列化程式，可從 Microsoft.Identity.Client.Extensions.Msal 開源程式庫取得。 您可以透過下列 NuGet 套件將其包含在您的應用程式中：Microsoft.Identity.Client.Extensions.Msal。