Plataforma de identidad de Microsoft y credenciales de contraseña de propietario de recursos de OAuth 2.0

La Plataforma de identidad de Microsoft admite la concesión de credenciales de contraseña de propietario de recursos (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 con el protocolo de la 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 que no use el flujo de ROPC. En la mayoría de los escenarios, hay alternativas más seguras y recomendables. 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 no se puedan usar otros más seguros.

Importante

• La plataforma de identidad de Microsoft solo admite la concesión de ROPC para inquilinos de Microsoft Entra, no cuentas personales. Esto significa que debe usar un punto de conexión específico del inquilino (https://login.microsoftonline.com/{TenantId_or_Name}) o el punto de conexión organizations.
• Las cuentas personales que se invitan a un inquilino de Microsoft Entra no pueden usar el flujo de ROPC.
• Las cuentas que no tienen contraseñas no pueden iniciar sesión con ROPC, lo que significa que características como el inicio de sesión por SMS, FIDO y la aplicación Authenticator no funcionarán con ese flujo. Use un tipo de concesión que no sea ROPC si la aplicación o los usuarios requieren estas características.
• 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, el Id. de Microsoft Entra y AD FS que se usan para autenticar cuentas locales). Si los usuarios se redirigen a página completa a un proveedor de identidades locales, el Id. de Microsoft Entra no puede probar el nombre de usuario y la contraseña en el proveedor de identidades. Sin embargo, la autenticación de paso a través se admite con ROPC.
• Una excepción a un escenario de federación de identidades híbrida sería la siguiente: la directiva de detección del dominio principal con el valor de AllowCloudPasswordValidation establecido en TRUE permitirá que el flujo de ROPC funcione para los usuarios federados cuando la contraseña local se sincronice con la nube. Para más información, consulte Habilitación de la autenticación de ROPC directa de los usuarios federados para aplicaciones heredadas.
• El flujo ropc no admite contraseñas con espacios en blanco iniciales o finales.

Diagrama del protocolo

En el diagrama siguiente se muestra el flujo de ROPC.

Solicitud de autorización

El flujo de ROPC es una solicitud única que envía la identificación del cliente y las credenciales del usuario al proveedor de identidades y después, a cambio, recibe tokens. 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 que una solicitud se realice correctamente, el cliente deberá descartar de manera segura las credenciales del usuario de la memoria. Nunca deben guardarse.

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

Respuesta de autenticación correcta

En el ejemplo siguiente se muestra una respuesta de token correcta:

{
    "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	String	Siempre se establece en Bearer.
scope	Cadenas separadas por espacios	Si se devolvió un token de acceso, este parámetro muestra los ámbitos para los que es válido el token de acceso.
expires_in	int	Número de segundos durante 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 incluye el ámbito openid.
refresh_token	Cadena opaca	Se emite si el parámetro scope original incluye offline_access.

Puede usar el token de actualización para adquirir nuevos tokens de acceso y tokens de actualización con el mismo flujo que se describe en la Documentación del flujo de código de OAuth.

Advertencia

No intente validar ni leer tokens para ninguna API de su propiedad, 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 un JWT y también se pueden cifrar para los usuarios consumidores (cuenta Microsoft). Aunque la lectura de tokens es una herramienta útil de depuración y aprendizaje, no tome dependencias de esto en el código ni asuma detalles sobre los tokens que no son para una API que controle.

Respuesta de error

Si el usuario no ha proporcionado la contraseña o el nombre de usuario adecuado o si el cliente no ha recibido el consentimiento solicitado, la autenticación no se realizará.

Error	Descripción	Acción del cliente
invalid_grant	Error de autenticación	Las credenciales no eran las correctas o el cliente no tiene consentimiento para los ámbitos solicitados. Si no se conceden los ámbitos, se devolverá un error consent_required. Para solucionar este error, el cliente debe enviar al usuario una solicitud interactiva mediante una vista web o un explorador.
invalid_request	La solicitud se construyó de manera inadecuada.	El tipo de concesión no es compatible con los contextos de autenticación /common ni /consumers. Use /organizations o un identificador de inquilino en su lugar.

Saber más

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