Suporte ao fluxo de autenticação na MSAL

A MSAL (Biblioteca de Autenticação da Microsoft) dá suporte a várias concessões de autorização e aos fluxos de token associados para uso em diferentes tipos de aplicativos e cenários.

Fluxo de autenticação	Habilita	Tipos de aplicativos com suporte
Código de autorização	Entrada do usuário e acesso a APIs 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 Web em nome do usuário em dispositivos com restrições de entrada, como smart TVs e dispositivos 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. Não use esse fluxo – use o código de autorização com PKCE.	* 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. Não use esse fluxo.	Desktop, Móvel
IWA (Autenticação Integrada do Windows)	Permite que os aplicativos em computadores ingressados no domínio ou no Microsoft Entra adquiram um token silenciosamente (sem qualquer interação com a interface 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	o 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 (silencioso) – O usuário pode não ser solicitado a inserir a entrada. Também chamada de aquisição de token "silenciosa", o aplicativo tenta obter um token usando um método em que 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 do OAuth 2.0 pode ser usada por aplicativos Web, SPA (aplicativos de página única) e aplicativos nativos (móveis e desktop) para obter acesso a recursos protegidos, como APIs 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 a seguir, o aplicativo:

1. Solicita um código de autorização que foi resgatado para um token de acesso
2. Usa o token de acesso para chamar uma API Web, 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 o 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. Algumas bibliotecas e estruturas solicitam o código de autorização automaticamente para você, e solicitar um código manualmente, 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.0 permite acessar recursos hospedados na Web usando a identidade de um aplicativo. Esse tipo de concessão normalmente é usado para interações de servidor para servidor que devem ser executadas em segundo plano, sem interação imediata com um usuário. Esses tipos de aplicativo normalmente são chamados de daemons ou contas de serviço.

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 a seguir, o aplicativo:

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

Certificados

No diagrama a seguir, o aplicativo:

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

Essas credenciais de cliente precisam ser:

• Registrado com o Microsoft Entra ID
• Transmitidas ao construir o objeto do aplicativo cliente confidencial em seu código

Restrições das credenciais do cliente

Não há suporte para o fluxo de cliente confidencial não tem em plataformas móveis como Android, iOS ou UWP. Os aplicativos móveis são considerados aplicativos cliente públicos que não conseguem garantir a confidencialidade das credenciais.

Código do dispositivo

O fluxo de código do dispositivo OAuth 2.0 permite que os usuários se conectem por dispositivos com restrições de entrada, como Smart TVs, dispositivos IOT e impressoras. A autenticação interativa com a ID do Microsoft Entra requer um navegador da Web. O fluxo de código do dispositivo permite que o usuário use outro dispositivo (por exemplo, computador ou celular) para entrar interativamente quando o dispositivo ou o sistema operacional não fornecer um navegador da Web.

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. Exemplos desse tipo de aplicativo incluem aqueles em execução em dispositivos IoT ou ferramentas de CLI (interface de linha de comando).

No seguinte diagrama:

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). Em seguida, o usuário deve inserir o código e prosseguir com uma experiência de autenticação normal, incluindo solicitações de consentimento e autenticação multifator, se necessário.
2. Após a autenticação bem-sucedida, o aplicativo de linha de comando recebe os tokens necessários por meio de um canal de apoio e os usa para executar as chamadas à API Web necessárias.

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:
  • Locatário: https://login.microsoftonline.com/{tenant}/,, onde {tenant} é 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

O fluxo da concessão implícita foi substituído pelo fluxo de 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

Aviso

Não é mais recomendável usar o fluxo da concessão implícita. 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.0 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. As estruturas de plataforma cruzada, como essas, exigem recursos adicionais para a interação com as plataformas nativas móveis e de desktop em que são executadas.

Tokens emitidos pelo modo de fluxo implícito têm uma limitação de duração, porque retornam ao navegador via URL (onde response_mode é query ou fragment). 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 autenticação em nome do usuário OAuth 2.0 é usado quando um aplicativo invoca um serviço ou API Web que, por sua vez, precisa chamar outro serviço ou API Web. A ideia é propagar a identidade do usuário delegado e as permissões pela cadeia de solicitação. Para o serviço de camada intermediária fazer 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.

No seguinte diagrama:

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 Web, ela solicita outro token em nome do usuário.
4. A API Web protegida usa esse token para chamar uma API 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)

A concessão de credenciais de senha de proprietário do recurso (ROPC) do OAuth 2.0 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.

Aviso

O fluxo de ROPC (credenciais de senha de proprietário do recurso) NÃO é recomendado. O ROPC requer um alto grau de confiança e exposição da credencial. Recorra ao uso de 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?.

No diagrama a seguir, 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 nos computadores Windows conectados ao domínio, recomendamos a IWA (autenticação integrada do Windows), em vez do 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 tem suporte em aplicativos .NET desktop e ASP.NET Core.
• Não há suporte para o ROPC nos aplicativos da UWP (Plataforma Universal do Windows).
• Há suporte para o ROPC no Azure AD B2C somente para contas locais.
  • Para saber mais sobre como usar o ROPC na MSAL.NET e no Azure AD B2C, confira Usar o ROPC com o Azure AD B2C.

Autenticação integrada do Windows (IWA)

A MSAL dar suporte à IWA (autenticação integrada do Windows) para aplicativos móveis ou de área de trabalho executados nos computadores Windows ingressados no Microsoft Entra ou conectados ao domínio. Usando a IWA, esses aplicativos adquirem um token silenciosamente, sem interação com a interface do usuário.

No diagrama a seguir, o aplicativo:

1. Adquire um token usando a autenticação integrada do Windows
2. Usa o token para fazer solicitações do recurso

Restrições da IWA

Compatibilidade

A IWA (Autenticação Integrada do Windows) está habilitada para aplicativos .NET desktop, .NET e Plataforma Universal do Windows.

A IWA dar suportesomente aos usuários federados do AD FS – usuários criados no Active Directory e apoiados pelo 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.

MFA (autenticação multifator)

A autenticação não interativa (silenciosa) da IWA poderá falhar, se a MFA estiver habilitada no locatário do Microsoft Entra 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 da MFA podem estar fora do seu controle como desenvolvedor, o aplicativo deve resolver normalmente uma falha de aquisição silenciosa de token da IWA.

Restrições de URI de autoridade

A autoridade passada na construção do aplicativo cliente público deve ser uma das seguintes:

• https://login.microsoftonline.com/{tenant}/ – Esta autoridade indica um aplicativo de locatário único, cujo público-alvo de entrada é restrito aos usuários no locatário especificado do Microsoft Entra. 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/ – Esta autoridade indica um aplicativo multilocatário, cujo público-alvo de entrada inclui os usuários em qualquer locatário do Microsoft Entra.

Os valores de autoridade NÃO devem conter /common ou /consumers, pois as MSAs (contas Microsoft) pessoais não são compatíveis com a IWA.

Requisitos de consentimento

Como a IWA é um fluxo silencioso:

• O usuário do seu aplicativo deve ter consentido o uso do aplicativo anteriormente.

  OR

• O administrador de locatários deve ter consentido o uso do aplicativo anteriormente para todos os usuários no locatário.

Para atender a qualquer requisito, uma destas operações deve ter sido concluída:

• Como desenvolvedor do aplicativo, você selecionou Conceder no portal do Azure por conta própria.
• 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 forma de os usuários consentirem com o aplicativo; confira Consentimento do usuário.
• Você forneceu uma forma de o administrador do locatário consentir com o aplicativo; confira Consentimento do administrador.

Para saber mais sobre o consentimento, confira Permissões e consentimento.

Próxima etapa

Saiba como adquirir e armazenar em cache os tokens usados nestes fluxos:

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