Accesso a MSAL.NET

MSAL.NET app generano messaggi di log che consentono di diagnosticare i problemi. È possibile configurare la registrazione con alcune righe di codice e controllare in modo personalizzato il livello di dettaglio e se i dati personali e dell'organizzazione vengono registrati. La registrazione non è abilitata per impostazione predefinita. È consigliabile abilitare la registrazione MSAL per consentire agli utenti di inviare i log in caso di problemi di autenticazione. Si noti che MSAL non archivia alcun log e invia i log alla destinazione specificata nell'implementazione del logger.

Livelli di registrazione

Esistono diversi livelli di dettagli di registrazione:

• LogAlways: livello base che include log di importanti metriche di stato per agevolare la diagnosi delle operazioni di MSAL.
• Critical: i log che descrivono un arresto anomalo non recuperabile dell'applicazione o del sistema, oppure un guasto catastrofico che richiede attenzione immediata.
• Error: indica che si è verificato un problema e che è stato generato un errore. Usato per il debug e l'identificazione dei problemi.
• Warning: include i log negli scenari in cui non si è necessariamente verificato un errore o un errore, ma sono destinati alla diagnostica e all'individuazione dei problemi. Questo è il livello minimo consigliato che deve essere abilitato nelle app di produzione.
• Informational: MSAL registra gli eventi destinati a scopi informativi, non necessariamente destinati al debug.
• Verbose: MSAL registra i dettagli completi del comportamento della libreria. Nell'ambiente di produzione, il livello di verbosità dovrebbe essere abilitato solo temporaneamente per raccogliere i log a fini di debug specifici.

Dati personali e aziendali

Per impostazione predefinita, il logger MSAL non acquisisce dati personali o aziendali estremamente sensibili. La libreria offre la possibilità di abilitare la registrazione dei dati personali e dell'organizzazione se si decide di farlo. Per informazioni dettagliate, vedere Gestione delle informazioni personali in MSAL.NET.

Configurare la registrazione in MSAL.NET

In MSAL la registrazione viene impostata durante la creazione dell'applicazione usando il WithLogging(IIdentityLogger, Boolean) generatore. Questo metodo accetta i parametri seguenti:

• identityLoggerè l'implementazione della registrazione usata da MSAL.NET per produrre log a scopo di debug o controllo dell'integrità. I log vengono inviati solo se la registrazione è abilitata.
• enablePiiLogging abilita la registrazione dei dati personali e dell'organizzazione (PII) se impostato su true. Per impostazione predefinita, questo parametro è impostato su false, in modo che l'applicazione non registri i dati sensibili.

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

Implementazione di IIdentityLogger

Livello di log da un file di configurazione

È consigliabile configurare il codice in modo da usare un file di configurazione nell'ambiente per impostare il livello di log in quanto consentirà al codice di modificare il livello di registrazione MSAL senza dover ricompilare o riavviare l'applicazione. Questa operazione è fondamentale per scopi di diagnostica, consentendo di raccogliere rapidamente i log necessari dall'applicazione attualmente distribuita nell'ambiente di produzione. La registrazione dettagliata può comportare costi elevati, quindi è preferibile usare per impostazione predefinita il livello Informational e abilitare la registrazione dettagliata quando si verifica un problema. Vedere Provider di configurazione JSON per un esempio su come caricare i dati da un file di configurazione senza riavviare l'applicazione.

Livello di log da una variabile di ambiente

Un'altra opzione consigliata consiste nel configurare il codice in modo da usare una variabile di ambiente nel computer per impostare il livello di log perché consentirà al codice di modificare il livello di registrazione MSAL senza dover ricompilare l'applicazione.

Vedere EventLogLevel per informazioni dettagliate sui livelli di log disponibili.

Esempio:

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

Utilizzo di MyIdentityLogger:

MyIdentityLogger myLogger = new MyIdentityLogger();

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

Registrazione in una cache dei token distribuiti

Se si usano i serializzatori della cache dei token del pacchetto Microsoft.Identity.Web.TokenCache in .NET, è possibile abilitare log aggiuntivi per la memorizzazione nella cache.

Per abilitare la registrazione della cache distribuita, impostare la MinLevel proprietà su Debug.

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

Per altri dettagli, vedere Implementare un provider di registrazione personalizzato .

ID di correlazione

I log consentono di comprendere il comportamento msal sul lato client. Per comprendere cosa accade sul lato servizio, il team necessita di un ID di correlazione. Questo ID traccia una richiesta di autenticazione tramite i vari servizi back-end.

L'ID di correlazione può essere ottenuto in tre modi:

1. Da un risultato di autenticazione riuscito: AuthenticationResult.CorrelationId.
2. Da un'eccezione di servizio: MsalException.CorrelationId.
3. Passando un ID di correlazione personalizzato a WithCorrelationId(Guid) quando si compila una richiesta di token.

Quando si specifica un ID di correlazione personalizzato, usare un valore ID diverso per ogni richiesta. Non usare una costante perché non sarà possibile distinguere tra le richieste.

Tracce di rete

Nei casi in cui i log dettagliati non forniscono informazioni sufficienti, è possibile ottenere una traccia di rete usando strumenti come Fiddler o mitmproxy. È possibile configurare lo strumento preferito come proxy locale e accettare il traffico dai dispositivi nella rete locale, consentendo di acquisire tracce da altri dispositivi, ad esempio telefoni iPhone o Android. È possibile che sia necessaria una configurazione specifica della piattaforma prima di acquisire i log.

Se tale strumento non è possibile usare, è possibile modificare l'oggetto HttpClient usato da MSAL per registrare il traffico HTTP. Per riferimento, vedere questa implementazione personalizzata HttpClient con la registrazione.

È possibile aggiungere personalizzati HttpClient come segue:

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

Tracce di rete quando si usa WAM

Per raccogliere tracce di rete per Web Account Manager (WAM) in Windows con Fiddler, sono necessari alcuni passaggi aggiuntivi.

1. Abilitare il loopback AppContainer in Fiddler facendo clic su WinConfig, selezionando Esentare tutto e salvare le modifiche.

2. Abilitare la decrittografia HTTPS, ma escludere ADFS (msft.sts.microsoft.com) dalla decrittografia HTTPS: