Referencia de la API de autenticación nativa
Se aplica a:
inquilinos de personal 
inquilinos externos (más información)
La autenticación nativa de Microsoft Entra permite hospedar la interfaz de usuario de la aplicación en la aplicación cliente, en lugar de delegar la autenticación en los exploradores, lo que da lugar a una experiencia de autenticación integrada de forma nativa. Como desarrollador, tiene control total sobre la apariencia de la interfaz de inicio de sesión.
En este artículo de referencia de API se describen los detalles necesarios solo cuando se realizan manualmente solicitudes HTTP sin procesar para ejecutar el flujo. Sin embargo, no se recomienda este enfoque. Por lo tanto, cuando sea posible, use un SDK de autenticación integrado y compatible de Microsoft. Para obtener más información sobre cómo usar el SDK, consulta Tutorial: Preparación de la aplicación móvil Android para la autenticación nativa y Tutorial: Preparación de la aplicación móvil de iOS/macOS para la autenticación nativa.
Cuando una llamada a los puntos de conexión de API se realiza correctamente, recibirá un token de identificador para la identificación del usuario y un token de acceso para llamar a las API protegidas. Todas las respuestas de la API tienen un formato JSON.
La API de autenticación nativa de Microsoft Entra admite el registro y el inicio de sesión de dos métodos de autenticación:
Correo electrónico con contraseña, que admite el registro y el inicio de sesión con un correo electrónico y una contraseña, y el autoservicio de restablecimiento de contraseña (SSPR).
Código de acceso de un solo uso por correo electrónico, que admite el registro y el inicio de sesión con un código de acceso de un solo uso por correo electrónico.
Nota:
Actualmente, los puntos de conexión de la API de autenticación nativa no admiten el Uso compartido de recursos entre orígenes (CORS).
Requisitos previos
Un inquilino externo de Microsoft Entra. Si no tiene uno, cree un inquilino externo.
Si aún no lo ha hecho, Registre una aplicación en el Centro de administración de Microsoft Entra. Asegúrese de conceder permisos delegados y habilitar los flujos de autenticación nativa y de cliente público.
Si aún no lo ha hecho, Cree un flujo de usuarios en el Centro de administración de Microsoft Entrar. Cuando cree el flujo de usuario, tome nota de los atributos de usuario que configura que son obligatorios, ya que estos atributos son los que Microsoft Entra espera que la aplicación envíe.
Asocie el registro de su aplicación con el flujo de usuarios.
Para el flujo de inicio de sesión, registre un usuario cliente, que utilizará para probar las API de inicio de sesión. Como alternativa, este usuario de prueba se puede obtener después de ejecutar el flujo de registro.
En el caso del flujo de autoservicio de restablecimiento de contraseña, habilite el restablecimiento de contraseñas de autoservicio para los usuarios del cliente en la cuenta empresarial externa. El autoservicio de restablecimiento de contraseña está disponible para los usuarios del cliente que utilizan el correo electrónico con el método de autenticación de contraseña.
Token de continuación
Cada vez que se llama a un punto de conexión en cualquiera de los flujos, inicio de sesión, registro o SSPR, el punto de conexión incluye un token de continuación en su respuesta. El token de continuación es un identificador único que usa Microsoft Entra ID para mantener el estado entre las llamadas a distintos puntos de conexión dentro del mismo flujo. Debe incluir este token en las solicitudes posteriores en el mismo flujo.
Cada token de continuación es válido durante un período específico y solo se puede usar para las solicitudes posteriores dentro del mismo flujo.
Referencia de la API de registro
Para completar un flujo de registro de usuario para cualquiera de los métodos de autenticación, la aplicación interactúa con cuatro puntos de conexión, /signup/v1.0/start, /signup/v1.0/challenge, /signup/v1.0/continue y /token.
Puntos de conexión de API de registro
| Punto de conexión | Descripción |
|---|---|
/signup/v1.0/start |
Este punto de conexión inicia el flujo de registro. Pasa el Id. de aplicación válido, el nuevo nombre de usuario y tipo de desafíoy luego, obtiene un nuevo token de continuación. El punto de conexión puede devolver una respuesta para indicar a la aplicación que utilice un flujo de autenticación web si los métodos de autenticación elegidos por la aplicación no son compatibles con Microsoft Entra. |
/signup/v1.0/challenge |
Su aplicación llama a este punto de conexión con una lista de tipos de desafíos admitidas por Microsoft Entra. A continuación, Microsoft Entra selecciona uno de los métodos de autenticación admitidos para que el usuario se autentique con él. |
/signup/v1.0/continue |
Este punto de conexión ayuda a continuar el flujo para crear la cuenta de usuario o interrumpir el flujo debido a la falta de requisitos, como requisitos de directiva de contraseñas o formatos de atributos erróneos. Este punto de conexión genera un token de continuación y lo devuelve a la aplicación. El punto de conexión puede devolver una respuesta para indicar a la aplicación que utilice un flujo de autenticación basado en web si la aplicación no tiene un método de autenticación elegido por Microsoft Entra. |
/token |
La aplicación llama a este punto de conexión para solicitar finalmente los tokens de seguridad. La aplicación debe incluir el token de continuación que adquiere en la última llamada realizada con éxito al punto de conexión /signup/v1.0/continue. |
Tipos de desafíos para el registro
La API permite a la aplicación anunciar los métodos de autenticación que admite cuando realiza una llamada a Microsoft Entra. Para ello, la aplicación usa el parámetro challenge_type en su solicitud. Este parámetro contiene valores predefinidos, que representan diferentes métodos de autenticación.
Obtenga más información sobre los tipos de desafío en tipos de desafío de autenticación nativa. En este artículo se explican los valores de tipo de desafío que debe para un método de autenticación.
Detalles del protocolo de flujo de registro
El diagrama de secuencia muestra el flujo del proceso de inicio de sesión.
En este diagrama se indica que la aplicación recopila el nombre de usuario (correo electrónico), la contraseña (para el correo electrónico con métodos de autenticación de contraseña) y los atributos del usuario en diferentes momentos (y posiblemente en pantallas independientes). Sin embargo, puede diseñar su aplicación para recopilar el nombre de usuario (correo electrónico), la contraseña y todos los valores de atributos obligatorios y opcionales en la misma pantalla, y luego enviarlos todos a través del punto de conexión /signup/v1.0/start. En este caso, la aplicación no necesita realizar llamadas ni controlar las respuestas de los pasos opcionales.
Paso 1: Solicitud para iniciar el flujo de registro
El flujo de registro comienza cuando la aplicación realiza una solicitud POST al punto de conexión /signup/v1.0/start para iniciar el flujo de registro.
He aquí ejemplos de solicitud (presentamos la solicitud de ejemplo en varias líneas para facilitar la lectura):
Ejemplo 1:
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&username=contoso-consumer@contoso.com
Ejemplo 2 (incluir atributos de usuario y contraseña en la solicitud):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&password={secure_password}
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postalCode": "{user_postal_code}"}
&username=contoso-consumer@contoso.com
| Parámetro | Obligatorio | Descripción |
|---|---|---|
tenant_subdomain |
Sí | Subdominio del inquilino externo que creó. En la dirección URL, reemplace {tenant_subdomain} por el subdominio Directorio (inquilino). Por ejemplo, si el dominio principal del inquilino es contoso.onmicrosoft.com, use Contoso. Si no tiene el subdominio de inquilino, obtenga información sobre cómo leer los detalles del inquilino. |
client_id |
Sí | El identificador de aplicación (cliente) de la aplicación que registró en el Centro de administración de Microsoft Entra. |
username |
Sí | Correo electrónico del usuario cliente con el que quiere registrarse, como contoso-consumer@contoso.com. |
challenge_type |
Sí | Una lista separada por espacios de cadenas de tipo de desafío de autorización que admite la aplicación, como oob password redirect. La lista siempre debe incluir el tipo de desafío redirect. Se espera que el valor sea o oob redirect oob password redirect para el correo electrónico con el método de autenticación de contraseña. |
password |
No | El valor de la contraseña que la aplicación recopila del usuario cliente. Puede enviar la contraseña de un usuario a través del /signup/v1.0/start o posteriormente en el punto de conexión /signup/v1.0/continue. Reemplace {secure_password} con el valor de la contraseña que la aplicación recopila del usuario cliente. Es su responsabilidad confirmar que el usuario es consciente de la contraseña que desea utilizar proporcionando el campo de confirmación de contraseña en la interfaz de usuario de la aplicación. También debe asegurarse de que el usuario es consciente de lo que constituye una contraseña segura según la directiva de su organización. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. Este parámetro solo se puede aplicar al correo electrónico con el método de autenticación de contraseña. |
attributes |
No | Los atributos de usuario que recopila la aplicación del usuario cliente. El valor es una cadena, pero con formato de objeto JSON cuyos valores de clave son nombres programables de atributos de usuario. Estos atributos pueden ser incorporados o personalizados, y obligatorios u opcionales. Los nombres clave del objeto dependen de los atributos que el administrador haya configurado en el Centro de administración de Microsoft Entra. Puede enviar algunos o todos los atributos de usuario a través del /signup/v1.0/startpunto de conexión o posterior en el punto de conexión /signup/v1.0/continue. Si envía todos los atributos requeridos a través del punto de conexión /signup/v1.0/start, no necesita enviar ningún atributo en el punto de conexión /signup/v1.0/continue. Sin embargo, si envía algunos atributos requeridos a través del punto de conexión /signup/v1.0/start, puede enviar el resto de atributos requeridos más tarde en el punto de conexión /signup/v1.0/continue. Reemplace {given_name}, {user_age} y {postal_code} por los valores de nombre, edad y código postal respectivamente que la aplicación recopila del usuario del cliente. Microsoft Entra omite los atributos que envíe, que no existen. |
Respuesta correcta
Este es un ejemplo de una respuesta correcta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAA…",
}
| Parámetro | Descripción |
|---|---|
continuation_token |
Token de continuación que devuelve Microsoft Entra. |
Si una aplicación no es compatible con un método de autenticación requerido por Microsoft Entra, es necesario recurrir al flujo de autenticación basado en web. En este escenario, Microsoft Entra informa a la aplicación devolviendo un tipo de desafío de redirección en su respuesta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parámetro | Descripción |
|---|---|
challenge_type |
Microsoft Entra devuelve una respuesta que tiene un tipo de desafío. El valor de este tipo de desafío es el redireccionamiento, lo que permite a la aplicación usar el flujo de autenticación basado en web. |
Esta respuesta se considera correcta, pero la aplicación debe cambiar a un flujo de autenticación basado en web. En este caso, le recomendamos que utilice una biblioteca de autenticación compatible y creada por Microsoft.
Respuesta de error
Ejemplo:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "user_already_exists",
"error_description": "AADSTS1003037: It looks like you may already have an account.... .\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
1003037
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parámetro | Descripción |
|---|---|
error |
Una cadena de código de error que puede usarse para clasificar los tipos de errores y para reaccionar a los errores. |
error_description |
Un mensaje de error específico que puede ayudarle a identificar la causa de un error de autenticación. |
error_codes |
Una lista de códigos de error específicos de Microsoft Entra que pueden ayudarle a diagnosticar errores. |
timestamp |
La hora a la que se produjo el error. |
trace_id |
Un identificador único para la solicitud que puede ayudarle a diagnosticar errores. |
correlation_id |
Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes. |
invalid_attributes |
Lista (matriz de objetos) de atributos que no se pudieron validar. Esta respuesta es posible si la aplicación envía atributos de usuario y el suberrorvalor del parámetro es attribute_validation_failed. |
suberror |
Cadena de código de error que se puede usar para clasificar aún más tipos de errores. |
Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):
| Valor de error | Descripción |
|---|---|
invalid_request |
La validación del parámetro de la solicitud falló, por ejemplo, cuando el valor del parámetro challenge_type contiene un método de autenticación no admitido o la solicitud no incluyó el parámetro client_id el valor del Id. de cliente está vacío o no es válido. Use el parámetro error_description para obtener información sobre la causa exacta del error. |
invalid_client |
El ID de cliente que la aplicación incluye en la solicitud corresponde a una aplicación que carece de configuración de autenticación nativa, por ejemplo, no es un cliente público o no está habilitado para la autenticación nativa. Use el parámetro suberror para obtener información sobre la causa exacta del error. |
unauthorized_client |
El id. de cliente utilizado en la solicitud tiene un formato de id. de cliente válido, pero no existe en el inquilino externo o es incorrecto. |
unsupported_challenge_type |
El valor del parámetro challenge_type no incluye el tipo de desafío redirect. |
user_already_exists |
El usuario ya existe. |
invalid_grant |
La contraseña que envía la aplicación no cumple todos los requisitos de complejidad, por ejemplo, es demasiado corta. Use el parámetro suberror para obtener información sobre la causa exacta del error. Este parámetro solo se puede aplicar al correo electrónico con el método de autenticación de contraseña. |
Si el parámetro de error tiene un valor de invalid_grant, Microsoft Entra incluye un suberror parámetro en su respuesta. Estos son los valores posibles del parámetro suberror para un error de invalid_grant:
| Valor del sub error | Descripción |
|---|---|
password_too_weak |
La contraseña es demasiado débil ya que no cumple los requisitos de complejidad. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. Esta respuesta es posible si la aplicación envía una contraseña de usuario. |
password_too_short |
La nueva contraseña tiene menos de 8 caracteres. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. Esta respuesta es posible si la aplicación envía una contraseña de usuario. |
password_too_long |
La nueva contraseña tiene más de 256 caracteres. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. Esta respuesta es posible si la aplicación envía una contraseña de usuario. |
password_recently_used |
La nueva contraseña no debe ser la misma a una que se haya utilizado recientemente. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. Esta respuesta es posible si la aplicación envía una contraseña de usuario. |
password_banned |
La nueva contraseña contiene una palabra, frase o patrón prohibido. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. Esta respuesta es posible si la aplicación envía una contraseña de usuario. |
password_is_invalid |
Por ejemplo, la contraseña no es válida, porque utiliza caracteres no permitidos. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. Esta respuesta es posible si la aplicación envía una contraseña de usuario. |
Si el parámetro de error tiene un valor de invalid_client, Microsoft Entra incluye un parámetro suberror en su respuesta. Estos son los valores posibles del parámetro suberror para un error de invalid_client:
| Valor del sub error | Descripción |
|---|---|
nativeauthapi_disabled |
El Id. de cliente para una aplicación que no está habilitada para la autenticación nativa. |
Nota:
Si envía todos los atributos obligatorios a través del punto de conexión /signup/v1.0/start, pero no todos los atributos opcionales, no podrá enviar ningún atributo opcional adicional posteriormente a través del punto de conexión /signup/v1.0/continue. Microsoft Entra no solicita explícitamente atributos opcionales, ya que no son obligatorios para que se complete el flujo de registro. Consulte la tabla de la sección Envío de atributos de usuario a puntos de conexión para conocer los atributos de usuario que puede enviar a los puntos de conexión /signup/v1.0/start y /signup/v1.0/continue.
Paso 2: Seleccionar un método de autenticación
La aplicación solicita a Microsoft Entra que seleccione uno de los tipos de desafío admitidos para que el usuario se autentique. Para ello, la aplicación realiza una llamada al punto de conexión /signup/v1.0/challenge. La aplicación debe incluir el token de continuación que adquiere del punto de conexión /signup/v1.0/start de la solicitud.
Este es un ejemplo de la solicitud (presentamos la solicitud de ejemplo en varias líneas para facilitar la lectura).
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…
| Parámetro | Obligatorio | Descripción |
|---|---|---|
tenant_subdomain |
Sí | Subdominio del inquilino externo que creó. En la dirección URL, reemplace {tenant_subdomain} por el subdominio Directorio (inquilino). Por ejemplo, si el dominio principal del inquilino es contoso.onmicrosoft.com, use Contoso. Si no tiene el subdominio de inquilino, obtenga información sobre cómo leer los detalles del inquilino. |
client_id |
Sí | El identificador de aplicación (cliente) de la aplicación que registró en el Centro de administración de Microsoft Entra. |
challenge_type |
No | Una lista separada por espacios de autorización tipo de desafío cadenas que admite la aplicación, como oob password redirect. La lista siempre debe incluir el tipo de desafío redirect. Se espera que el valor sea oob redirect para el código de acceso de un solo uso del correo electrónico y oob password redirect para el correo electrónico con el método de autenticación de contraseña. |
continuation_token |
Sí | Token de continuación que Microsoft Entra devolvió en la solicitud anterior. |
Respuesta correcta
Microsoft Entra envía un código de acceso de un solo uso al correo electrónico del usuario, y luego responde con el tipo de desafío con un valor de OOB e información adicional sobre dicho código:
HTTP/1.1 200 OK
Content-Type: application/json
{
"interval": 300,
"continuation_token": "AQABAAEAAAYn...",
"challenge_type": "oob",
"binding_method": "prompt",
"challenge_channel": "email",
"challenge_target_label": "c***r@co**o**o.com",
"code_length": 8
}
| Parámetro | Descripción |
|---|---|
interval |
El período de tiempo en segundos que la aplicación debe esperar antes de intentar volver a enviar OTP. |
continuation_token |
Token de continuación que devuelve Microsoft Entra. |
challenge_type |
Tipo de desafío seleccionado para que el usuario se autentique. |
binding_method |
El único valor válido es símbolo del sistema. Este parámetro puede utilizarse en el futuro para ofrecer al usuario otras maneras de introducir el código de acceso de un solo uso. Se emite si challenge_type esOOB |
challenge_channel |
Tipo del canal a través del cual se envió el código de acceso de un solo uso. Por el momento, solo se admite el canal de correo electrónico. |
challenge_target_label |
Un correo electrónico ofuscado a donde se envió el código de acceso de un solo uso. |
code_length |
Longitud del código de acceso de un solo uso que genera Microsoft Entra. |
Si una aplicación no es compatible con un método de autenticación requerido por Microsoft Entra, es necesario recurrir al flujo de autenticación basado en web. En este escenario, Microsoft Entra informa a la aplicación devolviendo un tipo de desafío de redirección en su respuesta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parámetro | Descripción |
|---|---|
challenge_type |
Microsoft Entra devuelve una respuesta que tiene un tipo de desafío. El valor de este tipo de desafío es el redireccionamiento, lo que permite a la aplicación usar el flujo de autenticación basado en web. |
Esta respuesta se considera correcta, pero la aplicación debe cambiar a un flujo de autenticación basado en web. En este caso, le recomendamos que utilice una biblioteca de autenticación compatible y creada por Microsoft.
Respuesta de error
Ejemplo:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parámetro | Descripción |
|---|---|
error |
Una cadena de código de error que puede usarse para clasificar los tipos de errores y para reaccionar a los errores. |
error_description |
Un mensaje de error específico que puede ayudarle a identificar la causa de un error de autenticación. |
error_codes |
Una lista de códigos de error específicos de Microsoft Entra que pueden ayudarle a diagnosticar errores. |
timestamp |
La hora a la que se produjo el error. |
trace_id |
Un identificador único para la solicitud que puede ayudarle a diagnosticar errores. |
correlation_id |
Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes. |
Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):
| Valor de error | Descripción |
|---|---|
invalid_request |
Error en la validación de los parámetros de la solicitud, por ejemplo, el Id. de cliente está vacío o no es válido. |
expired_token |
El token de continuación ha expirado. |
unsupported_challenge_type |
El valor del parámetro challenge_type no incluye el tipo de desafío redirect. |
invalid_grant |
El token de continuación no es válido. |
Paso 3: Enviar el código de acceso de un solo uso
La aplicación envía el código de acceso de un solo uso enviado al correo electrónico del usuario. Dado que estamos enviando un código de acceso de un solo uso, se requiere un parámetro oob, y el parámetro grant_type debe tener un valor oob.
He aquí un ejemplo de solicitud (presentamos la solicitud de ejemplo en varias líneas para facilitar la lectura):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=oob
&oob={otp_code}
| Parámetro | Obligatorio | Descripción |
|---|---|---|
tenant_subdomain |
Sí | Subdominio del inquilino externo que creó. En la dirección URL, reemplace {tenant_subdomain} por el subdominio Directorio (inquilino). Por ejemplo, si el dominio principal del inquilino es contoso.onmicrosoft.com, use Contoso. Si no tiene el subdominio de inquilino, obtenga información sobre cómo leer los detalles del inquilino. |
continuation_token |
Sí | Token de continuación que Microsoft Entra devolvió en la solicitud anterior. |
client_id |
Sí | El identificador de aplicación (cliente) de la aplicación que registró en el Centro de administración de Microsoft Entra. |
grant_type |
Sí | Se puede usar una solicitud al punto de conexión /signup/v1.0/continue para enviar el código de acceso de un solo uso, la contraseña o los atributos de usuario. En este caso, el valor grant_type se utiliza para diferenciar entre estos tres casos de uso. Los valores posibles para grant_type son OOB, contraseña, atributos. En esta llamada, como estamos enviando un código de acceso de un solo uso, se espera que el valor sea oob. |
oob |
Sí | Código de acceso de un solo uso que el usuario del cliente recibió en su correo electrónico. Reemplace {otp_code} por los valores del código de acceso de un solo uso que el usuario del cliente recibió en su correo electrónico. Para volver a enviar un código de acceso de un solo uso, la aplicación debe volver a realizar una solicitud al punto de conexión /signup/v1.0/challenge. |
Una vez que la aplicación envía correctamente el código de acceso de un solo uso, el flujo de registro depende de los escenarios que se muestran en la tabla:
| Escenario | Procedimiento |
|---|---|
La aplicación envía correctamente la contraseña del usuario (para el correo electrónico con el método de autenticación de contraseña) mediante el punto de conexión /signup/v1.0/start y no hay atributos configurados en el Centro de administración de Microsoft Entra o todos los atributos de usuario requeridos se envían mediante el punto de conexión /signup/v1.0/start. |
Microsoft Entra emite un token de continuación. La aplicación puede utilizar el token de continuación para solicitar tokens de seguridad como se muestra en el paso 5. |
La aplicación envía correctamente la contraseña del usuario (para el correo electrónico con el método de autenticación de contraseña) mediante /signup/v1.0/start, pero no todos los atributos de usuario requeridos, Microsoft Entra indica los atributos que la aplicación necesita enviar como se muestra en los atributos de usuario requeridos. |
La aplicación debe enviar los atributos de usuario requeridos a través del punto de conexión /signup/v1.0/continue. La respuesta es similar a la de Atributos de usuario requeridos. Envíe los atributos de usuario como se muestran en Enviar atributos de usuario. |
La aplicación no envía la contraseña del usuario (para el correo electrónico con el método de autenticación de contraseña) a través del punto de conexión /signup/v1.0/start. |
La respuesta de Microsoft Entra indica que la credencial es necesaria. Consulte respuesta. Esta respuesta es posible para el correo electrónico con el método de autenticación de contraseña. |
Respuesta
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "credential_required",
"error_description": "AADSTS55103: Credential required. Trace ID: d6966055-...-80500 Correlation ID: 3944-...-60d6 Timestamp: yy-mm-dd 02:37:33Z",
"error_codes": [
55103
],
"timestamp": "yy-mm-dd 02:37:33Z",
"trace_id": "d6966055-...-80500",
"correlation_id": "3944-...-60d6",
"continuation_token": "AQABEQEAAAA..."
}
| Parámetro | Descripción |
|---|---|
error |
Una cadena de código de error que puede usarse para clasificar los tipos de errores y para reaccionar a los errores. |
error_description |
Un mensaje de error específico que puede ayudarle a identificar la causa de un error de autenticación. |
error_codes |
Una lista de códigos de error específicos de Microsoft Entra que pueden ayudarle a diagnosticar errores. |
timestamp |
La hora a la que se produjo el error. |
trace_id |
Un identificador único para la solicitud que puede ayudarle a diagnosticar errores. |
correlation_id |
Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes. |
continuation_token |
Token de continuación que devuelve Microsoft Entra. |
suberror |
Cadena de código de error que se puede usar para clasificar aún más tipos de errores. |
Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):
| Valor de error | Descripción |
|---|---|
credential_required |
La autenticación es necesaria para la creación de cuentas, por lo que hay que realizar una llamada al punto de conexión /signup/v1.0/challenge para determinar la credencial que el usuario debe proporcionar. |
invalid_request |
Ha ocurrido un error en la validación de los parámetros de la solicitud, como un error en la validación del token de continuación o la solicitud no incluía el parámetro client_id, el valor del id. de cliente está vacío o no es válido, o el administrador de inquilinos externo no ha habilitado el OTP de correo electrónico para todos los usuarios del inquilino. |
invalid_grant |
El tipo de subvención incluido en la solicitud no es válido o compatible, o el valor OTP es incorrecto. |
expired_token |
El token de continuación incluido en la solicitud ha expirado. |
Si el parámetro de error tiene un valor de invalid_grant, Microsoft Entra incluye un suberror parámetro en su respuesta. Estos son los valores posibles del parámetro suberror para un error de invalid_grant:
| Valor del sub error | Descripción |
|---|---|
invalid_oob_value |
El valor del código de acceso de un solo uso no es válido. |
Para obtener la credencial de contraseña del usuario, la aplicación debe realizar una llamada al punto de conexión /signup/v1.0/challenge para determinar la credencial que el usuario debe proporcionar.
He aquí un ejemplo de solicitud (presentamos la solicitud de ejemplo en varias líneas para facilitar la lectura):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…
| Parámetro | Obligatorio | Descripción |
|---|---|---|
tenant_subdomain |
Sí | Subdominio del inquilino externo que creó. En la dirección URL, reemplace {tenant_subdomain} por el subdominio Directorio (inquilino). Por ejemplo, si el dominio principal del inquilino es contoso.onmicrosoft.com, use Contoso. Si no tiene el subdominio de inquilino, obtenga información sobre cómo leer los detalles del inquilino. |
client_id |
Sí | El identificador de aplicación (cliente) de la aplicación que registró en el Centro de administración de Microsoft Entra. |
challenge_type |
No | Una lista separada por espacios de autorización tipo de desafío cadenas que admite la aplicación, como oob password redirect. La lista siempre debe incluir el tipo de desafío redirect. Para el correo electrónico con el flujo de registro de contraseñas, se espera que el valor contenga password redirect. |
continuation_token |
Sí | Token de continuación que Microsoft Entra devolvió en la solicitud anterior. |
Respuesta correcta
Si la contraseña es el método de autenticación configurado para el usuario en el Centro de administración de Microsoft Entra, se devuelve una respuesta correcta con el token de continuación a la aplicación.
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "password",
"continuation_token": " AQABAAEAAAAty..."
}
| Parámetro | Descripción |
|---|---|
challenge_type |
contraseña se devuelve en la respuesta de la credencial necesaria. |
continuation_token |
Token de continuación que devuelve Microsoft Entra. |
Si una aplicación no es compatible con un método de autenticación requerido por Microsoft Entra, es necesario recurrir al flujo de autenticación basado en web. En este escenario, Microsoft Entra informa a la aplicación devolviendo un tipo de desafío de redirección en su respuesta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parámetro | Descripción |
|---|---|
challenge_type |
Microsoft Entra devuelve una respuesta que tiene un tipo de desafío. El valor de este tipo de desafío es el redireccionamiento, lo que permite a la aplicación usar el flujo de autenticación basado en web. |
Esta respuesta se considera correcta, pero la aplicación debe cambiar a un flujo de autenticación basado en web. En este caso, le recomendamos que utilice una biblioteca de autenticación compatible y creada por Microsoft.
Paso 4: Autenticación y obtención del token para registrarse
La aplicación debe enviar las credenciales del usuario, en este caso la contraseña, que Microsoft Entra solicitó en el paso anterior. La aplicación debe enviar una credencial de contraseña si no lo ha hecho a través del punto de conexión /signup/v1.0/start. La aplicación realiza una solicitud al punto de conexión /signup/v1.0/continue para enviar la contraseña. Dado que estamos enviando una contraseña, se requiere un parámetro password, y el parámetro grant_type debe tener un valor contraseña.
He aquí un ejemplo de solicitud (presentamos la solicitud de ejemplo en varias líneas para facilitar la lectura):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=password
&password={secure_password}
| Parámetro | Obligatorio | Descripción |
|---|---|---|
tenant_subdomain |
Sí | Subdominio del inquilino externo que creó. En la dirección URL, reemplace {tenant_subdomain} por el subdominio Directorio (inquilino). Por ejemplo, si el dominio principal del inquilino es contoso.onmicrosoft.com, use Contoso. Si no tiene el subdominio de inquilino, obtenga información sobre cómo leer los detalles del inquilino. |
continuation_token |
Sí | Token de continuación que Microsoft Entra devolvió en el paso anterior. |
client_id |
Sí | El identificador de aplicación (cliente) de la aplicación que registró en el Centro de administración de Microsoft Entra. |
grant_type |
Sí | Se puede usar una solicitud al punto de conexión /signup/v1.0/continue para enviar el código de acceso de un solo uso, la contraseña o los atributos de usuario. En este caso, el valor grant_type se utiliza para diferenciar entre estos tres casos de uso. Los valores posibles para grant_type son OOB, contraseña, atributos. En esta llamada, como estamos enviando la contraseña del usuario, se espera que el valor sea contraseña. |
password |
Sí | El valor de la contraseña que la aplicación recopila del usuario cliente. Reemplace {secure_password} con el valor de la contraseña que la aplicación recopila del usuario cliente. Es su responsabilidad confirmar que el usuario es consciente de la contraseña que desea utilizar proporcionando el campo de confirmación de contraseña en la interfaz de usuario de la aplicación. También debe asegurarse de que el usuario es consciente de lo que constituye una contraseña segura según la directiva de su organización. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. |
Respuesta correcta
Si la solicitud se realiza correctamente, pero no se configuraron atributos en el Centro de administración de Microsoft Entra o todos los atributos requeridos fueron enviados a través del punto de conexión /signup/v1.0/start, la aplicación obtiene un token de continuación sin enviar ningún atributo. La aplicación puede utilizar el token de continuación para solicitar tokens de seguridad como se muestra en el paso 5. En caso contrario, la respuesta de Microsoft Entra indica que la aplicación debe enviar los atributos requeridos. Estos atributos, incorporados o personalizados, fueron configurados en el Centro de administración de Microsoft Entra por el administrador del inquilino.
Atributos de usuario requeridos
Esta respuesta solicita a la aplicación que envíe valores para los atributos nombre, *edad y teléfono.
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "attributes_required",
"error_description": "User attributes required",
"error_codes": [
55106
],
"timestamp": "yy-mm-dd 02:37:33Z",
"trace_id": "d6966055-...-80500",
"correlation_id": "3944-...-60d6",
"continuation_token": "AQABAAEAAAAtn...",
"required_attributes": [
{
"name": "displayName",
"type": "string",
"required": true,
"options": {
"regex": ".*@.**$"
}
},
{
"name": "extension_2588abcdwhtfeehjjeeqwertc_age",
"type": "string",
"required": true
},
{
"name": "postalCode",
"type": "string",
"required": true,
"options": {
"regex":"^[1-9][0-9]*$"
}
}
],
}
Nota:
Los atributos personalizados (también conocidos como extensiones de directorio) se denominan mediante la convención extension_{appId-without-hyphens}_{attribute-name} donde {appId-without-hyphens} es la versión despojada del Id. de cliente para la aplicación de extensiones. Por ejemplo, si el Id. de cliente de la aplicación de extensiones es 2588a-bcdwh-tfeehj-jeeqw-ertc y el nombre del atributo es aficiones, el atributo personalizado se denomina comoextension_2588abcdwhtfeehjjeeqwertc_hobbies. Obtenga más información sobre atributos personalizados y la aplicación de extensión.
| Parámetro | Descripción |
|---|---|
error |
Este atributo se establece si Microsoft Entra no puede crear la cuenta de usuario porque es necesario comprobar o enviar un atributo. |
error_description |
Un mensaje de error específico que puede ayudarle a identificar la causa del error. |
error_codes |
Una lista de códigos de error específicos de Microsoft Entra que pueden ayudarle a diagnosticar errores. |
timestamp |
La hora a la que se produjo el error. |
trace_id |
Un identificador único para la solicitud que puede ayudarle a diagnosticar errores. |
correlation_id |
Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes. |
continuation_token |
Token de continuación que devuelve Microsoft Entra. |
required_attributes |
Una lista (matriz de objetos) de atributos que la aplicación necesita enviar en la siguiente llamada para continuar. Estos atributos son los atributos adicionales que la aplicación debe enviar aparte del nombre de usuario. Microsoft Entra incluye este parámetro es la respuesta si el valor de error parámetro es attributes_required. |
Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):
| Valor de error | Descripción |
|---|---|
invalid_request |
Ha ocurrido un error en la validación del parámetro de la solicitud, como el error en la validación del token de continuación o que la solicitud no incluía el parámetro client_id o que el valor del Id. del cliente está vacío o no es válido. |
invalid_grant |
El tipo de subvención incluido en la solicitud no es válido ni compatible. Los valores posibles para el grant_type son OOB, contraseña, atributos |
expired_token |
El token de continuación incluido en la solicitud ha expirado. |
attributes_required |
Se requiere uno o más de los atributos de usuario. |
Si una aplicación no es compatible con un método de autenticación requerido por Microsoft Entra, es necesario recurrir al flujo de autenticación basado en web. En este escenario, Microsoft Entra informa a la aplicación devolviendo un tipo de desafío de redirección en su respuesta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parámetro | Descripción |
|---|---|
challenge_type |
Microsoft Entra devuelve una respuesta que tiene un tipo de desafío. El valor de este tipo de desafío es el redireccionamiento, lo que permite a la aplicación usar el flujo de autenticación basado en web. |
Esta respuesta se considera correcta, pero la aplicación debe cambiar a un flujo de autenticación basado en web. En este caso, le recomendamos que utilice una biblioteca de autenticación compatible y creada por Microsoft.
Respuesta de error
Ejemplo:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_grant",
"error_description": "New password is too weak",
"error_codes": [
399246
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
"suberror": "password_too_weak"
}
| Parámetro | Descripción |
|---|---|
error |
Una cadena de código de error que puede usarse para clasificar los tipos de errores y para reaccionar a los errores. |
error_description |
Un mensaje de error específico que puede ayudarle a identificar la causa de un error de autenticación. |
error_codes |
Una lista de códigos de error específicos de Microsoft Entra que pueden ayudarle a diagnosticar errores. |
timestamp |
La hora a la que se produjo el error. |
trace_id |
Un identificador único para la solicitud que puede ayudarle a diagnosticar errores. |
correlation_id |
Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes. |
suberror |
Cadena de código de error que se puede usar para clasificar aún más tipos de errores. |
Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):
| Valor de error | Descripción |
|---|---|
invalid_request |
Ha ocurrido un error en la validación del parámetro challenge_type, como cuando el parámetro incluye un tipo de desafío no válido. |
invalid_grant |
La subvención enviada no es válida, por ejemplo, la contraseña enviada es demasiado corta. Use el parámetro suberror para obtener información sobre la causa exacta del error. |
expired_token |
El token de continuación ha expirado. |
attributes_required |
Se requiere uno o más de los atributos de usuario. |
Si el parámetro de error tiene un valor de invalid_grant, Microsoft Entra incluye un suberror parámetro en su respuesta. Estos son los posibles valores del parámetro suberror:
| Valor del sub error | Descripción |
|---|---|
password_too_weak |
La contraseña es demasiado débil ya que no cumple los requisitos de complejidad. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. |
password_too_short |
La nueva contraseña tiene menos de 8 caracteres. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. |
password_too_long |
La nueva contraseña tiene más de 256 caracteres. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. |
password_recently_used |
La nueva contraseña no debe ser la misma a una que se haya utilizado recientemente. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. |
password_banned |
La nueva contraseña contiene una palabra, frase o patrón prohibido. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. |
password_is_invalid |
Por ejemplo, la contraseña no es válida, porque utiliza caracteres no permitidos. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. Esta respuesta es posible si la aplicación envía una contraseña de usuario. |
Enviar atributos de usuario
Para continuar con el flujo, la aplicación necesita realizar una llamada al punto de conexión /signup/v1.0/continue para enviar los atributos de usuario requeridos. Dado que estamos enviando atributos, se requiere un parámetro attributes, y el parámetro grant_type debe tener un valor igual a atributos.
He aquí un ejemplo de solicitud (presentamos la solicitud de ejemplo en varias líneas para facilitar la lectura):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=attributes
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postaCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...
| Parámetro | Obligatorio | Descripción |
|---|---|---|
tenant_subdomain |
Sí | Subdominio del inquilino externo que creó. En la dirección URL, reemplace {tenant_subdomain} por el subdominio Directorio (inquilino). Por ejemplo, si el dominio principal del inquilino es contoso.onmicrosoft.com, use Contoso. Si no tiene el subdominio de inquilino, obtenga información sobre cómo leer los detalles del inquilino. |
continuation_token |
Sí | Token de continuación que Microsoft Entra devolvió en la solicitud anterior. |
client_id |
Sí | El identificador de aplicación (cliente) de la aplicación que registró en el Centro de administración de Microsoft Entra. |
grant_type |
Sí | Se puede usar una solicitud al punto de conexión /signup/v1.0/continue para enviar el código de acceso de un solo uso, la contraseña o los atributos de usuario. En este caso, el valor grant_type se utiliza para diferenciar entre estos tres casos de uso. Los valores posibles para grant_type son OOB, contraseña, atributos. En esta llamada, dado que estamos enviando atributos de usuario, se espera que el valor sea atributos. |
attributes |
Sí | Los valores de atributo de usuario que recopila la aplicación del usuario cliente. El valor es una cadena, pero con formato de objeto JSON cuyas claves son nombres de atributos de usuario, integrados o personalizados. Los nombres clave del objeto dependen de los atributos que el administrador haya configurado en el Centro de administración de Microsoft Entra. Reemplace {given_name}, {user_age} y {postal_code} por los valores de nombre, edad y código postal respectivamente que la aplicación recopila del usuario del cliente. Microsoft Entra omite los atributos que envíe, que no existen. |
Respuesta correcta
Si la solicitud se realiza correctamente, Microsoft Entra emite un token de continuación, que la aplicación puede usar para solicitar tokens de seguridad.
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAAYn..."
}
| Parámetro | Descripción |
|---|---|
continuation_token |
Token de continuación que devuelve Microsoft Entra. |
Si una aplicación no es compatible con un método de autenticación requerido por Microsoft Entra, es necesario recurrir al flujo de autenticación basado en web. En este escenario, Microsoft Entra informa a la aplicación devolviendo un tipo de desafío de redirección en su respuesta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parámetro | Descripción |
|---|---|
challenge_type |
Microsoft Entra devuelve una respuesta que tiene un tipo de desafío. El valor de este tipo de desafío es el redireccionamiento, lo que permite a la aplicación usar el flujo de autenticación basado en web. |
Esta respuesta se considera correcta, pero la aplicación debe cambiar a un flujo de autenticación basado en web. En este caso, le recomendamos que utilice una biblioteca de autenticación compatible y creada por Microsoft.
Respuesta de error
Ejemplo:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "expired_token",
"error_description": "AADSTS901007: The continuation_token is expired. .\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
552003
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parámetro | Descripción |
|---|---|
error |
Una cadena de código de error que puede usarse para clasificar los tipos de errores y para reaccionar a los errores. |
error_description |
Un mensaje de error específico que puede ayudarle a identificar la causa de un error de autenticación. |
error_codes |
Una lista de códigos de error específicos de Microsoft Entra que pueden ayudarle a diagnosticar errores. |
timestamp |
La hora a la que se produjo el error. |
trace_id |
Un identificador único para la solicitud que puede ayudarle a diagnosticar errores. |
correlation_id |
Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes. |
continuation_token |
Token de continuación que devuelve Microsoft Entra. |
unverified_attributes |
Una lista (matriz de objetos) de nombres de clave de atributo que se deben comprobar. Este parámetro se incluye en la respuesta cuando el errorvalor del parámetro es verification_required. |
required_attributes |
Una lista (matriz de objetos) de atributos que la aplicación debe enviar. Microsoft Entra incluye este parámetro en su respuesta cuando el valor del parámetro error es attributes_required. |
invalid_attributes |
Lista (matriz de objetos) de atributos que no se pudieron validar. Este parámetro se incluye en la respuesta cuando el valor del parámetro suberror es attribute_validation_failed. |
suberror |
Cadena de código de error que se puede usar para clasificar aún más tipos de errores. |
Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):
| Valor de error | Descripción |
|---|---|
invalid_request |
Ha ocurrido un error en la validación del parámetro de la solicitud, como el error en la validación del token de continuación o que la solicitud no incluía el parámetro client_id o que el valor del Id. del cliente está vacío o no es válido. |
invalid_grant |
El tipo de concesión proporcionado no es válido, no se admite o no se puede validar, como la validación de atributos. Use el parámetro suberror para obtener información sobre la causa exacta del error. |
expired_token |
El token de continuación incluido en la solicitud ha expirado. |
attributes_required |
Se requiere uno o más de los atributos de usuario. |
Si el parámetro de error tiene un valor de invalid_grant, Microsoft Entra incluye un suberror parámetro en su respuesta. Estos son los valores posibles del parámetro suberror para un error de invalid_grant:
| Valor del sub error | Descripción |
|---|---|
attribute_validation_failed |
Ha ocurrido un error en la validación de atributos de usuario. El parámetro invalid_attributes contiene la lista (matriz de objetos) de atributos cuya validación ha fallado. |
Paso 5: Solicitud de tokens de seguridad
La aplicación realiza una solicitud POST al punto de conexión /token y proporciona el token de continuación obtenido en el paso anterior para adquirir tokens de seguridad.
Este es un ejemplo de solicitud (presentamos la solicitud de ejemplo en varias líneas para facilitar la lectura):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
continuation_token=ABAAEAAAAtyo...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&username=contoso-consumer@contoso.com
&scope={scopes}
&grant_type=continuation_token
| Parámetro | Obligatorio | Descripción |
|---|---|---|
tenant_subdomain |
Sí | Subdominio del inquilino externo que creó. En la dirección URL, reemplace {tenant_subdomain} por el subdominio Directorio (inquilino). Por ejemplo, si el dominio principal del inquilino es contoso.onmicrosoft.com, use Contoso. Si no tiene el subdominio de inquilino, obtenga información sobre cómo leer los detalles del inquilino. |
client_id |
Sí | El identificador de aplicación (cliente) de la aplicación que registró en el Centro de administración de Microsoft Entra. |
grant_type |
Sí | El valor del parámetro debe ser token de continuación. |
continuation_token |
Sí | Token de continuación que Microsoft Entra devolvió en el paso anterior. |
scope |
Sí | Lista separada por espacios de ámbitos para los que el token de acceso es válido. Reemplace {scopes} por los ámbitos válidos para los que Microsoft Entra devuelve el token de acceso. |
username |
Sí | Correo electrónico del usuario cliente con el que quiere registrarse, como contoso-consumer@contoso.com. |
Respuesta correcta
Este es un ejemplo de una respuesta correcta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"token_type": "Bearer",
"scope": "openid profile",
"expires_in": 4141,
"access_token": "eyJ0eXAiOiJKV1Qi...",
"refresh_token": "AwABAAAA...",
"id_token": "eyJ0eXAiOiJKV1Q..."
}
| Parámetro | Descripción |
|---|---|
access_token |
Token de acceso que solicitó la aplicación desde el punto de conexión /token. La aplicación puede usar este token de acceso para solicitar acceso a recursos protegidos, como las API web. |
token_type |
Indica el valor de tipo de token. El único tipo que admite Microsoft Entra es Bearer. |
expires_in |
El período de tiempo en segundos que el token de acceso sigue siendo válido. |
scopes |
Lista separada por espacios de ámbitos para los que el token de acceso es válido. |
refresh_token |
Un token de actualización de OAuth 2.0. La aplicación puede utilizar este token para obtener otros tokens de acceso una vez que expire el token de acceso actual. Los tokens de actualización tienen una duración larga. Pueden mantener el acceso a los recursos durante períodos prolongados. Para obtener más información sobre cómo actualizar un token de acceso, consulte el artículo Actualizar el token de acceso. Nota: Solo se emitió si se solicitó el ámbito deoffline_access. |
id_token |
Un token web JSON (Jwt) usado para identificar al usuario del cliente. La aplicación puede descodificar el token para leer información sobre el usuario que inició sesión. La aplicación puede almacenar en caché los valores y mostrarlos, y los clientes confidenciales pueden usar este token para la autorización. Para obtener más información sobre los tokens de Id. consulte tokens de Id. Nota: Solo se emite si se solicita el ámbito de openid. |
Respuesta de error
Ejemplo:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The client doesn't have consent for the requested scopes.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parámetro | Descripción |
|---|---|
error |
Una cadena de código de error que puede usarse para clasificar los tipos de errores y para reaccionar a los errores. |
error_description |
Un mensaje de error específico que puede ayudarle a identificar la causa de un error de autenticación. |
error_codes |
Una lista de códigos de error específicos de Microsoft Entra que pueden ayudarle a diagnosticar errores. |
timestamp |
La hora a la que se produjo el error. |
trace_id |
Un identificador único para la solicitud que puede ayudarle a diagnosticar errores. |
correlation_id |
Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes. |
Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):
| Valor de error | Descripción |
|---|---|
invalid_request |
Ha ocurrido un error en la validación de los parámetros de la solicitud, como que el cliente/aplicación no tiene consentimiento para los ámbitos solicitados. |
invalid_grant |
El token de continuación incluido en la solicitud no es válido. |
unauthorized_client |
El Id. de cliente incluido en la solicitud no es válido o no existe. |
unsupported_grant_type |
El tipo de concesión incluido en la solicitud no se admite o no es correcto. |
Envío de atributos de usuario a puntos de conexión
En el Centro de administración Microsoft Entra, puede configurar los atributos de usuario como obligatorios u opcionales. Esta configuración determina cómo responde Microsoft Entra al realizar una llamada a sus puntos de conexión. Los atributos opcionales no son obligatorios para que se complete el flujo de registro. Por lo tanto, cuando todos los atributos son opcionales, deben enviarse para que se pueda comprobar el nombre de usuario. De lo contrario, el registro se completa sin los atributos opcionales.
En la tabla siguiente se resume cuándo es posible enviar atributos de usuario a los puntos de conexión de Microsoft Entra.
| Punto de conexión | Atributos requeridos | Atributos opcionales | Atributos obligatorios y opcionales |
|---|---|---|---|
Punto de conexión /signup/v1.0/start |
Sí | Sí | Sí |
Punto de conexión /signup/v1.0/continue antes de la comprobación del nombre de usuario |
Sí | Sí | Sí |
Punto de conexión /signup/v1.0/continue después de la comprobación del nombre de usuario |
Sí | No | Sí |
Formato de los valores de atributos de usuario
Especifique la información que desea recopilar del usuario mediante la configuración del flujo de usuario en el Centro de administración de Microsoft Entra. Use el artículo Recopilar atributos de usuario personalizados durante el registro para obtener información sobre cómo recopilar valores para atributos integrados y personalizados.
También puede especificar el tipo de entrada de usuario para los atributos que configure. La siguiente tabla resume los tipos de entrada de usuario admitidos, y cómo enviar los valores recopilados por los controles de interfaz de usuario a Microsoft Entra.
| Tipo de entrada de usuario | Formato de los valores enviados |
|---|---|
| TextBox | Un valor único, como el puesto de trabajo, Ingeniero de software. |
| SingleRadioSelect | Valor único como Lenguaje, Noruego. |
| CheckboxMultiSelect | Uno o varios valores, como una afición o varias Baile o Baile, natación, viaje. |
Esta es una solicitud de ejemplo que muestra cómo enviar los valores de los atributos:
POST /{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue HTTP/1.1
Host: {tenant_subdomain}.ciamlogin.com
Content-Type: application/x-www-form-urlencoded
continuation_token=ABAAEAAAAtfyo...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=attributes
&attributes={"jobTitle": "Software Engineer", "extension_2588abcdwhtfeehjjeeqwertc_language": "Norwegian", "extension_2588abcdwhtfeehjjeeqwertc_hobbies": "Dancing,Swimming,Traveling"}
&continuation_token=AQABAAEAAAAtn...
Obtenga más información sobre los tipos de entrada de atributos de usuario en el artículo Tipos de entrada de atributos de usuario personalizados.
Referencia a atributos de usuario
Cuando se crea un flujo de usuario de registro, se configuran los atributos de usuario que se desea recopilar del usuario durante el registro. Los nombres de los atributos de usuario en el Centro de administración de Microsoft Entra son diferentes de la forma en que se hace referencia a ellos en la API de autenticación nativa.
Por ejemplo, Nombre para mostrar en el Centro de administración de Microsoft Entra se hace referencia como displayName en la API.
Use el artículo Atributos de perfil de usuario para obtener información sobre cómo hacer referencia a atributos de usuario integrados y personalizados en la API de autenticación nativa.
Referencia de la API de inicio de sesión
Los usuarios deben iniciar sesión con el método de autenticación que usan para registrarse. Por ejemplo, los usuarios que utilizan el correo electrónico con el método de autenticación de contraseña para registrarse deben iniciar sesión en el correo electrónico y la contraseña.
Para solicitar tokens de seguridad, la aplicación interactúa con tres puntos de conexión: /initiate, /challenge y /token.
Puntos de conexión de API de inicio de sesión
| Punto de conexión | Descripción |
|---|---|
/initiate |
Este punto de conexión inicia el flujo de inicio de sesión. Si la aplicación la llama con un nombre de usuario de una cuenta de usuario que ya existe, devuelve una respuesta correcta con un token de continuación. Si su aplicación solicita usar métodos de autenticación que no son admitidos por Microsoft Entra, esta respuesta de punto de conexión puede indicar a su aplicación que necesita usar un flujo de autenticación basado en el explorador. |
/challenge |
su aplicación llama a este punto de conexión con una lista de tipos de desafíos admitidos por el servicio de identidad. Nuestro servicio de identidad genera un código de acceso de un solo uso y luego lo envía al canal de desafío elegido, por ejemplo, el correo electrónico. Si la aplicación llama repetidamente a este punto de conexión, se enviará una nueva OTP cada vez que se realice una llamada. |
/token |
Este punto de conexión comprueba el código de acceso de un solo uso que recibe de su aplicación y, luego, emite tokens de seguridad para ella. |
Tipos de desafíos de inicio de sesión
La API permite a la aplicación anunciar los métodos de autenticación que admite, cuando realiza una llamada a Microsoft Entra. Para ello, la aplicación usa el parámetro challenge_type en su solicitud. Este parámetro contiene valores predefinidos, que representan diferentes métodos de autenticación.
En el caso de un método de autenticación dado, los valores del tipo de desafío que una aplicación envía a Microsoft Entra durante el flujo de registro son los mismos que cuando la aplicación inicia sesión. Por ejemplo, el correo electrónico con método de autenticación de contraseña usa los valores de tipo de desafío oob, password y redirect para flujos de registro e inicio de sesión.
Puede obtener más información sobre los tipos de desafío en el artículo Tipos de desafío de la autenticación nativa.
Detalles del protocolo de flujo de inicio de sesión
El diagrama de secuencia muestra el flujo del proceso de registro.
Una vez que la aplicación comprueba el correo electrónico del usuario con OTP, recibe tokens de seguridad. Si la entrega del código de acceso de un solo uso se retrasa o nunca llega al correo electrónico del usuario, puede solicitar que se le envíe otro código de acceso de un solo uso. Microsoft Entra vuelve a enviar otro código de acceso de un solo uso si no se ha comprobado el anterior. Cuando Microsoft Entra vuelve a enviar un código de acceso de un solo uso, invalida el código enviado anteriormente.
En las secciones siguientes, resumimos el flujo del diagrama de secuencia en tres pasos básicos.
Paso 1: Solicitud para iniciar el flujo de inicio de sesión
El flujo de autenticación comienza cuando la aplicación realiza una solicitud POST al punto de conexión /initiate para iniciar el flujo de inicio de sesión.
He aquí un ejemplo de solicitud (presentamos la solicitud de ejemplo en varias líneas para facilitar la lectura):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/initiate
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect
&username=contoso-consumer@contoso.com
| Parámetro | Obligatorio | Descripción |
|---|---|---|
tenant_subdomain |
Sí | Subdominio del inquilino externo que creó. En la dirección URL, reemplace {tenant_subdomain} por el subdominio Directorio (inquilino). Por ejemplo, si el dominio principal del inquilino es contoso.onmicrosoft.com, use Contoso. Si no tiene el subdominio de inquilino, obtenga información sobre cómo leer los detalles del inquilino. |
client_id |
Sí | El identificador de aplicación (cliente) de la aplicación que registró en el Centro de administración de Microsoft Entra. |
username |
Sí | Correo electrónico del usuario del cliente, como contoso-consumer@contoso.com. |
challenge_type |
Sí | Una lista separada por espacios de autorización tipo de desafío cadenas que admite la aplicación, como oob password redirect. La lista siempre debe incluir el tipo de desafío redirect. Se espera que oob redirect el valor sea para el código de acceso de un solo uso de correo electrónico y password redirect para el correo electrónico con contraseña. |
Respuesta correcta
Este es un ejemplo de una respuesta correcta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| Parámetro | Descripción |
|---|---|
continuation_token |
Token de continuación que devuelve Microsoft Entra. |
Si una aplicación no es compatible con un método de autenticación requerido por Microsoft Entra, es necesario recurrir al flujo de autenticación basado en web. En este escenario, Microsoft Entra informa a la aplicación devolviendo un tipo de desafío de redirección en su respuesta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parámetro | Descripción |
|---|---|
challenge_type |
Microsoft Entra devuelve una respuesta que tiene un tipo de desafío. El valor de este tipo de desafío es el redireccionamiento, lo que permite a la aplicación usar el flujo de autenticación basado en web. |
Esta respuesta se considera correcta, pero la aplicación debe cambiar a un flujo de autenticación basado en web. En este caso, le recomendamos que utilice una biblioteca de autenticación compatible y creada por Microsoft.
Respuesta de error
Ejemplo:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parámetro | Descripción |
|---|---|
error |
Una cadena de código de error que puede usarse para clasificar los tipos de errores y para reaccionar a los errores. |
error_description |
Un mensaje de error específico que puede ayudarle a identificar la causa de un error de autenticación. |
error_codes |
Una lista de códigos de error específicos de Microsoft Entra que pueden ayudarle a diagnosticar errores. |
timestamp |
La hora a la que se produjo el error. |
trace_id |
Un identificador único para la solicitud que puede ayudarle a diagnosticar errores. |
correlation_id |
Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes. |
Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):
| Valor de error | Descripción |
|---|---|
invalid_request |
Ha ocurrido un error en la validación del parámetro challenge_type, como cuando el parámetro incluye un tipo de desafío no válido. o la solicitud no incluyó el parámetro client_id, el valor de Id. de cliente está vacío o no es válido. Use el parámetro error_description para obtener información sobre la causa exacta del error. |
unauthorized_client |
El id. de cliente utilizado en la solicitud tiene un formato de id. de cliente válido, pero no existe en el inquilino externo o es incorrecto. |
invalid_client |
El Id. de cliente que la aplicación incluye en la solicitud corresponde a una aplicación que carece de configuración de autenticación nativa, como que no es un cliente público o que no está habilitada para la autenticación nativa. Use el parámetro suberror para obtener información sobre la causa exacta del error. |
user_not_found |
El nombre de usuario no existe. |
unsupported_challenge_type |
El valor del parámetro challenge_type no incluye el tipo de desafío redirect. |
Si el parámetro de error tiene un valor de invalid_client, Microsoft Entra incluye un parámetro suberror en su respuesta. Estos son los valores posibles del parámetro suberror para un error de invalid_client:
| Valor del sub error | Descripción |
|---|---|
nativeauthapi_disabled |
El Id. de cliente para una aplicación que no está habilitada para la autenticación nativa. |
Paso 2: Seleccionar un método de autenticación
Para continuar con el flujo, la aplicación utiliza el token de continuación que adquiere en el paso anterior para solicitar a Microsoft Entra que seleccione uno de los tipos de desafío admitidos para que el usuario se autentique con él. La aplicación realiza una solicitud POST al punto de conexión /challenge.
Este es un ejemplo de solicitud (presentamos la solicitud de ejemplo en varias líneas para facilitar la lectura):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect
&continuation_token=uY29tL2F1dGhlbnRpY...
| Parámetro | Obligatorio | Descripción |
|---|---|---|
tenant_subdomain |
Sí | Subdominio del inquilino externo que creó. En la dirección URL, reemplace {tenant_subdomain} por el subdominio Directorio (inquilino). Por ejemplo, si el dominio principal del inquilino es contoso.onmicrosoft.com, use Contoso. Si no tiene el subdominio de inquilino, obtenga información sobre cómo leer los detalles del inquilino. |
client_id |
Sí | El identificador de aplicación (cliente) de la aplicación que registró en el Centro de administración de Microsoft Entra. |
continuation_token |
Sí | Token de continuación que Microsoft Entra devolvió en la solicitud anterior. |
challenge_type |
No | Una lista separada por espacios de autorización tipo de desafío cadenas que admite la aplicación, como oob password redirect. La lista siempre debe incluir el tipo de desafío redirect. Se espera que oob redirect el valor sea para el código de acceso de un solo uso de correo electrónico y password redirect para el correo electrónico con contraseña. |
Respuesta correcta
Si el administrador del inquilino configuró el código de acceso de un solo uso por correo electrónico en el Centro de administración de Microsoft Entra como método de autenticación del usuario, Microsoft Entra envía un código de acceso de un solo uso al correo electrónico del usuario, después responde con un tipo de desafío de oob y proporciona más información sobre el código de acceso de un solo uso.
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"challenge_type": "oob",
"binding_method": "prompt ",
"challenge_channel": "email",
"challenge_target_label ": "c***r@co**o**o.com ",
"code_length": 8
}
| Parámetro | Descripción |
|---|---|
continuation_token |
Token de continuación que devuelve Microsoft Entra. |
challenge_type |
Tipo de desafío seleccionado para que el usuario se autentique. |
binding_method |
El único valor válido es símbolo del sistema. Este parámetro puede utilizarse en el futuro para ofrecer al usuario otras maneras de introducir el código de acceso de un solo uso. Se emite si challenge_type esOOB |
challenge_channel |
Tipo del canal a través del cual se envió el código de acceso de un solo uso. En este momento, se admite el correo electrónico. |
challenge_target_label |
Un correo electrónico ofuscado a donde se envió el código de acceso de un solo uso. |
code_length |
Longitud del código de acceso de un solo uso que genera Microsoft Entra. |
Si una aplicación no es compatible con un método de autenticación requerido por Microsoft Entra, es necesario recurrir al flujo de autenticación basado en web. En este escenario, Microsoft Entra informa a la aplicación devolviendo un tipo de desafío de redirección en su respuesta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parámetro | Descripción |
|---|---|
challenge_type |
Microsoft Entra devuelve una respuesta que tiene un tipo de desafío. El valor de este tipo de desafío es el redireccionamiento, lo que permite a la aplicación usar el flujo de autenticación basado en web. |
Esta respuesta se considera correcta, pero la aplicación debe cambiar a un flujo de autenticación basado en web. En este caso, le recomendamos que utilice una biblioteca de autenticación compatible y creada por Microsoft.
Respuesta de error
Ejemplo:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parámetro | Descripción |
|---|---|
error |
Una cadena de código de error que puede usarse para clasificar los tipos de errores y para reaccionar a los errores. |
error_description |
Un mensaje de error específico que puede ayudarle a identificar la causa de un error de autenticación. |
error_codes |
Una lista de códigos de error específicos de Microsoft Entra que pueden ayudarle a diagnosticar errores. |
timestamp |
La hora a la que se produjo el error. |
trace_id |
Un identificador único para la solicitud que puede ayudarle a diagnosticar errores. |
correlation_id |
Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes. |
Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):
| Valor de error | Descripción |
|---|---|
invalid_request |
Ha ocurrido un error en la validación del parámetro challenge_type, como cuando el parámetro incluye un tipo de desafío no válido. |
invalid_grant |
El token de continuación incluido en la solicitud no es válido. |
expired_token |
El token de continuación incluido en la solicitud ha expirado. |
unsupported_challenge_type |
El valor del parámetro challenge_type no incluye el tipo de desafío redirect. |
Paso 3: Solicitud de tokens de seguridad
La aplicación realiza una solicitud POST al punto de conexión /token y proporciona las credenciales del usuario elegidas en el paso anterior, en este caso la contraseña, para adquirir los tokens de seguridad.
He aquí un ejemplo de solicitud (presentamos la solicitud de ejemplo en varias líneas para facilitar la lectura):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=password
&password={secure_password}
&scope=openid offline_access
| Parámetro | Obligatorio | Descripción |
|---|---|---|
tenant_subdomain |
Sí | Subdominio del inquilino externo que creó. En la dirección URL, reemplace {tenant_subdomain} por el subdominio Directorio (inquilino). Por ejemplo, si el dominio principal del inquilino es contoso.onmicrosoft.com, use Contoso. Si no tiene el subdominio de inquilino, obtenga información sobre cómo leer los detalles del inquilino. |
client_id |
Sí | El identificador de aplicación (cliente) de la aplicación que registró en el Centro de administración de Microsoft Entra. |
continuation_token |
Sí | Token de continuación que Microsoft Entra devolvió en la solicitud anterior. |
grant_type |
Sí | El valor debe ser password en el caso del correo electrónico con el método de autenticación de contraseña y oob en el caso del método de autenticación de código de acceso de un solo uso del correo electrónico. |
scope |
Sí | Una lista de ámbitos separada por espacios. Todos los ámbitos deben proceder de un único recurso, junto con los ámbitos de OpenID Connect (OIDC), como perfil, *openid y correo electrónico. La aplicación debe incluir el ámbito openid para que Microsoft Entra emita un token de identificación. La aplicación debe incluir offline_access ámbito de Microsoft Entra para emitir un token de actualización. Obtenga más información sobre permisos y consentimiento en la plataforma de identidad de Microsoft. |
password |
Sí (para correo electrónico con contraseña) |
El valor de la contraseña que la aplicación recopila del usuario cliente. Reemplace {secure_password} con el valor de la contraseña que la aplicación recopila del usuario cliente. |
oob |
Sí (para código de acceso de un solo uso de correo electrónico) |
Código de acceso de un solo uso que el usuario del cliente recibió en su correo electrónico. Reemplace {otp_code} por el código de acceso de un solo uso que el usuario del cliente recibió en su correo electrónico. Para volver a enviar un código de acceso de un solo uso, la aplicación debe volver a realizar una solicitud al punto de conexión /challenge. |
Respuesta correcta
Este es un ejemplo de una respuesta correcta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"token_type": "Bearer",
"scope": "openid profile",
"expires_in": 4141,
"access_token": "eyJ0eXAiOiJKV1Qi...",
"refresh_token": "AwABAAAA...",
"id_token": "eyJ0eXAiOiJKV1Q..."
}
| Parámetro | Descripción |
|---|---|
token_type |
Indica el valor de tipo de token. El único tipo que admite Microsoft Entra es Bearer. |
scopes |
Lista separada por espacios de ámbitos para los que el token de acceso es válido. |
expires_in |
El período de tiempo en segundos que el token de acceso sigue siendo válido. |
access_token |
Token de acceso que solicitó la aplicación desde el punto de conexión /token. La aplicación puede usar este token de acceso para solicitar acceso a recursos protegidos, como las API web. |
refresh_token |
Un token de actualización de OAuth 2.0. La aplicación puede utilizar este token para obtener otros tokens de acceso una vez que expire el token de acceso actual. Los tokens de actualización tienen una duración larga. Pueden mantener el acceso a los recursos durante períodos prolongados. Para obtener más información sobre cómo actualizar un token de acceso, consulte el artículo Actualizar el token de acceso. Nota: Solo se emite si solicita el ámbito offline_access. |
id_token |
Un token web JSON (Jwt) usado para identificar al usuario del cliente. La aplicación puede descodificar el token para solicitar información sobre el usuario que inició sesión. La aplicación puede almacenar en caché los valores y mostrarlos, y los clientes confidenciales pueden usar este token para la autorización. Para obtener más información sobre los tokens de Id. consulte tokens de Id. Nota: Solo se emite si solicita el ámbito openid. |
Respuesta de error
Ejemplo:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_grant",
"error_description": "AADSTS901007: Error validating credentials due to invalid username or password.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parámetro | Descripción |
|---|---|
error |
Una cadena de código de error que puede usarse para clasificar los tipos de errores y para reaccionar a los errores. |
error_description |
Un mensaje de error específico que puede ayudarle a identificar la causa de un error de autenticación. |
error_codes |
Una lista de códigos de error específicos de Microsoft Entra que pueden ayudarle a diagnosticar errores. |
timestamp |
La hora a la que se produjo el error. |
trace_id |
Un identificador único para la solicitud que puede ayudarle a diagnosticar errores. |
correlation_id |
Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes. |
Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):
| Valor de error | Descripción |
|---|---|
invalid_request |
Ha ocurrido un error en la validación de los parámetros de la solicitud. Para comprender lo que ha ocurrido, use el mensaje en la descripción del error. |
invalid_grant |
El token de continuación incluido en la solicitud no es válido o las credenciales de inicio de sesión del usuario cliente incluidas en la solicitud no son válidas o el tipo de concesión incluido en la solicitud es desconocido. |
invalid_client |
El identificador de cliente incluido en la solicitud no es para un cliente público. |
expired_token |
El token de continuación incluido en la solicitud ha expirado. |
invalid_scope |
Uno o varios de los ámbitos incluidos en la solicitud no son válidos. |
Si el parámetro de error tiene un valor de invalid_grant, Microsoft Entra incluye un suberror parámetro en su respuesta. Estos son los valores posibles del parámetro suberror para un error de invalid_grant:
| Valor del sub error | Descripción |
|---|---|
invalid_oob_value |
El valor del código de acceso de un solo uso no es válido. Este suberror solo se aplica el código de acceso de un solo uso de correo electrónico. |
Autoservicio de restablecimiento de contraseña (SSPR)
Si utiliza el correo electrónico y la contraseña como método de autenticación en su aplicación, use la API de restablecimiento de contraseña de autoservicio (SSPR) para que los usuarios del cliente puedan restablecer su contraseña. Use esta API en situaciones de olvido de contraseña o cambio de contraseña.
Puntos de conexión API de autoservicio de restablecimiento de contraseñas
Para utilizar esta API, la aplicación interactúa con el punto de conexión que se muestra en la siguiente tabla:
| Punto de conexión | Descripción |
|---|---|
/start |
Su aplicación llama a este punto de conexión cuando el usuario cliente selecciona el vínculo o botón Olvidé la contraseña o Cambiar contraseña en la aplicación. Este punto de conexión valida el nombre de usuario del usuario (correo electrónico), y luego devuelve un token de continuación para su uso en el flujo de restablecimiento de contraseña. Si su aplicación solicita usar métodos de autenticación que no son admitidos por Microsoft Entra, esta respuesta de punto de conexión puede indicar a su aplicación que necesita usar un flujo de autenticación basado en el explorador. |
/challenge |
Acepta una lista de tipos de desafío admitidos por el cliente y el token de continuación. Se emite un desafío a una de las credenciales de recuperación preferidas. Por ejemplo, el desafío oob emite un código de acceso de un solo uso fuera de banda al correo electrónico asociado a la cuenta de usuario del cliente. Si su aplicación solicita usar métodos de autenticación que no son admitidos por Microsoft Entra, esta respuesta de punto de conexión puede indicar a su aplicación que necesita usar un flujo de autenticación basado en el explorador. |
/continue |
Valida el reto emitido por el punto de conexión /challenge, y luego devuelve un token de continuación para el punto de conexión /submit o emite otro desafío para el usuario. |
/submit |
Acepta una nueva contraseña introducida por el usuario junto con el token de continuación para completar el flujo de restablecimiento de contraseña. Este punto de conexión emite otro token de continuación. |
/poll_completion |
Por último, la aplicación puede utilizar el token de continuación emitido por el punto de conexión /submitpara comprobar el estado de la solicitud de restablecimiento de contraseña. |
Tipos de desafíos de restablecimiento de contraseña en autoservicio
La API permite a la aplicación anunciar los métodos de autenticación que admite, cuando realiza una llamada a Microsoft Entra. Para ello, la aplicación usa el parámetro challenge_type en su solicitud. Este parámetro contiene valores predefinidos, que representan diferentes métodos de autenticación.
Para el flujo de SSPR, los valores de tipo de desafío son oob, y redireccionamiento.
Obtenga más información sobre los tipos de desafío en tipos de desafío de autenticación nativa.
Detalles del protocolo de restablecimiento de contraseña en autoservicio
El diagrama de secuencia muestra el flujo del proceso de restablecimiento de contraseña.
Este diagrama indica que la aplicación recopila el nombre de usuario (correo electrónico) y la contraseña del usuario en diferentes momentos (y posiblemente en pantallas separadas). Sin embargo, puede diseñar su aplicación para recopilar el nombre de usuario (correo electrónico) y la nueva contraseña en la misma pantalla. En este caso, la aplicación guarda la contraseña y luego la envía a través del punto de conexión /submit donde se requiere.
Paso 1: Solicitar el inicio del flujo de restablecimiento de contraseña de autoservicio
El flujo de restablecimiento de contraseña comienza cuando la aplicación realiza una solicitud POST al punto de conexión /start para iniciar el flujo de restablecimiento de contraseña de autoservicio.
Este es un ejemplo de solicitud (presentamos la solicitud de ejemplo en varias líneas para facilitar la lectura):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&username=contoso-consumer@contoso.com
| Parámetro | Obligatorio | Descripción |
|---|---|---|
tenant_subdomain |
Sí | Subdominio del inquilino externo que creó. En la dirección URL, reemplace {tenant_subdomain} por el subdominio Directorio (inquilino). Por ejemplo, si el dominio principal del inquilino es contoso.onmicrosoft.com, use Contoso. Si no tiene el subdominio de inquilino, obtenga información sobre cómo leer los detalles del inquilino. |
client_id |
Sí | El identificador de aplicación (cliente) de la aplicación que registró en el Centro de administración de Microsoft Entra. |
username |
Sí | Correo electrónico del usuario del cliente, como contoso-consumer@contoso.com. |
challenge_type |
Sí | Una lista separada por espacios de autorización tipo de desafío cadenas que admite la aplicación, como oob password redirect. La lista siempre debe incluir el tipo de desafío redirect. Para esta solicitud, se espera que el valor contenga oob redirect. |
Respuesta correcta
Ejemplo:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| Parámetro | Descripción |
|---|---|
continuation_token |
Token de continuación que devuelve Microsoft Entra. |
Si una aplicación no es compatible con un método de autenticación requerido por Microsoft Entra, es necesario recurrir al flujo de autenticación basado en web. En este escenario, Microsoft Entra informa a la aplicación devolviendo un tipo de desafío de redirección en su respuesta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parámetro | Descripción |
|---|---|
challenge_type |
Microsoft Entra devuelve una respuesta que tiene un tipo de desafío. El valor de este tipo de desafío es el redireccionamiento, lo que permite a la aplicación usar el flujo de autenticación basado en web. |
Esta respuesta se considera correcta, pero la aplicación debe cambiar a un flujo de autenticación basado en web. En este caso, le recomendamos que utilice una biblioteca de autenticación compatible y creada por Microsoft.
Respuesta de error
Ejemplo:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parámetro | Descripción |
|---|---|
error |
Una cadena de código de error que puede usarse para clasificar los tipos de errores y para reaccionar a los errores. |
error_description |
Un mensaje de error específico que puede ayudarle a identificar la causa de un error de autenticación. |
error_codes |
Una lista de códigos de error específicos de Microsoft Entra que pueden ayudarle a diagnosticar errores. |
timestamp |
La hora a la que se produjo el error. |
trace_id |
Un identificador único para la solicitud que puede ayudarle a diagnosticar errores. |
correlation_id |
Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes. |
Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):
| Valor de error | Descripción |
|---|---|
invalid_request |
Ha ocurrido un error en la validación del parámetro de la solicitud, como cuando el parámetro challenge_type incluye un tipo de desafío no válido o la solicitud no incluye un parámetro client_id cuyo valor de Id. de cliente está vacío o no es válido. Use el parámetro error_description para obtener información sobre la causa exacta del error. |
user_not_found |
El nombre de usuario no existe. |
unsupported_challenge_type |
El valor del parámetro challenge_type no incluye el tipo de desafío redirect. |
invalid_client |
El Id. de cliente que la aplicación incluye en la solicitud corresponde a una aplicación que carece de configuración de autenticación nativa, como que no es un cliente público o que no está habilitada para la autenticación nativa. Use el parámetro suberror para obtener información sobre la causa exacta del error. |
unauthorized_client |
El id. de cliente utilizado en la solicitud tiene un formato de id. de cliente válido, pero no existe en el inquilino externo o es incorrecto. |
Si el parámetro de error tiene un valor de invalid_client, Microsoft Entra incluye un parámetro suberror en su respuesta. Estos son los valores posibles del parámetro suberror para un error de invalid_client:
| Valor del sub error | Descripción |
|---|---|
nativeauthapi_disabled |
El Id. de cliente para una aplicación que no está habilitada para la autenticación nativa. |
Paso 2: Seleccionar un método de autenticación
Para continuar con el flujo, la aplicación utiliza el token de continuación adquirido en el paso anterior para solicitar a Microsoft Entra que seleccione uno de los tipos de desafío admitidos para que el usuario se autentique con él. La aplicación realiza una solicitud POST al punto de conexión /challenge. Si esta solicitud tiene éxito, Microsoft Entra envía un código de acceso de un solo uso al correo electrónico de la cuenta del usuario. Por el momento, solo admitimos OTP por correo electrónico.
He aquí un ejemplo (presentamos la solicitud de ejemplo en varias líneas para facilitar la lectura):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY...
| Parámetro | Obligatorio | Descripción |
|---|---|---|
tenant_subdomain |
Sí | Subdominio del inquilino externo que creó. En la dirección URL, reemplace {tenant_subdomain} por el subdominio Directorio (inquilino). Por ejemplo, si el dominio principal del inquilino es contoso.onmicrosoft.com, use Contoso. Si no tiene el subdominio de inquilino, obtenga información sobre cómo leer los detalles del inquilino. |
client_id |
Sí | El identificador de aplicación (cliente) de la aplicación que registró en el Centro de administración de Microsoft Entra. |
continuation_token |
Sí | Token de continuación que Microsoft Entra devolvió en la solicitud anterior. |
challenge_type |
No | Una lista separada por espacios de autorización tipo de desafío cadenas que admite la aplicación, como oob redirect. La lista siempre debe incluir el tipo de desafío redirect. Para esta solicitud, se espera que el valor contenga oob redirect. |
Respuesta correcta
Ejemplo:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"challenge_type": "oob",
"binding_method": "prompt ",
"challenge_channel": "email",
"challenge_target_label ": "c***r@co**o**o.com ",
"code_length": 8
}
| Parámetro | Descripción |
|---|---|
continuation_token |
Token de continuación que devuelve Microsoft Entra. |
challenge_type |
Tipo de desafío seleccionado para que el usuario se autentique. |
binding_method |
El único valor válido es símbolo del sistema. Este parámetro puede utilizarse en el futuro para ofrecer al usuario otras maneras de introducir el código de acceso de un solo uso. Se emite si challenge_type esOOB |
challenge_channel |
Tipo del canal a través del cual se envió el código de acceso de un solo uso. En este momento, se admite el correo electrónico. |
challenge_target_label |
Un correo electrónico ofuscado a donde se envió el código de acceso de un solo uso. |
code_length |
Longitud del código de acceso de un solo uso que genera Microsoft Entra. |
Si una aplicación no es compatible con un método de autenticación requerido por Microsoft Entra, es necesario recurrir al flujo de autenticación basado en web. En este escenario, Microsoft Entra informa a la aplicación devolviendo un tipo de desafío de redirección en su respuesta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parámetro | Descripción |
|---|---|
challenge_type |
Microsoft Entra devuelve una respuesta que tiene un tipo de desafío. El valor de este tipo de desafío es el redireccionamiento, lo que permite a la aplicación usar el flujo de autenticación basado en web. |
Esta respuesta se considera correcta, pero la aplicación debe cambiar a un flujo de autenticación basado en web. En este caso, le recomendamos que utilice una biblioteca de autenticación compatible y creada por Microsoft.
Respuesta de error
Ejemplo:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parámetro | Descripción |
|---|---|
error |
Una cadena de código de error que puede usarse para clasificar los tipos de errores y para reaccionar a los errores. |
error_description |
Un mensaje de error específico que puede ayudarle a identificar la causa de un error de autenticación. |
error_codes |
Una lista de códigos de error específicos de Microsoft Entra que pueden ayudarle a diagnosticar errores. |
timestamp |
La hora a la que se produjo el error. |
trace_id |
Un identificador único para la solicitud que puede ayudarle a diagnosticar errores. |
correlation_id |
Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes. |
Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):
| Valor de error | Descripción |
|---|---|
invalid_request |
Error de validación de parámetros de solicitud, como cuando el parámetro challenge_type incluye un tipo de desafío no válido o token de continuación error de validación. |
expired_token |
El token de continuación ha expirado. |
unsupported_challenge_type |
El valor del parámetro challenge_type no incluye el tipo de desafío redirect. |
Paso 3: Enviar el código de acceso de un solo uso
A continuación, la aplicación realiza una solicitud POST al punto de conexión /continue. En la solicitud, la aplicación debe incluir las credenciales del usuario elegidas en el paso anterior y el token de continuación emitido desde el punto de conexión /challenge.
Este es un ejemplo de solicitud (presentamos la solicitud de ejemplo en varias líneas para facilitar la lectura):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=oob
&oob={otp_code}
| Parámetro | Obligatorio | Descripción |
|---|---|---|
tenant_subdomain |
Sí | Subdominio del inquilino externo que creó. En la dirección URL, reemplace {tenant_subdomain} por el subdominio Directorio (inquilino). Por ejemplo, si el dominio principal del inquilino es contoso.onmicrosoft.com, use Contoso. Si no tiene el subdominio de inquilino, obtenga información sobre cómo leer los detalles del inquilino. |
continuation_token |
Sí | Token de continuación que Microsoft Entra devolvió en la solicitud anterior. |
client_id |
Sí | El identificador de aplicación (cliente) de la aplicación que registró en el Centro de administración de Microsoft Entra. |
grant_type |
Sí | El único valor válido es OOB. |
oob |
Sí | Código de acceso de un solo uso que el usuario del cliente recibió en su correo electrónico. Reemplace {otp_code} por el código de acceso de un solo uso que el usuario del cliente recibió en su correo electrónico. Para volver a enviar un código de acceso de un solo uso, la aplicación debe volver a realizar una solicitud al punto de conexión /challenge. |
Respuesta correcta
Ejemplo:
HTTP/1.1 200 OK
Content-Type: application/json
{
"expires_in": 600,
"continuation_token": "czZCaGRSa3F0MzpnW...",
}
| Parámetro | Descripción |
|---|---|
expires_in |
Tiempo en segundos antes de que expire el continuation_token. El valor máximo de expires_in son 600 segundos. |
continuation_token |
Token de continuación que devuelve Microsoft Entra. |
Respuesta de error
Ejemplo:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS55200: The continuation_token is invalid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
55200
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parámetro | Descripción |
|---|---|
error |
Una cadena de código de error que puede usarse para clasificar los tipos de errores y para reaccionar a los errores. |
error_description |
Un mensaje de error específico que puede ayudarle a identificar la causa de un error de autenticación. |
error_codes |
Una lista de códigos de error específicos de Microsoft Entra que pueden ayudarle a diagnosticar errores. |
timestamp |
La hora a la que se produjo el error. |
trace_id |
Un identificador único para la solicitud que puede ayudarle a diagnosticar errores. |
correlation_id |
Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes. |
suberror |
Cadena de código de error que se puede usar para clasificar aún más tipos de errores. |
Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):
| Valor de error | Descripción |
|---|---|
invalid_request |
Ha ocurrido un error en la validación de los parámetros de la solicitud, como un error en la validación del token de continuación o la solicitud no incluía el parámetro client_id, el valor del Id. de cliente está vacío o no es válido, o el administrador de inquilinos externo no ha habilitado SSPR y OTP por correo electrónico para todos los usuarios del inquilino. Use el parámetro error_description para obtener información sobre la causa exacta del error. |
invalid_grant |
El tipo de subvención es desconocido o no coincide con el valor de tipo de subvención esperado. Use el parámetro suberror para obtener información sobre la causa exacta del error. |
expired_token |
El token de continuación ha expirado. |
Si el parámetro de error tiene un valor de invalid_grant, Microsoft Entra incluye un suberror parámetro en su respuesta. Estos son los valores posibles del parámetro suberror para un error de invalid_grant:
| Valor del sub error | Descripción |
|---|---|
invalid_oob_value |
El código de acceso de un solo uso proporcionado por el usuario no es válido. |
Paso 4: Enviar una nueva contraseña
La aplicación recopila una nueva contraseña del usuario, y luego utiliza el token de continuación emitido por el punto de conexión /continue para enviar la contraseña mediante una solicitud POST al punto de conexión /submit.
He aquí un ejemplo (presentamos la solicitud de ejemplo en varias líneas para facilitar la lectura):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/submit
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0Mzp...
&new_password={new_password}
| Parámetro | Obligatorio | Descripción |
|---|---|---|
tenant_subdomain |
Sí | Subdominio del inquilino externo que creó. En la dirección URL, reemplace {tenant_subdomain} por el subdominio Directorio (inquilino). Por ejemplo, si el dominio principal del inquilino es contoso.onmicrosoft.com, use Contoso. Si no tiene el subdominio de inquilino, obtenga información sobre cómo leer los detalles del inquilino. |
continuation_token |
Sí | Token de continuación que Microsoft Entra devolvió en la solicitud anterior. |
client_id |
Sí | El identificador de aplicación (cliente) de la aplicación que registró en el Centro de administración de Microsoft Entra. |
new_password |
Sí | Nueva contraseña del usuario. Reemplace {new_password} por la nueva contraseña del usuario. Es su responsabilidad confirmar que el usuario es consciente de la contraseña que desea utilizar proporcionando el campo de confirmación de contraseña en la interfaz de usuario de la aplicación. También debe asegurarse de que el usuario es consciente de lo que constituye una contraseña segura según la directiva de su organización. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. |
Respuesta correcta
Ejemplo:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"poll_interval": 2
}
| Parámetro | Descripción |
|---|---|
continuation_token |
Token de continuación que devuelve Microsoft Entra. |
poll_interval |
La cantidad mínima de tiempo en segundos que la aplicación debe esperar entre las solicitudes de sondeo para comprobar el estado de la solicitud de restablecimiento de contraseña a través del punto de conexión /poll_completion, consulte el paso 5 |
Respuesta de error
Ejemplo:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parámetro | Descripción |
|---|---|
error |
Una cadena de código de error que puede usarse para clasificar los tipos de errores y para reaccionar a los errores. |
error_description |
Un mensaje de error específico que puede ayudarle a identificar la causa de un error de autenticación. |
error_codes |
Una lista de códigos de error específicos de Microsoft Entra que pueden ayudarle a diagnosticar errores. |
timestamp |
La hora a la que se produjo el error. |
trace_id |
Un identificador único para la solicitud que puede ayudarle a diagnosticar errores. |
correlation_id |
Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes. |
suberror |
Cadena de código de error que se puede usar para clasificar aún más tipos de errores. |
Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):
| Valor de error | Descripción |
|---|---|
invalid_request |
Ha ocurrido un error en la validación del parámetro de la solicitud, como el error en la validación del token de continuación. |
expired_token |
El token de continuación ha expirado. |
invalid_grant |
La subvención enviada no es válida, por ejemplo, la contraseña enviada es demasiado corta. Use el parámetro suberror para obtener información sobre la causa exacta del error. |
Si el parámetro de error tiene un valor de invalid_grant, Microsoft Entra incluye un suberror parámetro en su respuesta. Estos son los posibles valores del parámetro suberror:
| Valor del sub error | Descripción |
|---|---|
password_too_weak |
La contraseña es demasiado débil ya que no cumple los requisitos de complejidad. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. |
password_too_short |
La nueva contraseña tiene menos de 8 caracteres. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. |
password_too_long |
La nueva contraseña tiene más de 256 caracteres. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. |
password_recently_used |
La nueva contraseña no debe ser la misma a una que se haya utilizado recientemente. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. |
password_banned |
La nueva contraseña contiene una palabra, frase o patrón prohibido. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. |
password_is_invalid |
Por ejemplo, la contraseña no es válida, porque utiliza caracteres no permitidos. Obtenga más información sobre las directivas de contraseña de Microsoft Entra. Esta respuesta es posible si la aplicación envía una contraseña de usuario. |
Paso 5: Sondear el estado de restablecimiento de la contraseña
Por último, dado que la actualización de la configuración del usuario con la nueva contraseña conlleva cierto retraso, la aplicación puede utilizar el punto de conexión /poll_completion para sondear a Microsoft Entra sobre el estado del restablecimiento de la contraseña. La cantidad mínima de tiempo en segundos que la aplicación debe esperar entre las solicitudes de sondeo se devuelve desde el punto de conexión /submit en el parámetro poll_interval.
He aquí un ejemplo (presentamos la solicitud de ejemplo en varias líneas para facilitar la lectura):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/poll_completion
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0...
| Parámetro | Obligatorio | Descripción |
|---|---|---|
tenant_subdomain |
Sí | Subdominio del inquilino externo que creó. En la dirección URL, reemplace {tenant_subdomain} por el subdominio Directorio (inquilino). Por ejemplo, si el dominio principal del inquilino es contoso.onmicrosoft.com, use Contoso. Si no tiene el subdominio de inquilino, obtenga información sobre cómo leer los detalles del inquilino. |
continuation_token |
Sí | Token de continuación que Microsoft Entra devolvió en la solicitud anterior. |
client_id |
Sí | El identificador de aplicación (cliente) de la aplicación que registró en el Centro de administración de Microsoft Entra. |
Respuesta correcta
Ejemplo:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "succeeded",
"continuation_token":"czZCaGRSa3F0..."
}
| Parámetro | Descripción |
|---|---|
status |
Estado de la solicitud de restablecimiento de contraseña. Si Microsoft Entra devuelve un estado fallido, la aplicación puede volver a enviar la nueva contraseña haciendo otra solicitud al punto de conexión /submit e incluyendo el nuevo token de continuación. |
continuation_token |
Token de continuación que devuelve Microsoft Entra. Si el estado es correcto, la aplicación puede utilizar el token de continuación que Microsoft Entra devuelve para solicitar tokens de seguridad a través del punto de conexión /token como se explica en el paso 5 del flujo de registro. Esto significa que una vez que un usuario haya restablecido correctamente su contraseña, podrá iniciar sesión directamente en su aplicación sin necesidad de iniciar un nuevo flujo de inicio de sesión. |
Estos son los posibles estados que devuelve Microsoft Entra (posibles valores del parámetro status):
| Valor de error | Descripción |
|---|---|
succeeded |
El restablecimiento de la contraseña se ha completado correctamente. |
failed |
No se ha podido restablecer la contraseña. La aplicación puede volver a enviar la nueva contraseña realizando otra solicitud al punto de conexión /submit. |
not_started |
No se ha iniciado el restablecimiento de contraseña. La aplicación puede volver a comprobar el estado más tarde. |
in_progress |
Se está restableciendo la contraseña. La aplicación puede volver a comprobar el estado más tarde. |
Respuesta de error
Ejemplo:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "expired_token",
"error_description": "AADSTS901007: The continuation_token is expired.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
552003
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parámetro | Descripción |
|---|---|
error |
Una cadena de código de error que puede usarse para clasificar los tipos de errores y para reaccionar a los errores. |
error_description |
Un mensaje de error específico que puede ayudarle a identificar la causa de un error de autenticación. |
error_codes |
Una lista de códigos de error específicos de Microsoft Entra que pueden ayudarle a diagnosticar errores. |
timestamp |
La hora a la que se produjo el error. |
trace_id |
Un identificador único para la solicitud que puede ayudarle a diagnosticar errores. |
correlation_id |
Un identificador exclusivo para la solicitud que puede ayudar en los diagnósticos entre componentes. |
Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):
| Valor de error | Descripción |
|---|---|
invalid_request |
Ha ocurrido un error en la validación de los parámetros de la solicitud, como error en la validación del token de continuación. |
expired_token |
El token de continuación ha expirado. |