Compartir vía

Plataforma de identidad de Microsoft y Credenciales de Contraseña del Propietario del Recurso (ROPC) de OAuth 2.0

  • Artículo

La Plataforma de identidad de Microsoft admite la concesión de credenciales de contraseña de administrador del recurso (ROPC) de OAuth 2.0, que permite que, para que una aplicación inicie la sesión del usuario, se pueda controlar directamente su contraseña. En este artículo se describe cómo programar directamente contra el protocolo en su aplicación. Cuando sea posible, se recomienda usar las bibliotecas de autenticación de Microsoft (MSAL) admitidas, en lugar de adquirir tokens y API web protegidas por llamadas. Además, eche un vistazo a las aplicaciones de ejemplo que usan MSAL.

Advertencia

Microsoft recomienda no usar el flujo ROPC. Es incompatible con la autenticación multifactor (MFA). En la mayoría de los escenarios, hay alternativas más seguras disponibles y recomendadas. Este flujo requiere un alto grado de confianza en la aplicación y conlleva riesgos que no están presentes en otros flujos. Solo debe usar este flujo cuando los flujos más seguros no sean viables.

Importante

  • La plataforma de identidad de Microsoft solo admite la concesión de ROPC para inquilinos de Microsoft Entra, no para cuentas personales. Esto significa que debe usar un punto de conexión específico para el inquilino (https://login.microsoftonline.com/{TenantId_or_Name}) o el punto de conexión organizations.
  • Las cuentas personales que se inviten a un inquilino de Microsoft Entra no podrán usar el flujo de ROPC.
  • Las cuentas que no tienen contraseñas no pueden iniciar sesión con ROPC, lo que significa que las características como el inicio de sesión sms, FIDO y la aplicación Authenticator no funcionarán con ese flujo. Si la aplicación o los usuarios requieren estas características, use un tipo de concesión distinto de ROPC.
  • Si los usuarios deben usar la autenticación multifactor (MFA) para iniciar sesión en la aplicación, se les bloqueará.
  • ROPC no se admite en escenarios de federación de identidades híbridas (por ejemplo: Microsoft Entra ID y AD FS que se usan para autenticar cuentas locales). Si los usuarios son redirigidos completamente a una página en un proveedor de identidades local, Microsoft Entra ID no puede verificar el nombre de usuario y la contraseña contra ese proveedor de identidades. Sin embargo, la autenticación transferida se admite con ROPC.
  • Una excepción a un escenario de federación de identidad híbrida sería la siguiente: La directiva de detección del dominio de origen con AllowCloudPasswordValidation establecida en TRUE permitirá que el flujo ROPC funcione para los usuarios federados cuando una contraseña local en las instalaciones se sincroniza en la nube. Para obtener más información, consulte Habilitar la autenticación ROPC directa de usuarios federados para aplicaciones heredadas.
  • El flujo roPC no admite contraseñas con espacios en blanco iniciales o finales.

Cómo migrar desde ROPC

A medida que MFA es más frecuente, algunas API web de Microsoft solo aceptarán tokens de acceso si han superado los requisitos de MFA. Las aplicaciones y las plataformas de prueba que dependen de ROPC se bloquearán. Microsoft Entra no emitirá el token o el recurso rechazará la solicitud.

Si usa ROPC para adquirir tokens y acceder a APIs protegidas, migre a una estrategia de adquisición de tokens más segura.

Cuando el contexto de usuario está disponible

Si un usuario final necesita acceder a un recurso, la aplicación cliente que actúa en su nombre debe usar una forma de autenticación interactiva. El usuario final solo puede ser desafiado para la autenticación multifactor cuando se le solicite en el navegador.

  • Para aplicaciones web:
  • Las API web no pueden mostrar un explorador. En su lugar, deberán devolver un desafío a la aplicación cliente. Para obtener más información, consulte API web y usuarios con desafíos en las API web.
  • Las aplicaciones de escritorio deben usar la autenticación basada en agente. Los corredores usan la autenticación basada en navegador, por lo que pueden aplicar MFA y también habilitar la configuración más segura posible.
  • Las aplicaciones móviles también deben configurarse para usar la autenticación basada en broker (Authenticator, Portal de la empresa).

Cuando el contexto de usuario no está disponible

Ejemplos de escenarios en los que no hay ningún contexto de usuario implicado puede ser, pero no se limita a:

  • Un script que se ejecuta como parte de una canalización de integración continua.
  • Un servicio que necesita llamar a un recurso en nombre propio, sin detalles del usuario.

Los desarrolladores de aplicaciones deben usar la autenticación de entidad de servicio, que se muestra en los ejemplos de demonio. MFA no se aplica a los Principales de Servicio.

Hay varias maneras de autenticarse como entidad de servicio:

  • Si la aplicación se ejecuta en la infraestructura de Azure, use Managed Identity. La identidad administrada elimina la sobrecarga de mantener y rotar secretos y certificados.
  • Si la aplicación se ejecuta en un sistema administrado por otro proveedor de identidades compatible con OAuth2, como GitHub, use credenciales de identidad federada.
  • Si no puede usar una identidad administrada o una identidad federada, use una credencial de certificado .

Advertencia

No utilice la autenticación de entidad de servicio cuando haya un contexto de usuario disponible. El acceso a través de la aplicación es intrínsecamente de alto privilegio, a menudo concediéndole acceso a toda la organización y, posiblemente, permitiendo que un actor malintencionado acceda a los datos de los clientes de cualquier usuario.

Diagrama de protocolo

En el diagrama siguiente se muestra el flujo ROPC.

Diagrama que muestra el flujo de credenciales de contraseña del propietario del recurso

Solicitud de autorización

El flujo ROPC es una única solicitud; envía la identificación del cliente y las credenciales del usuario al proveedor de identidades y recibe tokens a cambio. El cliente debe solicitar la dirección de correo electrónico (UPN) y la contraseña del usuario antes de hacerlo. Inmediatamente después de una solicitud correcta, el cliente debe descartar de forma segura las credenciales del usuario de la memoria. Nunca debe salvarlos.

// 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 Condición Descripción
tenant Obligatorio Entidad de directorio en la que desea iniciar sesión el usuario. El inquilino puede estar en formato de nombre descriptivo o GUID. Sin embargo, su parámetro no se puede establecer en common o consumers, pero puede establecerse en organizations.
client_id Obligatorio El identificador de aplicación (cliente) que la página Centro de administración de Microsoft Entra: registros de aplicaciones asignó a la aplicación.
grant_type Obligatorio Debe establecerse en password.
username Obligatorio Dirección de correo electrónico del usuario.
password Obligatorio Contraseña del usuario.
scope Recomendado Una lista de ámbitos o permisos separados por espacios que requiere la aplicación. En un flujo interactivo, el administrador o el usuario deben dar su consentimiento a estos ámbitos con antelación.
client_secret A veces es necesario Si la aplicación es un cliente público, no se puede incluir el client_secret o client_assertion. Si la aplicación es un cliente confidencial, debe incluirse.
client_assertion A veces es necesario Una forma diferente de client_secret, generada mediante un certificado. Para más información, consulte Credenciales de certificados.

Respuesta de autenticación exitosa

En el ejemplo siguiente se muestra una respuesta de token exitosa.

{
    "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 Descripción
token_type Cuerda Siempre se establece en Bearer.
scope Cadenas separadas por espacios Si se devolvió un token de acceso, este parámetro enumera los ámbitos para los que el token de acceso es válido.
expires_in int Número de segundos para los que el token de acceso incluido es válido.
access_token Cadena opaca Se emite para los ámbitos solicitados.
id_token JWT Se emite si el parámetro scope original incluía el ámbito de openid.
refresh_token Cadena opaca Se emite si el parámetro scope original incluía offline_access.

Puede utilizar el token de actualización para obtener nuevos tokens de acceso y tokens de actualización usando el mismo flujo descrito en la documentación del flujo de código de OAuth .

Advertencia

No intente validar ni leer tokens para ninguna API que no posea, incluidos los tokens de este ejemplo, en el código. Los tokens de los servicios de Microsoft pueden usar un formato especial que no se validará como JWT y, además, se pueden cifrar para los usuarios consumidores (cuenta Microsoft). Aunque leer tokens es una herramienta útil de depuración y aprendizaje, no dependa de esto en su código ni asuma especificaciones sobre los tokens que no son para una API que usted controla.

Respuesta de error

Si el usuario no ha proporcionado el nombre de usuario o la contraseña correctos, o el cliente no ha recibido el consentimiento solicitado, se producirá un error en la autenticación.

Error Descripción Acción del cliente
invalid_grant Error de autenticación Las credenciales eran incorrectas o el cliente no tiene consentimiento para los ámbitos solicitados. En caso de que no se concedan los ámbitos, se devolverá un error consent_required. Para resolver este error, el cliente debe enviar al usuario a un aviso interactivo mediante una vista web o un explorador.
invalid_request La solicitud se construyó incorrectamente El tipo de concesión no se admite en los contextos de autenticación /common o /consumers. Use /organizations o un identificador de inquilino en su lugar.

Aprende más

Para obtener un ejemplo de implementación del flujo ROPC, consulte el ejemplo de código de la aplicación de consola de .NET en GitHub.