Serializace mezipaměti tokenů v MSAL.NET

Po získání tokenu hoknihovna MSAL (Microsoft Authentication Library) ukládá do mezipaměti. Veřejné klientské aplikace (desktopové/mobilní aplikace) by se měly před získáním tokenu jinou metodou pokusit získat token z mezipaměti. Metody získávání důvěrných klientských aplikací spravují mezipaměť sami. Tento článek popisuje výchozí a vlastní serializaci mezipaměti tokenů v MSAL.NET.

Rychlý souhrn

Doporučení je následující:

Knihovna Microsoft.Identity.Web poskytuje balíček NuGet Microsoft.Identity.Web.TokenCache obsahující serializaci mezipaměti tokenů:

Extension – metoda Description
AddInMemoryTokenCaches Serializace mezipaměti tokenu paměti. Tato implementace je skvělá v ukázkách a pro aplikace démona (z aplikace do tokenů aplikace / AcquireTokenForClient ). Je také vhodné v produkčních aplikacích za předpokladu, že vám nevadí, pokud dojde ke ztrátě mezipaměti tokenů při restartování webové aplikace. Počínaje microsoft.Identity.Web 1.19.0 je MSAL.Net nakonfigurovaný tak, aby ve všech instancích aplikace používá statickou (sdílenou) mezipaměť a je rychlejší než jiné mechanismy ukládání do mezipaměti, ale neumožňuje řídit velikost mezipaměti.
AddSessionTokenCaches Mezipaměť tokenů je svázaná s uživatelskou relací. Tato možnost není ideální, pokud token ID obsahuje mnoho deklarací identity, protože soubor cookie by byl příliš velký.
AddDistributedTokenCaches Mezipaměť tokenů je adaptér proti implementaci ASP.NET Core, takže můžete vybírat mezi distribuovanou mezipamětí IDistributedCache paměti, mezipamětí Redis, distribuovanou mezipamětí NCache nebo mezipamětí SQL Server mezipamětí. Podrobnosti o IDistributedCache implementacích najdete v tématu Distribuovaná mezipaměť paměti.

V mezipaměti tokenů paměti

Tady je příklad kódu, který používá mezipaměť v paměti v metodě ConfigureServices třídy Startup v ASP.NET Core aplikaci:

#using Microsoft.Identity.Web
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 je vhodné v produkčním prostředí, pokud si vyžádáte pouze tokeny aplikace. Pokud používáte tokeny uživatelů, měli byste zvážit distribuovanou mezipaměť tokenů.

Z hlediska mezipaměti by byl kód podobný ve webových aplikacích ASP.NET Core webových rozhraních API.

Distribuované mezipaměti tokenů

Tady jsou příklady možných distribuovaných mezipamětí:

// 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 => 
  {
    // You can disable the L1 cache if you wish. For instance in some cases where you share the L2 cache
    // between instances of your apps.
    options.DisableL1Cache = false;
    
    // Or limit the memory (by default this is 500 Mb)
    options.SizeLimit = 500 * 1024 * 1024,   // 500 Mb

    // You can choose if you encrypt or not 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
// -----------------------------------------------------

// For instance the distributed in memory cache (not cleared when you stop the app)
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 a 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;
});

Další informace naleznete v tématu:

Využití distribuované mezipaměti je součástí kurzu ASP.NET Core aplikace ve fázi 2–2 mezipaměti tokenů.

Monitorování poměru přístupů do mezipaměti a výkonu mezipaměti

MSAL zpřístupňuje důležité metriky jako součást objektu AuthenticationResult. AuthenticationResultMetadata . Tyto metriky můžete protokolovat k vyhodnocení stavu aplikace.

Metric Význam Kdy spustit alarm?
DurationTotalInMs Celkový čas strávený v MSAL, včetně síťových volání a mezipaměti Poplach při celkové vysoké latenci (> 1 s). Hodnota závisí na zdroji tokenu. Z mezipaměti: jeden přístup k mezipaměti. z AAD: dvě přístupy do mezipaměti a jedno volání HTTP. První volání (za proces) bude trvat déle, protože jedno další volání HTTP.
DurationInCacheInMs Doba strávená načítáním a uložením mezipaměti tokenů, kterou vlastní vývojář aplikace (například Save to Redis). Alarmy v špičkách.
DurationInHttpInMs Čas strávený prováděním volání HTTP AAD. Alarmy v špičkách.
TokenSource Určuje zdroj tokenu. Tokeny se načítají z mezipaměti mnohem rychleji (například ~ 100 ms oproti ~ 700 MS). Dá se použít k monitorování a alarmu poměru přístupů do mezipaměti. Použijte s DurationTotalInMs .
CacheRefreshReason Určuje důvod načtení přístupového tokenu od poskytovatele identity. Použijte s TokenSource .

Další kroky

Následující ukázky ilustrují serializaci mezipaměti tokenů.

Ukázka Platforma Description
Active-Directory-dotnet-Desktop-MSGraph-v2 Plocha (WPF) aplikace Windows Desktop .net (WPF) volá rozhraní API Microsoft Graph. Diagram znázorňuje topologii s desktopovou aplikací WPF TodoListClient do služby Azure AD Díky interaktivnímu získání tokenu a k Microsoft Graph.
Active-Directory-dotnet-v1-to-v2 Plocha (konzola) sada Visual Studioch řešení ilustrující migraci aplikací Azure AD v 1.0 (pomocí ADAL.NET) pro Microsoft identity platform aplikací (pomocí MSAL.NET). Konkrétně se podívejte na článek Migrace mezipaměti tokenů a Důvěrná mezipaměť tokenů klienta.
ms-identity-aspnet-webapp-openidconnect ASP.NET (net472) Příklad serializace mezipaměti tokenů v ASP.NET MVC (pomocí MSAL.NET). Viz zejména MsalAppBuilder.