Serialisasi cache token

Setelah Pustaka Autentikasi Microsoft (MSAL) memperoleh token, pustaka tersebut menyimpan token itu di 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

Rekomendasinya adalah:

• Saat mengembangkan aplikasi seluler, cache sudah dikonfigurasi sebelumnya di MSAL.
• Saat menulis aplikasi desktop, gunakan cache token lintas platform seperti yang dijelaskan di aplikasi desktop.
• Saat menulis aplikasi klien rahasia baru (aplikasi web, API web, atau aplikasi layanan ke layanan atau daemon, gunakan Microsoft. Identity.Web sebagai API tingkat yang lebih tinggi. Ini menawarkan integrasi dengan ASP.NET Core, ASP.NET Classic, dan berfungsi mandiri juga.
• Aplikasi klien rahasia yang ada yang memanfaatkan MSAL.NET secara langsung dapat terus melakukannya.
• Aplikasi web dan API web harus menggunakan cache token terdistribusi (misalnya, Redis, SQL Server, Azure Cosmos DB) bersama dengan cache memori yang dibatasi.
• Enkripsi saat tidak aktif dapat dikonfigurasi secara opsional menggunakan ASP.NET Core Perlindungan Data.
• Aplikasi web juga dapat mengandalkan cookie sesi; namun, opsi ini tidak disarankan karena ukuran cookie.
• Aplikasi layanan-ke-layanan dan daemon dapat hanya mengandalkan cache memori. Jika aplikasi Anda melayani banyak penyewa, konfigurasikan kebijakan pengeluaran.
• Token identitas terkelola hanya di-cache dalam memori.

Klien rahasia yang menggunakan Microsoft. Identity.Web

Paket NuGet Microsoft.Identity.Web.TokenCache menyediakan serialisasi cache token di dalam pustaka Microsoft.Identity.Web. Pustaka menyediakan integrasi dengan ASP.NET Core dan ASP.NET Classic, dan abstraksinya dapat digunakan untuk mendorong aplikasi web atau kerangka kerja API lainnya.

Note

Contoh di bawah ini adalah untuk ASP.NET Core. Untuk ASP.NET kode serupa, lihat ms-identity-aspnet-wepapp-openidconnect sampel aplikasi web untuk implementasi referensi.

Metode ekstensi	Deskripsi
AddInMemoryTokenCaches	Membuat cache sementara dalam memori untuk penyimpanan dan pengambilan token. Cache token dalam memori lebih cepat daripada jenis cache lainnya, tetapi tokennya tidak disimpan saat aplikasi dimulai ulang, dan Anda tidak dapat mengontrol ukuran cache. Cache di memori cocok untuk aplikasi yang tidak mengharuskan token tetap dipertahankan setelah aplikasi dimulai ulang. Gunakan cache token dalam memori di aplikasi yang berpartisipasi dalam skenario autentikasi mesin-ke-mesin seperti layanan, daemon, dan lainnya yang menggunakan AcquireTokenForClient (pemberian kredensial 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 menjadi terlalu besar.
AddDistributedTokenCaches	Cache token adalah adaptor terhadap implementasi ASP.NET CoreIDistributedCache. Ini memungkinkan Anda memilih antara cache memori terdistribusi, cache Redis, NCache terdistribusi, atau cache SQL Server. Untuk detail tentang IDistributedCache implementasi, lihat Cache memori terdistribusi.

Cache token dalam memori

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

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

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

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

Untuk informasi selengkapnya, lihat:

• Enkripsi cache terdistribusi dan opsi tingkat lanjut lainnya
• Menangani pengeluaran cache L2
• Menyiapkan cache Redis di Docker
• Troubleshooting

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

Klien rahasia yang menggunakan MSAL.NET

.NET klien rahasia disarankan untuk menggunakan Microsoft. Identity.Web, yang didasarkan pada MSAL.NET, karena API tingkat yang lebih tinggi dapat menangani skenario kompleks di luar kotak (misalnya, pengguna tamu, Evaluasi Akses Berkelanjutan, token Bukti Kepemilikan). Aplikasi yang perlu mengakses API Azure harus menggunakan Azure SDK, yang memanfaatkan MSAL secara internal.

Materi berikut relevan jika Anda menggunakan MSAL.NET secara langsung.

Teknologi cache yang tersedia

• Cache memori tanpa pengeluaran
• Cache memori dengan pengeluaran
• Cache terdistribusi dan cache memori gabungan

Cache memori tanpa pengeluaran

Gunakan .WithCacheOptions(CacheOptions.EnableSharedCacheOptions) saat membangun aplikasi layanan-ke-layanan - AcquireTokenForClient yang tidak menargetkan banyak (lebih dari 100.000) penyewa.

Important

Tidak ada cara untuk mengontrol ukuran cache dengan opsi ini. Jika Anda sedang membuat situs web, API web, atau aplikasi multi-penyewa antarlayanan, lihat bagian Memory cache with eviction.

    // 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) menjadikan cache token MSAL internal digunakan bersama di antara instans aplikasi klien MSAL. Berbagi cache token lebih cepat daripada menggunakan serialisasi cache token apa pun, tetapi cache token dalam memori internal tidak memiliki kebijakan pengeluaran. Token yang sudah ada diperbarui di tempat yang sama, tetapi pengambilan token untuk pengguna, tenant, dan sumber daya yang berbeda membuat ukuran cache bertambah seiring dengan itu.

Cache memori dengan pengeluaran

Tambahkan referensi ke paket NuGet Microsoft.Identity.Web.TokenCache dalam proyek Anda.

Kode berikut menunjukkan cara menambahkan cache dalam memori dengan pengeluaran:

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)
         });
      });
  }

Cache terdistribusi

Jika Anda menggunakan app.AddDistributedTokenCache, cache token adalah adaptor terhadap implementasi .NETIDistributedCache. Jadi Anda dapat memilih antara cache SQL Server, cache Redis, cache Azure Cosmos DB, atau cache lain yang mengimplementasikan antarmuka IDistributedCache.

Untuk tujuan pengujian, Anda dapat menggunakan services.AddDistributedMemoryCache(), implementasi dalam memori dari IDistributedCache.

Berikut adalah kode untuk cache 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);
      });
     });

Berikut adalah kode untuk cache 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;
        };
      });
    });

Berikut adalah kode untuk cache 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;
        });
       });

Untuk informasi selengkapnya tentang cache terdistribusi, lihat:

• Enkripsi cache terdistribusi dan opsi tingkat lanjut
• Menangani pengeluaran cache L2
• Menyiapkan cache Redis di Docker
• Troubleshooting

Menonaktifkan cache token warisan

MSAL memiliki beberapa kode internal khusus untuk memungkinkan berinteraksi dengan cache warisan Pustaka Autentikasi Microsoft (ADAL). Ketika MSAL dan ADAL tidak digunakan berdampingan, cache warisan tidak digunakan dan kode warisan terkait tidak perlu. MSAL 4.25.0 menambahkan kemampuan untuk menonaktifkan kode cache ADAL warisan dan meningkatkan performa penggunaan cache. Untuk perbandingan performa sebelum dan sesudah menonaktifkan cache warisan, lihat GitHub permintaan pull 2309.

Panggil .WithLegacyCacheCompatibility(false) pada pembangun aplikasi seperti pada kode berikut.

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

Sampel

• Sampel berikut adalah aplikasi web ASP.NET: Gunakan OpenID Connect untuk memasukkan pengguna ke platform identitas Microsoft.

Aplikasi desktop

Dalam aplikasi desktop, kami sarankan Anda menggunakan cache token lintas platform. MSAL.NET menyediakan cache token lintas platform di pustaka terpisah bernama Microsoft. Identity.Client.Extensions.MSAL.

Merujuk ke paket NuGet

Tambahkan paket NuGet Microsoft.Identity.Client.Extensions.Msal ke proyek Anda.

Mengonfigurasi cache token

Contoh berikut menunjukkan cara menggunakan cache token lintas platform:

 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);    

Mode cadangan teks biasa

Cache token lintas platform memungkinkan Anda menyimpan token yang tidak terenkripsi dalam file teks biasa yang dibatasi ACL. Ini berguna dalam kasus ketika enkripsi data saat disimpan gagal, yang terkadang terjadi karena faktor lingkungan. Anda dapat menggunakan mode fallback teks biasa dengan menggunakan pola kode berikut:

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

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

Aplikasi perangkat bergerak

MSAL.NET menyediakan cache token dalam memori secara default. Serialisasi disediakan secara default untuk target seluler MAUI.

Menulis cache Anda sendiri

Jika Anda ingin menulis serializer cache token Anda sendiri, MSAL.NET menyediakan serialisasi cache token kustom di subplatform .NET Framework dan .NET Core. Kejadian dipicu saat cache diakses. Aplikasi dapat memilih untuk melakukan serialisasi atau deserialisasi cache.

Pada aplikasi klien rahasia yang menangani pengguna (aplikasi web yang memasukkan pengguna dan memanggil API web, dan API web yang memanggil API web hilir), mungkin ada banyak pengguna. Pengguna diproses secara paralel. Untuk alasan keamanan dan kinerja, rekomendasi kami adalah menyerialisasikan satu cache per pengguna. Peristiwa serialisasi menghitung kunci cache berdasarkan identitas pengguna yang diproses dan menserialisasikan atau mendeserialisasi cache token untuk pengguna tersebut.

Ingat, serialisasi kustom tidak tersedia di platform seluler. MSAL sudah mendefinisikan mekanisme serialisasi yang aman dan berkinerja untuk platform ini. namun, .NET aplikasi desktop dan .NET Core memiliki arsitektur yang bervariasi. Dan MSAL tidak dapat menerapkan mekanisme serialisasi tujuan umum.

Misalnya, situs web mungkin memilih untuk menyimpan token di cache Redis, atau aplikasi desktop mungkin menyimpan token dalam file terenkripsi. Jadi, serialisasi tidak disediakan secara bawaan. Untuk memiliki aplikasi cache token persisten di desktop .NET atau .NET Core, sesuaikan serialisasi.

Kelas dan antarmuka berikut digunakan dalam serialisasi cache token:

• ITokenCache mendefinisikan event untuk berlangganan permintaan serialisasi cache token serta metode untuk menserialisasikan atau mendeserialisasikan cache dalam berbagai format (MSAL 2.x dan MSAL 3.x).
• TokenCacheCallback adalah fungsi callback yang diteruskan ke event sehingga Anda dapat menangani serialisasi. Mereka dipanggil dengan argumen jenis TokenCacheNotificationArgs.
• TokenCacheNotificationArgs hanya menyediakan nilai ClientId aplikasi dan referensi ke pengguna yang untuknya token tersebut tersedia.

Important

MSAL.NET membuat cache token untuk Anda. Ini menyediakan cache IToken untuk Anda saat Anda memanggil properti UserTokenCache dan AppTokenCache milik aplikasi. Anda tidak seharusnya mengimplementasikan antarmuka sendiri.

Anda bertanggung jawab, saat menerapkan serialisasi cache token kustom, untuk merespons event BeforeAccess dan AfterAccess (atau varian Async-nya). Delegasi BeforeAccess bertanggung jawab untuk melakukan deserialisasi cache, sedangkan delegasi AfterAccess bertanggung jawab untuk melakukan serialisasi cache. Sebagian dari kejadian ini menyimpan atau memuat blob, yang diteruskan melalui argumen kejadian ke media penyimpanan apa pun yang Anda inginkan.

Strateginya berbeda tergantung pada apakah Anda menulis serialisasi cache token untuk aplikasi klien publik (desktop) atau aplikasi klien rahasia (aplikasi web, API web, aplikasi daemon).

Cache token kustom untuk aplikasi web atau API web (aplikasi klien rahasia)

Jika Anda ingin menulis serializer cache token Anda sendiri untuk aplikasi klien rahasia, kami sarankan agar Anda mewarisi Microsoft.Identity.Web.MsalAbstractTokenCacheProvider dan mengambil alih metode WriteCacheBytesAsync dan ReadCacheBytesAsync.

Contoh serializer cache token disediakan dalam Microsoft. Identity.Web/TokenCacheProviders.

Cache token kustom untuk aplikasi desktop atau seluler (aplikasi klien publik)

MSAL.NET v2.x dan versi yang lebih baru menyediakan beberapa opsi untuk membuat serialisasi cache token klien publik. Anda dapat membuat serialisasi cache hanya ke format MSAL.NET (cache format terpadu umum di seluruh MSAL dan platform).
Menyesuaikan serialisasi cache token untuk berbagi status akses menyeluruh antara ADAL.NET 3.x, ADAL.NET 5.x, dan MSAL.NET dijelaskan dalam bagian dari sampel berikut: active-directory-dotnet-v1-to-v2.

Serialisasi cache token sederhana (hanya MSAL)

Kode berikut adalah contoh implementasi naif dari serialisasi kustom cache token untuk aplikasi desktop. Di sini, cache token pengguna adalah file di folder yang sama dengan aplikasi.

Setelah Anda membangun aplikasi, Anda mengaktifkan serialisasi dengan memanggil metode TokenCacheHelper.EnableSerialization() dan meneruskan properti UserTokenCache aplikasi.

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

Kelas pembantu TokenCacheHelper didefinisikan sebagai:

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)
                         );
    }
   }
  }
 }

Serializer cache token berbasis file berkualitas produksi untuk aplikasi klien publik (untuk aplikasi desktop yang berjalan di Windows, Mac, dan Linux) tersedia melalui pustaka sumber terbuka Microsoft.Identity.Client.Extensions.Msal. Anda dapat menyertakannya dalam aplikasi Anda dari paket NuGet berikut: Microsoft. Identity.Client.Extensions.Msal.

Memantau rasio hit cache dan performa cache

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

Ukuran	Meaning	Kapan harus memicu alarm?
DurationTotalInMs	Total waktu yang dihabiskan di MSAL, termasuk panggilan jaringan dan cache.	Alarm pada latensi tinggi keseluruhan (> 1 detik). Nilai tergantung pada sumber token. Dari cache: satu akses cache. Dari Microsoft Entra ID: dua akses cache ditambah satu panggilan HTTP. Panggilan pertama (per proses) membutuhkan 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 saat terjadi lonjakan.
DurationInHttpInMs	Waktu yang dihabiskan untuk melakukan panggilan HTTP ke Microsoft Entra ID.	Alarm saat terjadi lonjakan.
TokenSource	Sumber token. Token diambil dari cache jauh lebih cepat (misalnya, ~100 ms versus ~700 ms). Dapat digunakan untuk memantau dan memberikan alarm pada rasio hit cache.	Gunakan dengan DurationTotalInMs.
CacheRefreshReason	Alasan untuk mengambil token akses dari penyedia identitas.	Gunakan dengan TokenSource.

Perkiraan ukuran

Saat menggunakan cache token, penting untuk mempertimbangkan ukuran potensial cache, terutama untuk aplikasi yang sangat tersedia dan terdistribusi. Saat pengguna masuk, akan ada entri cache untuk setiap pengguna, berukuran sekitar 7KB. Ukurannya akan lebih besar jika Anda memanggil beberapa API hilir. Untuk autentikasi layanan ke layanan, akan ada entri cache untuk setiap penyewa dan API hilir, berukuran sekitar 2KB.

Perkiraan terperinci tercantum di bawah ini.

Alur aplikasi (AcquireTokenForClient, AcquireTokenForManagedIdentity)

• Hanya token akses yang di-cache. Satu token berukuran sekitar 2–3 KB saat disimpan. Akan ada 1 token per ID klien aplikasi * penyewa * sumber daya hilir. Misalnya, aplikasi multipenyewa yang melayani 1000 penyewa dan memerlukan token untuk Graph dan SharePoint akan menggunakan: 3 KB * 1000 * 2, yakni sekitar 6 MB.

Situs web memanggil API web hilir (AcquireTokenByAuthCode)

• Token akses – 4KB; 1 token per ID klien aplikasi * pengguna * penyewa * sumber daya hilir.
• Refresh token – 2KB; 1 token per ID aplikasi klien * pengguna.
• Token ID – 2KB; 1 token per ID aplikasi klien * pengguna * jumlah penyewa tempat pengguna tersebut masuk.

Note

Kami sangat menyarankan untuk menggunakan API tingkat yang lebih tinggi dari Microsoft.Identity.Web untuk ini dan bukan MSAL secara langsung. Pertimbangan cache tetap sama.

API Web memanggil API web lainnya (AcquireTokenOnBehalfOf)

Sama seperti untuk skenario situs web, tetapi akan ada 1 simpul untuk setiap sesi, bukan untuk setiap pengguna. Secara bawaan, MSAL mengidentifikasi sesi dengan membuat hash dari pernyataan upstream, tetapi hal ini dapat diubah. Lihat Proses OBO yang Berjalan Lama.

Note

Kami sangat menyarankan untuk menggunakan API tingkat yang lebih tinggi dari Microsoft.Identity.Web untuk ini dan bukan MSAL secara langsung. Pertimbangan terkait cache tetap sama.

Jenis cache token

MSAL.NET beroperasi dengan dua jenis cache token - pengguna dan aplikasi.

Cache token aplikasi yang menyimpan token akses untuk aplikasi ini. Ini dipertahankan dan diperbarui secara diam-diam saat memanggil AcquireTokenForClient.

Cache token pengguna menyimpan token ID, token akses, dan token refresh untuk akun yang berinteraksi dengan MSAL.NET. Ini digunakan dan diperbarui secara diam-diam jika diperlukan saat memanggil AcquireTokenSilent. Ini diperbarui oleh setiap metode akuisisi token, dengan pengecualian AcquireTokenForClient yang hanya menggunakan cache aplikasi.

Langkah berikutnya

Sampel berikut mengilustrasikan serialisasi cache token.

Sample	Platform	Deskripsi
active-directory-dotnet-desktop-msgraph-v2	Desktop (WPF)	aplikasi Windows Desktop .NET (WPF) yang memanggil Microsoft Graph API.
active-directory-dotnet-v1-to-v2	Desktop (konsol)	Kumpulan solusi Visual Studio yang menggambarkan migrasi aplikasi Azure AD v1.0 (menggunakan ADAL.NET) ke aplikasi platform identitas Microsoft (menggunakan MSAL.NET).
ms-identity-aspnet-webapp-openidconnect	ASP.NET (net472)	Contoh serialisasi cache token dalam aplikasi ASP.NET MVC (menggunakan MSAL.NET).