Protokollierung in MSAL für iOS/macOS

Die Microsoft Authentication Library (MSAL)-Apps (MSAL) generieren Protokollmeldungen, die bei der Diagnose von Problemen helfen können. Eine App kann die Protokollierung mit einigen Codezeilen konfigurieren und benutzerdefinierte Kontrolle über die Detailebene und darüber verfügen, ob persönliche und organisatorische Daten protokolliert werden. Es wird empfohlen, eine MSAL-Protokollierungsimplementierung zu erstellen und Benutzern die Möglichkeit zu bieten, Protokolle zu übermitteln, wenn Authentifizierungsprobleme auftreten.

Protokollierungsebenen

MSAL bietet mehrere Ebenen der Protokollierungsdetails:

  • LogAlways: Auf dieser Protokollebene wird keine Ebenenfilterung durchgeführt. Protokollmeldungen aller Ebenen werden protokolliert.
  • Kritisch: Protokolle, die einen nicht wiederherstellbaren Anwendungs- oder Systemabsturz oder einen katastrophalen Ausfall beschreiben, der sofortige Aufmerksamkeit erfordert.
  • Fehler: Gibt an, dass ein Fehler aufgetreten ist und ein Fehler generiert wurde. Wird zum Debuggen und Identifizieren von Problemen verwendet.
  • Warnung: Es muss nicht unbedingt ein Fehler oder Ausfall aufgetreten sein, sondern dies dient der Diagnose und der Eingrenzung von Problemen.
  • Informationen: MSAL protokolliert Ereignisse, die zu Informationszwecken vorgesehen sind und nicht unbedingt für das Debuggen bestimmt sind.
  • Verbose (Standard): MSAL protokolliert die vollständigen Details des Bibliotheksverhaltens.

Note

Nicht alle Protokollierungsebenen sind für alle MSAL-SDKs verfügbar.

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.

In den folgenden Abschnitten finden Sie weitere Details zur MSAL-Fehlerprotokollierung für Ihre Anwendung.

MSAL für iOS- und macOS-Protokollierung – ObjC

Legen Sie einen Rückruf fest, um die MSAL-Protokollierung zu erfassen und in die Protokollierung Ihrer eigenen Anwendung zu integrieren. Die Signatur für den Rückruf sieht wie folgt aus:

/*!
    The LogCallback block for the MSAL logger

    @param  level           The level of the log message
    @param  message         The message being logged
    @param  containsPII     If the message might contain Personally Identifiable Information (PII)
                            this will be true. Log messages possibly containing PII will not be
                            sent to the callback unless PIllLoggingEnabled is set to YES on the
                            logger.

 */
typedef void (^MSALLogCallback)(MSALLogLevel level, NSString *message, BOOL containsPII);

Beispiel:

[MSALGlobalConfig.loggerConfig setLogCallback:^(MSALLogLevel level, NSString *message, BOOL containsPII)
    {
        if (!containsPII)
        {
#if DEBUG
            // IMPORTANT: MSAL logs may contain sensitive information. Never output MSAL logs with NSLog, or print, directly unless you're running your application in debug mode. If you're writing MSAL logs to file, you must store the file securely.
            NSLog(@"MSAL log: %@", message);
#endif
        }
    }];

Personenbezogene Daten

MsAL erfasst oder protokolliert standardmäßig keine personenbezogenen Daten. Mit der Bibliothek können App-Entwickler dies über eine Eigenschaft in der MSALLogger-Klasse aktivieren. Durch das Aktivieren pii.Enabledübernimmt die App die Verantwortung für die sichere Verarbeitung streng vertraulicher Daten und die Einhaltung gesetzlicher Vorschriften.

// By default, the `MSALLogger` doesn't capture any PII

// PII will be logged
MSALGlobalConfig.loggerConfig.piiEnabled = YES;

// PII will NOT be logged
MSALGlobalConfig.loggerConfig.piiEnabled = NO;

Protokollierungsebenen

Verwenden Sie einen der folgenden Werte, um die Protokollierungsstufe festzulegen, wenn Sie MSAL für iOS und macOS verwenden:

Grad Description
MSALLogLevelNothing Alle Protokollierung deaktivieren
MSALLogLevelError Standardebene, druckt Informationen nur dann aus, wenn Fehler auftreten
MSALLogLevelWarning Warnungen
MSALLogLevelInfo Einstiegspunkte der Bibliothek mit Parametern und verschiedenen Schlüsselbund-Operationen
MSALLogLevelVerbose API-Nachverfolgung

Beispiel:

MSALGlobalConfig.loggerConfig.logLevel = MSALLogLevelVerbose;

Protokollnachrichtenformat

Der Nachrichtenteil von MSAL-Protokollnachrichten ist im Format von TID = <thread_id> MSAL <sdk_ver> <OS> <OS_ver> [timestamp - correlation_id] message

Beispiel:

TID = 551563 MSAL 0.2.0 iOS Sim 12.0 [2018-09-24 00:36:38 - 36764181-EF53-4E4E-B3E5-16FE362CFC44] acquireToken returning with error: (MSALErrorDomain, -42400) User cancelled the authorization session.

Die Bereitstellung von Korrelations-IDs und Zeitstempeln ist hilfreich, um Probleme nachzuverfolgen. Zeitstempel- und Korrelations-ID-Informationen sind in der Protokollmeldung verfügbar. Die einzige zuverlässige Quelle, um sie abzurufen, sind MSAL-Protokollmeldungen.

Nächste Schritte

Weitere Codebeispiele finden Sie unter Microsoft Identity Platform Codebeispiele.

  • Last updated on