Přihlášení MSAL.NET

MSAL.NET aplikace generují zprávy protokolu, které můžou pomoct s diagnostikou problémů. Protokolování můžete nakonfigurovat pomocí několika řádků kódu a mít vlastní kontrolu nad úrovní podrobností a to, jestli se protokolují osobní a organizační data. Protokolování není ve výchozím nastavení povolené. Doporučujeme povolit protokolování MSAL, abyste uživatelům umožnili odesílat protokoly, když mají problémy s ověřováním. Všimněte si, že MSAL neukládá žádné záznamy a odesílá je do cíle zadaného v implementaci loggeru.

Note

Od MSAL.NET 4.58.0 mohou vývojáři také použít OpenTelemetry k agregaci protokolů a měření výkonu aplikace.

Úrovně protokolování

K dispozici je několik úrovní podrobností protokolování:

• LogAlways: Základní úroveň, která zahrnuje protokoly důležitých metrik stavu, které pomáhají s diagnostikou operací MSAL.
• Critical: Protokoly, které popisují neobnovitelné zhroucení aplikace nebo systému nebo katastrofické selhání vyžadující okamžitou pozornost.
• Error: Označuje, že se něco nepovedlo a vygenerovala se chyba. Používá se k ladění a identifikaci problémů.
• Warning: Zahrnuje protokoly ve scénářích, kdy nedošlo k chybě nebo selhání, ale jsou určené pro diagnostiku a určení problémů. Toto je doporučená minimální úroveň, která by měla být povolena v produkčních aplikacích.
• Informational: MSAL bude zaznamenávat události určené pro informativní účely, nikoli nutně pro ladění.
• Verbose: MSAL protokoluje úplné podrobnosti o chování knihovny. V produkčním prostředí by úroveň podrobného protokolování měla být povolena pouze dočasně, aby bylo možné shromáždit protokoly pro konkrétní účel ladění.

Osobní a organizační data

Ve výchozím nastavení protokolovací nástroj MSAL nezachytává žádná vysoce citlivá osobní ani organizační data. Knihovna nabízí možnost povolit protokolování osobních a organizačních dat, pokud se tak rozhodnete. Podrobnosti najdete v tématu Zpracování identifikovatelných osobních údajů v MSAL.NET.

Konfigurace protokolování v MSAL.NET

V MSAL se protokolování nastavuje při vytváření aplikace pomocí tvůrce WithLogging(IIdentityLogger, Boolean). Tato metoda přebírá následující parametry:

• identityLoggerje implementace protokolování používaná MSAL.NET k vytváření protokolů pro účely ladění nebo kontroly stavu. Protokoly se odesílají jenom v případě, že je povolené protokolování.
• enablePiiLogging umožňuje protokolování osobních a organizačních dat (PII), pokud je nastavená hodnota true. Ve výchozím nastavení je tento parametr nastavený na false, aby aplikace neukládala citlivá data.

IIdentityLogger – rozhraní

namespace Microsoft.IdentityModel.Abstractions
{
    public interface IIdentityLogger
    {
        //
        // Summary:
        //     Checks to see if logging is enabled at given eventLogLevel.
        //
        // Parameters:
        //   eventLogLevel:
        //     Log level of a message.
        bool IsEnabled(EventLogLevel eventLogLevel);

        //
        // Summary:
        //     Writes a log entry.
        //
        // Parameters:
        //   entry:
        //     Defines a structured message to be logged at the provided Microsoft.IdentityModel.Abstractions.LogEntry.EventLogLevel.
        void Log(LogEntry entry);
    }
}

Note

Knihovny vyšší úrovně (Microsoft.Identity.Web, Microsoft.IdentityModel) již poskytují implementace tohoto rozhraní pro různá prostředí (zejména ASP.NET Core).

Implementace IIdentityLogger

Úroveň protokolování z konfiguračního souboru

Důrazně doporučujeme nakonfigurovat kód tak, aby používal konfigurační soubor ve vašem prostředí k nastavení úrovně protokolu, protože umožní kódu změnit úroveň protokolování MSAL, aniž by bylo nutné znovu sestavit nebo restartovat aplikaci. To je důležité pro diagnostické účely, které umožňují rychle shromáždit požadované protokoly z aplikace, která je aktuálně nasazená v produkčním prostředí. Podrobné protokolování může být náročné, proto je nejlepší ve výchozím nastavení používat úroveň Informational a podrobné protokolování povolit až při výskytu problému. Příklad, jak načíst data z konfiguračního souboru bez restartování aplikace, najdete v poskytovateli konfigurace JSON.

Úroveň protokolování z proměnné prostředí

Další možností je nakonfigurovat kód tak, aby na počítači používal proměnnou prostředí, aby nastavil úroveň protokolu, protože umožní vašemu kódu změnit úroveň protokolování MSAL, aniž by bylo nutné znovu sestavit aplikaci.

Podrobnosti o dostupných úrovních protokolování naleznete v EventLogLevel.

Příklad:

class MyIdentityLogger : IIdentityLogger
{
    public EventLogLevel MinLogLevel { get; }

    public MyIdentityLogger()
    {
        //Retrieve the log level from an environment variable
        var msalEnvLogLevel = Environment.GetEnvironmentVariable("MSAL_LOG_LEVEL");

        if (Enum.TryParse(msalEnvLogLevel, out EventLogLevel msalLogLevel))
        {
            MinLogLevel = msalLogLevel;
        }
        else
        {
            //Recommended default log level
            MinLogLevel = EventLogLevel.Informational;
        }
    }

    public bool IsEnabled(EventLogLevel eventLogLevel)
    {
        return eventLogLevel <= MinLogLevel;
    }

    public void Log(LogEntry entry)
    {
        //Log Message here:
        Console.WriteLine(entry.Message);
    }
}

Pomocí MyIdentityLogger:

MyIdentityLogger myLogger = new MyIdentityLogger();

var app = ConfidentialClientApplicationBuilder
    .Create(TestConstants.ClientId)
    .WithClientSecret("secret")
    .WithLogging(myLogger, enablePiiLogging)
    .Build();

Protokolování v distribuované mezipaměti tokenů

Pokud v .NETu používáte serializátory mezipaměti tokenů z balíčku Microsoft.Identity.Web.TokenCache, můžete povolit další protokolování mezipaměti.

Chcete-li povolit protokolování distribuované mezipaměti, nastavte vlastnost MinLevel na hodnotu Debug.

     app.AddDistributedTokenCache(services =>
     {
          services.AddDistributedMemoryCache();
          services.AddLogging(configure => configure.AddConsole())
               .Configure<LoggerFilterOptions>(options => options.MinLevel = Microsoft.Extensions.Logging.LogLevel.Debug);
     });

Další podrobnosti najdete v tématu Implementace vlastního zprostředkovatele protokolování .

Identifikátor korelace

Protokoly událostí pomáhají pochopit chování knihovny MSAL na klientské straně. Aby tým porozuměl tomu, co se děje na straně služby, potřebuje ID korelace. Toto ID trasuje požadavek na ověření prostřednictvím různých back-endových služeb.

ID korelace lze získat třemi způsoby:

1. Z úspěšného výsledku ověření: AuthenticationResult.CorrelationId.
2. Z výjimky v rámci služby: MsalException.CorrelationId.
3. Předáním vlastního identifikátoru korelace do WithCorrelationId(Guid) při vytváření žádosti o token

Při zadávání vlastního ID korelace použijte pro každý požadavek jinou hodnotu ID. Nepoužívejte konstantu, protože nebudeme moct rozlišovat mezi požadavky.

Sledování sítě

Important

Trasování sítě obvykle obsahuje identifikovatelné osobní údaje a přihlašovací údaje. Odstraňte z protokolů všechny citlivé údaje před jejich zveřejněním na GitHubu.

V případech, kdy podrobné protokoly neposkytují dostatek informací, můžete pomocí nástrojů, jako je Fiddler nebo mitmproxy, pořídit záznam síťové komunikace. Nástroj, který si zvolíte, můžete nakonfigurovat tak, aby byl místním proxy serverem a přijímal provoz ze zařízení v místní síti, což vám umožní zachytit trasování z jiných zařízení, jako jsou iPhone nebo telefony s Androidem. Před zachytáváním protokolů může být vyžadována konfigurace specifická pro konkrétní platformu.

Pokud takový nástroj není možné použít, můžete upravit HttpClient, který používá MSAL k protokolování provozu HTTP. Pro referenci viz tuto vlastní HttpClient implementaci s protokolováním.

Warning

Tento klient by se neměl používat v produkčním prostředí a pouze pro protokolování.

Vlastní HttpClient můžete přidat takto:

var msalPublicClient = PublicClientApplicationBuilder
       .Create(ClientId)
       .WithHttpClientFactory(new HttpSnifferClientFactory())
       .Build();

Trasování sítě při používání WAM

Ke shromáždění síťových tras pro Web Account Manager (WAM) ve Windows pomocí Fiddleru je potřeba provést několik dalších kroků.

1. Povolte ve Fiddleru zpětnou smyčku pro AppContainer kliknutím na WinConfig, výběrem možnosti Exempt All a uložením změn.

2. Povolte dešifrování HTTPS, ale vylučte ADFS (msft.sts.microsoft.com) z dešifrování HTTPS: