Serialização de cache de token

O pacote NuGet Microsoft.Identity.Web.TokenCache fornece serialização do cache de tokens na biblioteca Microsoft.Identity.Web. A biblioteca fornece integração com ASP.NET Core e ASP.NET Clássico, e suas abstrações podem ser usadas para impulsionar outras estruturas de API ou aplicativo Web.

Cache de token na memória

Aqui está um exemplo de código que usa o cache na memória no método ConfigureServices da classe Startup em um aplicativo 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 será adequado em produção se você solicitar tokens somente de aplicativo. Se você usar tokens de usuário, considere usar um cache de token distribuído.

O código de configuração do cache de token é semelhante entre aplicativos Web ASP.NET Core e APIs Web.

Caches distribuídos de token

Aqui estão exemplos de possíveis caches distribuídos:

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

Para obter mais informações, consulte:

• Criptografia de cache distribuído e outras opções avançadas
• Manipular remoção de cache L2
• Configurar um cache Redis no Docker
• Solução de problemas

O uso do cache distribuído é destacado no tutorial do aplicativo Web ASP.NET Core, no cache de token da fase 2-2.

Recomenda-se que clientes confidenciais .NET usem Microsoft.Identity.Web, que se baseia em MSAL.NET, pois APIs de nível superior conseguem lidar nativamente com cenários complexos (por exemplo, usuários convidados, Avaliação Contínua de Acesso e tokens de prova de posse). Os aplicativos que precisam acessar Azure APIs devem usar SDK do Azure, que aproveita a MSAL internamente.

O material a seguir será relevante se você estiver usando MSAL.NET diretamente.

Tecnologias de cache disponíveis

• Cache na memória sem remoção
• Cache na memória com remoção
• Caches distribuídos e de memória combinados

Cache na memória sem remoção

Use .WithCacheOptions(CacheOptions.EnableSharedCacheOptions) ao criar um aplicativo serviço a serviço - AcquireTokenForClient que não tem como destino muitos (mais de 100.000) locatários.

    // 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) torna o cache interno de tokens do MSAL compartilhado entre instâncias do aplicativo cliente MSAL. O compartilhamento de um cache de token é mais rápido do que usar qualquer serialização de cache de token, mas o cache de token interno na memória não tem políticas de redução. Os tokens existentes são atualizados no local, mas a busca de tokens para diferentes usuários, locatários e recursos faz com que o cache cresça adequadamente.

Cache na memória com remoção

Adicione uma referência ao pacote NuGet Microsoft.Identity.Web.TokenCache ao seu projeto.

O código a seguir mostra como adicionar um cache na memória com remoção:

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ídos

Se você usar app.AddDistributedTokenCache, o cache de token é um adaptador em relação à implementação IDistributedCache .NET. Portanto, você pode escolher entre um cache SQL Server, um cache Redis, um cache Azure Cosmos DB ou qualquer outro cache que implemente a interface IDistributedCache.

Para fins de teste, você pode usar services.AddDistributedMemoryCache(), uma implementação em memória de IDistributedCache.

Este é o código para um cache de 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);
      });
     });

Este é o código para um 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;
        };
      });
    });

Este é o código para um cache de 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;
        });
       });

Para obter mais informações sobre caches distribuídos, consulte:

• Criptografia de cache distribuído e opções avançadas
• Manipular remoção de cache L2
• Configurar um cache Redis no Docker
• Solução de problemas

Desabilitando um cache de token legado

O MSAL tem algum código interno especificamente para permitir a interação com o cache herdado da Biblioteca do Microsoft Authenticator (ADAL). Quando MSAL e ADAL não são usados lado a lado, o cache herdado não é usado e o código herdado relacionado é desnecessário. A MSAL 4.25.0 adiciona a capacidade de desabilitar o código de cache ADAL herdado e melhorar o desempenho do uso do cache. Para obter uma comparação de desempenho antes e depois de desabilitar o cache herdado, consulte GitHub solicitação de pull 2309.

Chame .WithLegacyCacheCompatibility(false) em um construtor de aplicativos, como no código a seguir.

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

Exemplos

• O exemplo a seguir é um aplicativo Web ASP.NET: use o OpenID Connect para conectar usuários para plataforma de identidade da Microsoft.

Em aplicativos para desktop, recomendamos que você use o cache de tokens multiplataforma. MSAL.NET fornece o cache de token multiplataforma em uma biblioteca separada chamada Microsoft. Identity.Client.Extensions.MSAL.

Referência ao pacote NuGet

Adicione o pacote NuGet Microsoft.Identity.Client.Extensions.Msal ao seu projeto.

Configurando o cache de token

O exemplo a seguir mostra como usar um cache de token multiplataforma:

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

Modo de fallback de texto sem formatação

O cache de tokens multiplataforma permite armazenar tokens não criptografados em um arquivo de texto simples com restrição de ACL. Isso é útil nos casos em que a criptografia em repouso falha, o que ocorre ocassionalmente devido a motivos relacionados ao ambiente. Você pode usar o modo de fallback de texto sem formatação usando o seguinte padrão de código:

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

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

MSAL.NET fornece um cache de token na memória por padrão. A serialização está disponível por padrão para os destinos móveis do MAUI.

Se você quiser escrever seu próprio serializador de cache de tokens, o MSAL.NET fornece serialização personalizada do cache de tokens nas subplataformas .NET Framework e .NET Core. Os eventos são acionados quando o cache é acessado. Os aplicativos podem escolher se deseja serializar ou desserializar o cache.

Em aplicativos cliente confidenciais que manipulam usuários (aplicativos Web que conectam usuários e chamam APIs Web e APIs Web que chamam APIs Web downstream), pode haver muitos usuários. Os usuários são processados em paralelo. Por motivos de segurança e desempenho, nossa recomendação é serializar um cache por usuário. Os eventos de serialização calculam uma chave de cache com base na identidade do usuário processado e serializam ou desserializam um cache de token para esse usuário.

Lembre-se de que a serialização personalizada não está disponível em plataformas móveis. A MSAL já define um mecanismo de serialização seguro e com desempenho para essas plataformas. .NET desktop e aplicativos .NET Core, no entanto, têm arquiteturas variadas. E a MSAL não pode implementar um mecanismo de serialização de uso geral.

Por exemplo, os sites podem optar por armazenar tokens em um cache Redis ou os aplicativos da área de trabalho podem armazenar tokens em um arquivo criptografado. Portanto, a serialização não é fornecida pronta para uso. Para ter um aplicativo de cache de token persistente em .NET desktop ou .NET Core, personalize a serialização.

As seguintes classes e interfaces são usadas na serialização do cache de token:

• ITokenCache define eventos para assinar as solicitações de serialização de cache de tokens e métodos para serializar ou desserializar o cache em vários formatos (MSAL 2.x e MSAL 3.x).
• TokenCacheCallback é um retorno de chamada passado aos eventos para permitir que você controle a serialização. Eles são chamados com argumentos do tipo TokenCacheNotificationArgs.
• TokenCacheNotificationArgs fornece apenas o ClientId valor do aplicativo e uma referência ao usuário para o qual o token está disponível.

As estratégias são diferentes dependendo se você está escrevendo uma serialização de cache de token para um aplicativo cliente público (área de trabalho) ou um aplicativo cliente confidencial (aplicativo Web, API Web, aplicativo daemon).

Cache de token personalizado para um aplicativo Web ou API Web (aplicativo cliente confidencial)

Se quiser gravar seu próprio serializador de cache de token para aplicativos cliente confidenciais, recomendamos que você herde de Microsoft.Identity.Web.MsalAbstractTokenCacheProvider e substitua os métodos WriteCacheBytesAsync e ReadCacheBytesAsync.

Exemplos de serializadores de cache de token são fornecidos em Microsoft. Identity.Web/TokenCacheProviders.

Cache de token personalizado para um aplicativo móvel ou desktop (aplicativo cliente público)

MSAL.NET v2.x e versões posteriores fornecem várias opções para serializar o cache de token de um cliente público. Você pode serializar o cache apenas para o formato MSAL.NET (o cache de formato unificado é comum entre a MSAL e as plataformas).
A personalização da serialização do cache de token para compartilhar o estado de logon único entre ADAL.NET 3.x, ADAL.NET 5.x e MSAL.NET é parcialmente explicado no exemplo a seguir: active-directory-dotnet-v1-to-v2.

Serialização de cache de token simples (somente MSAL)

O código a seguir é um exemplo de uma implementação ingênua da serialização personalizada de um cache de token para aplicativos da área de trabalho. Aqui, o cache de token de usuário é um arquivo na mesma pasta que o aplicativo.

Depois de criar o aplicativo, você habilita a serialização chamando o método TokenCacheHelper.EnableSerialization() e passando a propriedade UserTokenCache do aplicativo.

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

A TokenCacheHelper classe auxiliar é definida como:

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

Um serializador de cache de token baseado em arquivo com qualidade do produto para aplicativos cliente públicos (para aplicativos da área de trabalho em execução no Windows, Mac e Linux) está disponível na biblioteca de código aberto Microsoft.Identity.Client.Extensions.Msal. Você pode incluí-lo em seus aplicativos do seguinte pacote NuGet: Microsoft. Identity.Client.Extensions.Msal.