Rejestrowanie zdarzeń w MSAL na iOS/macOS

Aplikacje Microsoft Authentication Library (MSAL) generują komunikaty dziennika, które mogą pomóc w diagnozowaniu problemów. Aplikacja może skonfigurować rejestrowanie przy użyciu kilku wierszy kodu i mieć niestandardową kontrolę nad poziomem szczegółowości oraz informacją, czy są rejestrowane dane osobiste i organizacyjne. Zalecamy utworzenie mechanizmu rejestrowania zdarzeń w bibliotece MSAL oraz zapewnienie użytkownikom możliwości przesyłania logów, gdy wystąpią problemy z uwierzytelnianiem.

Poziomy rejestrowania

Biblioteka MSAL udostępnia kilka poziomów szczegółowości rejestrowania:

  • LogAlways: Na tym poziomie dziennika nie stosuje się filtrowania. Wiadomości dziennika na wszystkich poziomach będą rejestrowane.
  • Krytyczne: dzienniki, które opisują nieodwracalną awarię aplikacji lub systemu albo katastrofalną awarię, która wymaga natychmiastowej uwagi.
  • Błąd: wskazuje, że wystąpił problem i został wygenerowany błąd. Służy do debugowania i identyfikowania problemów.
  • Ostrzeżenie: Niekoniecznie wystąpił błąd lub awaria, ale służą one do diagnostyki i identyfikowania problemów.
  • Informacje: biblioteka MSAL będzie rejestrować zdarzenia przeznaczone do celów informacyjnych niekoniecznie przeznaczone do debugowania.
  • Pełne (ustawienie domyślne): biblioteka MSAL rejestruje pełne szczegóły zachowania biblioteki.

Note

Nie wszystkie poziomy dziennika są dostępne dla wszystkich zestawów MSAL SDK

Dane osobowe i organizacyjne

Domyślnie rejestrator MSAL nie rejestruje żadnych szczególnie chronionych danych osobowych ani danych organizacyjnych. Biblioteka udostępnia opcję włączania rejestrowania danych osobistych i organizacyjnych, jeśli zdecydujesz się to zrobić.

Poniższe sekcje zawierają więcej szczegółowych informacji na temat rejestrowania błędów biblioteki MSAL dla aplikacji.

MSAL dla systemów iOS i macOS — rejestrowanie (ObjC)

Ustaw funkcję wywołania zwrotnego, aby przechwytywać dzienniki MSAL i uwzględniać je w mechanizmie rejestrowania własnej aplikacji. Podpis wywołania zwrotnego wygląda następująco:

/*!
    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);

Przykład:

[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
        }
    }];

Dane osobowe

Domyślnie biblioteka MSAL nie przechwytuje ani nie rejestruje żadnych danych osobowych. Biblioteka umożliwia deweloperom aplikacji włączenie tej funkcji za pomocą właściwości w klasie MSALLogger. Włączenie polecenia pii.Enabledpowoduje, że aplikacja ponosi odpowiedzialność za bezpieczne obsługiwanie wysoce poufnych danych i przestrzeganie wymagań prawnych.

// 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;

Poziomy rejestrowania

Aby ustawić poziom rejestrowania podczas rejestrowania przy użyciu biblioteki MSAL dla systemów iOS i macOS, użyj jednej z następujących wartości:

Level Description
MSALLogLevelNothing Wyłącz wszystkie rejestrowanie
MSALLogLevelError Poziom domyślny, wyświetla informacje tylko wtedy, gdy wystąpią błędy
MSALLogLevelWarning Warnings
MSALLogLevelInfo Punkty wejścia biblioteki z parametrami i różnymi operacjami łańcucha kluczy
MSALLogLevelVerbose Śledzenie interfejsu API

Przykład:

MSALGlobalConfig.loggerConfig.logLevel = MSALLogLevelVerbose;

Format komunikatu dziennika

Część komunikatu w komunikatach dziennika MSAL ma format TID = <thread_id> MSAL <sdk_ver> <OS> <OS_ver> [timestamp - correlation_id] message

Przykład:

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.

Udostępnianie identyfikatorów korelacji i sygnatur czasowych jest przydatne podczas śledzenia problemów. Informacje o sygnaturze czasowej i identyfikatorze korelacji są dostępne w komunikacie dziennika. Jedynym niezawodnym miejscem do ich pobrania są komunikaty dziennika biblioteki MSAL.

Następne kroki

Aby uzyskać więcej przykładów kodu, zapoznaj się z przykładami kodu Platforma tożsamości Microsoft.

  • Last updated on