Partilhar via

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

  • Artigo

A plataforma de identidade da Microsoft suporta o de concessão de credenciais de senha do proprietário de recursos (ROPC) OAuth 2.0, 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 o uso das Bibliotecas de Autenticação da Microsoft (MSAL) com suporte para adquirir tokens e chamar APIs da Web protegidas. Dê também uma olhada nas aplicações de exemplo que utilizam o MSAL.

Advertência

A Microsoft recomenda que você não use fluxo ROPC; é incompatível com a autenticação multifator (MFA). Na maioria dos cenários, alternativas mais seguras estão disponíveis e são recomendadas. Esse fluxo requer um grau muito alto 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 suporta a concessão ROPC apenas 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 extremidade organizations.
  • 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 usar a autenticação multifator (MFA) para fazer login na aplicação, serão impedidos de fazer login.
  • 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 usuários forem redirecionados de página inteira para um provedor de identidade local, o Microsoft Entra ID não poderá testar o nome de usuário e a senha em relação a esse provedor de identidade. No entanto, de autenticação de passagem é suportada com o ROPC.
  • Uma exceção a um cenário de federação de identidades híbridas seria a seguinte: A política de Home Realm Discovery com a definição AllowCloudPasswordValidation (com e) configurada para 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, consulte 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.

Como migrar do ROPC

À medida que a MFA se torna mais prevalente, algumas APIs da Web da Microsoft só aceitarão tokens de acesso se tiverem passado pelos requisitos de MFA. Aplicativos e equipamentos 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 o ROPC para adquirir tokens para chamar APIs downstream protegidas, migre para uma estratégia segura de aquisição de tokens.

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

Se um usuário final precisar acessar um recurso, o aplicativo cliente que age em seu nome deve usar uma forma de autenticação interativa. O usuário final só pode ser desafiado para MFA quando solicitado no navegador.

  • Para aplicações Web:
  • As APIs da Web não podem exibir um navegador. Em vez disso, eles devem devolver um desafio ao aplicativo cliente. Para obter detalhes, consulte APIs da Web e Desafio a Utilizadores em APIs da Web.
  • Os aplicativos de desktop devem usar autenticação baseada em broker. Os corretores usam autenticação baseada em navegador, para que possam impor MFA e também permitir a postura mais segura possível.
  • Os aplicativos móveis também devem ser configurados para usar a autenticação baseada em broker (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 estão limitados a, o seguinte:

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

Os programadores de aplicações devem usar autenticação da Entidade de Serviço, conforme ilustrado nos exemplos de processos daemon . A AMF não se aplica a Principais de Serviço.

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

  • Se a sua aplicação estiver a ser executada na infraestrutura do Azure, utilize Managed Identity. O Managed Identity elimina a sobrecarga de manter e rotacionar segredos e certificados.
  • Se seu aplicativo estiver sendo executado em um sistema gerenciado por outro provedor de identidade compatível com OAuth2, como o GitHub, use Federated Identity Credentials.
  • Se não for possível usar uma Identidade Gerenciada ou uma Identidade Federada, use uma credencial de certificado .

Advertência

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

Diagrama de protocolo

O diagrama a seguir mostra o fluxo ROPC.

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

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. Não deve nunca 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 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 O ID do Aplicativo (cliente) que a página do Centro de administração do Microsoft Entra - Registros de aplicativo atribuiu ao seu aplicativo.
grant_type Necessário Deve ser definido como password.
username Necessário O endereço de e-mail do usuário.
password Necessário A senha do usuário.
scope Recomendado Uma lista separada por espaços de escoposou 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 as credenciais do certificado .

Resposta de autenticação bem-sucedida

O exemplo seguinte 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 Descrição
token_type Cadeia 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 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 e que foram solicitados.
id_token JWT Emitido se o parâmetro original scope incluísse o escopo openid.
refresh_token Cadeia opaca Emitido se o parâmetro scope original 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 .

Advertência

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 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 de consent_required 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 mal formulado O tipo de concessão não é suportado nos contextos de autenticação /common ou /consumers. Em vez disso, use /organizations ou um ID de locatário.

Saiba mais

Para obter um exemplo de implementação do fluxo ROPC, consulte o .NET console application code example no GitHub.