Supervisión de aplicaciones mediante MSAL.NET

Para asegurarse de que los servicios de autenticación que usan MSAL.NET se ejecutan correctamente, MSAL proporciona muchas maneras de supervisar su comportamiento para que los problemas se puedan identificar y solucionar antes de que se produzcan en producción. El uso incorrecto de MSAL (en relación con el ciclo de vida y la memoria caché del token) no conduce a errores inmediatos, pero a veces se propagarán bajo escenarios de tráfico elevado después de que la aplicación esté en producción durante un período de tiempo.

Por ejemplo, si solo se usa una instancia de una aplicación cliente confidencial y MSAL no está configurado para serializar la caché de tokens, la memoria caché crecerá para siempre. Surge otro problema al crear una nueva aplicación de cliente confidencial y no utilizar la caché, lo que dará lugar a problemas como la limitación de tráfico por parte del proveedor de identidad. Para obtener recomendaciones sobre cómo usar MSAL correctamente, consulte Alta disponibilidad.

Logging

Una de las herramientas que proporciona MSAL para combatir problemas de producción es registrar errores cuando MSAL no está configurado correctamente. Es fundamental habilitar el registro siempre que sea posible para supervisar los registros de errores y ayudar en el diagnóstico de eventos problemáticos. Consulte Registro en MSAL.NET para obtener más información.

Los errores siguientes se registrarán en MSAL:

• Cuando se usa una autoridad que termina en /common o /organizations para la autenticación mediante credenciales de cliente (AcquireTokenForClient(IEnumerable<String>)).
  • La autoridad actual apunta al punto final /common o /organizations, lo cual no se recomienda. Consulte Flujos de credenciales de cliente para obtener más detalles.
• Cuando se usa la caché de tokens interna predeterminada mientras se usan aplicaciones cliente confidenciales.
  • La caché de tokens predeterminada proporcionada por MSAL no está diseñada para ser eficaz cuando se usa en aplicaciones cliente confidenciales. Consulte Serialización de caché de tokens en MSAL.NET para obtener más detalles.

Metrics

Además del registro, MSAL ofrece métricas importantes en AuthenticationResult.AuthenticationResultMetadata. Consulte Adición de supervisión en torno a las operaciones de MSAL para obtener más detalles.

• DurationTotalInMs : tiempo total invertido en la adquisición de un token de MSAL, incluidas las llamadas de red y las operaciones de caché. Cree una alerta sobre una latencia alta general (más de 1 segundo). Tenga en cuenta que la primera llamada de adquisición de tokens siempre realiza una llamada HTTP adicional.

• DurationInCacheInMs : tiempo dedicado a cargar o guardar la caché de tokens, que el desarrollador de aplicaciones personaliza (por ejemplo, guardar en Redis). Cree una alerta sobre picos.

  Note

  Para comprender cómo personalizar el almacenamiento en caché de tokens, consulte Serialización de caché de tokens en MSAL.NET.

• DurationInHttpInMs : tiempo dedicado a realizar llamadas HTTP al proveedor de identidades. Cree una alerta sobre picos.

• TokenSource: indica el origen del token, normalmente la memoria caché o el proveedor de identidades. Los tokens se recuperan de la memoria caché mucho más rápido (por ejemplo, ~100 ms frente a ~700 ms). Esta métrica se puede usar para supervisar la proporción de aciertos de caché.

• CacheRefreshReason : especifica el motivo para capturar el token de acceso del proveedor de identidades. Consulte CacheRefreshReason. Use junto con TokenSource.

• TokenEndpoint - el URI real del punto de conexión del token que se usa para obtener el token. Resulta útil para comprender cómo MSAL resuelve el inquilino en llamadas silenciosas y la región en llamadas regionales.

  Note

  La regionalización solo está disponible para aplicaciones Microsoft internas.

• RegionDetails : los detalles sobre la región que se usa para realizar una llamada, como la región usada y cualquier error de detección automática.

  Note

  La regionalización solo está disponible para aplicaciones Microsoft internas.

OpenTelemetry

A partir de MSAL 4.58.0, la biblioteca admite OpenTelemetry : un conjunto de API que permiten instrumentar, generar y recopilar datos de telemetría de forma coherente y estandarizada. Para empezar, asegúrese de que;

1. Instale la versión más reciente de MSAL.NET.
2. Agregue la dependencia del paquete OpenTelemetry al proyecto.
3. Agregue una dependencia de exportador que le permita exportar registros, por ejemplo, el exportador de consola para OpenTelemetry.NET.

En el código de inicialización de la aplicación, antes de arrancar el cliente de autenticación MSAL (por ejemplo, PublicClientApplication o ConfidentialClientApplication), declare una nueva MeterProvider instancia mediante el código siguiente.

using var meterProvider = Sdk.CreateMeterProviderBuilder()
    .AddMeter("MicrosoftIdentityClient_Common_Meter")
    .AddConsoleExporter()
    .Build();

Esto inicializará el proveedor de medidores y usará el medidor integrado MSAL.NET (MicrosoftIdentityClient_Common_Meter) que captura una serie de contadores y histogramas. Cuando se usa un exportador de consola, debería ver la salida redirigida directamente al terminal:

En la sección siguiente se describen los contadores y histogramas admitidos para el medidor predeterminado.

Counters

msalsuccess_counter

Contador para registrar la agregación de solicitudes correctas en MSAL.

Metadata

msalfailure_counter

Contador para registrar la agregación de solicitudes fallidas en MSAL.

Metadata

Histogramas

MsalTotalDuration_1a_histogram

Histograma para capturar la latencia total en milisegundos para la adquisición de tokens a través de MSAL.

Metadata

MsalDurationInL1CacheInUs_1b_histogram

Histograma para capturar la latencia cuando se usa una caché L1. Los valores están en microsegundos para la adquisición de tokens mediante MSAL.

Metadata

MsalDurationInL2Cache_1a_histogram

Histograma para capturar la latencia de caché L2 en milisegundos para la adquisición de tokens a través de MSAL.

Metadata

MsalDurationInHttp_1a_histogram

Histograma para capturar la latencia HTTP en milisegundos para la adquisición de tokens a través de MSAL.

Metadata

Información adicional

Para obtener información adicional sobre el uso de OpenTelemetry con aplicaciones de .NET, consulte .NET observabilidad con OpenTelemetry.