Serializzazione della cache dei token

Il pacchetto NuGet Microsoft.Identity.Web.TokenCache fornisce la serializzazione della cache dei token all'interno della libreria Microsoft.Identity.Web. La libreria fornisce l'integrazione con ASP.NET Core e ASP.NET classico e le relative astrazioni possono essere usate per guidare altre app Web o framework API.

Cache dei token in memoria

Ecco un esempio di codice che usa la cache in memoria nel metodo ConfigureServices della classe Startup in un'applicazione 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 è adatto nell'ambiente di produzione se si richiedono token solo app. Se si usano token utente, è consigliabile usare una cache dei token distribuiti.

Il codice di configurazione della cache dei token è simile tra ASP.NET Core app Web e API Web.

Cache dei token distribuiti

Ecco alcuni esempi di possibili cache distribuite:

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

Per ulteriori informazioni consulta:

• Crittografia cache distribuita e altre opzioni avanzate
• Gestire la rimozione della cache L2
• Configurare una cache Redis in Docker
• Risoluzione dei problemi

L'uso della cache distribuita viene illustrato nel tutorial dell'app web ASP.NET Core nella fase 2-2 della cache dei token.

Per i client riservati .NET, è consigliabile usare Microsoft.Identity.Web, che si basa su MSAL.NET, poiché le API di livello superiore sono in grado di gestire scenari complessi in modo immediato (ad esempio utenti guest, Valutazione continua dell'accesso, token Proof-of-Possession). Le applicazioni che devono accedere alle API di Azure devono usare Azure SDK, che sfrutta internamente MSAL.

Il materiale seguente è rilevante se si usa direttamente MSAL.NET.

Tecnologie di memorizzazione nella cache disponibili

• Cache di memoria senza rimozione
• Cache di memoria con rimozione
• Cache distribuite e di memoria combinate

Cache di memoria senza rimozione

Usare .WithCacheOptions(CacheOptions.EnableSharedCacheOptions) quando si crea un'applicazione da servizio a servizio AcquireTokenForClient che non è destinata a molti tenant (più di 100.000).

    // 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) rende condivisa la cache dei token MSAL interna tra le istanze dell'applicazione client MSAL. La condivisione di una cache dei token è più veloce rispetto all'uso di qualsiasi serializzazione della cache dei token, ma la cache interna dei token in memoria non dispone di criteri di rimozione. I token esistenti vengono aggiornati direttamente nella cache, ma il recupero di token per utenti, tenant e risorse differenti fa crescere di conseguenza la cache.

Cache di memoria con rimozione

Aggiungi al progetto il pacchetto NuGet Microsoft.Identity.Web.TokenCache.

Il codice seguente illustra come aggiungere una cache in memoria con rimozione:

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 distribuite

Se si usa app.AddDistributedTokenCache, la cache dei token è un adattatore rispetto all'implementazione di .NETIDistributedCache. È quindi possibile scegliere tra una cache SQL Server, una cache Redis, una cache Azure Cosmos DB o qualsiasi altra cache che implementa l'interfaccia IDistributedCache.

A scopo di test, è possibile usare services.AddDistributedMemoryCache(), un'implementazione in memoria di IDistributedCache.

Ecco il codice per una 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);
      });
     });

Ecco il codice per una 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;
        };
      });
    });

Ecco il codice per una 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;
        });
       });

Per altre informazioni sulle cache distribuite, vedere:

• Crittografia della cache distribuita e opzioni avanzate
• Gestire la rimozione della cache L2
• Configurare una cache Redis in Docker
• Risoluzione dei problemi

Disabilitazione di una cache dei token legacy

MSAL include codice interno specifico per abilitare l'interazione con la cache di Libreria di Autenticazione Microsoft legacy (ADAL). Quando MSAL e ADAL non vengono usati side-by-side, la cache legacy non viene usata e il codice legacy correlato non è necessario. MSAL 4.25.0 aggiunge la possibilità di disabilitare il codice della cache ADAL legacy e migliorare le prestazioni di utilizzo della cache. Per un confronto delle prestazioni prima e dopo la disabilitazione della cache legacy, vedere GitHub richiesta pull 2309.

Chiamare .WithLegacyCacheCompatibility(false) su un generatore di applicazioni come il codice seguente.

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

Esempi

• L'esempio seguente è un'app Web ASP.NET: Usare OpenID Connect per consentire agli utenti di accedere alla piattaforma di identità Microsoft.

Nelle applicazioni desktop è consigliabile usare la cache dei token multipiattaforma. MSAL.NET fornisce la cache dei token multipiattaforma in una libreria separata denominata Microsoft. Identity.Client.Extensions.MSAL.

Riferimento al pacchetto NuGet

Aggiungi il pacchetto NuGet Microsoft.Identity.Client.Extensions.Msal al tuo progetto.

Configurazione della cache dei token

L'esempio seguente illustra come usare una cache di token multipiattaforma:

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

Modalità di fallback in testo normale

La cache dei token multipiattaforma consente di archiviare token non crittografati in un file di testo normale con restrizioni ACL. Ciò è utile nei casi in cui la crittografia dei dati a riposo non riesce, cosa che occasionalmente accade per motivi legati all'ambiente. È possibile usare la modalità di fallback di testo normale usando il modello di codice seguente:

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

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

MSAL.NET fornisce una cache dei token in memoria per impostazione predefinita. La serializzazione è disponibile per impostazione predefinita per i target mobili di MAUI.

Se si vuole scrivere un serializzatore di cache dei token personalizzato, MSAL.NET fornisce la serializzazione della cache dei token personalizzata in .NET Framework e .NET sottopiattaforme Core. Gli eventi vengono attivati quando si accede alla cache. Le app possono scegliere se serializzare o deserializzare la cache.

Nelle applicazioni client confidenziali che gestiscono gli utenti (app Web che consentono agli utenti di accedere e chiamano API Web, e API Web che chiamano API Web downstream), possono esserci numerosi utenti. Gli utenti vengono elaborati in parallelo. Per motivi di sicurezza e prestazioni, è consigliabile serializzare una cache per utente. Gli eventi di serializzazione calcolano una chiave della cache in base all'identità dell'utente elaborato e serializzano o deserializzano una cache dei token per tale utente.

Tenere presente che la serializzazione personalizzata non è disponibile nelle piattaforme per dispositivi mobili. MSAL definisce già un meccanismo di serializzazione sicuro ed efficiente per queste piattaforme. .NET applicazioni desktop e .NET Core, tuttavia, hanno architetture diverse. E MSAL non può implementare un meccanismo di serializzazione per utilizzo generico.

Ad esempio, i siti Web potrebbero scegliere di archiviare i token in una cache Redis o le app desktop potrebbero archiviare i token in un file crittografato. Quindi la serializzazione non viene fornita come predefinita. Per avere un'applicazione cache dei token persistente in .NET desktop o .NET Core, personalizzare la serializzazione.

Le classi e le interfacce seguenti vengono usate nella serializzazione della cache dei token:

• ITokenCache definisce gli eventi a cui sottoscriversi per le richieste di serializzazione della cache dei token e i metodi per serializzare o deserializzare la cache in diversi formati (MSAL 2.x e MSAL 3.x).
• TokenCacheCallback è un callback passato agli eventi in modo da poter gestire la serializzazione. Vengono chiamati con argomenti di tipo TokenCacheNotificationArgs.
• TokenCacheNotificationArgs fornisce solo il ClientId valore dell'applicazione e un riferimento all'utente per il quale è disponibile il token.

Le strategie sono diverse a seconda che si stia scrivendo una serializzazione della cache dei token per un'applicazione client pubblica (desktop) o un'applicazione client riservata (app Web, API Web, app daemon).

Cache dei token personalizzata per un'app Web o un'API Web (applicazione client riservata)

Se si desidera scrivere un serializzatore personalizzato della cache dei token per applicazioni client confidenziali, è consigliato ereditare da Microsoft.Identity.Web.MsalAbstractTokenCacheProvider e sostituire i metodi WriteCacheBytesAsync e ReadCacheBytesAsync.

Esempi di serializzatori di cache dei token sono disponibili in Microsoft. Identity.Web/TokenCacheProviders.

Cache dei token personalizzata per un'app desktop o per dispositivi mobili (applicazione client pubblica)

MSAL.NET v2.x e versioni successive offrono diverse opzioni per serializzare la cache dei token di un client pubblico. È possibile serializzare la cache solo nel formato MSAL.NET (la cache di formato unificato è comune in MSAL e nelle piattaforme).
La personalizzazione della serializzazione della cache dei token per condividere lo stato di single sign-on tra ADAL.NET 3.x, ADAL.NET 5.x e MSAL.NET è spiegata in una parte del seguente esempio: active-directory-dotnet-v1-to-v2.

Serializzazione semplice della cache dei token (solo MSAL)

Il codice seguente è un esempio di implementazione ingenua della serializzazione personalizzata di una cache dei token per le applicazioni desktop. In questo caso, la cache dei token utente è un file nella stessa cartella dell'applicazione.

Dopo aver compilato l'applicazione, si abilita la serializzazione chiamando il metodo TokenCacheHelper.EnableSerialization() e passando la proprietà UserTokenCache dell'applicazione.

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

La TokenCacheHelper classe helper è definita come:

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 serializzatore della cache dei token basato su file, di livello produttivo, per applicazioni client pubbliche (per applicazioni desktop in esecuzione su Windows, Mac e Linux) è disponibile nella libreria open source Microsoft.Identity.Client.Extensions.Msal. È possibile includerlo nelle applicazioni dal pacchetto NuGet seguente: Microsoft. Identity.Client.Extensions.Msal.