Belirteç önbelleği serileştirmesi

Microsoft Authentication Library (MSAL) bir belirteç aldıktan sonra bu belirteci önbelleğe alır. Genel istemci uygulamaları (masaüstü ve mobil uygulamalar), başka bir yöntemle belirteç almadan önce önbellekten belirteç almaya çalışmalıdır. Gizli istemci uygulamalarında edinme yöntemleri önbelleği kendileri yönetir. Bu makalede, MSAL.NET'de belirteç önbelleğinin varsayılan ve özel seri hale getirilmesi açıkılmaktadır.

Summary

Öneri:

• Mobil uygulamalar yazarken önbelleğe alma MSAL tarafından önceden yapılandırılmıştır.
• Masaüstü uygulaması yazarken, masaüstü uygulamalarında açıklandığı gibi platformlar arası belirteç önbelleğini kullanın.
• Yeni gizli istemci uygulamaları (web uygulamaları, web API'leri veya hizmetten hizmete ya da daemon uygulamaları) yazarken, daha üst düzey bir API olarak Microsoft.Identity.Web kullanın. ASP.NET Core, ASP.NET Classic ile tümleştirme sunar ve tek başına da çalışır.
• MSAL.NET doğrudan kullanan mevcut gizli istemci uygulamaları bunu yapmaya devam edebilir.
• Web uygulamaları ve web API'leri, kısıtlanmış bir bellek önbelleğiyle birlikte dağıtılmış bir belirteç önbelleği (örneğin, Redis, SQL Server, Azure Cosmos DB) kullanmalıdır.
• Bekleyen verilerin şifrelenmesi, ASP.NET Core Veri Koruması kullanılarak isteğe bağlı şekilde yapılandırılabilir.
• Web uygulamaları oturum tanımlama bilgilerini de kullanır; ancak tanımlama bilgisi boyutu nedeniyle bu seçenek önerilmez.
• Hizmet-hizmet ve daemon uygulamaları yalnızca bellek önbelleğe almayı kullanıyor olabilir. Uygulamanız birçok kiracıya hizmet ediyorsa bir çıkarma ilkesi yapılandırın.
• Yönetilen kimlik belirteçleri yalnızca bellekte önbelleğe alınır.

Microsoft.Identity.Web kullanan gizli istemciler

Microsoft.Identity.Web.TokenCache NuGet paketi, Microsoft.Identity.Web kitaplığı içinde belirteç önbelleği serileştirmesi sağlar. Kitaplık hem ASP.NET Core hem de ASP.NET Klasik ile tümleştirme sağlar ve soyutlamaları diğer web uygulaması veya API çerçevelerini yönlendirmek için kullanılabilir.

Note

Aşağıdaki örnekler ASP.NET Core içindir. ASP.NET için kod benzerdir; referans uygulama için web uygulaması ms-identity-aspnet-wepapp-openidconnect örneğine bakın.

Uzantı yöntemi	Description
AddInMemoryTokenCaches	Belirteç depolama ve alma için bellekte geçici bir önbellek oluşturur. Bellek içi belirteç önbellekleri diğer önbellek türlerinden daha hızlıdır, ancak belirteçleri uygulama yeniden başlatmaları arasında kalıcı olmaz ve önbellek boyutunu denetleyemezsiniz. Bellek içi önbellekler, uygulama yeniden başlatmaları arasında belirteçlerin kalıcı olmasını gerektirmeyen uygulamalar için uygundur. AcquireTokenForClient kullanan hizmetler, daemon'lar ve diğerleri gibi makineden makineye kimlik doğrulama senaryolarına katılan uygulamalarda bellek içi belirteç önbelleği kullanın (istemci kimlik bilgileri verir). Bellek içi belirteç önbellekleri, örnek uygulamalar ve yerel uygulama geliştirme sırasında da iyidir. Microsoft. Identity.Web sürüm 1.19.0+ tüm uygulama örneklerinde bellek içi belirteç önbelleğini paylaşır.
AddSessionTokenCaches	Belirteç önbelleği kullanıcı oturumuna bağlıdır. Kimlik belirteci çok sayıda claim içeriyorsa, tanımlama bilgisi çok büyük olacağından bu seçenek ideal değildir.
AddDistributedTokenCaches	Belirteç önbelleği, ASP.NET Core IDistributedCache uygulamasına karşı bir bağdaştırıcıdır. Dağıtılmış bellek önbelleği, Redis önbelleği, dağıtılmış NCache veya SQL Server önbelleği arasında seçim yapmanıza olanak tanır. Uygulamalar hakkında IDistributedCache ayrıntılı bilgi için bkz . Dağıtılmış bellek önbelleği.

Bellek içi belirteç önbelleği

Bir ASP.NET Core uygulamasında başlangıç sınıfınınConfigureServices yönteminde bellek içi önbelleği kullanan bir kod örneği aşağıda verilmiştir:

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 yalnızca uygulama belirteçleri istemeniz durumunda üretim için uygundur. Kullanıcı belirteçleri kullanıyorsanız, dağıtılmış belirteç önbelleği kullanmayı göz önünde bulundurun.

Belirteç önbelleği yapılandırma kodu, ASP.NET Core web uygulamaları ile web API'leri arasında benzerdir.

Dağıtılmış belirteç önbellekleri

Olası dağıtılmış önbellek örnekleri aşağıda verilmiştir:

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

Daha fazla bilgi için bakınız:

• Dağıtılmış önbellek şifrelemesi ve diğer gelişmiş seçenekler
• L2 önbelleği çıkarmayı işleme
• Docker'da Redis önbelleği ayarlama
• Troubleshooting

Dağıtılmış önbellek kullanımı, 2-2. aşama belirteç önbelleğindekiASP.NET Core web uygulaması öğreticisinde yer alır.

MSAL.NET kullanan gizli istemciler

.NET gizli istemcilerinin, MSAL.NET tabanlı Microsoft.Identity.Web kullanmaları önerilir; çünkü üst düzey API'ler karmaşık senaryoları (örneğin konuk kullanıcılar, Sürekli Erişim Değerlendirmesi, Sahiplik Kanıtı belirteçleri) doğrudan işleyebilir. Azure API'lerine erişmesi gereken uygulamalar, MSAL'yi dahili olarak kullanan Azure SDK kullanmalıdır.

Doğrudan MSAL.NET kullanıyorsanız aşağıdaki malzeme geçerlidir.

Kullanılabilir önbelleğe alma teknolojileri

• Çıkarma olmadan bellek önbelleği
• Çıkarma özellikli bellek önbelleği
• Birleşik dağıtılmış ve bellek önbellekleri

Tahliyesiz bellek önbelleği

Çok sayıda (100.000'den fazla) kiracıyı hedeflemeyen bir hizmetten hizmete uygulama oluştururken .WithCacheOptions(CacheOptions.EnableSharedCacheOptions) kullanın - AcquireTokenForClient

Important

Bu seçenekle önbelleğin boyutunu denetlemenin bir yolu yoktur. Bir web sitesi, web API’si veya çok kiracılı hizmetten hizmete uygulama oluşturuyorsanız Memory cache with eviction bölümüne bakın.

    // 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) iç MSAL belirteci önbelleğini MSAL istemci uygulaması örnekleri arasında paylaştırır. Belirteç önbelleğini paylaşmak, herhangi bir belirteç önbelleği serileştirmesini kullanmaktan daha hızlıdır, ancak iç bellek içi belirteç önbelleğinde çıkarma ilkeleri yoktur. Mevcut belirteçler yerinde yenilenir, ancak farklı kullanıcılar, kiracılar ve kaynaklar için belirteçler getirildiğinde önbellek buna göre büyür.

Tahliyeli bellek önbelleği

Projenize Microsoft.Identity.Web.TokenCache NuGet paketini ekleyin.

Aşağıdaki kod, çıkarma ile bellek içi önbelleğin nasıl ekleneceğini gösterir:

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

Dağıtılmış önbellekler

app.AddDistributedTokenCache kullanıyorsanız, belirteç önbelleği .NET IDistributedCache uygulaması için bir bağdaştırıcıdır. Böylece SQL Server önbelleği, Redis önbelleği, Azure Cosmos DB önbelleği veya IDistributedCache arabirimini uygulayan diğer önbellekler arasında seçim yapabilirsiniz.

Test amacıyla, bellek içi uygulamasını services.AddDistributedMemoryCache()kullanabilirsinizIDistributedCache.

SQL Server önbelleğinin kodu aşağıdadır:

     // 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 önbelleğinin kodu aşağıdadır:

    // 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 önbelleğinin kodu aşağıdadır:

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

Dağıtılmış önbellekler hakkında daha fazla bilgi için bkz:

• Dağıtılmış önbellek şifrelemesi ve gelişmiş seçenekler
• L2 önbellek tahliyesini işle
• Docker'da Redis önbelleği ayarlama
• Troubleshooting

Eski belirteç önbelleğini devre dışı bırakma

MSAL,eski Microsoft Authentication Library (ADAL) önbelleğiyle etkileşime geçmek için özel olarak bazı iç kodlara sahiptir. MSAL ve ADAL yan yana kullanılmadığında, eski önbellek kullanılmaz ve ilgili eski kod gereksizdir. MSAL 4.25.0 , eski ADAL önbellek kodunu devre dışı bırakma ve önbellek kullanım performansını iyileştirme özelliği ekler. Eski önbellek devre dışı bırakılmadan önceki ve sonraki performans karşılaştırması için bkz: GitHub pull request’i 2309.

Aşağıdaki kod gibi bir uygulama oluşturucuda çağrısı .WithLegacyCacheCompatibility(false) yapın.

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

Samples

• Aşağıdaki örnek, ASP.NET bir web uygulamasıdır: Kullanıcıların Microsoft kimlik platformu oturum açmak için OpenID Connect'i kullanın.

Masaüstü uygulamaları

Masaüstü uygulamalarında platformlar arası belirteç önbelleğini kullanmanızı öneririz. MSAL.NET, platformlar arası belirteç önbelleğini Microsoft.Identity.Client.Extensions.MSAL adlı ayrı bir kitaplıkta sağlar.

NuGet paketine başvurma

Microsoft.Identity.Client.Extensions.Msal NuGet paketini projenize ekleyin.

Belirteç önbelleğini yapılandırma

Aşağıdaki örnekte platformlar arası belirteç önbelleğinin nasıl kullanılacağı gösterilmektedir:

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

Düz metin geri dönüş modu

Platformlar arası belirteç önbelleği, şifrelenmemiş belirteçleri ACL ile kısıtlanmış bir düz metin dosyasında depolamanıza olanak tanır. Bu, beklemedeki şifrelemenin başarısız olduğu durumlarda kullanışlıdır; bu da zaman zaman ortama bağlı nedenlerle gerçekleşir. Aşağıdaki kod desenini kullanarak düz metin geri dönüş modunu kullanabilirsiniz:

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

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

Mobil uygulamalar

MSAL.NET varsayılan olarak bellek içi belirteç önbelleği sağlar. MAUI mobil hedefleri için serileştirme varsayılan olarak sağlanır.

Kendi önbelleğinizi yazma

Kendi belirteç önbelleği seri hale getiricinizi yazmak istiyorsanız, MSAL.NET .NET Framework ve .NET Core alt platformlarında özel belirteç önbelleği serileştirmesi sağlar. Önbelleğe erişildiğinde olaylar tetiklenir. Uygulamalar önbelleği seri hale getirmeyi veya seri durumdan çıkarmayı seçebilir.

Kullanıcılarla çalışan gizli istemci uygulamalarında (kullanıcıların oturum açmasını sağlayan ve web API’lerini çağıran web uygulamaları ile aşağı akış web API’lerini çağıran web API’leri) çok sayıda kullanıcı olabilir. Kullanıcılar paralel olarak işlenir. Güvenlik ve performans nedenleriyle, kullanıcı başına bir önbelleği seri hale getirmemiz önerilir. Serileştirme olayları, işlenen kullanıcının kimliğini temel alarak bir önbellek anahtarı hesaplar ve bu kullanıcı için bir belirteç önbelleğini serileştirir veya seri durumdan çıkarır.

Özel serileştirmenin mobil platformlarda kullanılamadığını unutmayın. MSAL, bu platformlar için güvenli ve performanslı bir serileştirme mekanizmasını zaten tanımlar. Ancak masaüstü ve .NET Core uygulamaları .NET çeşitli mimarilere sahiptir. Ayrıca MSAL, genel amaçlı serileştirme mekanizması uygulayamaz.

Örneğin, web siteleri belirteçleri Redis önbelleğinde depolamayı seçebilir veya masaüstü uygulamaları belirteçleri şifrelenmiş bir dosyada depolayabilir. Yani serileştirme varsayılan olarak sunulmuyor. .NET masaüstünde veya .NET Core'da kalıcı bir belirteç önbellek uygulamasına sahip olmak için serileştirmeyi özelleştirin.

Belirteç önbelleği serileştirmesinde aşağıdaki sınıflar ve arabirimler kullanılır:

• ITokenCache, belirteç önbelleği serileştirme isteklerine abone olmak için olayları ve önbelleği çeşitli biçimlerde (MSAL 2.x ve MSAL 3.x) serileştirmek veya seri durumdan çıkarmak için yöntemleri tanımlar.
• TokenCacheCallback, serileştirmeyi yönetmeniz için olaylara aktarılan bir geri çağırımdır. Bunlar TokenCacheNotificationArgs türünde bağımsız değişkenlerle çağrılır.
• TokenCacheNotificationArgs yalnızca uygulamanın ClientId değerini ve belirtecin kullanılabildiği kullanıcıya ilişkin bir başvuru sağlar.

Important

MSAL.NET sizin için belirteç önbellekleri oluşturur. Bir uygulamanın IToken ve UserTokenCache özelliklerini çağırdığınızda size AppTokenCache önbellek sağlar. Arabirimi kendiniz gerçekleştirmeniz gerekmiyor.

Özel belirteç önbelleği serileştirmesi uyguladığınızda sorumluluğunuz, BeforeAccess ve AfterAccess olaylarına (veya bunların Async türlerine) tepki vermektir. BeforeAccess temsilcisi önbelleği seri durumdan çıkarmaktan sorumluyken, AfterAccess temsilcisi önbelleği seri duruma getirmekten sorumludur. Bu olayların bazı bölümleri, istediğiniz depolama alanına olay bağımsız değişkeni aracılığıyla aktarılan blob’ları depolar veya yükler.

Stratejiler, genel istemci uygulaması (masaüstü) veya gizli bir istemci uygulaması (web uygulaması, web API'si, daemon uygulaması ) için belirteç önbelleği serileştirmesi yazmanıza bağlı olarak farklıdır.

Web uygulaması veya web API'si için özel belirteç önbelleği (gizli istemci uygulaması)

Gizli istemci uygulamaları için kendi belirteç önbelleği serileştiricinizi yazmak istiyorsanız, Microsoft.Identity.Web.MsalAbstractTokenCacheProvider sınıfından türetmenizi ve WriteCacheBytesAsync ile ReadCacheBytesAsync yöntemlerini geçersiz kılmanızı öneririz.

Belirteç önbelleği serileştiricilerine ilişkin örnekler Microsoft.Identity.Web/TokenCacheProviders içinde sağlanır.

Masaüstü veya mobil uygulama (genel istemci uygulaması) için özel belirteç önbelleği

MSAL.NET v2.x ve sonraki sürümler, genel istemcinin belirteç önbelleğini serileştirmek için çeşitli seçenekler sağlar. Önbelleği yalnızca MSAL.NET biçimine göre seri hale getirebilirsiniz (birleşik biçim önbelleği MSAL ve platformlar arasında yaygındır).
ADAL.NET 3.x, ADAL.NET 5.x ve MSAL.NET arasında çoklu oturum açma durumunu paylaşmak için belirteç önbelleği serileştirmesinin özelleştirilmesi şu örneğin bir bölümünde açıklanmıştır: active-directory-dotnet-v1-to-v2.

Basit belirteç önbelleği serileştirme (yalnızca MSAL)

Aşağıdaki kod, masaüstü uygulamaları için belirteç önbelleğinin özel seri hale getirilmesine yönelik basit bir uygulama örneğidir. Burada kullanıcı belirteci önbelleği, uygulamayla aynı klasörde yer alan bir dosyadır.

Uygulamayı derledikten sonra, TokenCacheHelper.EnableSerialization() yöntemini çağırıp uygulamanın UserTokenCache özelliğini geçirerek serileştirmeyi etkinleştirirsiniz.

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

Yardımcı TokenCacheHelper sınıfı şu şekilde tanımlanır:

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 ve Linux üzerinde çalışan masaüstü uygulamaları için ortak istemci uygulamalarına yönelik, üretim kalitesinde dosya tabanlı bir belirteç önbelleği seri hale getiricisi, Microsoft.Identity.Client.Extensions.Msal açık kaynak kitaplığı tarafından sunulmaktadır. Uygulamalarınıza aşağıdaki NuGet paketinden ekleyebilirsiniz: Microsoft. Identity.Client.Extensions.Msal.

Önbellek isabet oranlarını ve önbellek performansını izleme

MSAL, AuthenticationResult.AuthenticationResultMetadata nesnesinin bir parçası olarak önemli ölçümleri kullanıma sunar. Uygulamanızın durumunu değerlendirmek için bu ölçümleri günlüğe kaydedebilirsiniz.

Metric	Meaning	Ne zaman alarm tetiklemeli?
DurationTotalInMs	Ağ çağrıları ve önbellek de dahil olmak üzere MSAL'de harcanan toplam süre.	Genel yüksek gecikme alarmı (> 1 saniye). Değer belirteç kaynağına bağlıdır. Önbellekten: bir önbellek erişimi. Microsoft Entra ID: İki önbellek erişimi ve bir HTTP çağrısı. Ek bir HTTP çağrısı nedeniyle ilk çağrı (işlem başına) daha uzun sürer.
DurationInCacheInMs	Uygulama geliştiricisi tarafından özelleştirilen belirteç önbelleğini yüklemek veya kaydetmek için harcanan süre (örneğin, Redis'e kaydedin).	Ani artışlarda alarm.
DurationInHttpInMs	Microsoft Entra ID HTTP çağrıları yapmak için harcanan zaman.	Ani artışlarda alarm.
TokenSource	Token’ın kaynağı. Belirteçler önbellekten çok daha hızlı alınır (örneğin, ~100 ms ile ~700 ms). Önbellek isabet oranını izlemek ve alarma almak için kullanılabilir.	DurationTotalInMs ile kullanın.
CacheRefreshReason	Kimlik sağlayıcısından erişim belirtecini getirme nedeni.	TokenSource ile kullanın.

Boyut yaklaşıkları

Belirteç önbelleği kullanırken, özellikle yüksek oranda kullanılabilir ve dağıtılmış uygulamalar için önbelleğin olası boyutunu göz önünde bulundurmanız önemlidir. Kullanıcılar oturum açtığında, her kullanıcı için yaklaşık 7 KB boyutunda bir önbellek girişi olacaktır. Birkaç aşağı akış API'sini çağırıyorsanız boyut daha büyük olacaktır. Hizmetler arası kimlik doğrulaması için, her kiracı ve alt API için yaklaşık 2 KB boyutunda bir önbellek girdisi bulunacaktır.

Ayrıntılı tahminler aşağıda listelenmiştir.

Uygulama akışları (AcquireTokenForClient, AcquireTokenForManagedIdentity)

• Yalnızca erişim belirteçleri önbelleğe alınır. Bir belirteç, kalıcı olarak depolandığında yaklaşık 2-3 KB boyutundadır. Uygulama istemci kimliği * kiracılar * alt akış kaynakları başına 1 belirteç olacaktır. Örneğin, 1000 kiracıya hizmet veren ve Graph ile SharePoint için belirteçlere ihtiyaç duyan çok kiracılı bir uygulama şu değeri kullanır: 3 KB * 1000 * 2, yani yaklaşık 6 MB.

Aşağı akış web API'leriniAcquireTokenByAuthCode () çağıran web sitesi

• Erişim belirteçleri – 4 KB; Uygulama istemci kimliği * kullanıcı * kiracı * aşağı akış kaynağı başına 1 belirteç.
• Yenileme belirteci – 2 KB; İstemci uygulama kimliği * kullanıcı başına 1 belirteç.
• Kimlik belirteci – 2 KB; İstemci uygulama kimliği * kullanıcı * kullanıcının oturum açtığı kiracı sayısı başına 1 belirteç.

Note

Bunun için doğrudan MSAL değil, daha üst düzey API'lerin Microsoft.Identity.Web kullanılmasını kesinlikle öneririz. Önbelleğe alma konusunda dikkat edilmesi gerekenler aynıdır.

Diğer web API'lerini çağıran Web API'si (AcquireTokenOnBehalfOf)

Web sitesi senaryosunda olduğu gibi, ancak her kullanıcı için değil, her oturum için 1 düğüm olacaktır. Varsayılan olarak MSAL, bir oturumu üst akış beyanının karma değerini oluşturarak tanımlar, ancak bu değiştirilebilir. Bkz. Uzun Süre Çalışan OBO İşlemleri.

Note

Bunun için doğrudan MSAL değil, daha üst düzey API'lerin Microsoft.Identity.Web kullanılmasını kesinlikle öneririz. Önbelleğe alma konusunda dikkat edilmesi gerekenler aynıdır.

Belirteç önbelleği türleri

MSAL.NET iki tür belirteç önbelleğiyle çalışır: kullanıcı ve uygulama.

Bu uygulama için erişim belirteçlerini tutan uygulama belirteci önbelleği . AcquireTokenForClient çağrılırken sessizce korunur ve güncelleştirilir.

Kullanıcı belirteci önbelleği, MSAL.NET'in etkileşimde bulunduğu hesaplara ait kimlik belirteçlerini, erişim belirteçlerini ve yenileme belirteçlerini içerir. AcquireTokenSilent çağrılırken gerekirse sessizce kullanılır ve güncelleştirilir. Yalnızca uygulama önbelleğini kullanan AcquireTokenForClient dışında her belirteç alma yöntemi tarafından güncelleştirilir.

Sonraki Adımlar

Aşağıdaki örneklerde belirteç önbelleği serileştirme gösterilmektedir.

Sample	Platform	Description
active-directory-dotnet-desktop-msgraph-v2	Masaüstü (WPF)	Microsoft Graph API'sini çağıran Windows masaüstü .NET (WPF) uygulaması.
active-directory-dotnet-v1-to-v2	Masaüstü (konsol)	Azure AD v1.0 uygulamalarının (ADAL.NET kullanarak) Microsoft kimlik platformu uygulamalara (MSAL.NET kullanarak) geçişini gösteren Visual Studio çözümleri kümesi.
ms-identity-aspnet-webapp-openidconnect	ASP.NET (net472)	bir ASP.NET MVC uygulamasında (MSAL.NET kullanarak) belirteç önbelleği serileştirme örneği.