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.

Requisitos previos

1. Un inquilino externo de Microsoft Entra. Si no tiene uno, cree un inquilino externo.

2. 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.

3. 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.

4. Asocie el registro de su aplicación con el flujo de usuarios.

5. 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.

6. 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

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 la solicitud de la aplicación. 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 

Respuesta correcta

Este es un ejemplo de una respuesta correcta:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "AQABAAEAAA…",
} 

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" 
} 

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"
} 

Estos son los posibles errores que puedes encontrar (posibles valores del parámetro 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 valores posibles del parámetro suberror para un error de invalid_grant:

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:

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…

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
} 

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"
}

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"
} 

Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):

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}

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:

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..."
} 

Estos son los posibles errores que puedes encontrar (posibles valores del parámetro 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 valores posibles del parámetro suberror para un error de invalid_grant:

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…

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..."
}

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" 
} 

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}

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]*$"
            }
        }
    ],
}

Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):

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" 
} 

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"
}

Estos son los posibles errores que puedes encontrar (posibles valores del parámetro 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:

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...

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..."
} 

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" 
} 

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" 
}

Estos son los posibles errores que puedes encontrar (posibles valores del parámetro 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 valores posibles del parámetro suberror para un error de invalid_grant:

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 

Respuesta adecuada

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..."
}

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"
} 

Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):

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.

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.

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

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.

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 

Respuesta correcta

Este es un ejemplo de una respuesta correcta:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

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" 
} 

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"
} 

Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):

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:

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... 

Respuesta correcta

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
} 

HTTP/1.1 200 OK
Content-Type: application/json

{   
   "continuation_token": "uY29tL2F1dGhlbnRpY",   
   "challenge_type": "password" 
} 

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" 
} 

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"
} 

Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):

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 

Respuesta adecuada

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..."
}

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"
} 

Estos son los posibles errores que puedes encontrar (posibles valores del parámetro 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 valores posibles del parámetro suberror para un error de invalid_grant:

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:

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 

Respuesta correcta

Ejemplo:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

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" 
} 

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"
} 

Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):

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:

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... 

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
} 

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" 
} 

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"
} 

Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):

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}

Respuesta correcta

Ejemplo:

HTTP/1.1 200 OK
Content-Type: application/json

{ 
    "expires_in": 600,
    "continuation_token": "czZCaGRSa3F0MzpnW...",
} 

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"
} 

Estos son los posibles errores que puedes encontrar (posibles valores del parámetro 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 valores posibles del parámetro suberror para un error de invalid_grant:

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}

Respuesta correcta

Ejemplo:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "poll_interval": 2
}

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"
} 

Estos son los posibles errores que puedes encontrar (posibles valores del parámetro 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:

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... 

Respuesta correcta

Ejemplo:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "succeeded",
    "continuation_token":"czZCaGRSa3F0..."
} 

Estos son los posibles estados que devuelve Microsoft Entra (posibles valores del parámetro status):

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"
} 

Estos son los posibles errores que puedes encontrar (posibles valores del parámetro error):

Contenido relacionado

• Configuración de un proveedor de notificaciones personalizado.