Adición de un conector de API a un flujo de usuario

2025-04-30

Se aplica a: círculo verde con un símbolo de marca de verificación blanco. Inquilinos internos círculo blanco con un símbolo X gris. Inquilinos externos (más información)

Para usar un conector de API, primero debe crear el conector de API y, a continuación, habilitarlo en un flujo de usuario.

Importante

A partir del 12 de julio de 2021, si los clientes de Microsoft Entra B2B configuran nuevas integraciones de Google para usarlas con el registro de autoservicio para sus aplicaciones personalizadas o de línea de negocio, la autenticación con identidades de Google no funcionará hasta que las autenticaciones se muevan a vistas web del sistema. Más información.
El 30 de septiembre de 2021, Google eliminó la compatibilidad con la función de inicio de sesión a través de vistas web integradas. Si las aplicaciones autentican a los usuarios con una vista web insertada y usa la federación de Google con Azure AD B2C o Microsoft Entra B2B para invitaciones de usuarios externos o registro de autoservicio, los usuarios de Google Gmail no se pueden autenticar. Más información.

Creación de un conector de API

Inicie sesión en el Centro de administración de Microsoft Entra como al menos un administrador de usuarios.
Vaya a Entra ID>Identidades externas>Información general.
Seleccione Todos los conectores de API y, a continuación, seleccione Nuevo conector de API.
Escriba el nombre para mostrar de la llamada. Por ejemplo, Compruebe el estado de aprobación.
Proporcione la dirección URL del punto de conexión para la llamada API.
Elija el tipo de autenticación y configure la información de autenticación para llamar a la API. Aprenda a proteger el conector de API.
Seleccione Guardar.

Solicitud enviada a la API

Un conector de API se materializa como una solicitud HTTP POST , enviando atributos de usuario ("claims") como pares clave-valor en un cuerpo JSON. Los atributos se serializan de forma similar a las propiedades de usuario de Microsoft Graph .

Solicitud de ejemplo

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

Solo las propiedades de usuario y los atributos personalizados enumerados en la experiencia de Entra ID>External Identities>Overview>Custom user attributes están disponibles para ser enviados en la solicitud.

Los atributos personalizados existen en el formato extension_<extensions-app-id>_AttributeName en el directorio. La API esperará recibir las notificaciones con este mismo formato serializado. Para más información sobre los atributos personalizados, consulte Definición de atributos personalizados para flujos de registro de autoservicio.

Además, las notificaciones normalmente se envían en todas las solicitudes:

Configuraciones regionales de la interfaz de usuario ('ui_locales'): las configuraciones regionales de un usuario final configuradas en su dispositivo, que la API puede usar para devolver respuestas internacionalizadas.

Dirección de correo electrónico ("correo electrónico") o identidades ("identidades"): estas afirmaciones pueden ser utilizadas por su API para identificar al usuario final que se autentica en la aplicación.

Importante

Si una reclamación no tiene un valor en el momento en que se llama al punto de conexión de la API, no se envía a esta. La API debe estar diseñada para verificar y manejar específicamente el caso en el que una reclamación no está presente en la solicitud.

Habilitación del conector de API en un flujo de usuario

Siga estos pasos para agregar el conector de API a un flujo de usuario de autoservicio de registro.

Inicie sesión en el Centro de administración de Microsoft Entra como al menos un administrador de usuarios.
Vaya a Entra ID>Identidades externas>Información general.
Seleccione Flujos de usuario y, a continuación, seleccione el flujo de usuario al que desea agregar el conector de API.
Seleccione Conectores de API y, a continuación, seleccione los puntos de conexión de API que desea invocar en los pasos siguientes del flujo de usuario:
- Después de federar con un proveedor de identidades durante el registro
- Antes de crear el usuario
Seleccione Guardar.

Inmediatamente después de que el usuario se autentique con un proveedor de identidades (como Google, Facebook o Microsoft Entra ID), se invoca un conector de API en este paso del proceso de registro. Este paso precede a la página de colección de atributos, que es el formulario presentado al usuario para recopilar atributos de usuario.

Solicitud de ejemplo enviada a la API en este paso

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

Las notificaciones exactas enviadas a la API dependen de la información proporcionada por el proveedor de identidades. Siempre se envía "email".

Tipos de respuesta esperados de la API web en este paso

Cuando la API web recibe una solicitud HTTP de Microsoft Entra ID durante un flujo de usuario, puede devolver estas respuestas:

Respuesta de continuación
Respuesta de bloqueo

Respuesta de continuación

Una respuesta de continuación indica que el flujo de usuario debe continuar en el paso siguiente: la página de colección de atributos.

En una respuesta de continuación, la API puede devolver una declaración que:

Rellena previamente el campo de entrada de la página de colección de atributos.

Vea un ejemplo de una respuesta de continuación.

Respuesta de bloqueo

Una respuesta de bloqueo termina el flujo de usuario. La API puede emitir intencionadamente una respuesta de bloqueo para detener la continuación del flujo de usuario mostrando una página de bloqueo al usuario. La página de bloqueo muestra el mensaje userMessage proporcionado por la API.

Vea un ejemplo de una respuesta de bloqueo.

Antes de crear el usuario

Después de la página de recopilación de atributos, se invoca un conector de API en este paso del proceso de registro, si se incluye uno. Este paso siempre se invoca antes de crear una cuenta de usuario en Microsoft Entra ID.

Solicitud de ejemplo enviada a la API en este paso

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

Las notificaciones exactas enviadas a la API dependen de la información recopilada por el usuario o proporcionada por el proveedor de identidades.

Tipos de respuesta esperados de la API web en este paso

Cuando la API web recibe una solicitud HTTP de Microsoft Entra ID durante un flujo de usuario, puede devolver estas respuestas:

Respuesta de continuación
Respuesta de bloqueo
Respuesta de validación

Respuesta de continuación

Una respuesta de continuación indica que el flujo de usuario debe continuar en el paso siguiente: creación del usuario en el directorio.

En una respuesta de continuación, la API puede devolver una declaración que:

Sobrescribe cualquier valor ya asignado a la reclamación desde la página de colección de atributos.

Vea un ejemplo de una respuesta de continuación.

Respuesta de bloqueo

Vea un ejemplo de una respuesta de bloqueo.

Respuesta de error de validación

Cuando la API responde con una respuesta de error de validación, el flujo de usuario permanece en la página de colección de atributos y se muestra userMessage al usuario. El usuario puede editar el formulario y volver a enviarlo. Este tipo de respuesta se puede usar para la validación de datos de entrada.

Vea un ejemplo de una respuesta de error de validación.

Respuestas de ejemplo

Ejemplo de una respuesta de continuación

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

{
    "version": "1.0.0",
    "action": "Continue",
    "postalCode": "12349", // return claim
    "extension_<extensions-app-id>_CustomAttribute": "value" // return claim
}

Parámetro	Tipo	Obligatorio	Descripción
Versión	Cuerda	Sí	Versión de la API.
acción	Cuerda	Sí	El valor debe ser `Continue`.
<atributoDeUsuarioIntegrado>	<tipo de atributo>	No	Los valores se pueden almacenar en el directorio si se seleccionan como solicitud para recibir en la configuración del conector de API y como atributos de usuario para un flujo de usuario. Los valores se pueden devolver en el token si se seleccionan como una reclamación de la aplicación.
<extension_{extensions-app-id}_AtributoPersonalizado>	<tipo de atributo>	No	La notificación no necesita contener `_<extensions-app-id>_`, es opcional. Los valores devueltos pueden sobrescribir los valores recopilados de un usuario.

Ejemplo de una respuesta de bloqueo

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

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "There was an error with your request. Please try again or contact support.",
}

Parámetro	Tipo	Obligatorio	Descripción
Versión	Cuerda	Sí	Versión de la API.
acción	Cuerda	Sí	El valor debe ser `ShowBlockPage`.
mensajeDeUsuario	Cuerda	Sí	Mensaje que se va a mostrar al usuario.

Experiencia del usuario final con una respuesta de bloqueo

Imagen de ejemplo del aspecto de la experiencia del usuario final después de que una API devuelva una respuesta de bloqueo.

Ejemplo de una respuesta de error de validación

HTTP/1.1 400 Bad Request
Content-type: application/json

{
    "version": "1.0.0",
    "status": 400,
    "action": "ValidationError",
    "userMessage": "Please enter a valid Postal Code.",
}

Parámetro	Tipo	Obligatorio	Descripción
Versión	Cuerda	Sí	Versión de la API.
acción	Cuerda	Sí	El valor debe ser `ValidationError`.
estado	Entero/cadena	Sí	Debe ser un valor `400` o `"400"` para una respuesta ValidationError.
mensajeDeUsuario	Cuerda	Sí	Mensaje que se va a mostrar al usuario.

Nota:

El código de estado HTTP debe ser "400" además del valor de "status" en el cuerpo de la respuesta.

Experiencia del usuario final con una respuesta de error de validación

Imagen de ejemplo del aspecto de la experiencia del usuario final después de que una API devuelva una respuesta de error de validación.

Procedimientos recomendados y solución de problemas

Uso de funciones de nube sin servidor

Las funciones sin servidor, como los desencadenadores HTTP en Azure Functions, proporcionan una manera de crear puntos de conexión de API para usarlos con el conector de API. Puede usar la función en la nube sin servidor para, por ejemplo, realizar la lógica de validación y limitar los registros a dominios de correo electrónico específicos. La función de nube sin servidor también puede llamar e invocar a otras API web, almacenes de datos y otros servicios en la nube para escenarios complejos.

Procedimientos recomendados

Asegúrese de que:

La API sigue los contratos de solicitud y respuesta tal como se describió anteriormente.
La URL de endpoint del conector de la API apunta al endpoint correcto de la API.
La API busca explícitamente valores NULL de las notificaciones recibidas de las que depende.
La API implementa un método de autenticación descrito en protección del conector de API.
La API responde lo más rápido posible para garantizar una experiencia de usuario fluida.
- Microsoft Entra ID espera un máximo de 20 segundos para recibir una respuesta. Si no se recibe ninguno, realiza un intento más (reintento) al llamar a la API.
- Si usa una función sin servidor o un servicio web escalable, use un plan de hospedaje que mantenga la API "activa" o "caliente" en producción. Para Azure Functions, se recomienda usar como mínimo el plan Premium.
Garantice una alta disponibilidad de la API.
Supervise y optimice el rendimiento de las API de nivel inferior, las bases de datos u otras dependencias de la API.
Los puntos de conexión deben cumplir los requisitos de seguridad de TLS y cifrado de Microsoft Entra. Para más información, consulte Requisitos del conjunto de cifrado y TLS.

Uso del registro

En general, resulta útil usar las herramientas de registro habilitadas por el servicio de API web, como Application Insights, para supervisar la API para detectar códigos de error inesperados, excepciones y un rendimiento deficiente.

Supervise los códigos de estado HTTP que no sean HTTP 200 ni 400.
Un código de estado HTTP 401 o 403 suele indicar que hay un problema con la autenticación. Compruebe la capa de autenticación de la API y la configuración correspondiente en el conector de API.
Use niveles más agresivos de registro (por ejemplo, "trace" o "debug") en el desarrollo, si es necesario.
Supervise la API en busca de tiempos de respuesta prolongados.

Pasos siguientes

Aprenda a agregar un proceso de aprobación personalizado al registro automático.
Comienza con nuestros ejemplos de inicio rápido.

Compartir vía

Adición de un conector de API a un flujo de usuario

Creación de un conector de API

Solicitud enviada a la API

Habilitación del conector de API en un flujo de usuario

Después de la federación con un proveedor de identidades durante el registro

Solicitud de ejemplo enviada a la API en este paso

Tipos de respuesta esperados de la API web en este paso

Respuesta de continuación

Respuesta de bloqueo

Antes de crear el usuario

Solicitud de ejemplo enviada a la API en este paso

Tipos de respuesta esperados de la API web en este paso

Respuesta de continuación

Respuesta de bloqueo

Respuesta de error de validación

Respuestas de ejemplo

Ejemplo de una respuesta de continuación

Ejemplo de una respuesta de bloqueo

Ejemplo de una respuesta de error de validación

Procedimientos recomendados y solución de problemas

Uso de funciones de nube sin servidor

Procedimientos recomendados

Uso del registro

Pasos siguientes

Comentarios

Recursos adicionales