Logga in MSAL.NET

MSAL.NET appar genererar loggmeddelanden som kan hjälpa dig att diagnostisera problem. Du kan konfigurera loggning med några rader kod och ha anpassad kontroll över detaljnivån och om personliga data och organisationsdata loggas eller inte. Loggning är inte aktiverat som standard. Vi rekommenderar att du aktiverar MSAL-loggning så att användarna kan skicka loggar när de har autentiseringsproblem. Observera att MSAL inte lagrar några loggar och skickar loggar till målet som anges i loggimplementeringen.

Loggningsnivåer

Det finns flera nivåer av loggningsinformation:

• LogAlways: Basnivå som innehåller loggar med viktiga hälsomått som hjälper dig med diagnostik för MSAL-åtgärder.
• Critical: Loggar som beskriver ett program eller en systemkrasch som inte kan återställas, eller ett oåterkalleligt fel som kräver omedelbar uppmärksamhet.
• Error: Anger att något har gått fel och att ett fel har genererats. Används för att felsöka och identifiera problem.
• Warning: Innehåller loggar i scenarier där det inte nödvändigtvis har inträffat ett fel eller problem, utan är avsedda för diagnostik och för att identifiera problem. Det här är den rekommenderade miniminivån som ska aktiveras i produktionsappar.
• Informational: MSAL loggar händelser som är avsedda för informationsändamål, inte nödvändigtvis avsedda för felsökning.
• Verbose: MSAL loggar fullständig information om bibliotekets beteende. I produktionsmiljön bör utförlig nivå endast aktiveras tillfälligt för att samla in loggar för ett specifikt felsökningssyfte.

Personliga och organisatoriska data

Som standard samlar MSAL-loggaren inte in några mycket känsliga personliga data eller organisationsdata. Biblioteket ger möjlighet att aktivera loggning av personliga data och organisationsdata om du bestämmer dig för att göra det. Mer information finns i Hantera personligt identifierbar information i MSAL.NET.

Konfigurera loggning i MSAL.NET

I MSAL ställs loggningen in när programmet skapas med hjälp av byggaren WithLogging(IIdentityLogger, Boolean). Den här metoden tar följande parametrar:

• identityLoggerär loggningsimplementeringen som används av MSAL.NET för att skapa loggar för felsökning eller hälsokontroll. Loggar skickas endast om loggning är aktiverat.
• enablePiiLogging aktiverar loggning av personliga data och organisationsdata (PII) om de är inställda på true. Som standard är den här parametern inställd på false, så att programmet inte loggar känsliga data.

IIdentityLogger-gränssnitt

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

implementering av IIdentityLogger

Loggnivå från en konfigurationsfil

Vi rekommenderar starkt att du konfigurerar koden så att den använder en konfigurationsfil i din miljö för att ange loggnivån eftersom den gör att koden kan ändra MSAL-loggningsnivån utan att behöva återskapa eller starta om programmet. Detta är viktigt för diagnostikändamål, vilket gör det möjligt att snabbt samla in de loggar som krävs från programmet som för närvarande distribueras i produktion. Utförlig loggning kan vara kostsam, så det är bäst att använda nivån Informational som standard och aktivera utförlig loggning när ett problem uppstår. Se JSON-konfigurationsprovidern för ett exempel på hur du läser in data från en konfigurationsfil utan att starta om programmet.

Loggnivå från en miljövariabel

Ett annat alternativ som vi rekommenderar är att konfigurera koden så att den använder en miljövariabel på datorn för att ange loggnivån eftersom koden kan ändra MSAL-loggningsnivån utan att behöva återskapa programmet.

Se EventLogLevel för mer information om de tillgängliga loggnivåerna.

Exempel:

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

Användning av MyIdentityLogger:

MyIdentityLogger myLogger = new MyIdentityLogger();

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

Loggning i en distribuerad tokencache

Om du använder tokencachens serialiserare från Microsoft. Identity.Web.TokenCache-paketet på .NET kan du aktivera ytterligare cachelagringsloggar.

Om du vill aktivera loggning av distribuerad cache anger du MinLevel egenskapen till Debug.

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

Mer information finns i Implementera en anpassad loggningsprovider .

Korrelations-ID

Loggar hjälper dig att förstå MSAL-beteendet på klientsidan. För att förstå vad som händer på tjänstsidan behöver teamet ett korrelations-ID. Detta ID spårar en autentiseringsbegäran genom de olika backend-tjänsterna.

Korrelations-ID:t kan hämtas på tre sätt:

1. Från ett lyckat autentiseringsresultat: AuthenticationResult.CorrelationId.
2. Från ett tjänstfel: MsalException.CorrelationId.
3. Genom att skicka ett anpassat korrelations-ID till WithCorrelationId(Guid) när du skapar en tokenbegäran.

När du anger ett eget korrelations-ID använder du ett annat ID-värde för varje begäran. Använd inte en konstant eftersom vi inte kan skilja mellan begäranden.

Nätverksspårningar

I fall där utförliga loggar inte ger tillräckligt med insikter kan du få en nätverksspårning med verktyg som Fiddler eller mitmproxy. Du kan konfigurera ditt valfritt verktyg för att vara en lokal proxy och acceptera trafik från enheter i ditt lokala nätverk, så att du kan samla in spårningar från andra enheter, till exempel iPhone- eller Android-telefoner. Plattformsspecifik konfiguration kan krävas innan du samlar in loggar.

Om det här verktyget inte är möjligt att använda kan du ändra det HttpClient som används av MSAL för att logga HTTP-trafiken. Som referens, se denna anpassade HttpClient implementering med loggning.

Anpassade HttpClient kan läggas till så här:

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

Nätverksspårningar när du använder WAM

För att samla in nätverksspårningar för Web Account Manager (WAM) på Windows med Fiddler krävs några extra steg.

1. Aktivera AppContainer-loopback i Fiddler genom att klicka på WinConfig, välja Undanta alla och spara ändringarna.

2. Aktivera HTTPS-dekryptering, men exkludera ADFS (msft.sts.microsoft.com) från HTTPS-dekryptering: