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 terminalorganizations
. - 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.
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de