Plataforma de identidade da Microsoft e concessão de credenciais de senha de proprietário do recurso do OAuth 2.0

A plataforma de identidade da Microsoft oferece suporte à concessão de ROPC (credenciais de senha de proprietário do recurso) OAuth 2.0, que permite que um aplicativo entre no usuário manipulando diretamente sua senha. Este artigo descreve como programar diretamente no protocolo do seu aplicativo. Quando possível, recomendamos que você use as MSAL (bibliotecas de autenticação da Microsoft) com suporte para adquirir tokens e chamar APIs Web seguras. Confira também os aplicativos de exemplo que usam MSAL.

Aviso

A Microsoft recomenda que você não use o fluxo ROPC. Na maioria dos cenários, alternativas mais seguras estão disponíveis e são recomendadas. Esse fluxo exige um grau muito alto de confiança no aplicativo e traz riscos que não estão presentes em outros fluxos. Use-o somente quando outros fluxos mais seguros não forem viáveis.

Importante

• A plataforma de identidade da Microsoft dá suporte apenas ao ROPC em locatários do Microsoft Entra, não a contas pessoais. Isso significa que você deve usar um terminal específico do locatário (https://login.microsoftonline.com/{TenantId_or_Name}) ou o terminal organizations.
• As contas pessoais que são convidadas a um locatário do Microsoft Entra não podem usar o ROPC.
• Contas sem senhas não podem entrar com ROPC, ou seja, recursos como conexão por SMS, FIDO e o aplicativo Authenticator não funcionarão com esse fluxo. Se seu aplicativo ou seus usuários precisarem desses recursos, use um tipo de concessão diferente de ROPC.
• Se os usuários precisarem usar a MFA (autenticação multifator) para fazer logon no aplicativo, eles serão bloqueados em vez disso.
• Não há suporte para o ROPC em cenários de federação de identidade híbrida (por exemplo, ID do Microsoft Entra e AD FS usados para autenticar contas locais). Se os usuários forem redirecionados em uma página inteira para um provedor de identidade local, a ID do Microsoft Entra não poderá testar o nome de usuário e a senha nesse provedor de identidade. No entanto, há suporte para a autenticação de passagem com ROPC.
• Uma exceção a um cenário de federação de identidade híbrida seria o seguinte: a política de descoberta de realm inicial com AllowCloudPasswordValidation definido como TRUE permitirá que o fluxo de ROPC funcione para usuários federados quando uma senha local for sincronizada com a nuvem. Para obter mais informações, consulte Habilitar a autenticação ROPC direta de usuários federados para aplicativos herdados.
• Senhas com espaços em branco à esquerda ou à direita não são compatíveis com o fluxo ROPC.

Diagrama do protocolo

O diagrama a seguir mostra o fluxo do ROPC.

Solicitação de autorização

O fluxo de ROPC é uma solicitação única que envia a identificação do cliente e as credenciais do usuário ao provedor de identidade e recebe tokens em troca. O cliente deve solicitar o endereço de e-mail (UPN) e a senha do usuário antes de fazer isso. Imediatamente após uma solicitação bem-sucedida, o cliente deve descartar com segurança as credenciais do usuário da memória. Ele nunca deve salvá-los.

// Line breaks and spaces are for legibility only.  This is a public client, so no secret is required.

POST {tenant}/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=user.read%20openid%20profile%20offline_access
&username=MyUsername@myTenant.com
&password=SuperS3cret
&grant_type=password

Parâmetro	Condição	Descrição
tenant	Obrigatório	O locatário do diretório no qual você deseja fazer o login. O locatário pode estar no formato de nome amigável ou GUID. No entanto, o parâmetro dele não pode ser definido como common ou consumers, mas como organizations.
client_id	Obrigatório	A ID do aplicativo (cliente) que a página do centro de administração do Microsoft Entra – Registros de aplicativo atribui ao seu aplicativo.
grant_type	Obrigatório	Deve ser definido como password.
username	Obrigatório	Endereço de email do usuário.
password	Obrigatório	A senha do usuário.
scope	Recomendadas	Uma lista separada por espaço de escopos ou permissões que o aplicativo exige. Em um fluxo interativo, o administrador ou o usuário deve consentir com esses escopos com antecedência.
client_secret	Às vezes necessário	Se o aplicativo for um cliente público, não será possível incluir client_secret ou client_assertion. Se o aplicativo for um cliente confidencial, ele deverá ser incluído.
client_assertion	Às vezes necessário	Uma forma diferente de client_secret, gerada usando um certificado. Para saber mais, confira Credenciais de certificado.

Resposta de autenticação bem-sucedida

O exemplo abaixo mostra uma resposta de token bem-sucedida:

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

Parâmetro	Formatar	Descrição
token_type	String	Sempre defina como Bearer.
scope	Cadeia de caracteres separadas por espaço	Se um token de acesso foi retornado, esse parâmetro lista os escopos para os quais o token de acesso é válido.
expires_in	INT	Número de segundos para o qual o token de acesso incluído é válido.
access_token	Cadeia de caracteres opaca	Emitido para os escopos que foram solicitados.
id_token	JWT	Emitido quando o parâmetro original scope inclui o escopo openid.
refresh_token	Cadeia de caracteres opaca	Emitido quando o parâmetro original scope inclui offline_access.

Você pode usar o token de atualização para adquirir novos tokens de acesso e atualizar os tokens usando o mesmo fluxo descrito na documentação do fluxo de código do OAuth.

Aviso

Não tente validar nem ler tokens de APIs que não sejam suas em seu código, incluindo os tokens deste exemplo. Os tokens de serviços da Microsoft podem usar um formato especial que não será validado como um JWT e também podem ser criptografados para usuários do consumidor (conta Microsoft). Embora a leitura de tokens seja uma ferramenta útil de depuração e aprendizagem, não assuma dependências disso em seu código ou assuma informações específicas sobre tokens que não são de uma API que você controla.

Resposta de erro

Se o usuário não tiver fornecido o nome de usuário ou a senha corretos, ou se o cliente não tiver recebido o consentimento solicitado, a autenticação falhará.

Erro	Descrição	Ação do cliente
invalid_grant	A autenticação falhou	As credenciais estavam incorretas ou o cliente não tem consentimento para os escopos solicitados. Se os escopos não forem concedidos, um erro consent_required será retornado. Para resolver esse erro, o cliente deve enviar o usuário a um prompt interativo usando um modo de exibição da Web ou navegador.
invalid_request	A solicitação foi mal construída	O tipo de concessão não tem suporte nos contextos de autenticação /common ou /consumers. Em vez disso, use /organizations ou uma ID de locatário.

Saiba mais

Para obter um exemplo de implementação do fluxo ROPC, consulte o código de exemplo do aplicativo de console .NET no GitHub.