Aanmelden bij MSAL.NET

MSAL.NET apps logboekberichten genereren waarmee problemen kunnen worden vastgesteld. U kunt logboekregistratie configureren met een paar regels code en aangepaste controle hebben over het detailniveau en of persoonlijke en organisatorische gegevens wel of niet worden vastgelegd. Logboekregistratie is niet standaard ingeschakeld. U wordt aangeraden MSAL-logboekregistratie in te schakelen om gebruikers een manier te bieden om logboeken in te dienen wanneer ze verificatieproblemen ondervinden. Houd er rekening mee dat MSAL geen logboeken opslaat en logboeken verzendt naar het doel dat is opgegeven in de implementatie van de logboekregistratie.

Logboekregistratieniveaus

Er zijn verschillende niveaus met logboekregistratiedetails:

• LogAlways: basisniveau dat logboeken met belangrijke metrische statusgegevens bevat om te helpen bij het diagnosticeren van MSAL-bewerkingen.
• Critical: Logboeken die een onherstelbare toepassing of systeemcrash beschrijven, of een onherstelbare fout waarvoor onmiddellijke aandacht is vereist.
• Error: Geeft aan dat er iets mis is gegaan en er een fout is gegenereerd. Wordt gebruikt voor foutopsporing en het identificeren van problemen.
• Warning: Bevat logboeken in scenario's waarin er niet noodzakelijkerwijs een fout of fout is opgetreden, maar zijn bedoeld voor diagnostische gegevens en het vaststellen van problemen. Dit is het aanbevolen minimumniveau dat moet worden ingeschakeld in productie-apps.
• Informational: MSAL zal gebeurtenissen vastleggen die bedoeld zijn voor informatieve doeleinden, niet noodzakelijkerwijs bedoeld voor foutopsporing.
• Verbose: MSAL registreert de volledige details van het gedrag van de bibliotheek. In een productieomgeving mag uitgebreid niveau alleen tijdelijk worden ingeschakeld om logboeken te verzamelen voor een specifiek foutopsporingsdoel.

Persoonlijke en organisatorische gegevens

Standaard legt de MSAL-logboekregistratie geen zeer gevoelige persoonlijke of organisatorische gegevens vast. De bibliotheek biedt de optie om persoonlijke en organisatiegegevens in te schakelen als u dit wilt doen. Zie De verwerking van persoonsgegevens in MSAL.NET voor meer informatie.

Logboekregistratie configureren in MSAL.NET

In MSAL wordt logboekregistratie ingesteld tijdens het maken van de toepassing met behulp van de WithLogging(IIdentityLogger, Boolean) opbouwfunctie. Deze methode gebruikt de volgende parameters:

• identityLoggeris de implementatie van logboekregistratie die door MSAL.NET wordt gebruikt om logboeken te produceren voor foutopsporing of statuscontrole. Logboeken worden alleen verzonden als logboekregistratie is ingeschakeld.
• enablePiiLogging maakt logboekregistratie van persoonlijke en organisatiegegevens (PII) mogelijk als deze is ingesteld op waar. Deze parameter is standaard ingesteld op false, zodat uw toepassing geen gevoelige gegevens in een logboek opgeeft.

IIdentityLogger-interface

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

IIdentityLogger-implementatie

Logboekniveau van een configuratiebestand

Het wordt ten zeerste aanbevolen om uw code te configureren voor het gebruik van een configuratiebestand in uw omgeving om het logboekniveau in te stellen, omdat uw code het MSAL-logboekregistratieniveau kan wijzigen zonder de toepassing opnieuw te hoeven bouwen of opnieuw te starten. Dit is essentieel voor diagnostische doeleinden, zodat u snel de vereiste logboeken kunt verzamelen van de toepassing die momenteel in productie is geïmplementeerd. Uitgebreide logboekregistratie kan kostbaar zijn, dus u kunt het beste het Informational niveau standaard gebruiken en uitgebreide logboekregistratie inschakelen wanneer er een probleem optreedt. Zie de JSON-configuratieprovider voor een voorbeeld van het laden van gegevens uit een configuratiebestand zonder de toepassing opnieuw op te starten.

Logboekniveau van een omgevingsvariabele

Een andere optie is om uw code te configureren voor het gebruik van een omgevingsvariabele op de computer om het logboekniveau in te stellen, omdat uw code het MSAL-logboekregistratieniveau kan wijzigen zonder de toepassing opnieuw te hoeven bouwen.

Zie EventLogLevel voor meer informatie over de beschikbare logboekniveaus.

Voorbeeld:

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

Met behulp van MyIdentityLogger:

MyIdentityLogger myLogger = new MyIdentityLogger();

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

Aanmelden in een gedistribueerde tokencache

Als u tokencacheserialisaties uit Microsoft gebruikt. Identity.Web.TokenCache-pakket op .NET kunt u extra cachelogboeken inschakelen.

Als u logboekregistratie van gedistribueerde cache wilt inschakelen, stelt u de MinLevel eigenschap in op Debug.

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

Zie Een aangepaste logboekregistratieprovider implementeren voor meer informatie.

Correlatie-id

Logboeken helpen inzicht te hebben in het MSAL-gedrag aan de clientzijde. Om te begrijpen wat er aan de servicezijde gebeurt, heeft het team een correlatie-id nodig. Deze id traceert een verificatieaanvraag via de verschillende back-endservices.

De correlatie-id kan op drie manieren worden verkregen:

1. Van een geslaagd verificatieresultaat: AuthenticationResult.CorrelationId.
2. Uit een service-uitzondering: MsalException.CorrelationId.
3. Door een aangepaste correlatie-id door te geven aan WithCorrelationId(Guid) bij het bouwen van een tokenaanvraag.

Wanneer u uw eigen correlatie-id opgeeft, gebruikt u een andere id-waarde voor elke aanvraag. Gebruik geen constante omdat we geen onderscheid kunnen maken tussen de aanvragen.

Netwerktraceringen

In gevallen waarin uitgebreide logboeken onvoldoende inzichten bieden, kunt u een netwerktracering verkrijgen met behulp van hulpprogramma's zoals Fiddler of mitmproxy. U kunt uw hulpprogramma naar keuze configureren als een lokale proxy en verkeer van apparaten in uw lokale netwerk accepteren, zodat u traceringen van andere apparaten, zoals iPhone of Android-telefoons, kunt vastleggen. Platformspecifieke configuratie is mogelijk vereist voordat logboeken worden vastgelegd.

Als een dergelijk hulpprogramma niet kan worden gebruikt, kunt u het HttpClient gebruikte door MSAL wijzigen om het HTTP-verkeer te registreren. Raadpleeg deze aangepaste HttpClient implementatie met logboekregistratie ter referentie.

Aangepast HttpClient kan als volgt worden toegevoegd:

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

Netwerktraceringen bij het gebruik van WAM

Voor het verzamelen van netwerktraceringen voor Web Account Manager (WAM) op Windows met Fiddler zijn enkele extra stappen nodig.

1. Schakel AppContainer-loopback in Fiddler in door op WinConfig te klikken, Alles uitsluiten te selecteren en de wijzigingen op te slaan.

2. HTTPS-ontsleuteling inschakelen, maar ADFS (msft.sts.microsoft.com) uitsluiten van HTTPS-ontsleuteling: