トークン キャッシュのシリアル化

Microsoft.Identity.Web.TokenCache NuGet パッケージは、Microsoft.Identity.Web ライブラリ内でトークン キャッシュのシリアル化を提供します。 ライブラリは、ASP.NET Coreと ASP.NET Classic の両方との統合を提供し、その抽象化を使用して他の Web アプリまたは API フレームワークを駆動できます。

メモリ内トークン キャッシュ

ASP.NET Core アプリケーションの Startup クラスの 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 Web アプリと Web 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 Cache を設定する
• Troubleshooting

分散キャッシュの使用方法は、フェーズ 2-2 トークン キャッシュの ASP.NET Core Web アプリのチュートリアルで紹介されています。

.NET の機密クライアントでは、MSAL.NET に基づく Microsoft.Identity.Web の使用が推奨されます。これは、より高レベルの API で複雑なシナリオ（ゲスト ユーザー、継続的アクセス評価、Proof-of-Possession トークンなど）に標準で対応できるためです。 AZURE API にアクセスする必要があるアプリケーションでは、MSAL を内部的に活用するAzure SDKを使用する必要があります。

MSAL.NET を直接使用している場合は、次の資料が関連します。

使用可能なキャッシュ テクノロジ

• 削除なしのメモリ キャッシュ
• 削除を含むメモリ キャッシュ
• 分散キャッシュとメモリ キャッシュの組み合わせ

削除なしのメモリ キャッシュ

.WithCacheOptions(CacheOptions.EnableSharedCacheOptions)を使用して、多くの (100,000 を超える) テナントを対象としないAcquireTokenForClientサービス間アプリケーションを構築します。

    // 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 Cache のコードを次に示します。

    // 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 Cache を設定する
• Troubleshooting

レガシ トークン キャッシュの無効化

MSAL には、レガシ Microsoft Authentication Library (ADAL) キャッシュとの対話を可能にするために特別に内部コードがいくつかあります。 MSAL と ADAL がサイド バイ サイドで使用されていない場合、レガシ キャッシュは使用されず、関連するレガシ コードは不要です。 MSAL 4.25.0 では 、従来の ADAL キャッシュ コードを無効にし、キャッシュの使用パフォーマンスを向上させる機能が追加されました。 レガシ キャッシュを無効にする前と無効にした後のパフォーマンス比較については、pull request 2309 GitHub参照してください。

次のコードのように、アプリケーション ビルダーで .WithLegacyCacheCompatibility(false) を呼び出します。

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

Samples

• 次のサンプルは ASP.NET Web アプリです: OpenID Connect を使用してユーザーを Microsoft ID プラットフォームにサインインさせる。

デスクトップ アプリケーションでは、クロスプラットフォーム トークン キャッシュを使用することをお勧めします。 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 サブプラットフォームでカスタム トークン キャッシュのシリアル化を提供します。 キャッシュにアクセスされたときに、イベントが発火します。 アプリは、キャッシュをシリアル化または逆シリアル化するかどうかを選択できます。

ユーザーを処理する機密クライアント アプリケーション (ユーザーをサインインして Web API を呼び出す Web アプリ、ダウンストリーム Web API を呼び出す Web API) には、多くのユーザーが存在する可能性があります。 ユーザーは並行して処理されます。 セキュリティとパフォーマンス上の理由から、ユーザーごとに 1 つのキャッシュをシリアル化することをお勧めします。 シリアル化イベントは、処理されたユーザーの ID に基づいてキャッシュ キーを計算し、そのユーザーのトークン キャッシュをシリアル化または逆シリアル化します。

カスタム シリアル化はモバイル プラットフォームでは使用できないことに注意してください。 MSAL では、これらのプラットフォームのセキュリティで保護されたパフォーマンスの高いシリアル化メカニズムが既に定義されています。 ただし、.NETデスクトップ アプリケーションと .NET Core アプリケーションには、さまざまなアーキテクチャがあります。 また、MSAL は汎用シリアル化メカニズムを実装できません。

たとえば、Web サイトが Redis Cache にトークンを格納することを選択したり、デスクトップ アプリが暗号化されたファイルにトークンを格納したりする場合があります。 そのため、シリアル化はすぐには提供されません。 .NET デスクトップまたは .NET Core で永続的なトークン キャッシュを使用するには、シリアル化をカスタマイズします。

トークン キャッシュのシリアル化では、次のクラスとインターフェイスが使用されます。

• ITokenCache は、さまざまな形式 (MSAL 2.x および MSAL 3.x) でキャッシュをシリアル化または逆シリアル化するためのトークン キャッシュのシリアル化要求とメソッドをサブスクライブするイベントを定義します。
• TokenCacheCallback は、シリアル化を処理できるようにイベントに渡されるコールバックです。 これらは、 TokenCacheNotificationArgs型の引数を使用して呼び出されます。
• TokenCacheNotificationArgs は、アプリケーションの ClientId 値と、トークンが使用可能なユーザーへの参照のみを提供します。

戦略は、 パブリック クライアント アプリケーション (デスクトップ) または 機密 クライアント アプリケーション (Web アプリ、Web API、デーモン アプリ) のトークン キャッシュのシリアル化を記述するかどうかによって異なります。

Web アプリまたは Web API のカスタム トークン キャッシュ (機密クライアント アプリケーション)

機密クライアント アプリケーション用に独自のトークン キャッシュ シリアライザーを作成する場合は、Microsoft.Identity.Web.MsalAbstractTokenCacheProvider を継承し、WriteCacheBytesAsync メソッドと ReadCacheBytesAsync メソッドをオーバーライドすることをお勧めします。

トークン キャッシュ シリアライザーの例は、Microsoftで提供されています。Identity.Web/TokenCacheProviders。

デスクトップまたはモバイル アプリのカスタム トークン キャッシュ (パブリック クライアント アプリケーション)

v2.x 以降のバージョン MSAL.NET、パブリック クライアントのトークン キャッシュをシリアル化するためのオプションがいくつか用意されています。 キャッシュは、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)
                         );
    }
   }
  }
 }

パブリック クライアント アプリケーション向けの、製品品質のファイル ベースのトークン キャッシュ シリアライザーは、Microsoft.Identity.Client.Extensions.Msal オープンソース ライブラリで利用できます（Windows、Mac、Linux で実行されるデスクトップ アプリケーション用）。 これは、次の NuGet パッケージからアプリケーションに含めることができます: Microsoft。Identity.Client.Extensions.Msal。