Serialização da cache de tokens

O pacote NuGet Microsoft.Identity.Web.TokenCache fornece serialização da cache de tokens na biblioteca Microsoft.Identity.Web. A biblioteca oferece integração tanto com o ASP.NET Core como com o ASP.NET Classic, e as suas abstrações podem ser usadas para gerar outros frameworks de aplicações web ou APIs.

Cache de token em memória

Aqui está um exemplo de código que utiliza a cache em memória no método ConfigureServices da classe Startup numa aplicação 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 é adequado para produção se pedir tokens exclusivos da aplicação. Se utilizar tokens de utilizador, considere utilizar uma memória cache de tokens distribuída.

O código de configuração da cache de token é semelhante entre as aplicações web e as APIs web do ASP.NET Core.

Caches de tokens distribuídos

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

// 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:

• Encriptação de cache distribuída e outras opções avançadas
• Gerir a eliminação da cache L2
• Configurar uma cache Redis no Docker
• Troubleshooting

A utilização da cache distribuída está presente no tutorial da aplicação web ASP.NET Core, na cache de tokens da fase 2-2.

Recomenda-se que clientes confidenciais .NET utilizem a Microsoft. Identity.Web, que se baseia no MSAL.NET, pois APIs de nível superior conseguem lidar com cenários complexos logo de início (por exemplo, utilizadores convidados, Avaliação de Acesso Contínuo, tokens de Prova de Posse). As aplicações que precisam de aceder às APIs do Azure devem usar o SDK do Azure, que aproveita internamente o MSAL.

O seguinte material é relevante se estiver a usar o MSAL.NET diretamente.

Tecnologias de cache disponíveis

• Cache de memória sem expulsão
• Cache de memória com eliminação
• Caches distribuídas e de memória combinadas

Cache de memória sem expulsão

Use .WithCacheOptions(CacheOptions.EnableSharedCacheOptions) ao criar uma aplicação de serviço para serviço — AcquireTokenForClient que não se destina a muitos (mais de 100.000) inquilinos.

    // 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) faz com que a cache interna dos tokens MSAL seja partilhada entre instâncias de aplicação cliente MSAL. Partilhar uma cache de token é mais rápido do que usar qualquer serialização de cache de token, mas a cache interna de tokens em memória não tem políticas de expulsão. Os tokens existentes são atualizados no próprio local, mas obter tokens para diferentes utilizadores, locatários e recursos faz com que a cache aumente em conformidade.

Cache de memória com remoção

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

O seguinte código mostra como adicionar uma cache em memória com expulsã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ídas

Se usares app.AddDistributedTokenCache, a cache de tokens é um adaptador contra a implementação .NETIDistributedCache. Assim, pode escolher entre uma cache SQL Server, uma cache Redis, uma cache Azure Cosmos DB, ou qualquer outra cache que implemente a interface IDistributedCache.

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

Aqui está o código para uma cache do 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);
      });
     });

Aqui está o código para uma 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;
        };
      });
    });

Aqui está o código para uma cache do 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 mais informações sobre caches distribuídas, veja:

• Encriptação de cache distribuída e opções avançadas
• Gerir a eliminação da cache L2
• Configurar uma cache Redis no Docker
• Troubleshooting

Desativar uma cache legada de tokens

O MSAL tem algum código interno especificamente para permitir a interação com a cache legada da Biblioteca de Autenticação da Microsoft (ADAL). Quando o MSAL e o ADAL não são usados lado a lado, a cache legada não é usada e o código legado relacionado torna-se desnecessário. O MSAL 4.25.0 adiciona a capacidade de desativar o código de cache ADAL legado e melhorar o desempenho no uso da cache. Para uma comparação de desempenho antes e depois de desativar a cache antiga, consulte o pull request 2309 do GitHub.

Chame .WithLegacyCacheCompatibility(false) num construtor de aplicações, como no código seguinte.

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

Samples

• O exemplo seguinte é uma aplicação web ASP.NET: Use o OpenID Connect para iniciar sessão de utilizadores na plataforma de identidades da Microsoft.

Em aplicações de ambiente de trabalho, recomendamos que utilize a cache de tokens multiplataforma. O MSAL.NET fornece a cache de tokens multiplataforma numa biblioteca separada chamada Microsoft. Identidade.Cliente.Extensões.MSAL.

Referência ao pacote NuGet

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

Configuração da cache de tokens

O exemplo seguinte mostra como usar uma cache de tokens 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 retenção em texto simples

A cache de tokens multiplataforma permite-lhe armazenar tokens não encriptados num ficheiro de texto simples restrito por ACL. Isto é útil em casos em que a encriptação em repouso falha, o que ocasionalmente acontece por razões relacionadas com o ambiente. Pode usar o modo de recurso em texto simples utilizando 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);

O MSAL.NET fornece, por defeito, uma cache de tokens em memória. A serialização está disponível por predefinição para as plataformas móveis do MAUI.

Se quiser escrever o seu próprio serializador de cache de tokens, o MSAL.NET oferece serialização personalizada da cache de tokens nas subplataformas .NET Framework e .NET Core. Os eventos são disparados quando a cache é acedida. As aplicações podem escolher se serializam ou desserializam a cache.

Em aplicações cliente confidenciais que lidam com utilizadores (aplicações Web que iniciam sessão de utilizadores e chamam APIs Web, e APIs Web que chamam APIs Web a jusante), podem existir muitos utilizadores. Os utilizadores 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 utilizador processado e serializam ou desserializam uma cache de token para esse utilizador.

Lembra-te, a serialização personalizada não está disponível nas plataformas móveis. O MSAL já define um mecanismo de serialização seguro e eficaz para estas plataformas. No entanto, as aplicações de ambiente de trabalho .NET e .NET Core têm arquiteturas variadas. E o MSAL não pode implementar um mecanismo de serialização de uso geral.

Por exemplo, os websites podem optar por armazenar tokens numa cache Ridis, ou aplicações de ambiente de trabalho podem armazenar tokens num ficheiro encriptado. Portanto, a serialização não é fornecida logo à partida. Para ter uma aplicação de cache de token persistente no ambiente de trabalho .NET ou .NET Core, personalize a serialização.

As seguintes classes e interfaces são usadas na serialização da cache de tokens:

• ITokenCache define eventos para a subscrição de pedidos de serialização da cache de tokens e métodos para serializar ou desserializar a cache em vários formatos (MSAL 2.x e MSAL 3.x).
• TokenCacheCallback é um callback passado aos eventos para que possas gerir a serialização. São chamados com argumentos do tipo TokenCacheNotificationArgs.
• TokenCacheNotificationArgs apenas fornece o ClientId valor da aplicação e uma referência ao utilizador para o qual o token está disponível.

As estratégias variam dependendo se está a escrever uma serialização de cache token para uma aplicação cliente pública (desktop) ou para uma aplicação cliente confidencial (web app, web API, daemon app).

Cache personalizada de tokens para uma aplicação web ou API web (aplicação cliente confidencial)

Se quiser escrever o seu próprio serializador de cache de tokens para aplicações cliente confidenciais, recomendamos que herde de Microsoft.Identity.Web.MsalAbstractTokenCacheProvider e substitua os métodos WriteCacheBytesAsync e ReadCacheBytesAsync.

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

Cache personalizada de tokens para uma aplicação de ambiente de trabalho ou móvel (aplicação cliente pública)

O MSAL.NET v2.x e versões posteriores oferecem várias opções para serializar a cache de token de um cliente público. Pode serializar a memória cache apenas para o formato MSAL.NET (a memória cache em formato unificado é comum ao MSAL e às plataformas).
A personalização da serialização da cache de token para partilhar o estado de assinatura única entre ADAL.NET 3.x, ADAL.NET 5.x e MSAL.NET é explicada em parte do seguinte exemplo: active-directory-dotnet-v1-to-v2.

Serialização simples da cache de token (apenas MSAL)

O código seguinte é um exemplo de uma implementação ingénua de serialização personalizada de uma cache de token para aplicações de ambiente de trabalho. Aqui, a cache de token de utilizador é um ficheiro na mesma pasta que a aplicação.

Depois de compilar a aplicação, ativa a serialização chamando o método TokenCacheHelper.EnableSerialization() e passando a propriedade UserTokenCache da aplicação.

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

Está disponível na biblioteca de código aberto Microsoft.Identity.Client.Extensions.Msal um serializador de cache de tokens baseado em ficheiros, de nível de produção, para aplicações cliente públicas (para aplicações de ambiente de trabalho executadas em Windows, Mac e Linux). Pode incluí-lo nas suas aplicações a partir do pacote NuGet seguinte: Microsoft.Identity.Client.Extensions.Msal.