Serialisierung des Tokencaches

Das NuGet-Paket Microsoft.Identity.Web.TokenCache stellt die Tokencache-Serialisierung innerhalb der Microsoft.Identity.Web-Bibliothek bereit. Die Bibliothek bietet Integration sowohl mit ASP.NET Core als auch mit ASP.NET Classic, und seine Abstraktionen können verwendet werden, um andere Web-App- oder API-Frameworks zu steuern.

Cache für In-Memory-Token

Nachfolgend finden Sie ein Beispiel für Code, der den Speichercache in der ConfigureServices-Methode der Startup-Klasse in einer ASP.NET Core Anwendung verwendet:

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 eignet sich in der Produktion, wenn Sie nur App-Token anfordern. Wenn Sie Benutzertoken verwenden, sollten Sie einen verteilten Tokencache verwenden.

Der Code für die Konfiguration des Tokencaches ist bei ASP.NET Core-Web-Apps und Web-APIs ähnlich.

Verteilte Tokencaches

Hier sind Beispiele für mögliche verteilte Caches:

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

Weitere Informationen findest du unter:

• Verteilte Cacheverschlüsselung und andere erweiterte Optionen
• L2-Cache-Verdrängung verarbeiten
• Einrichten eines Redis-Caches in Docker
• Problembehandlung

Die Verwendung des verteilten Caches wird im Lernprogramm für ASP.NET Core Web App im Phase 2-2-Tokencache vorgestellt.

Vertraulichen .NET-Clients wird empfohlen, Microsoft.Identity.Web zu verwenden, das auf MSAL.NET basiert, da höherwertige APIs komplexe Szenarien direkt unterstützen können (z. B. Gastbenutzer, Continuous Access Evaluation, Proof-of-Possession-Token). Anwendungen, die auf Azure APIs zugreifen müssen, sollten Azure SDK verwenden, die MSAL intern nutzt.

Das folgende Material ist relevant, wenn Sie MSAL.NET direkt verwenden.

Verfügbare Cachetechnologien

• Speichercache ohne Entfernung
• Speichercache mit Verdrängung
• Kombinierte verteilte und Arbeitsspeichercaches

Speichercache ohne Entfernung

Verwenden Sie .WithCacheOptions(CacheOptions.EnableSharedCacheOptions) beim Erstellen einer Service-zu-Service-Anwendung – AcquireTokenForClient die nicht auf viele (mehr als 100.000) Mandanten abzielt.

    // 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) macht den internen MSAL-Tokencache zwischen MSAL-Clientanwendungsinstanzen gemeinsam. Die gemeinsame Nutzung eines Token-Caches ist schneller als jede Form der Token-Cache-Serialisierung, aber der interne In-Memory-Token-Cache verfügt über keine Entfernungsrichtlinien. Vorhandene Token werden direkt im Cache erneuert, aber das Abrufen von Token für verschiedene Benutzer, Mandanten und Ressourcen lässt den Cache entsprechend anwachsen.

Arbeitsspeicher-Cache mit Auslagerung

Fügen Sie Ihrem Projekt das Microsoft.Identity.Web.TokenCache-NuGet-Paket hinzu.

Der folgende Code zeigt, wie Sie einen In-Memory-Cache mit Eviction hinzufügen:

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

Verteilte Caches

Wenn Sie app.AddDistributedTokenCache verwenden, ist der Token-Cache ein Adapter für die .NET-Implementierung IDistributedCache. Sie können also zwischen einem SQL Server-Cache, einem Redis-Cache, einem Azure Cosmos DB-Cache oder einem anderen Cache wählen, der die IDistributedCache-Schnittstelle implementiert.

Für Testzwecke können Sie services.AddDistributedMemoryCache() verwenden, eine In-Memory-Implementierung von IDistributedCache.

Hier sehen Sie den Code für einen SQL Server Cache:

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

Hier sehen Sie den Code für einen 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;
        };
      });
    });

Hier sehen Sie den Code für einen Azure Cosmos DB Cache:

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

Weitere Informationen zu verteilten Caches finden Sie unter:

• Verteilte Cacheverschlüsselung und erweiterte Optionen
• L2-Cache-Verdrängung verarbeiten
• Einrichten eines Redis-Caches in Docker
• Problembehandlung

Deaktivieren eines Legacy-Token-Cache

MSAL verfügt über einen internen Code, um die Interaktion mit legacy Microsoft Authentication Library (MSAL) (ADAL)-Cache zu ermöglichen. Wenn MSAL und ADAL nicht nebeneinander verwendet werden, wird der Legacycache nicht verwendet, und der zugehörige Legacycode ist nicht erforderlich. MSAL 4.25.0 bietet die Möglichkeit, ADAL-Cachecode zu deaktivieren und die Leistung der Cachenutzung zu verbessern. Einen Leistungsvergleich vor und nach dem Deaktivieren des Legacycaches finden Sie unter GitHub Pullanforderung 2309.

Rufen Sie .WithLegacyCacheCompatibility(false) für einen Application Builder auf, wie im folgenden Code gezeigt.

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

Beispiele

• Das folgende Beispiel ist eine ASP.NET Web-App: Verwenden Sie OpenID Connect, um Benutzer bei Microsoft Identity Platform anzumelden.

In Desktopanwendungen wird empfohlen, den plattformübergreifenden Tokencache zu verwenden. MSAL.NET stellt den plattformübergreifenden Tokencache in einer separaten Bibliothek mit dem Namen Microsoft bereit. Identity.Client.Extensions.MSAL.

Verweisen auf das NuGet-Paket

Fügen Sie das Microsoft.Identity.Client.Extensions.Msal-NuGet-Paket Ihrem Projekt hinzu.

Konfigurieren des Tokencaches

Das folgende Beispiel zeigt, wie Sie einen plattformübergreifenden Tokencache verwenden:

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

Nur-Text-Fallbackmodus

Mit dem plattformübergreifenden Tokencache können Sie unverschlüsselte Token in einer ACL-eingeschränkten Nur-Text-Datei speichern. Dies ist in Fällen nützlich, in denen die Verschlüsselung im Ruhezustand fehlschlägt, was aufgrund von umgebungsbezogenen Gründen geschieht. Sie können den Nur-Text-Fallbackmodus verwenden, indem Sie das folgende Codemuster verwenden:

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

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

MSAL.NET stellt standardmäßig einen Cache für In-Memory-Token bereit. Serialisierung wird standardmäßig für mobile MAUI-Ziele bereitgestellt.

Wenn Sie einen eigenen Serializer für den Tokencache schreiben möchten, bietet MSAL.NET im .NET Framework und in den .NET-Core-Unterplattformen eine benutzerdefinierte Tokencache-Serialisierung. Ereignisse werden ausgelöst, wenn auf den Cache zugegriffen wird. Apps können auswählen, ob der Cache serialisiert oder deserialisiert werden soll.

Bei vertraulichen Clientanwendungen, die Benutzer verwalten (Web-Apps, die Benutzer anmelden und Web-APIs aufrufen, sowie Web-APIs, die nachgelagerte Web-APIs aufrufen), kann es viele Benutzer geben. Die Benutzer werden parallel verarbeitet. Aus Sicherheits- und Leistungsgründen wird empfohlen, jeweils einen Cache pro Benutzer zu serialisieren. Serialisierungsereignisse berechnen einen Cacheschlüssel basierend auf der Identität des verarbeiteten Benutzers und serialisieren oder deserialisieren eines Tokencaches für diesen Benutzer.

Denken Sie daran, dass die benutzerdefinierte Serialisierung auf mobilen Plattformen nicht verfügbar ist. MSAL definiert bereits einen sicheren und leistungsfähigen Serialisierungsmechanismus für diese Plattformen. .NET Desktop- und .NET Core-Anwendungen weisen jedoch unterschiedliche Architekturen auf. Und MSAL kann keinen allgemeinen Serialisierungsmechanismus implementieren.

Websites können z. B. Token in einem Redis-Cache speichern, oder Desktop-Apps speichern Token in einer verschlüsselten Datei. Also ist die Serialisierung nicht standardmäßig enthalten. Um eine persistente Tokencacheanwendung in .NET Desktop oder .NET Core zu verwenden, passen Sie die Serialisierung an.

Die folgenden Klassen und Schnittstellen werden in der Tokencache-Serialisierung verwendet:

• ITokenCache definiert Ereignisse zum Abonnieren von Anforderungen zur Tokencache-Serialisierung sowie Methoden zum Serialisieren oder Deserialisieren des Caches in verschiedenen Formaten (MSAL 2.x und MSAL 3.x).
• TokenCacheCallback ist ein Callback, der den Ereignissen übergeben wird, damit Sie die Serialisierung verarbeiten können. Sie werden mit Argumenten vom Typ TokenCacheNotificationArgsaufgerufen.
• TokenCacheNotificationArgs stellt nur den ClientId Wert der Anwendung und einen Verweis auf den Benutzer bereit, für den das Token verfügbar ist.

Die Strategien unterscheiden sich je nachdem, ob Sie eine Tokencache-Serialisierung für eine öffentliche Clientanwendung (Desktop) oder eine vertrauliche Clientanwendung (Web-App, Web-API, Daemon-App) schreiben.

Benutzerdefinierter Tokencache für eine Web-App oder Web-API (vertrauliche Clientanwendung)

Wenn Sie für vertrauliche Clientanwendungen einen eigenen Token-Cache-Serializer schreiben möchten, empfehlen wir Ihnen, von Microsoft.Identity.Web.MsalAbstractTokenCacheProvider zu erben und die Methoden WriteCacheBytesAsync und ReadCacheBytesAsync zu überschreiben.

Beispiele für Serialisierer für den Tokencache finden sich in Microsoft.Identity.Web/TokenCacheProviders.

Benutzerdefinierter Tokencache für eine Desktop- oder mobile App (öffentliche Clientanwendung)

MSAL.NET v2.x und neueren Versionen bieten mehrere Optionen zum Serialisieren des Tokencaches eines öffentlichen Clients. Sie können den Cache nur in das MSAL.NET Format serialisieren (der einheitliche Formatcache ist auf MSAL und den Plattformen üblich).
Die Anpassung der Tokencache-Serialisierung, um den Single Sign-On-Zustand zwischen ADAL.NET 3.x, ADAL.NET 5.x und MSAL.NET zu teilen, wird in einem Teil des folgenden Beispiels erläutert: active-directory-dotnet-v1-to-v2.

Einfache Tokencache-Serialisierung (nur MSAL)

Der folgende Code ist ein Beispiel für eine naive Implementierung der benutzerdefinierten Serialisierung eines Tokencaches für Desktopanwendungen. Hier ist der Benutzertokencache eine Datei im selben Ordner wie die Anwendung.

Nachdem Sie die Anwendung erstellt haben, aktivieren Sie die Serialisierung, indem Sie die TokenCacheHelper.EnableSerialization() Methode aufrufen und die Eigenschaft der Anwendung UserTokenCache übergeben.

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

Die TokenCacheHelper Hilfsklasse ist wie folgt definiert:

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

Ein dateibasierter Token-Cache-Serializer in Produktqualität für öffentliche Clientanwendungen (für Desktopanwendungen, die unter Windows, Mac und Linux ausgeführt werden) ist über die Open-Source-Bibliothek Microsoft.Identity.Client.Extensions.Msal verfügbar. Sie können es in Ihre Anwendungen aus dem folgenden NuGet-Paket einschließen: Microsoft. Identity.Client.Extensions.Msal.