Adquirir e armazenar tokens em cache usando a MSAL (Biblioteca de Autenticação da Microsoft)

  • Artigo

Os tokens de acesso permitem que os clientes chamem com segurança as APIs Web protegidas pelo Azure. Há muitas maneiras de adquirir um token usando a MSAL (Biblioteca de Autenticação da Microsoft). Algumas exigem a interação do usuário por meio de um navegador da Web, enquanto outras não exigem interação do usuário. Geralmente, o método usado para adquirir um token dependerá se o aplicativo for um aplicativo cliente público (para desktop ou dispositivo móvel) ou um aplicativo cliente confidencial (aplicativo Web, API Web ou aplicativo daemon)

A MSAL armazena um token em cache após ele ter sido adquirido. O código do aplicativo deve primeiro tentar obter um token silenciosamente do cache antes de tentar adquirir um token por outros meios.

Você também pode limpar o cache do token ao remover as contas armazenadas nele. No entanto, isso não remove o cookie de sessão que está no navegador.

Escopos ao adquirir tokens

Escopos são as permissões que uma API Web expõe para que os aplicativos cliente possam solicitar acesso. Os aplicativos cliente solicitam o consentimento do usuário para esses escopos quando fazem solicitações de autenticação para obter tokens para acessar as APIs da Web. A MSAL permite que você obtenha tokens para acessar as APIs da plataforma de identidade da Microsoft. O protocolo v2.0 usa escopos em vez de recursos nas solicitações. Com base na configuração da API Web da versão do token que ela aceita, o ponto de extremidade da v2.0 retorna o token de acesso à MSAL.

Vários métodos de aquisição de token do MSAL exigem um parâmetro scopes. O parâmetro scopes é uma lista de cadeias de caracteres que declaram as permissões e os recursos desejados que são solicitados. Escopos bem conhecidos são as permissões do Microsoft Graph.

Solicitar escopos para uma API Web

Quando o aplicativo precisar solicitar tokens com permissões específicas para uma API de recursos, passe os escopos que contêm o URI da ID do aplicativo da API no formato <app ID URI>/<scope>.

Alguns exemplos de valores de escopo para diferentes recursos:

  • API do Microsoft Graph: https://graph.microsoft.com/User.Read
  • API Web personalizada: api://11111111-1111-1111-1111-111111111111/api.read

O formato do valor do escopo varia de acordo com o recurso (a API) que recebe o token de acesso e os valores da declaração aud que ele aceita.

Somente para Microsoft Graph, o escopo user.read é mapeado para https://graph.microsoft.com/User.Read, e ambos os formatos de escopo podem ser usados de forma intercambiável.

Determinadas APIs Web, como a API do Azure Resource Manager (https://management.core.windows.net/) exigem uma barra à direita (/) na declaração do público-alvo (aud) do token de acesso. Neste caso, passe o escopo como https://management.core.windows.net//user_impersonation, incluindo a barra dupla à direita (//).

Outras APIs podem exigir que nenhum esquema ou host seja incluído no valor do escopo e espere apenas a ID do aplicativo (um GUID) e o nome do escopo, como por exemplo:

11111111-1111-1111-1111-111111111111/api.read

Dica

Se o recurso downstream não estiver sob controle, talvez seja necessário tentar diferentes formatos de valor de escopo (por exemplo, com/sem esquema e host) se você receber 401 ou outros erros ao passar o token de acesso para o recurso.

Conforme os recursos fornecidos pelo aplicativo ou requisitos mudam, você pode solicitar permissões adicionais, conforme necessário, usando o parâmetro de escopo. Esses escopos dinâmicos permitem que os usuários forneçam consentimento incremental para escopos.

Por exemplo, você pode conectar o usuário, mas inicialmente negar acesso a todos os recursos. Posteriormente, você pode oferecer ao usuário permissão para exibir o calendário dele solicitando o escopo do calendário nos métodos de token de aquisição e obter o consentimento do usuário para tal. Por exemplo, solicitando os escopos https://graph.microsoft.com/User.Read e https://graph.microsoft.com/Calendar.Read.

Adquirir tokens silenciosamente (do cache)

A MSAL mantém um cache de token (ou dois caches para aplicativos cliente confidenciais) e armazena um token em cache após ele ser adquirido. Em muitos casos, a tentativa de obter um token silenciosamente adquirirá outro token com mais escopos tendo como base um token armazenado no cache. Além disso, a MSAL também pode atualizar um token quando a expiração estiver próxima (pois o cache de tokens também contém um token de atualização).

O código-fonte do aplicativo deve primeiro tentar obter um token silenciosamente a partir do cache. Se a chamada do método retornar um erro ou exceção "IU necessária", tente adquirir um token por outros meios.

Há dois procedimentos nos quais você não deve tentar obter um token de forma silenciosa:

  • Fluxo de credenciais de cliente, que não usa o cache de token do usuário, mas usa um cache de token do aplicativo. Esse método se encarrega de verificar o cache de token do aplicativo antes de enviar uma solicitação ao STS (serviço de token de segurança).
  • Fluxo de código de autorização em aplicativos Web já que ele resgata o código obtido pelo aplicativo quando ele realizou a conexão do usuário e deu consentimento para mais escopos. Como um código, e não uma conta, é passado como parâmetro, o método não pode procurar no cache antes de resgatar o código, o que invoca uma chamada para o serviço.

Para aplicativos Web que utilizam o fluxo de código de autorização OpenID Connect, o padrão sugerido para os controladores é:

  • Instancie um aplicativo cliente confidencial com um cache de tokens com serialização personalizada.
  • Adquira o token usando o fluxo do código de autorização

Adquirir tokens

O método de aquisição de um token variará se ele for um aplicativo cliente público ou confidencial.

Aplicativos cliente públicos

Em aplicativos cliente públicos (para desktop e aplicativos móveis), você pode:

  • Obter tokens interativamente fazendo com que o usuário entre pela interface do usuário ou por uma janela pop-up.
  • Obter um token silenciosamente para o usuário conectado usando a IWA/Kerberos (autenticação integrada do Windows) se o aplicativo da área de trabalho estiver sendo executado em um computador Windows associado a um domínio ou ao Azure.
  • Obter um token com um nome de usuário e uma senha em aplicativos cliente de desktop do .NET Framework (não recomendado). Não use o nome de usuário e senha em aplicativos cliente confidenciais.
  • Obter um token por meio do fluxo de código do dispositivo em aplicativos executados em dispositivos que não têm um navegador da Web. O usuário recebe uma URL e um código. Depois, ele acessa um navegador da Web em outro dispositivo, insere o código e entra. Em seguida, o Microsoft Entra ID envia um token de volta ao dispositivo sem navegador.

Aplicativos cliente confidenciais

Para aplicativos cliente confidenciais (aplicativo Web, API Web ou aplicativo daemon, como um serviço Windows), você pode:

  • Adquire tokens para o próprio aplicativo e não para um usuário utilizando o fluxo de credenciais de cliente. Essa técnica pode ser usada para ferramentas de sincronização ou ferramentas que processam usuários em geral e não um usuário específico.
  • Use o fluxo OBO (on-behalf-of) para uma API Web para chamar uma API em nome do usuário. O aplicativo é identificado com as credenciais do cliente para adquirir um token com base na declaração de um usuário (SAML, por exemplo, ou um token JWT). Esse fluxo é usado por aplicativos que precisam acessar recursos de um usuário específico em chamadas de serviço a serviço. Os tokens devem ser armazenados em cache em uma sessão, não com base nos usuários.
  • Adquira tokens usando o fluxo de código de autorização em aplicativos Web depois que o usuário entrar usando a URL de solicitação de autorização. O aplicativo do OpenID Connect geralmente usa esse mecanismo que permite ao usuário entrar usando o Open ID Connect e acessar as APIs Web em nome do usuário. Os tokens podem ser armazenados em cache em um usuário ou em uma sessão. Se os tokens de cache forem armazenados em cache em uma base de usuário, recomendamos limitar o tempo de vida da sessão para que a ID do Microsoft Entra possa verificar o estado das políticas de Acesso Condicional com frequência.

Resultados da autenticação

Quando seu cliente solicita um token de acesso, o Microsoft Entra ID também retorna um resultado da autenticação que inclui metadados sobre o token de acesso. Essas informações incluem a data de expiração do token de acesso e os escopos para os quais ele é válido. Esses dados permitem ao aplicativo realizar o cache inteligente dos tokens de acesso sem precisar analisar o token de acesso em si. O resultado da autenticação expõe:

  • O token de acesso da API Web para acessar os recursos. Essa cadeia de caracteres geralmente é um JWT codificado em Base64, mas o cliente nunca deve explorar o token de acesso. Não há garantia de que o formato permaneça estável e pode ser criptografado para o recurso. A gravação de código que depende do conteúdo do token de acesso no cliente é uma das origens mais comuns de erros e quebras de lógica do cliente.
  • O token de ID para o usuário (um JWT).
  • A expiração do token, que informa a data/hora da expiração do token.
  • A ID do locatário contém o locatário no qual o usuário foi encontrado. Para usuários convidados (cenários B2B do Microsoft Entra), a ID do locatário é o locatário convidado e não o locatário exclusivo. Quando o token é entregue em nome de um usuário, o resultado da autenticação também contém informações sobre esse usuário. Para fluxos de clientes confidenciais em que os tokens são solicitados sem nenhum usuário (para o aplicativo), essas informações sobre o usuário são nulas.
  • Os escopos para os quais o token foi emitido.
  • A ID exclusiva para o usuário.

(Avançado) Acessar os tokens em cache do usuário em aplicativos e serviços em segundo plano

Você pode usar a implementação de cache de token do MSAL para permitir que aplicativos, APIs e serviços em segundo plano usem o cache de token de acesso para continuar atuando em nome dos usuários na sua ausência. Fazer isso é especialmente útil quando os aplicativos e serviços em segundo plano precisam continuar a trabalhar em nome do usuário depois que este sai do aplicativo Web de front-end.

Atualmente, a maioria dos processos em segundo plano usa permissões de aplicativo quando precisam trabalhar com os dados de um usuário sem que este esteja presente para se autenticar ou reautenticar. Como as permissões de aplicativo geralmente exigem o consentimento do administrador, o que requer elevação de privilégio, ocorre um conflito desnecessário porque o desenvolvedor não pretendia obter outra permissão além da que o usuário originalmente concedeu para seu aplicativo.

Este exemplo de código do GitHub mostra como evitar esse conflito desnecessário pelo acesso ao cache de token do MSAL a partir de aplicativos em segundo plano:

Acessar o cache de token do usuário conectado a partir de aplicativos, APIs e serviços em segundo plano

Confira também

Várias das plataformas com suporte da MSAL têm informações adicionais relacionadas ao cache de token na documentação da biblioteca dessa plataforma. Por exemplo: