Journalisation dans MSAL.NET

MSAL.NET applications génèrent des messages de journal qui peuvent aider à diagnostiquer les problèmes. Vous pouvez configurer la journalisation avec quelques lignes de code et avoir un contrôle personnalisé sur le niveau de détail et si les données personnelles et organisationnelles sont enregistrées ou non. La journalisation n’est pas activée par défaut. Nous vous recommandons d’activer la journalisation MSAL pour permettre aux utilisateurs d’envoyer des journaux lorsqu’ils rencontrent des problèmes d’authentification. Notez que MSAL ne stocke aucun message de journalisation et envoie les messages de journalisation à la destination fournie dans l’implémentation du module de journalisation.

Niveaux de journalisation

Il existe plusieurs niveaux de détail de journalisation :

• LogAlways : Niveau de base qui inclut les journaux des indicateurs d’intégrité importants pour aider au diagnostic des opérations MSAL.
• Critical: journaux qui décrivent une panne irrécupérable de l’application ou du système, ou une défaillance catastrophique nécessitant une attention immédiate.
• Error: indique qu’une erreur s’est produite et qu’une erreur a été générée. Utilisé pour le débogage et l’identification des problèmes.
• Warning: inclut les journaux d’activité dans les scénarios où il n’y a pas nécessairement eu d’erreur ou d’échec, mais sont destinés aux diagnostics et à l’identification des problèmes. Il s’agit du niveau minimal recommandé qui doit être activé dans les applications de production.
• Informational: MSAL consignera les événements à titre informatif, et non nécessairement à des fins de débogage.
• Verbose: MSAL enregistre les détails complets du comportement de la bibliothèque. En environnement de production, le niveau de verbosité ne doit être activé que temporairement afin de recueillir des journaux dans un but précis de débogage.

Données personnelles et organisationnelles

Par défaut, l’enregistreur d’événements MSAL ne capture pas de données personnelles ou organisationnelles hautement sensibles. La bibliothèque offre la possibilité d’activer la journalisation des données personnelles et organisationnelles si vous décidez de le faire. Pour plus d’informations, consultez Gestion des informations d’identification personnelle dans MSAL.NET.

Configurer la journalisation dans MSAL.NET

Dans MSAL, la journalisation est définie lors de la création de l’application à l’aide du WithLogging(IIdentityLogger, Boolean) générateur. Cette méthode prend les paramètres suivants :

• identityLoggerest l’implémentation de journalisation utilisée par MSAL.NET pour produire des journaux à des fins de débogage ou de contrôle d’intégrité. Les journaux sont envoyés uniquement si la journalisation est activée.
• enablePiiLogging permet de journaliser les données personnelles et organisationnelles (PII) si la valeur est true. Par défaut, ce paramètre est défini sur false, afin que votre application ne journale pas les données sensibles.

Interface IIdentityLogger

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

Implémentation d’IIdentityLogger

Niveau de journalisation à partir d’un fichier de configuration

Il est vivement recommandé de configurer votre code pour utiliser un fichier de configuration dans votre environnement pour définir le niveau de journalisation, car il permet à votre code de modifier le niveau de journalisation MSAL sans avoir à reconstruire ou redémarrer l’application. Cela est essentiel à des fins de diagnostic, ce qui permet de collecter rapidement les journaux requis à partir de l’application actuellement déployée en production. La journalisation détaillée peut être coûteuse, il est donc préférable d’utiliser par défaut le niveau Informational et d’activer la journalisation détaillée en cas de problème. Consultez le fournisseur de configuration JSON pour obtenir un exemple sur la façon de charger des données à partir d’un fichier de configuration sans redémarrer l’application.

Niveau de journalisation à partir d’une variable d’environnement

Une autre option que nous vous recommandons est de configurer votre code pour utiliser une variable d’environnement sur l’ordinateur pour définir le niveau de journalisation, car il permet à votre code de modifier le niveau de journalisation MSAL sans avoir à reconstruire l’application.

Consultez EventLogLevel pour en savoir plus sur les niveaux de journalisation disponibles.

Exemple :

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

Utilisation de MyIdentityLogger:

MyIdentityLogger myLogger = new MyIdentityLogger();

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

Journalisation dans un cache de jeton distribué

Si vous utilisez des sérialiseurs de cache de jetons du package Microsoft.Identity.Web.TokenCache sur .NET, vous pouvez activer des journaux supplémentaires pour le cache.

Pour activer la journalisation du cache distribué, définissez la MinLevel propriété sur Debug.

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

Pour plus d’informations, consultez Implémenter un fournisseur de journalisation personnalisé .

ID de corrélation :

Les journaux aident à comprendre le comportement MSAL côté client. Pour comprendre ce qui se passe côté service, l’équipe a besoin d’un ID de corrélation. Cet ID trace une demande d’authentification via les différents services principaux.

L’ID de corrélation peut être obtenu de trois façons :

1. À partir d’un résultat d’authentification réussi : AuthenticationResult.CorrelationId.
2. À partir d’une exception de service : MsalException.CorrelationId.
3. En transmettant un ID de corrélation personnalisé à WithCorrelationId(Guid) lors de la création d’une requête de jeton.

Lorsque vous fournissez votre propre ID de corrélation, utilisez une valeur d’ID différente pour chaque requête. N’utilisez pas de constante, car nous ne serons pas en mesure de différencier les demandes.

Traces réseau

Dans les cas où les journaux détaillés ne fournissent pas suffisamment d’informations, vous pouvez obtenir une trace réseau à l’aide d’outils tels que Fiddler ou mitmproxy. Vous pouvez configurer votre outil de choix pour être un proxy local et accepter le trafic à partir d’appareils sur votre réseau local, ce qui vous permet de capturer des traces à partir d’autres appareils, tels que iPhone ou téléphones Android. Une configuration propre à la plateforme peut être nécessaire avant la collecte des journaux.

Si cet outil n’est pas possible d’utiliser, vous pouvez modifier l’outil HttpClient utilisé par MSAL pour enregistrer le trafic HTTP. Pour référence, consultez cette implémentation personnalisée HttpClient avec la journalisation.

Vous pouvez ajouter des éléments personnalisés HttpClient comme suit :

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

Traces réseau lors de l’utilisation de WAM

Pour collecter des traces réseau pour le Gestionnaire de comptes web (WAM) sur Windows avec Fiddler, quelques étapes supplémentaires sont nécessaires.

1. Activez le bouclage AppContainer dans Fiddler en cliquant sur WinConfig, puis en sélectionnant Exempt All et en enregistrant les modifications.

2. Activez le déchiffrement HTTPS, mais excluez ADFS (msft.sts.microsoft.com) du déchiffrement HTTPS :