Suporte ao fluxo de autenticação no MSAL

A Biblioteca de Autenticação da Microsoft (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.

Tokens

Seu 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.

Fluxo ou ação de autenticação	Requer	Token de identificação	Token de acesso	Atualizar token	Código de autorização
Fluxo de 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 utilizador/palavra-passe (ROPC)	nome de utilizador, palavra-passe
Fluxo OIDC híbrido
Atualizar resgate de token	atualizar token

Autenticação interativa e não interativa

Vários desses fluxos suportam a aquisição de tokens interativos e não interativos.

• Interativo - O usuário pode ser solicitado a entrar pelo servidor de autorização. Por exemplo, para entrar, executar autenticação multifator (MFA) ou conceder consentimento para mais permissões de acesso a recursos.
• Não interativo (silencioso) - O usuário pode não ser solicitado para entrada. Também chamada de aquisição de token "silenciosa", 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.

Seu aplicativo baseado em MSAL deve primeiro tentar adquirir um token silenciosamente e voltar para o método interativo somente se a tentativa não interativa falhar. Para obter 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 pode ser resgatado por um token de acesso para chamar APIs da 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 da Web, Microsoft Graph

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

• Aplicativos de página única exigem PKCE (Proof Key for Code Exchange) ao usar o fluxo de concessão de código de autorização. PKCE é suportado pela MSAL.

• A especificação OAuth 2.0 exige 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, 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 de cliente

O fluxo de credenciais do cliente OAuth 2.0 permite que você acesse recursos hospedados na Web usando a identidade de um aplicativo. Este tipo de concessão é comumente utilizado para interações de servidor para servidor que têm de ser executadas em segundo plano, sem interação imediata com um utilizador. Estes tipos de aplicações são frequentemente denominados daemons ou conta 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 normalmente é 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 credencial.

Segredos da aplicação

No diagrama a seguir, o aplicativo:

1. Adquire um token usando credenciais secretas ou de senha 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:

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

Restrições para credenciais de cliente

O fluxo de cliente confidencial não é suportado em plataformas móveis como Android, iOS ou UWP. As aplicações móveis são consideradas aplicações cliente públicas que são incapazes de garantir a confidencialidade das suas credenciais.

Código do dispositivo

O fluxo de código de dispositivo OAuth 2.0 permite que os usuários entrem em dispositivos com restrição de entrada, como smart TVs, dispositivos IoT e impressoras. A autenticação interativa com o Microsoft Entra ID 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 que o usuário use outro dispositivo, como um computador ou telefone celular, para entrar interativamente.

Usando o fluxo de código do dispositivo, o aplicativo obtém tokens por meio de um processo de duas etapas projetado para esses dispositivos e sistemas operacionais. Exemplos de tais aplicativos incluem aqueles executados em dispositivos IoT e ferramentas de interface de linha de comando (CLI).

No diagrama a seguir:

1. Sempre que a autenticação do usuário é necessária, o aplicativo fornece um código e pede que o usuário use outro dispositivo, como um smartphone conectado à Internet, para visitar uma URL (por exemplo, https://microsoft.com/devicelogin). O usuário é então solicitado a inserir o código e prosseguir 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 de linha de comando recebe os tokens necessários por meio de um canal de retorno e os usa para executar as chamadas de API da Web necessárias.

Restrições para o código do dispositivo

• O fluxo de código do dispositivo está disponível apenas para aplicativos cliente públicos.
• Ao inicializar um aplicativo cliente público no MSAL, use um destes formatos de autoridade:
  • Inquilino: https://login.microsoftonline.com/{tenant}/, onde {tenant} é o ID do inquilino ou um nome de domínio associado ao inquilino.
  • Contabilidade profissional e escolar: https://login.microsoftonline.com/organizations/.

Concessão implícita

O fluxo de concessão implícito foi substituído pelo fluxo de código de autorização com PKCE como o fluxo de concessão de token preferido e mais seguro para aplicativos de página única (SPAs) do lado do cliente

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

O fluxo de concessão implícito do OAuth 2.0 permite que o aplicativo obtenha tokens de acesso da plataforma de identidade da Microsoft sem executar uma troca de credenciais de servidor back-end. O fluxo de concessão implícito permite que um aplicativo entre no usuário, mantenha uma sessão e obtenha tokens para outras APIs da Web a partir do código JavaScript baixado e executado pelo agente do usuário (normalmente um navegador da Web).

Restrições para subvenção implícita

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

Os tokens emitidos através do modo de fluxo implícito têm uma limitação de comprimento porque são devolvidos ao navegador por URL (onde response_mode está ou fragmentquery ). Alguns navegadores limitam o comprimento do URL na barra do navegador e falham quando é muito longo. Assim, esses tokens de fluxo implícitos não contêm groups ou wids declaram.

Em nome de (OBO)

O fluxo de fluxo de autenticação em nome do OAuth 2.0 é 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. A ideia é propagar a identidade e as permissões do usuário delegado através da 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.

No diagrama a seguir:

1. O aplicativo adquire um token de acesso para a API da Web.
2. Um cliente (web, desktop, celular ou aplicativo de página única) chama uma API da Web protegida, adicionando o token de acesso como um token de portador no cabeçalho de autenticação da solicitação HTTP. A API da 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 da Web também pode solicitar posteriormente tokens para outras APIs downstream (mas ainda em nome do mesmo usuário).

Nome de utilizador/palavra-passe (ROPC)

A concessão de credenciais de senha do proprietário do recurso (ROPC) do OAuth 2.0 permite que um aplicativo entre no usuário manipulando diretamente sua senha. Em seu aplicativo de desktop, você pode usar o fluxo de nome de usuário/senha para adquirir um token silenciosamente. Nenhuma interface do usuário é necessária ao usar o aplicativo.

No diagrama a seguir, o aplicativo:

1. Adquire um token enviando o nome de usuário e a senha para o provedor de identidade
2. Chama uma API da Web usando o token

Para adquirir um token silenciosamente em máquinas associadas ao domínio do Windows, recomendamos a autenticação integrada do Windows (IWA) em vez do ROPC. Para outros cenários, use o fluxo de código do dispositivo.

Restrições para ROPC

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

• O logon único não é suportado.
• A autenticação multifator (MFA) não é suportada.
  • Verifique com o administrador do locatário antes de usar esse fluxo - MFA é um recurso comumente usado.
• O acesso condicional não é suportado.
• O ROPC funciona apenas para contas de trabalho e escola.
• As contas pessoais da Microsoft (MSA) não são suportadas pelo ROPC.
• O ROPC é suportado em aplicativos .NET desktop e ASP.NET Core.
• O ROPC não é suportado em aplicativos da Plataforma Universal do Windows (UWP).
• O ROPC no Azure AD B2C é suportado apenas para contas locais.
  • Para obter informações sobre o ROPC no MSAL.NET e no Azure AD B2C, consulte Usando o ROPC com o Azure AD B2C.

Autenticação integrada do Windows (IWA)

O MSAL suporta autenticação integrada do Windows (IWA) para aplicações móveis e de ambiente de trabalho que são executadas em computadores Windows associados ao domínio ou que aderiram ao Microsoft Entra. Ao usar o IWA, esses aplicativos adquirem um token silenciosamente sem exigir a interação da interface do usuário pelo 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 para IWA

Compatibilidade

A autenticação integrada do Windows (IWA) está habilitada para aplicativos de área de trabalho .NET, .NET e Plataforma Universal do Windows.

A IWA suporta apenas utilizadores federados do AD FS - utilizadores criados no Ative Directory e apoiados pelo Microsoft Entra ID. Os usuários criados diretamente no Microsoft Entra ID sem o backup do Ative 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 e um desafio de MFA for emitido pela ID do Microsoft Entra. Se a IWA falhar, você deve recorrer 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. A autenticação de dois fatores normalmente é necessária quando um usuário entra de 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 do MFA e a frequência de desafio podem estar fora do seu controle como desenvolvedor, seu aplicativo deve lidar graciosamente com uma falha da aquisição silenciosa de tokens da IWA.

Restrições de URI da autoridade

A autoridade passada ao construir o 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 de entrada é restrito aos usuários no locatário especificado do Microsoft Entra. O {tenant} valor pode ser o ID do locatário no formato 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 de entrada são usuários em qualquer locatário do Microsoft Entra.

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 utilizador da sua aplicação deve ter consentido previamente a utilização da aplicação.

  OU

• O administrador do locatário deve ter consentido previamente que todos os usuários do locatário usem o aplicativo.

Para satisfazer qualquer dos requisitos, uma destas operações deve ter sido concluída:

• Você, como desenvolvedor do aplicativo, selecionou Grant no portal do Azure por conta própria.
• Um administrador de locatário selecionou Conceder/revogar consentimento de administrador para {domínio de locatário} na guia Permissões de API do registro do aplicativo no portal do Azure; consulte Adicionar permissões para acessar sua API da Web.
• Você forneceu uma maneira para os usuários consentirem com o aplicativo; consulte Consentimento do utilizador.
• Você forneceu uma maneira para o administrador do locatário consentir para o aplicativo; consulte Consentimento do administrador.

Para obter mais informações sobre consentimento, consulte Permissões e consentimento.

Próximo passo

Saiba mais sobre como adquirir e armazenar em cache os tokens usados nesses fluxos: