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. Em geral, o método usado para adquirir um token depende se o aplicativo é um aplicativo cliente público, como aplicativo de desktop ou móvel, ou um aplicativo cliente confidencial, como 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, o que é conseguido 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 o Azure AD para desenvolvedores (v1.0) e 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 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.

Também é possível no MSAL acessar recursos v1.0. Para obter mais informações, consulte Escopos para um aplicativo v1.0.

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://11111111-1111-1111-1111-111111111111/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:

11111111-1111-1111-1111-111111111111/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, no entanto, nos quais você não deve tentar adquirir silenciosamente um token:

  • 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

Geralmente, 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, como aplicativos de desktop e móveis, 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 desktop .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 Azure AD 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.
  • 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 Open ID connect e, em seguida, acesse APIs da Web em nome do usuário.

Resultados da autenticação

Quando seu cliente solicita um token de acesso, o Azure AD 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 B2B do Azure AD), 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.