Anmelden in MSAL.NET

MSAL.NET Apps generieren Protokollmeldungen, die bei der Diagnose von Problemen helfen können. Sie können die Protokollierung mit einigen Codezeilen konfigurieren und benutzerdefinierte Kontrolle über die Detailebene haben und festlegen, ob persönliche und organisatorische Daten protokolliert werden. Die Protokollierung ist standardmäßig nicht aktiviert. Es wird empfohlen, die MSAL-Protokollierung zu aktivieren, um Benutzern die Möglichkeit zu bieten, Protokolle zu übermitteln, wenn Authentifizierungsprobleme auftreten. Beachten Sie, dass MSAL keine Protokolle speichert und Protokolle an das Ziel ausgibt, das in der Loggerimplementierung bereitgestellt wird.

Protokollierungsebenen

Es gibt mehrere Ebenen der Protokollierungsdetails:

• LogAlways: Grundstufe, die Protokolle zu wichtigen Zustandsmetriken zur Unterstützung der Diagnose von MSAL-Vorgängen umfasst.
• Critical: Protokolle, die einen nicht wiederherstellbaren Anwendungs- oder Systemabsturz oder einen katastrophalen Fehler beschreiben, der sofortige Aufmerksamkeit erfordert.
• Error: Gibt an, dass ein Fehler aufgetreten ist und ein Fehler generiert wurde. Wird zum Debuggen und Identifizieren von Problemen verwendet.
• Warning: Enthält Protokolle auch in Szenarien, in denen nicht unbedingt ein Fehler oder Ausfall aufgetreten ist, die jedoch für die Diagnose und die genaue Lokalisierung von Problemen vorgesehen sind. Dies ist die empfohlene Mindeststufe, die in Produktions-Apps aktiviert werden sollte.
• Informational: MSAL protokolliert Ereignisse, die für Informationszwecke vorgesehen sind, nicht unbedingt für das Debuggen vorgesehen.
• Verbose: MSAL protokolliert die vollständigen Details des Bibliotheksverhaltens. In der Produktionsumgebung sollte der ausführliche Modus nur vorübergehend aktiviert werden, um Protokolle für einen bestimmten Debugging-Zweck zu erfassen.

Personenbezogene und organisatorische Daten

Standardmäßig erfasst der MSAL-Logger keine streng vertraulichen persönlichen oder organisatorischen Daten. Die Bibliothek bietet die Möglichkeit, die Protokollierung personenbezogener und organisatorischer Daten zu aktivieren, wenn Sie dies tun möchten. Ausführliche Informationen finden Sie unter "Umgang mit persönlich identifizierbaren Informationen in MSAL.NET".

Konfigurieren der Protokollierung in MSAL.NET

In MSAL wird die Protokollierung während der Anwendungserstellung mithilfe des WithLogging(IIdentityLogger, Boolean) Generators festgelegt. Diese Methode verwendet die folgenden Parameter:

• identityLoggerist die Protokollierungsimplementierung, die von MSAL.NET verwendet wird, um Protokolle für Debugging- oder Integritätsprüfungszwecke zu erstellen. Protokolle werden nur gesendet, wenn die Protokollierung aktiviert ist.
• enablePiiLogging aktiviert die Protokollierung von personenbezogenen und organisatorischen Daten (PII), wenn diese auf "true" festgelegt ist. Standardmäßig ist dieser Parameter auf "false" festgelegt, sodass ihre Anwendung keine vertraulichen Daten protokolliert.

IIdentityLogger-Schnittstelle

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-Implementierung

Protokollebene aus einer Konfigurationsdatei

Es wird dringend empfohlen, Ihren Code so zu konfigurieren, dass eine Konfigurationsdatei in Ihrer Umgebung verwendet wird, um die Protokollebene festzulegen, da ihr Code die MSAL-Protokollierungsebene ändern kann, ohne die Anwendung neu erstellen oder neu starten zu müssen. Dies ist für Diagnosezwecke von entscheidender Bedeutung, sodass schnell die erforderlichen Protokolle aus der Anwendung gesammelt werden können, die derzeit in der Produktion bereitgestellt wird. Ausführliche Protokollierung kann aufwendig sein, daher empfiehlt es sich, standardmäßig die Stufe Informational zu verwenden und die ausführliche Protokollierung nur zu aktivieren, wenn ein Problem auftritt. Ein Beispiel zum Laden von Daten aus einer Konfigurationsdatei, ohne die Anwendung neu zu starten, finden Sie unter JSON-Konfigurationsanbieter .

Protokollebene aus einer Umgebungsvariable

Eine weitere Option, die empfohlen wird, besteht darin, Ihren Code so zu konfigurieren, dass eine Umgebungsvariable auf dem Computer verwendet wird, um die Protokollebene festzulegen, da ihr Code die MSAL-Protokollierungsebene ändern kann, ohne die Anwendung neu erstellen zu müssen.

Siehe EventLogLevel für Details zu den verfügbaren Protokollebenen.

Beispiel:

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

Verwendung von MyIdentityLogger:

MyIdentityLogger myLogger = new MyIdentityLogger();

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

Anmelden in einem verteilten Tokencache

Wenn Sie Token-Cache-Serializer aus dem Microsoft.Identity.Web.TokenCache-Paket unter .NET verwenden, können Sie zusätzliche Cacheprotokollierung aktivieren.

Um die verteilte Cacheprotokollierung zu aktivieren, legen Sie die MinLevel Eigenschaft auf Debug.

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

Weitere Informationen finden Sie unter Implementieren eines benutzerdefinierten Protokollierungsanbieters .

Korrelations-ID

Protokolle helfen ihnen, das MSAL-Verhalten auf clientseitiger Seite zu verstehen. Um zu verstehen, was auf der Dienstseite passiert, benötigt das Team eine Korrelations-ID. Diese ID verfolgt eine Authentifizierungsanforderung über die verschiedenen Back-End-Dienste nach.

Die Korrelations-ID kann auf drei Arten abgerufen werden:

1. Aus einem erfolgreichen Authentifizierungsergebnis: AuthenticationResult.CorrelationId.
2. Aus einer Dienst-Ausnahme: MsalException.CorrelationId.
3. Durch Übergeben einer benutzerdefinierten Korrelations-ID WithCorrelationId(Guid) beim Erstellen einer Tokenanforderung.

Wenn Sie Ihre eigene Korrelations-ID angeben, verwenden Sie für jede Anforderung einen anderen ID-Wert. Verwenden Sie keine Konstante, da wir nicht zwischen den Anforderungen unterscheiden können.

Netzwerkablaufverfolgungen

In Fällen, in denen ausführliche Protokolle nicht genügend Aufschluss geben, können Sie mithilfe von Tools wie Fiddler oder mitmproxy eine Netzwerkablaufverfolgung erstellen. Sie können Ihr Wahltool so konfigurieren, dass es sich um einen lokalen Proxy handeln und Datenverkehr von Geräten in Ihrem lokalen Netzwerk akzeptiert, sodass Sie Ablaufverfolgungen von anderen Geräten, z. B. iPhone oder Android-Smartphones, erfassen können. Plattformspezifische Konfiguration kann vor dem Erfassen von Protokollen erforderlich sein.

Wenn ein solches Tool nicht verwendet werden kann, können Sie das HttpClient von MSAL verwendete Tool ändern, um den HTTP-Datenverkehr zu protokollieren. Referenz finden Sie in dieser benutzerdefinierten HttpClient Implementierung mit Protokollierung.

Benutzerdefinierte HttpClient kann wie folgt hinzugefügt werden:

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

Netzwerkablaufverfolgungen bei Verwendung von WAM

Um Netzwerkablaufverfolgungen für Web Account Manager (WAM) für Windows mit Fiddler zu sammeln, sind einige zusätzliche Schritte erforderlich.

1. Aktivieren Sie den AppContainer-Loopback in Fiddler, indem Sie auf "WinConfig" klicken, " Alle ausschließen" auswählen und die Änderungen speichern.

2. Aktivieren Sie die HTTPS-Entschlüsselung, schließen Sie jedoch ADFS (msft.sts.microsoft.com) aus der HTTPS-Entschlüsselung aus: