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.

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.

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 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 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:

• Registradas no Azure AD.
• 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 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 o Azure AD 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} é 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. 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 é 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 (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 o DevOps, podem achar o ROPC útil, mas você deve evitá-lo nos aplicativos em que você fornece uma interface do usuário interativa para entrada do usuário.

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.
• Há suporte para o ROPC nos aplicativos .NET Desktop e .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 é compatível com a IWA (autenticação integrada do Windows) para aplicativos móveis ou de desktop executados nos computadores Windows ingressados no Azure AD 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 de .NET Desktop, .NET Core e Plataforma Universal do Windows.

A IWA é compatível somente com usuários federados do AD FS – usuários criados no Active Directory e apoiados pelo Azure AD. Os usuários criados diretamente no Azure AD, 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 Azure AD e um desafio de MFA for emitido pelo Azure AD. Se a IWA falhar, você deverá retornar a um método interativo de autenticação, conforme descrito anteriormente.

O Azure AD 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 Azure AD. 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 Azure AD.

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óximas etapas

Agora que você examinou os fluxos de autenticação com suporte na MSAL, saiba mais sobre como adquirir e armazenar em cache os tokens usados nesses fluxos:

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