Partilhar via

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

  • Artigo

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

O MSAL armazena em cache um token depois que ele é 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 de token removendo as contas do cache. 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 da Web expõe às quais os aplicativos cliente podem solicitar acesso. Os aplicativos cliente solicitam o consentimento do usuário para esses escopos ao fazer solicitações de autenticação para obter tokens para acessar as APIs da Web. O MSAL permite que você obtenha tokens para acessar 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 da Web da versão do token que aceita, o ponto de extremidade v2.0 retorna o token de acesso ao MSAL.

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

Escopos de solicitação para uma API da Web

Quando seu aplicativo precisar solicitar um token de acesso com permissões específicas para uma API de recurso, passe os escopos que contêm o URI do 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 da Web personalizada: api://00001111-aaaa-2222-bbbb-3333cccc4444/api.read

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

Somente para o Microsoft Graph, o escopo é mapeado user.read 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/), esperam uma barra (/) na declaração de audiência (aud) do token de acesso. Nesse caso, passe o escopo como https://management.core.windows.net//user_impersonation, incluindo a barra dupla (//).

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

00001111-aaaa-2222-bbbb-3333cccc4444/api.read

Gorjeta

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

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

Por exemplo, você pode entrar no usuário, mas inicialmente negar-lhe acesso a quaisquer recursos. Mais tarde, você pode dar a eles a capacidade de visualizar seu calendário solicitando o escopo do calendário no método de token de aquisição e obtendo o consentimento do usuário para fazê-lo. Por exemplo, solicitando o e https://graph.microsoft.com/Calendar.Read escoposhttps://graph.microsoft.com/User.Read.

Adquirindo tokens silenciosamente (do cache)

O MSAL mantém um cache de token (ou dois caches para aplicativos cliente confidenciais) e armazena em cache um token após sua aquisição. Em muitos casos, tentar obter silenciosamente um token adquirirá outro token com mais escopos com base em um token no cache. Ele também é capaz de atualizar um token quando ele está se aproximando da expiração (já que o cache de token também contém um token de atualização).

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

Há dois fluxos em que você não deve tentar adquirir um token silenciosamente:

  • Fluxo de credenciais do cliente, que não usa o cache de token de usuário, mas um cache de token de aplicativo. Esse método cuida de verificar o cache de token de aplicativo antes de enviar uma solicitação para o serviço de token de segurança (STS).
  • O fluxo de código de autorização em aplicativos Web, pois resgata um código que o aplicativo obteve ao entrar no usuário e fazer com que ele consentisse com mais escopos. Como um código e não uma conta é passado como um parâmetro, o método não pode procurar no cache antes de resgatar o código, que invoca uma chamada para o serviço.

Para aplicativos Web que usam o fluxo de código de autorização do OpenID Connect, o padrão recomendado nos controladores é:

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

Adquirir tokens

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

Aplicações cliente públicas

Em aplicativos cliente públicos (desktop e mobile), você pode:

  • Obtenha tokens interativamente fazendo com que o usuário entre por meio de uma interface do usuário ou janela pop-up.
  • Obtenha um token silenciosamente para o usuário conectado usando a autenticação integrada do Windows (IWA/Kerberos) se o aplicativo da área de trabalho estiver sendo executado em um computador Windows associado a um domínio ou ao Azure.
  • Obtenha um token com um nome de usuário e senha em aplicativos cliente de área de trabalho do .NET Framework (não recomendado). Não use nome de usuário/senha em aplicativos cliente confidenciais.
  • Obtenha um token através 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, que então vai para um navegador da Web em outro dispositivo e insere o código e faz login. Em seguida, o Microsoft Entra ID envia um token de volta para o dispositivo sem navegador.

Aplicações de cliente confidenciais

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

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

Resultados da autenticação

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

  • O token de acesso para a API da Web acessar recursos. Essa cadeia de caracteres geralmente é um JWT codificado em Base64, mas o cliente nunca deve olhar para dentro do token de acesso. Não é garantido que o formato permaneça estável e pode ser criptografado para o recurso. As pessoas que escrevem código dependendo do conteúdo do token de acesso no cliente é uma das fontes mais comuns de erros e quebra 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 em que o token expira.
  • O ID do locatário contém o locatário no qual o usuário foi encontrado. Para usuários convidados (cenários do Microsoft Entra B2B), a ID do locatário é o locatário convidado, não o locatário exclusivo. Quando o token é entregue no 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 usuário (para o aplicativo), essas informações do usuário são nulas.
  • Os escopos para os quais o token foi emitido.
  • O ID exclusivo para o usuário.

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

Você pode usar a implementação do 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 a agir em nome dos usuários na ausência deles. Isso é especialmente útil se os aplicativos e serviços em segundo plano precisarem continuar a funcionar em nome do usuário depois que ele sair do aplicativo Web front-end.

Hoje, a maioria dos processos em segundo plano usa permissões de aplicativo quando precisam trabalhar com os dados de um usuário sem que eles estejam presentes para autenticar ou reautenticar. Como as permissões de aplicativos geralmente exigem o consentimento do administrador, o que requer elevação de privilégio, atrito desnecessário é encontrado, pois o desenvolvedor não pretendia obter permissão além daquela que o usuário originalmente consentiu para seu aplicativo.

Este exemplo de código no GitHub mostra como evitar esse atrito desnecessário acessando o cache de token do MSAL a partir de aplicativos em segundo plano:

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

Consulte também

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