Compartilhar via

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

  • Artigo

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 usar 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 de ROPC, pois ele é incompatível com a MFA (autenticação multifator). Na maioria dos cenários, alternativas mais seguras estão disponíveis e recomendadas. Esse fluxo requer um alto grau de confiança no aplicativo e traz riscos que não estão presentes em outros fluxos. Você só deve usar esse fluxo quando fluxos mais seguros não forem viáveis.

Importante

  • A plataforma de identidade da Microsoft dá suporte apenas à ROPC em locatários do Microsoft Entra, não a 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 extremidade organizations.
  • As contas pessoais que são convidadas a um locatário do Microsoft Entra não podem usar a ROPC.
  • Contas que não têm senhas não podem entrar com ROPC, o que significa que recursos como entrada por SMS, FIDO e o aplicativo Authenticator não funcionarão com esse fluxo. Se o aplicativo ou os usuários exigirem esses 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.
  • Não há suporte para a ROPC em cenários de federação de identidade híbrida (por exemplo, Microsoft Entra ID e AD FS usados para autenticar contas locais). Se os usuários forem redirecionados de 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 a ROPC.
  • Uma exceção em um cenário de federação de identidade híbrida seria a seguinte: a política de descoberta do domínio de origem com AllowCloudPasswordValidation definida como TRUE permitirá que o fluxo ROPC funcione para usuários federados quando uma senha local de instalação se sincroniza com a nuvem. Para mais informações, consulte Habilitação da autenticação direta ROPC de usuários federados para aplicações legadas.
  • Senhas com espaços em branco à esquerda ou à direita não são compatíveis com o fluxo ROPC.

Como migrar para longe do ROPC

À medida que a MFA se torna mais prevalente, algumas APIs Web da Microsoft só aceitarão tokens de acesso se tiverem aprovado os requisitos de MFA. Aplicativos e plataformas de teste que dependem do ROPC serão bloqueados. O Microsoft Entra não emitirá o token ou o recurso rejeitará a solicitação.

Se você estiver usando a ROPC para adquirir tokens para chamar APIs de downstream protegidas, migre para uma estratégia segura de aquisição de token.

Quando o contexto do usuário está disponível

Se um usuário final precisar acessar um recurso, o aplicativo cliente que atua em seu nome deverá usar uma forma de autenticação interativa. O usuário final só pode ser solicitado a realizar MFA quando isso for solicitado no navegador.

  • Para aplicativos Web:
  • As APIs Web não podem exibir um navegador. Em vez disso, elas devem retornar um desafio ao aplicativo cliente. Para obter detalhes, consulte APIs Web e usuários desafiadores em APIs Web.
  • Os aplicativos da área de trabalho devem usar a autenticação baseada em agente. Os agentes usam a autenticação baseada em navegador para poderem impor a MFA e também habilitar a postura mais segura possível.
  • Os aplicativos móveis também devem ser configurados para usar a autenticação baseada em agente (Authenticator, Portal da Empresa).

Quando o contexto do usuário não está disponível

Exemplos de cenários em que nenhum contexto de usuário está envolvido podem ser, mas não se limitam a:

  • Um script em execução como parte de um pipeline de CI.
  • Um serviço que precisa chamar um recurso em nome de si mesmo, sem detalhes do usuário.

Os desenvolvedores de aplicativos devem usar a autenticação da Entidade de serviço, que é ilustrada nos exemplos de daemon. A MFA não se aplica aos Service Principals.

Há várias maneiras de se autenticar como um principal de serviço:

  • Se o aplicativo estiver em execução na infraestrutura do Azure, use Identidade Gerenciada . A Identidade Gerenciada elimina a sobrecarga de manutenção e rotação de segredos e certificados.
  • Se o aplicativo estiver em execução em um sistema gerenciado por outro provedor de identidade compatível com OAuth2, como o GitHub, use as Credenciais de Identidade Federadas .
  • Se você não puder usar uma Identidade Gerenciada ou uma Identidade Federada, use uma credencial de certificado .

Aviso

Não use a autenticação da Entidade de serviço quando um contexto de usuário estiver disponível. O acesso somente ao aplicativo é inerentemente de alto privilégio, muitas vezes concedendo acesso completo ao locatário e potencialmente permitindo que um ator mal-intencionado acesse os dados do cliente de qualquer usuário.

Diagrama de protocolo

O diagrama a seguir mostra o fluxo ROPC.

diagrama Diagrama mostrando o fluxo de credenciais de senha do proprietário do recurso

Solicitação 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 UPN (endereço de email) 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 Necessário O locatário do diretório no qual você deseja fazer logon. O locatário pode estar no formato de nome amigável ou GUID. 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 do Centro de administração do Microsoft Entra – Registros de aplicativo atribui ao seu aplicativo.
grant_type Necessário Deve ser definido como password.
username Necessário O endereço de email do usuário.
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 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 deverá 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 as credenciais do certificado .

Resposta de autenticação bem-sucedida

O exemplo a seguir mostra uma resposta bem-sucedida do token:

{
    "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 Descrição
token_type Cadeia de caracteres Sempre defina como Bearer.
scope Cadeias 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 os quais 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 scope original inclui o escopo openid.
refresh_token Cadeia de caracteres opaca Emitido quando o parâmetro scope original inclui 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 do 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. Tokens para serviços da Microsoft podem usar um formato especial que não será validado como um JWT e também pode ser criptografado para usuários consumidores (conta da Microsoft). Embora a leitura de tokens seja uma ferramenta útil de depuração e aprendizado, não use dependências sobre isso em seu código ou assuma detalhes 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 a senha correto ou se o cliente não tiver recebido o consentimento solicitado, a autenticação falhará.

Erro Descrição Ação do cliente
invalid_grant Falha na autenticação 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 para um prompt interativo usando uma visão da Web ou navegador.
invalid_request A solicitação foi construída incorretamente Não há suporte para o tipo de concessão 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 exemplo de código do aplicativo de console .NET no GitHub.