Serialisatie van tokencache

De Microsoft. Identity.Web.TokenCache NuGet-pakket biedt serialisatie van tokenscache in de Microsoft. Identity.Web library. De bibliotheek biedt integratie met zowel ASP.NET Core als ASP.NET Classic, en de bijbehorende abstracties kunnen worden gebruikt om andere web-app- of API-frameworks te stimuleren.

Tokencache in het geheugen

Hier volgt een voorbeeld van code die gebruikmaakt van de cache in het geheugen in de methode ConfigureServices van de klasse Startup in een ASP.NET Core-toepassing:

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 is geschikt voor productie als u tokens aanvraagt die alleen voor apps zijn bedoeld. Als u gebruikerstokens gebruikt, kunt u overwegen om een gedistribueerde tokencache te gebruiken.

Configuratiecode voor tokencache is vergelijkbaar tussen ASP.NET Core web-apps en web-API's.

Gedistribueerde tokencaches

Hier volgen voorbeelden van mogelijke gedistribueerde 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;
});

Voor meer informatie, zie:

• Gedistribueerde cacheversleuteling en andere geavanceerde opties
• L2-cacheverwijdering afhandelen
• Een Redis-cache instellen in Docker
• Troubleshooting

Het gebruik van de gedistribueerde cache komt aan bod in de ASP.NET Core-web-appzelfstudie in de token-cache van fase 2-2.

Voor .NET-vertrouwelijke clients wordt aangeraden Microsoft.Identity.Web te gebruiken, dat is gebaseerd op MSAL.NET, omdat API’s op hoger niveau complexe scenario’s standaard kunnen afhandelen (bijvoorbeeld gastgebruikers, Continuous Access Evaluation, Proof-of-Possession-tokens). Toepassingen die toegang moeten hebben tot Azure API's, moeten gebruikmaken van Azure SDK, die intern gebruikmaakt van MSAL.

Het volgende materiaal is relevant als u MSAL.NET rechtstreeks gebruikt.

Beschikbare cachingtechnologieën

• Geheugencache zonder verwijdering
• Geheugencache met verwijdering
• Gecombineerde gedistribueerde en geheugencaches

Geheugencache zonder verwijdering

Gebruik .WithCacheOptions(CacheOptions.EnableSharedCacheOptions) bij het bouwen van een service-naar-service-applicatie - AcquireTokenForClient die niet is bedoeld voor veel (meer dan 100.000) tenants.

    // 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) maakt de interne MSAL-tokencache gedeeld tussen MSAL-clienttoepassingsexemplaren. Het delen van een tokencache is sneller dan het gebruik van serialisatie van tokenscaches, maar de interne tokencache in het geheugen heeft geen verwijderingsbeleid. Bestaande tokens worden vernieuwd, maar door tokens op te halen voor verschillende gebruikers, tenants en resources, wordt de cache dienovereenkomstig vergroot.

Geheugencache met verwijdering

Raadpleeg de Microsoft. Identity.Web.TokenCache NuGet-pakket voor uw project.

De volgende code laat zien hoe u een cache in het geheugen toevoegt met verwijdering:

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

Gedistribueerde caches

Als u app.AddDistributedTokenCache gebruikt, is de tokencache een adapter op de .NET-implementatie IDistributedCache. U kunt dus kiezen tussen een SQL Server-cache, een Redis-cache, een Azure Cosmos DB-cache of een andere cache die de IDistributedCache-interface implementeert.

Voor testdoeleinden kunt u services.AddDistributedMemoryCache() gebruiken, een in-memoryimplementatie van IDistributedCache.

Hier volgt de code voor een 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 volgt de code voor een 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 volgt de code voor een 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;
        });
       });

Zie voor meer informatie over gedistribueerde caches:

• Gedistribueerde cacheversleuteling en geavanceerde opties
• L2-cacheverwijdering afhandelen
• Een Redis-cache instellen in Docker
• Troubleshooting

Een verouderde tokencache uitschakelen

MSAL heeft specifieke interne code om interactie met verouderde Microsoft Authentication Library (ADAL)-cache mogelijk te maken. Wanneer MSAL en ADAL niet naast elkaar worden gebruikt, wordt de verouderde cache niet gebruikt en is de gerelateerde verouderde code niet nodig. MSAL 4.25.0 voegt de mogelijkheid toe om verouderde ADAL-cachecode uit te schakelen en de prestaties van het cachegebruik te verbeteren. Zie GitHub pull-aanvraag 2309 voor een prestatievergelijking voor en na het uitschakelen van de verouderde cache.

Roep .WithLegacyCacheCompatibility(false) een toepassingsbouwer aan zoals de volgende code.

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

Samples

• Het volgende voorbeeld is een ASP.NET-web-app: OpenID Connect gebruiken om gebruikers aan te melden bij Microsoft identity platform.

In desktoptoepassingen wordt u aangeraden de platformoverschrijdende tokencache te gebruiken. MSAL.NET biedt de platformoverschrijdende tokencache in een afzonderlijke bibliotheek met de naam Microsoft. Identity.Client.Extensions.MSAL.

Verwijzen naar het NuGet-pakket

Voeg het NuGet-pakket Microsoft.Identity.Client.Extensions.Msal toe aan uw project.

De tokencache configureren

In het volgende voorbeeld ziet u hoe u een platformoverschrijdende tokencache gebruikt:

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

Terugvalmodus voor tekst zonder opmaak

Met de platformonafhankelijke tokencache kunt u niet-versleutelde tokens opslaan in een onopgemaakt tekstbestand met ACL-beperkingen. Dit is handig in gevallen waarin versleuteling-at-rest mislukt, wat ocassioneel gebeurt vanwege omgevingsgerelateerde redenen. U kunt de terugvalmodus voor tekst zonder opmaak gebruiken met behulp van het volgende codepatroon:

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

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

MSAL.NET biedt standaard een tokencache in het geheugen. Serialisatie is standaard beschikbaar voor mobiele MAUI-doelen.

Als u uw eigen serialisatiefunctie voor tokencache wilt schrijven, biedt MSAL.NET aangepaste tokencacheserialisatie in het .NET Framework en .NET Core-subplatforms. Gebeurtenissen worden geactiveerd wanneer de cache wordt geopend. Apps kunnen kiezen of de cache moet worden geserialiseerd of gedeserialiseerd.

Voor vertrouwelijke clienttoepassingen die gebruikers verwerken (web-apps die gebruikers aanmelden en web-API's aanroepen en web-API's aanroepen die downstream-web-API's aanroepen), kunnen er veel gebruikers zijn. De gebruikers worden parallel verwerkt. Voor de veiligheid en prestaties wordt aanbevolen één cache per gebruiker te serialiseren. Serialisatiegebeurtenissen berekenen een cachesleutel op basis van de identiteit van de verwerkte gebruiker en serialiseren of deserialiseren van een tokencache voor die gebruiker.

Houd er rekening mee dat aangepaste serialisatie niet beschikbaar is op mobiele platforms. MSAL definieert al een veilig en performant serialisatiemechanisme voor deze platforms. .NET desktop- en .NET Core-toepassingen hebben echter verschillende architecturen. En MSAL kan geen serialisatiemechanisme voor algemeen gebruik implementeren.

Websites kunnen er bijvoorbeeld voor kiezen om tokens op te slaan in een Redis-cache of desktop-apps kunnen tokens opslaan in een versleuteld bestand. Serialisatie wordt dus niet standaard geleverd. Als u een permanente tokencachetoepassing wilt hebben in .NET bureaublad of .NET Core, past u de serialisatie aan.

De volgende klassen en interfaces worden gebruikt in serialisatie van tokencaches:

• ITokenCache definieert gebeurtenissen voor het abonneren op tokencacheserialisatieaanvragen en methoden voor het serialiseren of deserialiseren van de cache in verschillende indelingen (MSAL 2.x en MSAL 3.x).
• TokenCacheCallback is een callback die wordt doorgegeven aan de gebeurtenissen, zodat u de serialisatie kunt afhandelen. Ze worden aangeroepen met argumenten van het type TokenCacheNotificationArgs.
• TokenCacheNotificationArgs biedt alleen de waarde ClientId van de toepassing en een verwijzing naar de gebruiker waarvoor het token beschikbaar is.

De strategieën verschillen, afhankelijk van of u een tokencacheserialisatie schrijft voor een openbare clienttoepassing (desktop) of een vertrouwelijke clienttoepassing (web-app, web-API, daemon-app).

Aangepaste tokencache voor een web-app of web-API (vertrouwelijke clienttoepassing)

Als u uw eigen serialisatiefunctie voor de tokencache wilt schrijven voor vertrouwelijke clienttoepassingen, raden we u aan om over te erven van Microsoft.Identity.Web.MsalAbstractTokenCacheProvider en de methoden WriteCacheBytesAsync en ReadCacheBytesAsync te overschrijven.

Voorbeelden van tokencacheserialisaties zijn beschikbaar in Microsoft. Identity.Web/TokenCacheProviders.

Aangepaste tokencache voor een desktop- of mobiele app (openbare clienttoepassing)

MSAL.NET v2.x en latere versies bieden verschillende opties voor het serialiseren van de tokencache van een openbare client. U kunt de cache alleen serialiseren in de MSAL.NET-indeling (de cache met de uniforme indeling is gemeenschappelijk voor MSAL en de platforms).
Het aanpassen van de serialisatie van de tokencache om de status van eenmalige aanmelding te delen tussen ADAL.NET 3.x, ADAL.NET 5.x en MSAL.NET wordt uitgelegd in een deel van het volgende voorbeeld: active-directory-dotnet-v1-to-v2.

Eenvoudige serialisatie van tokencache (alleen MSAL)

De volgende code is een voorbeeld van een naïeve implementatie van aangepaste serialisatie van een tokencache voor bureaubladtoepassingen. Hier is de gebruikerstokencache een bestand in dezelfde map als de toepassing.

Nadat u de toepassing hebt gebouwd, schakelt u de serialisatie in door de methode aan te roepen en de TokenCacheHelper.EnableSerialization() eigenschap van UserTokenCache de toepassing door te geven.

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

De TokenCacheHelper helperklasse wordt gedefinieerd als:

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

Een serialisatiefunctie voor tokencache van productkwaliteit op basis van bestanden voor openbare clienttoepassingen (voor desktoptoepassingen die worden uitgevoerd op Windows, Mac en Linux) is beschikbaar via de Microsoft. Identity.Client.Extensions.Msal opensource-bibliotheek. U kunt deze opnemen in uw toepassingen vanuit het volgende NuGet-pakket: Microsoft. Identity.Client.Extensions.Msal.