Monitorização de aplicações usando MSAL.NET

Para garantir que os serviços de autenticação que utilizam MSAL.NET estão a correr corretamente, o MSAL oferece várias formas de monitorizar o seu comportamento, de modo a identificar e resolver problemas antes de ocorrerem em produção. O uso incorreto do MSAL (no que diz respeito ao ciclo de vida dos tokens e cache) não leva a falhas imediatas, no entanto, por vezes surgem em situações de alto tráfego após a aplicação estar em produção durante algum tempo.

Por exemplo, se apenas uma instância de uma aplicação cliente confidencial for usada e o MSAL não estiver configurado para serializar a cache do token, a cache crescerá para sempre. Outro problema surge ao criar uma nova aplicação cliente confidencial e não utilizar a cache, o que pode levar a problemas como limitação por parte do fornecedor de identidade. Para recomendações sobre como utilizar o MSAL de forma adequada, consulte Alta Disponibilidade.

Logging

Uma das ferramentas que o MSAL oferece para combater problemas de produção é registar erros quando o MSAL não está devidamente configurado. É fundamental permitir o registo sempre que possível para monitorizar os registos em busca de erros e ajudar no diagnóstico de eventos problemáticos. Consulte Iniciar sessão no MSAL.NET para mais detalhes.

Os seguintes erros serão registados em MSAL:

• Ao usar uma autoridade que termina em /common ou /organizations para autenticação de credenciais do cliente (AcquireTokenForClient(IEnumerable<String>)).
  • A autoridade atual aponta para o ponto final /common ou /organizations, o que não é recomendado. Consulte Fluxos de credenciais para clientes para mais detalhes.
• Quando a cache interna de token predefinida é usada ao utilizar aplicações cliente confidenciais.
  • A cache de tokens padrão fornecida pela MSAL não é concebida para ser eficaz quando usada em aplicações cliente confidenciais. Consulte a serialização da cache de token no MSAL.NET para mais detalhes.

Metrics

Para além do registo, o MSAL disponibiliza métricas importantes em AuthenticationResult.AuthenticationResultMetadata. Consulte Adicionar monitorização às operações do MSAL para mais informações.

• DurationTotalInMs - tempo total despendido pelo MSAL a adquirir um token, incluindo chamadas de rede e operações na cache. Crie um alerta sobre latência global elevada (mais de 1 segundo). Note-se que a primeira chamada de aquisição de token normalmente faz uma chamada HTTP extra.

• DurationInCacheInMs - tempo gasto a carregar ou guardar a cache de tokens, que é personalizada pelo programador da aplicação (por exemplo, guardar no Redis). Crie um alerta sobre os picos.

  Note

  Para compreender como personalizar a cache de tokens, veja Serialização da cache de tokens no MSAL.NET.

• DurationInHttpInMs - tempo gasto a fazer chamadas HTTP ao fornecedor de identidade. Crie um alerta sobre os picos.

• TokenSource- indica a origem do token - tipicamente a cache ou o fornecedor de identidade. Os tokens são recuperados da cache muito mais rapidamente (por exemplo, ~100 ms contra ~700 ms). Esta métrica pode ser usada para monitorizar a taxa de acerto do cache.

• CacheRefreshReason - especifica a razão para obter o token de acesso junto do fornecedor de identidade. Consulte CacheRefreshReason. Usar em conjunto com TokenSource.

• TokenEndpoint - o URI real do endpoint do token usado para obter o token. Útil para compreender como o MSAL resolve o locatário nas chamadas silenciosas e a região nas chamadas regionais.

  Note

  A regionalização está disponível apenas para aplicações internas da Microsoft.

• RegionDetails - os detalhes sobre a região utilizada para a chamada, como a região utilizada e qualquer erro de autodeteção.

  Note

  A regionalização está disponível apenas para aplicações internas da Microsoft.

OpenTelemetry

A partir do MSAL 4.58.0, a biblioteca suporta o OpenTelemetry – um conjunto de APIs que permitem instrumentação, geração e recolha de dados de telemetria de forma consistente e padronizada. Para começar, certifique-se de que;

1. Instale a versão mais recente do MSAL.NET.
2. Adicione a dependência do pacote OpenTelemetry ao seu projeto.
3. Adiciona uma dependência do exportador, que permite exportar registos, por exemplo, o exportador de consola para OpenTelemetry.NET.

No seu código de inicialização da aplicação, antes de iniciar o cliente de autenticação MSAL (por exemplo, PublicClientApplication ou ConfidentialClientApplication), declare uma nova MeterProvider instância, usando o seguinte código.

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

Isto irá inicializar o fornecedor de métricas e utilizar a métrica incorporada do MSAL.NET (MicrosoftIdentityClient_Common_Meter), que recolhe um conjunto de contadores e histogramas. Quando se utiliza um exportador de consola, deverá ver a saída a ser enviada diretamente no terminal:

A secção seguinte descreve os contadores e histogramas suportados para o medidor padrão.

Counters

msalsuccess_counter

Contador para registar a agregação de pedidos com êxito no MSAL.

Metadata

msalfailure_counter

Contador para captar a agregação de pedidos com falha no MSAL.

Metadata

Histogramas

MsalTotalDuration_1a_histogram

Histograma para captar a latência total em milissegundos para aquisição de tokens através da MSAL.

Metadata

MsalDurationInL1CacheInUs_1b_histogram

Histograma para captar latência quando é usada uma cache L1. Os valores estão em microssegundos para aquisição de tokens através da MSAL.

Metadata

MsalDurationInL2Cache_1a_histogram

Histograma para captar a latência do cache L2 em milissegundos para aquisição de tokens através do MSAL.

Metadata

MsalDurationInHttp_1a_histogram

Histograma para capturar a latência HTTP em milissegundos para aquisição de tokens através de MSAL.

Metadata

Informações adicionais

Para informações adicionais sobre a utilização do OpenTelemetry em aplicações .NET, consulte a observabilidade .NET com OpenTelemetry.