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

Artigo
04/08/2024

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.

Diagram showing the resource owner password credential flow

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.

Compartilhar via