Sérialisation du cache de jetons

Le package NuGet Microsoft.Identity.Web.TokenCache fournit la sérialisation du cache de jetons au sein de la bibliothèque Microsoft.Identity.Web. La bibliothèque fournit une intégration à la fois ASP.NET Core et ASP.NET Classic, et ses abstractions peuvent être utilisées pour piloter d’autres infrastructures d’application web ou d’API.

Cache de jetons en mémoire

Voici un exemple de code qui utilise le cache en mémoire dans la méthode ConfigureServices de la classe Startup dans une application 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 peut être utilisé en production si vous demandez uniquement des jetons d’application. Si vous utilisez des jetons utilisateur, envisagez d’utiliser un cache de jetons distribué.

Le code de configuration du cache de jetons est similaire entre les applications web ASP.NET Core et les API web.

Caches de jetons distribués

Voici des exemples de caches distribués possibles :

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

Pour en savoir plus, consultez :

• Chiffrement du cache distribué et autres options avancées
• Gérer l’éviction du cache L2
• Configurer un cache Redis dans Docker
• Troubleshooting

L’utilisation du cache distribué est présentée dans le tutoriel de l’application web ASP.NET Core, à la section cache de jetons de la phase 2-2.

Il est recommandé aux clients confidentiels .NET d’utiliser Microsoft.Identity.Web, qui s’appuie sur MSAL.NET, car les API de plus haut niveau peuvent gérer nativement des scénarios complexes (par exemple, les utilisateurs invités, l’évaluation continue de l’accès et les jetons de preuve de possession). Les applications qui doivent accéder aux API Azure doivent utiliser Kit de développement logiciel (SDK) Azure, qui tire parti de MSAL en interne.

Le matériel suivant est pertinent si vous utilisez MSAL.NET directement.

Technologies de mise en cache disponibles

• Cache mémoire sans éviction
• Mémoire cache avec éviction
• Caches distribués et caches en mémoire combinés

Cache mémoire sans éviction

Utilisez .WithCacheOptions(CacheOptions.EnableSharedCacheOptions) lors de la création d’une application de service à service - AcquireTokenForClient qui ne cible pas plus de 100 000 locataires.

    // 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) rend le cache de jeton MSAL interne partagé entre les instances d’application cliente MSAL. Le partage d’un cache de jetons est plus rapide que l’utilisation d’une sérialisation du cache de jetons, mais le cache de jetons interne en mémoire n’a pas de stratégies d’éviction. Les jetons existants sont actualisés sur place, mais l’extraction de jetons pour différents utilisateurs, locataires et ressources augmente le cache en conséquence.

Mémoire cache avec éviction

Ajoutez une référence au package NuGet Microsoft.Identity.Web.TokenCache dans votre projet.

Le code suivant montre comment ajouter un cache en mémoire avec éviction :

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

Caches distribués

Si vous utilisez app.AddDistributedTokenCache, le cache de jeton est un adaptateur par rapport à l’implémentation de IDistributedCache .NET. Vous pouvez donc choisir entre un cache SQL Server, un cache Redis, un cache Azure Cosmos DB ou tout autre cache implémentant l’interface IDistributedCache.

À des fins de test, vous pouvez utiliser services.AddDistributedMemoryCache(), une implémentation en mémoire de IDistributedCache.

Voici le code d'un 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);
      });
     });

Voici le code d’un 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;
        };
      });
    });

Voici le code d'un 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;
        });
       });

Pour plus d’informations sur les caches distribués, consultez :

• Chiffrement du cache distribué et options avancées
• Gérer l’éviction du cache L2
• Configurer un cache Redis dans Docker
• Troubleshooting

Désactivation d’un cache de jetons hérité

MSAL dispose d’un code interne conçu spécifiquement pour interagir avec le cache de l’ancienne bibliothèque Microsoft Authentication Library (ADAL). Lorsque MSAL et ADAL ne sont pas utilisés côte à côte, le cache hérité n’est pas utilisé et le code hérité associé n’est pas nécessaire. MSAL 4.25.0 ajoute la possibilité de désactiver le code de cache ADAL hérité et d’améliorer les performances d’utilisation du cache. Pour une comparaison des performances avant et après la désactivation du cache hérité, consultez la pull request GitHub 2309.

Appelez .WithLegacyCacheCompatibility(false) sur un générateur d’applications, comme dans le code suivant.

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

Échantillons

• L’exemple suivant est une application web ASP.NET : Utilisez OpenID Connect pour connecter des utilisateurs à Plateforme d'identités Microsoft.

Dans les applications de bureau, nous vous recommandons d’utiliser le cache de jetons multiplateforme. MSAL.NET fournit le cache de jetons multiplateforme dans une bibliothèque distincte nommée Microsoft. Identity.Client.Extensions.MSAL.

Référencer le package NuGet

Ajoutez le package NuGet Microsoft.Identity.Client.Extensions.Msal à votre projet.

Configuration du cache de jetons

L’exemple suivant montre comment utiliser un cache de jetons multiplateforme :

 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 de secours en texte brut

Le cache de jetons multiplateforme vous permet de stocker des jetons non chiffrés dans un fichier texte brut restreint à la liste de contrôle d’accès. Ceci est utile dans les cas où le chiffrement au repos échoue, ce qui se produit parfois pour des raisons liées à l’environnement. Vous pouvez utiliser le mode de secours en texte brut à l’aide du modèle de code suivant :

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

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

MSAL.NET fournit un cache de jetons en mémoire par défaut. La sérialisation est fournie par défaut pour les cibles mobiles MAUI.

Si vous souhaitez écrire votre propre sérialiseur de cache de jetons, MSAL.NET fournit une sérialisation personnalisée du cache de jetons dans .NET Framework et .NET sous-plateforme Core. Les événements sont déclenchés lorsque le cache est accessible. Les applications peuvent choisir de sérialiser ou de désérialiser le cache.

Sur les applications clientes confidentielles qui gèrent les utilisateurs (applications web qui connectent des utilisateurs et appellent des API web et des API web qui appellent des API web en aval), il peut y avoir de nombreux utilisateurs. Les utilisateurs sont traités en parallèle. Pour des raisons de sécurité et de performances, nous vous recommandons de sérialiser un cache par utilisateur. Les événements de sérialisation calculent une clé de cache basée sur l’identité de l’utilisateur traité et sérialisent ou désérialisent un cache de jetons pour cet utilisateur.

N’oubliez pas que la sérialisation personnalisée n’est pas disponible sur les plateformes mobiles. MSAL définit déjà un mécanisme de sérialisation sécurisé et performant pour ces plateformes. .NET applications de bureau et .NET Core, cependant, ont des architectures variées. Et MSAL ne peut pas implémenter un mécanisme de sérialisation à usage général.

Par exemple, les sites web peuvent choisir de stocker des jetons dans un cache Redis, ou les applications de bureau peuvent stocker des jetons dans un fichier chiffré. La sérialisation n’est donc pas fournie nativement. Pour qu’une application .NET Desktop ou .NET Core dispose d’un cache de jetons persistant, personnalisez la sérialisation.

Les classes et interfaces suivantes sont utilisées dans la sérialisation du cache de jetons :

• ITokenCache définit les événements auxquels s’abonner pour les requêtes de sérialisation du cache de jetons, ainsi que les méthodes permettant de sérialiser ou de désérialiser le cache dans différents formats (MSAL 2.x et MSAL 3.x).
• TokenCacheCallback est un rappel transmis aux événements pour que vous puissiez gérer la sérialisation. Ils sont appelés avec des arguments de type TokenCacheNotificationArgs.
• TokenCacheNotificationArgs fournit uniquement la ClientId valeur de l’application et une référence à l’utilisateur pour lequel le jeton est disponible.

Les stratégies sont différentes selon que vous écrivez une sérialisation du cache de jetons pour une application cliente publique (bureau) ou une application cliente confidentielle (application web, API web, application démon).

Cache de jetons personnalisé pour une application web ou une API web (application cliente confidentielle)

Si vous souhaitez écrire votre propre sérialiseur de cache de jeton pour des applications clientes confidentielles, nous vous recommandons d’hériter de Microsoft.Identity.Web.MsalAbstractTokenCacheProvider et de remplacer les méthodes WriteCacheBytesAsync et ReadCacheBytesAsync.

Des exemples de sérialiseurs de cache de jetons sont fournis dans Microsoft. Identity.Web/TokenCacheProviders.

Cache de jetons personnalisé pour une application de bureau ou mobile (application cliente publique)

MSAL.NET v2.x et versions ultérieures fournissent plusieurs options pour sérialiser le cache de jetons d’un client public. Vous pouvez sérialiser le cache uniquement au format MSAL.NET (le cache de format unifié est commun entre MSAL et les plateformes).
La personnalisation de la sérialisation du cache de jetons pour partager l’état d’authentification unique entre ADAL.NET 3.x, ADAL.NET 5.x et MSAL.NET est expliquée dans le cadre de l’exemple suivant : active-directory-dotnet-v1-to-v2.

Sérialisation du cache de jeton simple (MSAL uniquement)

Le code suivant est un exemple d’implémentation naïve de sérialisation personnalisée d’un cache de jetons pour les applications de bureau. Ici, le cache de jetons utilisateur est un fichier dans le même dossier que l’application.

Après avoir compilé l’application, vous activez la sérialisation en appelant la méthode TokenCacheHelper.EnableSerialization() et en transmettant la propriété UserTokenCache de l’application.

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

La TokenCacheHelper classe d’assistance est définie comme suit :

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

Un sérialiseur de cache de jetons basé sur des fichiers, de qualité professionnelle, pour les applications clientes publiques (pour les applications de bureau fonctionnant sous Windows, Mac et Linux) est disponible dans la bibliothèque open source Microsoft.Identity.Client.Extensions.Msal. Vous pouvez l’inclure dans vos applications à partir du package NuGet suivant : Microsoft. Identity.Client.Extensions.Msal.