Fluxos de autenticação suportados no MSAL

A Microsoft Authentication Library (MSAL) oferece suporte a várias concessões de autorização e fluxos de token associados para uso por diferentes tipos de aplicativos e cenários.

Fluxo de autenticação	Habilita	Tipos de aplicativos com suporte
Código de autorização	Login do usuário e acessar APIs da Web em nome do usuário.	* Desktop * Móvel * SPA (aplicativo de página única) (requer PKCE) * Web
Credenciais de cliente	Acesso a APIs Web usando a identidade do próprio aplicativo. Normalmente usado para comunicação de servidor para servidor e scripts automatizados que não exigem interação com o usuário.	Daemon
Código do dispositivo	Entrada do usuário e acesso a APIs da Web em nome do usuário em dispositivos com restrição de entrada, como smart TVs e dispositivos de Internet das Coisas (IoT). Também usado por aplicativos de CLI (interface de linha de comando).	Desktop, Móvel
Concessão implícita	Entrada do usuário e acesso a APIs Web em nome do usuário. O fluxo de concessão implícito não é mais recomendado - use o código de autorização com PKCE (Proof Key for Code Exchange).	* SPA (aplicativo de página única) * Web
OBO (On-Behalf-Of)	Acesse em uma API Web "upstream" para uma API Web "downstream" em nome do usuário. A identidade do usuário e as permissões delegadas são passadas da API upstream para a API downstream.	API Web
Nome de usuário/senha (ROPC)	Permite que um aplicativo conecte o usuário, processando diretamente a senha dele. O fluxo ROPC não é recomendado.	Desktop, Móvel
IWA (Autenticação Integrada do Windows)	Permite que aplicativos no domínio ou computadores ingressados no Microsoft Entra ID adquiram um token silenciosamente (sem qualquer interação de interface do usuário do usuário).	Desktop, Móvel

Tokens

O aplicativo pode usar um ou mais fluxos de autenticação. Cada fluxo usa determinados tipos de token para autenticação, autorização e atualização de token e alguns também usam um código de autorização.

Ação ou fluxo de autenticação	Exige	token de ID	Token de acesso	Token de atualização	Código de Autorização
Fluxo do código de autorização		✅	✅	✅	✅
Credenciais de cliente			✅ (somente aplicativo)
Fluxo de código do dispositivo		✅	✅	✅
Fluxo implícito		✅	✅
Fluxo em-nome-de	Token de acesso	✅	✅	✅
Nome de usuário/senha (ROPC)	Nome de usuário, senha	✅	✅	✅
Fluxo de OIDC híbrido		✅			✅
Resgate de token de atualização	Token de atualização	✅	✅	✅

Autenticação interativa e não interativa

Vários desses fluxos dão suporte à aquisição de tokens interativa e não interativa.

• Interativo – O usuário pode ser solicitado a inserir a entrada pelo servidor de autorização. Por exemplo, execute a MFA (autenticação multifator) para entrar ou para dar consentimento a mais permissões de acesso a recursos.
• Não interativo – O usuário pode não ser solicitado a inserir a entrada. Também chamada de aquisição silenciosa de token, o aplicativo tenta obter um token usando um método no qual o servidor de autorização pode não solicitar a entrada do usuário.

O aplicativo baseado em MSAL deve primeiro tentar adquirir um token silenciosamente e retornar ao método interativo somente se a tentativa não interativa falhar. Para mais informações sobre esse padrão, consulte Adquirir e armazenar tokens em cache usando a Biblioteca de Autenticação da Microsoft (MSAL).

Código de Autorização

A concessão de código de autorização OAuth 2.0 pode ser usada por aplicativos Web, aplicativos de página única (SPA) e aplicativos nativos (móveis e desktop) para obter acesso a recursos protegidos, como APIs da Web.

Quando os usuários entram em aplicativos Web, o aplicativo recebe um código de autorização que ele pode resgatar para que um token de acesso chame APIs Web.

No diagrama anterior, o aplicativo:

1. Solicita um código de autorização, que é resgatado para um token de acesso.
2. Usa o token de acesso para chamar uma API da Web, como o Microsoft Graph.

Restrições do código de autorização

• Os aplicativos de página única exigem a PKCE (Chave de Prova para Troca de Código) ao usar o fluxo de concessão de código de autorização. Há suporte para a PKCE na MSAL.

• A especificação do OAuth 2.0 requer que você use um código de autorização para resgatar um token de acesso apenas uma vez.

  Se você tentar adquirir um token de acesso várias vezes com o mesmo código de autorização, um erro semelhante ao seguinte será retornado pela plataforma de identidade da Microsoft. Lembre-se que algumas bibliotecas e estruturas solicitam o código de autorização automaticamente e a solicitação manual de um código, nesses casos, também resultará nesse erro.

  AADSTS70002: Error validating credentials. AADSTS54005: OAuth2 Authorization code was already redeemed, please retry with a new valid code or use an existing refresh token.

Credenciais do cliente

O fluxo de credenciais do cliente OAuth 2 permite acessar recursos hospedados na Web usando a identidade de um aplicativo. Esse tipo de concessão é comumente usado para interações de servidor para servidor (S2S) que devem ser executadas em segundo plano, sem interação imediata de um usuário. Esses tipos de aplicativos são frequentemente chamados de daemons ou serviços.

O fluxo de concessão de credenciais do cliente permite que um serviço Web (um cliente confidencial) use suas próprias credenciais, em vez de representar um usuário, para autenticar ao chamar outro serviço Web. Nesse cenário, o cliente é geralmente um serviço Web de camada intermediária, um serviço daemon ou um site. Para um nível mais alto de garantia, a plataforma de identidade da Microsoft também permite que o serviço de chamada use um certificado (em vez de um segredo compartilhado) como uma credencial.

Segredos do aplicativo

No diagrama anterior, o aplicativo:

1. Adquire um token usando um segredo de aplicativo ou credenciais de senha.
2. Usa o token para fazer solicitações de recursos.

Certificados

No diagrama anterior, o aplicativo:

1. Adquire um token usando credenciais de certificado.
2. Usa o token para fazer solicitações de recursos.

Esse tipo de credenciais de cliente precisa ser:

• Registradas no Azure AD.
• Transmitidas ao construir o objeto do aplicativo cliente confidencial em seu código.

Restrições das credenciais do cliente

O fluxo de cliente confidencial não é suportado em plataformas móveis como Android, iOS ou Plataforma Universal do Windows (UWP). Os aplicativos móveis são considerados aplicativos clientes públicos que são incapazes de garantir a confidencialidade dos segredos de autenticação.

Código do dispositivo

O fluxo de código do dispositivo OAuth 2 permite que os usuários entrem em dispositivos com restrição de entrada, como smart TVs, dispositivos de Internet das Coisas (IoT) e impressoras. A autenticação interativa com a ID do Microsoft Entra requer um navegador da Web. Quando o dispositivo ou sistema operacional não fornece um navegador da Web, o fluxo de código do dispositivo permite a possibilidade de usar outro dispositivo, como um computador ou celular, para entrar interativamente.

Com o fluxo de código do dispositivo, o aplicativo obtém tokens por meio de um processo de duas etapas projetado para esses dispositivos ou sistemas operacionais.

No diagrama anterior:

1. Sempre que a autenticação do usuário for necessária, o aplicativo fornece um código e solicita que o usuário use outro dispositivo (como um smartphone conectado à Internet) para acessar uma URL (por exemplo, https://microsoft.com/devicelogin). O usuário é então solicitado a inserir o código e prossegue com uma experiência de autenticação normal, incluindo prompts de consentimento e autenticação multifator, se necessário.
2. Após a autenticação bem-sucedida, o aplicativo solicitante recebe os tokens necessários da plataforma de identidade da Microsoft e os usa para executar as chamadas de API da Web de que precisa.

Restrições do código do dispositivo

• O fluxo de código do dispositivo só está disponível para aplicativos clientes públicos.
• Ao inicializar um aplicativo cliente público na MSAL, use um destes formatos de autoridade:
  • Baseado em locatário: https://login.microsoftonline.com/{tenant}/, onde {tenant} é o GUID que representa a ID do locatário ou um nome de domínio associado ao locatário.
  • Contas corporativas ou de estudante: https://login.microsoftonline.com/organizations/.

Concessão implícita

A concessão implícita foi substituída pelo fluxo do código de autorização com PKCE como o fluxo de concessão de token preferencial e mais seguro para SPAs (aplicativos de página única) no lado do cliente. Se você estiver criando um SPA, use o fluxo do código de autorização com PKCE.

Os aplicativos Web de página única gravados em JavaScript (incluindo estruturas como Angular, Vue.js ou React.js) são baixados no servidor e o código é executado diretamente no navegador. Como o código do lado do cliente é executado no navegador e não em um servidor Web, ele tem características de segurança diferentes dos aplicativos Web tradicionais do lado do servidor. Antes da disponibilidade da PKCE (Chave de Prova para Troca de Código) para o fluxo do código de autorização, o fluxo de concessão implícita foi usado pelo SPAs para melhorar a capacidade de resposta e a eficiência na obtenção de tokens de acesso.

O fluxo de concessão implícita do OAuth 2 permite ao aplicativo obter tokens de acesso da plataforma de identidade da Microsoft, sem realizar uma troca de credenciais do servidor back-end. O fluxo de concessão implícita permite que um aplicativo conecte o usuário, mantenha uma sessão e obtenha tokens para outras APIs Web de dentro do código JavaScript baixado e executado pelo agente do usuário (normalmente, um navegador da Web).

Restrições da concessão implícita

O fluxo de concessão implícita não inclui cenários de aplicativos que usam estruturas JavaScript de plataforma cruzada, como Electron ou React Native. Estruturas de plataforma cruzada como essas exigem recursos adicionais para interação com as plataformas nativas de desktop e dispositivos móveis nas quais são executadas.

Os tokens emitidos por meio do modo de fluxo implícito têm uma limitação de comprimento porque são retornados ao navegador na URL (onde response_mode é ou queryfragment). Alguns navegadores limitam o comprimento da URL na barra do navegador e falham quando ela é muito longa. Portanto, esses tokens de fluxo implícito não contêm declarações groups ou wids.

OBO (On-Behalf-Of)

O fluxo de fluxo de autenticação em nome do OAuth 2 é usado quando um aplicativo invoca um serviço ou API da Web que, por sua vez, precisa chamar outro serviço ou API da Web usando uma identidade de usuário delegada e permissões que precisam se propagar pela cadeia de solicitações. Para que o serviço de camada intermediária faça solicitações autenticadas para o serviço downstream, ele precisa proteger um token de acesso da plataforma de identidade da Microsoft em nome do usuário solicitante.

No diagrama anterior:

1. O aplicativo adquire um token de acesso para a API Web.
2. Um cliente (Web, área de trabalho, móvel ou aplicativo de página única) chama uma API Web protegida, adicionando o token de acesso como um token de portador ao cabeçalho de autenticação da solicitação HTTP. A API Web autentica o usuário.
3. Quando o cliente chama a API da Web, a API da Web solicita outro token em nome do usuário.
4. A API da Web protegida usa esse token para chamar uma API da Web downstream em nome do usuário. A API Web também pode solicitar tokens para outras APIs downstream (mas ainda em nome do mesmo usuário).

Nome de usuário/senha (ROPC)

Aviso

O fluxo de credenciais de senha do proprietário do recurso (ROPC) não é mais recomendado. O ROPC requer um alto grau de confiança e exposição da credencial. Use ROPC somente se um fluxo mais seguro não puder ser usado. Para saber mais, confira Qual é a solução para o problema crescente das senhas?.

A concessão de credenciais de senha de proprietário do recurso (RPOC) do OAuth 2 permite a um aplicativo conectar o usuário manipulando diretamente a senha dele. Em seu aplicativo de área de trabalho, é possível usar o fluxo de nome de usuário/senha para adquirir um token silenciosamente. Não é necessária uma interface do usuário ao usar o aplicativo.

Alguns cenários de aplicativos, como DevOps, podem achar o ROPC útil, mas você deve evitá-lo em qualquer aplicativo no qual você forneça uma interface do usuário interativa para entrada do usuário.

No diagrama anterior, o aplicativo:

1. Adquire um token ao enviar o nome de usuário e a senha ao provedor de identidade.
2. Chama a API Web usando o token.

Para adquirir um token silenciosamente em computadores ingressados no domínio do Windows, recomendamos usar o Gerenciador de Contas da Web (WAM) em vez de ROPC. Para outros cenários, use o fluxo de código do dispositivo.

Restrições do ROPC

As seguintes restrições se aplicam aos aplicativos que usam o fluxo ROPC:

• Não há suporte para o logon único.
• Não há suporte para a MFA (autenticação multifator).
  • Verifique com o administrador de locatários se a MFA é um recurso comumente usado, antes de usar esse fluxo.
• Não há suporte para o Acesso Condicional.
• O ROPC funciona apenas para contas corporativas e de estudante.
• Não há suporte para as MSAs (contas Microsoft) pessoais no ROPC.
• O ROPC é suportado em aplicativos .NET desktop e .NET.
• Não há suporte para o ROPC nos aplicativos da UWP (Plataforma Universal do Windows).
• ROPC no Microsoft Entra External ID é suportado apenas para contas locais.
  • Para obter informações sobre ROPC no MSAL.NET e Microsoft Entra External ID, consulte Resource Owner Password Credentials (ROPC) With B2C.

Autenticação integrada do Windows (IWA)

Observação

A Autenticação Integrada do Windows foi substituída por uma maneira mais confiável de obter tokens silenciosamente - WAM. O WAM pode fazer logon do usuário atual do Windows silenciosamente. Esse fluxo de trabalho não requer configuração complexa e funciona até mesmo para contas pessoais (Microsoft). Internamente, o Windows Broker (WAM) tentará várias estratégias para obter um token para o usuário atual do Windows, incluindo IWA e resgatar o PRT. Isso elimina a maioria das limitações com a IWA.

O MSAL oferece suporte à autenticação integrada do Windows (IWA) para aplicativos móveis e de área de trabalho que são executados em computadores Windows ingressados no domínio ou no Microsoft Entra ID. Usando a IWA, esses aplicativos adquirem um token silenciosamente, sem interação com a interface do usuário.

No diagrama anterior, o aplicativo:

1. Adquire um token usando a Autenticação Integrada do Windows.
2. Usa o token para fazer solicitações de recursos.

Restrições da IWA

• Compatibilidade. A autenticação integrada do Windows (IWA) está habilitada para aplicativos de área de trabalho .NET, .NET e UWP (Plataforma Universal do Windows). A IWA oferece suporte apenas a usuários federados pelo ADFS - usuários criados no Active Directory e com suporte do Microsoft Entra ID. Os usuários criados diretamente no Microsoft Entra ID, sem apoio do Active Directory (usuários gerenciados) não podem usar esse fluxo de autenticação.
• Autenticação multifator (MFA). A autenticação não interativa (silenciosa) da IWA pode falhar se a MFA estiver habilitada no locatário do Microsoft Entra ID e um desafio de MFA for emitido pelo Microsoft Entra ID. Se a IWA falhar, você deverá retornar a um método interativo de autenticação, conforme descrito anteriormente. O Microsoft Entra ID usa IA para determinar quando a autenticação de dois fatores é necessária. Normalmente, a autenticação de dois fatores é necessária quando um usuário se conecta em um país/região diferente, quando conectado a uma rede corporativa sem usar uma VPN e, às vezes, quando está conectado por meio de uma VPN. Como a configuração e a frequência de desafio do MFA podem estar fora de seu controle como desenvolvedor, seu aplicativo deve lidar normalmente com uma falha de aquisição silenciosa de token IWA.
• Restrições de URI de autoridade. A autoridade passada ao construir o aplicativo cliente público deve ser uma das:
  • https://login.microsoftonline.com/{tenant}/ - Essa autoridade indica um aplicativo de locatário único cujo público de entrada é restrito aos usuários no locatário de ID do Microsoft Entra especificado. O valor {tenant} pode ser a ID do locatário no formulário de GUID ou o nome de domínio associado ao locatário.
  • https://login.microsoftonline.com/organizations/ - Essa autoridade indica um aplicativo multilocatário cujo público de entrada são usuários em qualquer locatário do Microsoft Entra ID.
• Contas pessoais. Os valores de autoridade não devem conter /common ou /consumers porque as contas pessoais da Microsoft (MSA) não são suportadas pela IWA.
• Requisitos de consentimento. Como a IWA é um fluxo silencioso, o usuário do seu aplicativo deve ter consentido anteriormente em usar o aplicativo ou o administrador do locatário deve ter consentido previamente que todos os usuários no locatário usem o aplicativo. Para satisfazer qualquer um dos requisitos, uma destas operações deve ter sido concluída:
  • Você, como desenvolvedor do aplicativo, selecionou Conceder no Portal do Azure para si mesmo.
  • Um administrador de locatários selecionou Conceder/revogar consentimento do administrador para {domínio de locatário} na guia Permissões de API do registro do aplicativo no portal do Azure. Confira Adicionar permissões para acessar APIs Web.
  • Você forneceu uma maneira para os usuários consentirem com o aplicativo; consulte Visão geral de permissões e consentimento na plataforma de identidade da Microsoft.
  • Você forneceu uma maneira para o administrador do locatário consentir com o aplicativo; consulte Visão geral de permissões e consentimento na plataforma de identidade da Microsoft.

Próximas etapas

Agora que você analisou os fluxos de autenticação suportados pelo MSAL, saiba mais sobre como adquirir e armazenar em cache os tokens usados nesses fluxos.