Inicio de sesión en MSAL.NET

MSAL.NET aplicaciones generan mensajes de registro que pueden ayudar a diagnosticar problemas. Puede configurar el registro con algunas líneas de código y tener control personalizado sobre el nivel de detalle y si se registran o no datos personales y de la organización. El registro no está habilitado de forma predeterminada. Se recomienda habilitar el registro de MSAL para proporcionar una manera de que los usuarios envíen registros cuando tengan problemas de autenticación. Tenga en cuenta que MSAL no almacena ningún registro y emite registros al destino proporcionado en la implementación del registrador.

Niveles de registro

Hay varios niveles de detalle de registro:

• LogAlways: Nivel básico que incluye registros de métricas de estado importantes para ayudar en el diagnóstico de las operaciones de MSAL.
• Critical: Registros que describen un fallo irrecuperable de la aplicación o del sistema, o un fallo catastrófico que requiere atención inmediata.
• Error: indica que algo ha ido mal y se generó un error. Se usa para depurar e identificar problemas.
• Warning: Incluye registros en casos en los que no necesariamente se ha producido un error o un fallo, sino que están destinados al diagnóstico y la localización de problemas. Este es el nivel mínimo recomendado que se debe habilitar en las aplicaciones de producción.
• Informational: MSAL registrará eventos con fines informativos, no necesariamente destinados a la depuración.
• Verbose: MSAL registra los detalles completos del comportamiento de la biblioteca. En un entorno de producción, el nivel «verbose» solo debe habilitarse temporalmente para recopilar registros con un fin específico de depuración.

Datos personales y organizativos

De forma predeterminada, el registrador de MSAL no captura ningún dato personal o organizativo altamente confidencial. La biblioteca proporciona la opción de habilitar el registro de datos personales y organizativos si decide hacerlo. Para obtener más información, consulte Control de información de identificación personal en MSAL.NET.

Configurar el registro en MSAL.NET

En MSAL, el registro se establece durante la creación de la aplicación mediante el WithLogging(IIdentityLogger, Boolean) generador. Este método toma los parámetros siguientes:

• identityLoggeres la implementación de registro utilizada por MSAL.NET para generar registros con fines de depuración o comprobación de estado. Los registros solo se envían si el registro está habilitado.
• enablePiiLogging habilita el registro de datos personales y organizativos (PII) si se establece en true. De forma predeterminada, este parámetro se establece en false, de modo que la aplicación no registre datos confidenciales.

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

Implementación de IIdentityLogger

Nivel de registro desde un archivo de configuración

Se recomienda encarecidamente configurar el código para que use un archivo de configuración en el entorno para establecer el nivel de registro, ya que permitirá que el código cambie el nivel de registro de MSAL sin necesidad de volver a compilar o reiniciar la aplicación. Esto es fundamental para fines de diagnóstico, lo que permite recopilar rápidamente los registros necesarios de la aplicación que se implementa actualmente en producción. El registro «verbose» puede resultar costoso, por lo que es mejor utilizar el nivel Informational de forma predeterminada y habilitar el registro «verbose» cuando se detecte un problema. Consulte el proveedor de configuración JSON para obtener un ejemplo sobre cómo cargar datos desde un archivo de configuración sin reiniciar la aplicación.

Nivel de registro desde una variable de entorno

Otra opción que se recomienda es configurar el código para que use una variable de entorno en la máquina para establecer el nivel de registro, ya que permitirá que el código cambie el nivel de registro de MSAL sin necesidad de volver a generar la aplicación.

Consulte EventLogLevel para obtener más información sobre los niveles de registro disponibles.

Ejemplo:

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

Uso de MyIdentityLogger:

MyIdentityLogger myLogger = new MyIdentityLogger();

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

Inicio de sesión en una caché distribuida de tokens

Si usa serializadores de la caché de tokens del paquete Microsoft.Identity.Web.TokenCache en .NET, puede habilitar registros adicionales de caché.

Para habilitar el registro de caché distribuida, establezca la propiedad MinLevel en Debug.

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

Consulte Implementación de un proveedor de registro personalizado para obtener más detalles.

Identificador de correlación

Los registros ayudan a comprender el comportamiento de MSAL en el lado cliente. Para comprender lo que sucede en el lado del servicio, el equipo necesita un identificador de correlación. Este identificador realiza un seguimiento de una solicitud de autenticación a través de los distintos servicios back-end.

El identificador de correlación se puede obtener de tres maneras:

1. A partir de un resultado de autenticación correcto: AuthenticationResult.CorrelationId.
2. Desde una excepción de servicio: MsalException.CorrelationId.
3. Al pasar un identificador de correlación personalizado a WithCorrelationId(Guid) al compilar una solicitud de token.

Al proporcionar su propio identificador de correlación, use un valor de identificador diferente para cada solicitud. No use una constante, ya que no podremos diferenciar entre las solicitudes.

Seguimientos de red

En los casos en los que los registros detallados no proporcionan información suficiente, puede obtener un seguimiento de red mediante herramientas como Fiddler o mitmproxy. Puede configurar la herramienta que prefiera para que sea un proxy local y aceptar el tráfico desde dispositivos de la red local, lo que le permite capturar seguimientos de otros dispositivos, como teléfonos iPhone o Android. Es posible que se requiera una configuración específica de la plataforma antes de capturar registros.

Si esta herramienta no es posible usar, puede modificar la HttpClient usada por MSAL para registrar el tráfico HTTP. Para obtener referencia, consulte esta implementación personalizada HttpClient con el registro.

Se puede añadir un HttpClient personalizado de la siguiente manera:

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

Seguimientos de red al usar WAM

Para recopilar seguimientos de red para el Administrador de cuentas web (WAM) en Windows con Fiddler, se necesitan algunos pasos adicionales.

1. Habilite el bucle invertido de AppContainer en Fiddler haciendo clic en WinConfig, seleccionando Excluir todo y guardando los cambios.

2. Habilite el descifrado HTTPS, pero excluya ADFS (msft.sts.microsoft.com) del descifrado HTTPS: