Serialisasi cache token MSAL.NET

  • Artikel
  • 17 menit untuk membaca

Setelah Pustaka Autentikasi Microsoft (MSAL) memperoleh token, token tersebut disimpan dalam cache. Aplikasi klien publik (aplikasi desktop dan seluler) harus mencoba mendapatkan token dari cache sebelum memperoleh token dengan metode lain. Metode akuisisi pada aplikasi klien rahasia mengelola cache itu sendiri. Artikel ini membahas serialisasi default dan kustom cache token di MSAL.NET.

Ringkasan singkat

Rekomendasinya adalah:

  • Saat Anda menulis aplikasi desktop, gunakan cache token lintas platform seperti yang dijelaskan di Aplikasi desktop.
  • Jangan lakukan apa pun untuk aplikasi seluler dan UWP. MSAL.NET menyediakan penyimpanan yang aman untuk cache.
  • Di aplikasi web dan API web ASP.NET Core, gunakan Microsoft.Identity.Web sebagai API tingkat yang lebih tinggi. Anda akan mendapatkan cache token dan banyak lagi. Lihat Aplikasi web dan API web ASP.NET Core.
  • Dalam kasus aplikasi web dan API web lainnya:
    • Jika Anda meminta token untuk pengguna dalam aplikasi produksi, gunakan cache token terdistribusi (Redis, SQL Server, Azure Cosmos DB, memori terdistribusi). Gunakan pembuat serial cache token yang tersedia dari Microsoft.Identity.Web.TokenCache.
    • Jika tidak, jika Anda ingin menggunakan cache dalam memori:

      • Jika Anda hanya menggunakan AcquireTokenForClient, gunakan kembali instans aplikasi klien rahasia dan jangan tambahkan pembuat serial, atau buat aplikasi klien rahasia baru dan aktifkan opsi cache bersama.

        Cache bersama lebih cepat karena tidak diserialisasi. Namun, memori akan bertambah saat token di-cache. Jumlah token sama dengan jumlah penyewa dikalikan jumlah API downstream. Token aplikasi berukuran sekitar 2 KB, sedangkan token untuk pengguna berukuran sekitar 7 KB. Ini bagus untuk pengembangan, atau jika Anda memiliki sedikit pengguna.

      • Jika Anda ingin menggunakan cache token dalam memori dan mengontrol ukuran dan kebijakan pengeluarannya, gunakan opsi cache dalam memori Microsoft.Identity.Web.

  • Jika Anda membuat SDK dan ingin menulis pembuat serial cache token Anda sendiri untuk aplikasi klien rahasia, warisi dari Microsoft.Identity.Web.MsalAbstractTokenCacheProvider dan ganti metode WriteCacheBytesAsync dan ReadCacheBytesAsync.

Paket NuGet Microsoft.Identity.Web.TokenCache menyediakan serialisasi cache token dalam pustaka Microsoft.Identity.Web.

Metode ekstensi Deskripsi
AddInMemoryTokenCaches Membuat cache sementara di memori untuk penyimpanan dan pengambilan token. Cache token dalam memori lebih cepat daripada jenis cache lainnya, tetapi tokennya tidak bertahan di antara penghidupan ulang aplikasi, dan Anda tidak dapat mengontrol ukuran cache. Cache dalam memori bagus untuk aplikasi yang tidak memerlukan token untuk tetap ada di antara penghidupan ulang aplikasi. Gunakan cache token dalam memori di aplikasi yang berpartisipasi dalam skenario autentikasi mesin-ke-mesin seperti layanan, daemon, dan lainnya yang menggunakan AcquireTokenForClient (pemberian izin informasi masuk klien). Cache token dalam memori juga baik untuk aplikasi sampel dan selama pengembangan aplikasi lokal. Microsoft.Identity.Web versi 1.19.0+ berbagi cache token dalam memori di semua instans aplikasi.
AddSessionTokenCaches Cache token terikat ke sesi pengguna. Opsi ini tidak ideal jika token ID berisi banyak klaim, karena cookie akan menjadi terlalu besar.
AddDistributedTokenCaches Cache token adalah adaptor terhadap penerapan ASP.NET Core IDistributedCache. Hal ini memungkinkan Anda untuk memilih antara cache memori terdistribusi, cache Redis, NCache terdistribusi, atau cache SQL Server. Untuk detail tentang penerapan IDistributedCache, lihat Cache memori terdistribusi.

Cache token dalam memori

Berikut adalah contoh kode yang menggunakan cache dalam memori dalam metode ConfigureServices kelas Startup dalam aplikasi ASP.NET Core:

#using Microsoft.Identity.Web

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 cocok dalam produksi jika Anda meminta token khusus aplikasi. Jika Anda menggunakan token pengguna, pertimbangkan untuk menggunakan cache token terdistribusi.

Kode konfigurasi cache token antara aplikasi web ASP.NET Core dan API web ini mirip.

Cache token terdistribusi

Berikut adalah contoh kemungkinan cache terdistribusi:

// 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 'false'.
    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;
});

Untuk informasi selengkapnya, lihat:

Penggunaan cache terdistribusi ditampilkan dalam tutorial aplikasi web ASP.NET Core di cache token fase 2-2.

Memantau rasio hit cache dan kinerja cache

MSAL memperlihatkan metrik penting sebagai bagian dari objek AuthenticationResult.AuthenticationResultMetadata. Anda dapat mencatat metrik ini untuk menilai kondisi aplikasi Anda.

Metrik Makna Kapan harus memicu alarm?
DurationTotalInMs Total waktu yang dihabiskan di MSAL, termasuk panggilan jaringan dan cache. Alarm pada latensi tinggi secara keseluruhan (> 1 detik). Nilai tergantung pada sumber token. Dari cache: satu akses cache. Dari Azure Active Directory (Azure AD): dua akses cache ditambah satu panggilan HTTP. Panggilan pertama (per-proses) akan memakan waktu lebih lama karena satu panggilan HTTP tambahan.
DurationInCacheInMs Waktu yang dihabiskan untuk memuat atau menyimpan cache token, yang disesuaikan oleh pengembang aplikasi (misalnya, simpan ke Redis). Alarm pada paku.
DurationInHttpInMs Waktu yang dihabiskan untuk melakukan panggilan HTTP ke Azure Active Directory. Alarm pada paku.
TokenSource Sumber tokennya. Token diambil dari cache jauh lebih cepat (misalnya, ~ 100 ms versus ~ 700 ms). Dapat digunakan untuk memantau dan alarm rasio hit cache. Gunakan dengan DurationTotalInMs.
CacheRefreshReason Alasan mengambil token akses dari penyedia identitas. Gunakan dengan TokenSource.

Langkah berikutnya

Contoh berikut mengilustrasikan serialisasi cache token.

Sampel Platform Deskripsi
active-directory-dotnet-desktop-msgraph-v2 Desktop (WPF) Aplikasi Windows Desktop .NET (WPF) yang memanggil API Microsoft Graph. Diagram that shows a topology with a desktop app client flowing to Azure Active Directory by acquiring a token interactively and to Microsoft Graph.
active-directory-dotnet-v1-to-v2 Desktop (konsol) Kumpulan solusi Visual Studio yang menggambarkan migrasi aplikasi Azure Active Directory v1.0 (menggunakan ADAL.NET) ke aplikasi platform identitas Microsoft (menggunakan MSAL.NET). Untuk mempelajari selengkapnya, lihat Migrasi cache token dan Cache token klien rahasia.
ms-identity-aspnet-webapp-openidconnect ASP.NET (net472) Contoh serialisasi cache token dalam aplikasi MVC ASP.NET (menggunakan MSAL.NET). Untuk mempelajari selengkapnya, lihat MsalAppBuilder.