Entrando no MSAL.NET

MSAL.NET aplicativos geram mensagens de log que podem ajudar a diagnosticar problemas. Você pode configurar o registro em log com algumas linhas de código e ter controle personalizado sobre o nível de detalhes e se os dados pessoais e organizacionais são registrados ou não. O log não está habilitado por padrão. Recomendamos que você habilite o logging do MSAL para oferecer uma forma de os usuários enviarem logs quando tiverem problemas de autenticação. Observe que a MSAL não armazena logs e gera logs para o destino fornecido na implementação do logger.

Note

A partir do MSAL.NET 4.58.0, os desenvolvedores também podem usar o OpenTelemetry para agregar logs e medir o desempenho do aplicativo.

Níveis de log

Há vários níveis de detalhamento de logs:

• LogAlways: nível base que inclui logs de métricas de integridade importantes para auxiliar no diagnóstico de operações da MSAL.
• Critical: logs que descrevem uma falha irrecuperável do aplicativo ou do sistema, ou uma falha catastrófica que requer atenção imediata.
• Error: indica que algo deu errado e um erro foi gerado. Usado para depurar e identificar problemas.
• Warning: inclui logs em cenários em que não houve necessariamente um erro ou falha, mas são destinados a diagnósticos e à identificação de problemas. Esse é o nível mínimo recomendado que deve ser habilitado em aplicativos de produção.
• Informational: A MSAL registrará eventos para fins informativos, não necessariamente para depuração.
• Verbose: a MSAL registra todos os detalhes do comportamento da biblioteca. No ambiente de produção, o nível detalhado só deve ser habilitado temporariamente para coletar logs para uma finalidade específica de depuração.

Dados pessoais e organizacionais

Por padrão, o logger da MSAL não registra dados pessoais ou organizacionais altamente sensíveis. A biblioteca fornece a opção de habilitar o registro em log de dados pessoais e organizacionais se você decidir fazer isso. Para obter detalhes, consulte Tratamento de informações de identificação pessoal no MSAL.NET.

Configurar o registro em log no MSAL.NET

No MSAL, o log é configurado durante a criação do aplicativo usando o construtor WithLogging(IIdentityLogger, Boolean). Esse método usa os seguintes parâmetros:

• identityLogger é a implementação de registro em log usada por MSAL.NET para produzir logs para fins de depuração ou verificação de integridade. Os logs só são enviados se o registro estiver habilitado.
• enablePiiLogging habilita o registro em log de dados pessoais e organizacionais (PII) se definido como true. Por padrão, esse parâmetro é definido como false, para que seu aplicativo não registre dados confidenciais.

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

Note

Bibliotecas de nível superior (Microsoft.Identity.Web, Microsoft.IdentityModel) já fornecem implementações dessa interface para vários ambientes (em particular ASP.NET Core).

Implementação de IIdentityLogger

Nível de log de um arquivo de configuração

É altamente recomendável configurar seu código para usar um arquivo de configuração em seu ambiente para definir o nível de log, pois ele permitirá que seu código altere o nível de log msal sem a necessidade de recompilar ou reiniciar o aplicativo. Isso é fundamental para fins de diagnóstico, permitindo reunir rapidamente os logs necessários do aplicativo que está atualmente implantado em produção. O log detalhado pode ser caro, portanto, é melhor usar o nível Informational por padrão e habilitar o log detalhado quando um problema for encontrado. Consulte o provedor de configuração JSON para obter um exemplo sobre como carregar dados de um arquivo de configuração sem reiniciar o aplicativo.

Nível de log de uma variável de ambiente

Outra opção que recomendamos é configurar seu código para usar uma variável de ambiente no computador para definir o nível de log, pois permitirá que seu código altere o nível de log msal sem a necessidade de recompilar o aplicativo.

Consulte EventLogLevel para obter detalhes sobre os níveis de log disponíveis.

Exemplo:

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

Usando MyIdentityLogger:

MyIdentityLogger myLogger = new MyIdentityLogger();

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

Fazer logon em um cache de token distribuído

Se você usar serializadores de cache de tokens do pacote Microsoft.Identity.Web.TokenCache no .NET, poderá habilitar logs adicionais de cache.

Para habilitar o logging de cache distribuído, defina a propriedade MinLevel para Debug.

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

Consulte Implementar um provedor de log personalizado para obter mais detalhes.

ID de Correlação

Os logs ajudam a entender o comportamento da MSAL no lado do cliente. Para entender o que está acontecendo no lado do serviço, a equipe precisa de uma ID de correlação. Essa ID rastreia uma solicitação de autenticação por meio dos vários serviços de back-end.

A ID de correlação pode ser obtida de três maneiras:

1. A partir de um resultado de autenticação bem-sucedido: AuthenticationResult.CorrelationId
2. Devido a uma exceção de serviço: MsalException.CorrelationId.
3. Ao passar um ID de correlação personalizado para WithCorrelationId(Guid) ao criar uma solicitação de token.

Ao fornecer sua própria ID de correlação, use um valor de ID diferente para cada solicitação. Não use uma constante, pois não poderemos diferenciar entre as solicitações.

Rastreamentos de rede

Importante

Os rastreamentos de rede normalmente contêm informações e credenciais de identificação pessoal. Remova todos os detalhes confidenciais antes de postar os logs no GitHub.

Nos casos em que os logs detalhados não fornecem insights suficientes, você pode obter um rastreamento de rede usando ferramentas como Fiddler ou mitmproxy. Você pode configurar sua ferramenta de escolha para ser um proxy local e aceitar o tráfego de dispositivos em sua rede local, permitindo que você capture rastreamentos de outros dispositivos, como telefones iPhone ou Android. A configuração específica da plataforma pode ser necessária antes da captura de logs.

Se não for possível usar essa ferramenta, você poderá modificar o HttpClient que a MSAL usa para registrar em log o tráfego HTTP. Para referência, consulte esta implementação de HttpClient personalizado com registro em log.

Warning

Esse cliente não deve ser usado em produção e somente para registro em log.

O HttpClient personalizado pode ser adicionado da seguinte maneira:

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

Rastreamentos de rede ao usar o WAM

Para coletar rastreamentos de rede para o WAM (Gerenciador de Contas Web) em Windows com o Fiddler, são necessárias algumas etapas adicionais.

1. Habilite o loopback do AppContainer no Fiddler clicando em WinConfig, selecionando Isentar Tudo e salvando as alterações.

2. Habilite a descriptografia HTTPS, mas exclua o ADFS (msft.sts.microsoft.com) da descriptografia HTTPS: