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

Artigo
04/08/2024

A plataforma de identidade da Microsoft suporta a concessão OAuth 2.0 Resource Owner Password Credentials (ROPC), que permite que um aplicativo entre no usuário manipulando diretamente sua senha. Este artigo descreve como programar diretamente contra o protocolo na sua aplicação. Quando possível, recomendamos que utilize as Bibliotecas de Autenticação da Microsoft (MSAL) suportadas para adquirir tokens e chamar as APIs Web seguras. Também dê uma olhada nos aplicativos de exemplo que usam o 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. Este fluxo requer um grau muito elevado de confiança na aplicação e acarreta riscos que não estão presentes noutros fluxos. Você só deve usar esse fluxo quando outros fluxos mais seguros não forem viáveis.

Importante

A plataforma de identidade da Microsoft suporta apenas a concessão ROPC em locatários do Microsoft Entra, não em contas pessoais. Isso significa que você deve usar um ponto de extremidade específico do locatário (https://login.microsoftonline.com/{TenantId_or_Name}) ou o ponto de organizations extremidade.
As contas pessoais convidadas para um locatário do Microsoft Entra não podem usar o fluxo ROPC.
As contas que não têm senhas não podem entrar com o ROPC, o que significa que recursos como login por SMS, FIDO e o aplicativo Authenticator não funcionarão com esse fluxo. Se seu aplicativo ou usuários precisarem desses recursos, use um tipo de concessão diferente do ROPC.
Se os utilizadores precisarem de utilizar a autenticação multifator (MFA) para iniciar sessão na aplicação, serão bloqueados.
O ROPC não é suportado em cenários de federação de identidades híbridas (por exemplo, Microsoft Entra ID e AD FS usados para autenticar contas locais). Se os utilizadores forem redirecionados para um fornecedor de identidades no local, o Microsoft Entra ID não é capaz de testar o nome de utilizador e a palavra-passe nesse fornecedor de identidades. Contudo, a autenticação pass-through é suportada com o ROPC.
Uma exceção a um cenário de federação de identidade híbrida seria a seguinte: a política Home Realm Discovery com AllowCloudPasswordValidation definida como TRUE permitirá que o fluxo ROPC funcione para usuários federados quando uma senha local for sincronizada com a nuvem. Para obter mais informações, veja Ativar a autenticação ROPC direta de utilizadores federados para aplicações legadas.
Senhas com espaços em branco à esquerda ou à direita não são suportadas pelo fluxo ROPC.

Diagrama de protocolo

O diagrama a seguir mostra o fluxo ROPC.

Diagram showing the resource owner password credential flow

Pedido de autorização

O fluxo ROPC é uma única solicitação; Ele envia a identificação do cliente e as credenciais do usuário para o 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 fazê-lo. Imediatamente após uma solicitação bem-sucedida, o cliente deve descartar com segurança as credenciais do usuário da memória. 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	Description
`tenant`	Obrigatório	O locatário do diretório no qual você deseja fazer logon do usuário. O locatário pode estar no formato GUID ou nome amigável. No entanto, seu parâmetro não pode ser definido como `common` ou `consumers`, mas pode ser definido como `organizations`.
`client_id`	Necessário	A ID do Aplicativo (cliente) que a página Centro de administração do Microsoft Entra - Registros de aplicativos atribuiu ao seu aplicativo.
`grant_type`	Necessário	Deve ser definido como `password`.
`username`	Necessário	O endereço de correio eletrónico do utilizador.
`password`	Necessário	A senha do usuário.
`scope`	Recomendado	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 seu aplicativo for um cliente público, o `client_secret` ou `client_assertion` não poderá ser incluído. Se o aplicativo for um cliente confidencial, ele deve ser incluído.
`client_assertion`	Às vezes necessário	Uma forma diferente de `client_secret`, gerada usando um certificado. Para obter mais informações, consulte credenciais de certificado.

Resposta de autenticação bem-sucedida

O exemplo a seguir 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	Formato	Description
`token_type`	String	Sempre definido como `Bearer`.
`scope`	Strings 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`	número inteiro	Número de segundos para os quais o token de acesso incluído é válido.
`access_token`	Corda opaca	Emitido para os escopos que foram solicitados .
`id_token`	JWT	Emitido se o parâmetro original `scope` incluísse o `openid` escopo.
`refresh_token`	Corda opaca	Emitido se o parâmetro original `scope` incluísse `offline_access`.

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

Aviso

Não tente validar ou ler tokens para qualquer API que você não possua, incluindo os tokens neste exemplo, em seu código. Os tokens para 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 consumidores (conta da Microsoft). Embora a leitura de tokens seja uma ferramenta útil de depuração e aprendizagem, não dependa disso em seu código ou assuma especificidades sobre tokens que não são para uma API que você controla.

Resposta de erro

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

Erro	Description	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 `consent_required` erro será retornado. Para resolver esse erro, o cliente deve enviar o usuário para um prompt interativo usando um webview ou navegador.
`invalid_request`	O pedido foi construído indevidamente	O tipo de concessão não é suportado nos contextos `/common` ou `/consumers` de autenticação. Em vez disso, use `/organizations` ou um ID de locatário.

Mais informações

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

Partilhar via