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

  • Artículo

Para usar un conector de API, primero debe crear el conector de API y, después, habilitarlo en un flujo de usuario.

Importante

Creación de un conector de API

Sugerencia

Los pasos de este artículo pueden variar ligeramente en función del portal desde donde comienza.

  1. Inicie sesión en el Centro de administración de Microsoft Entra al menos como Administrador de usuario.

  2. Vaya a Identidad> Identidades externas>Información general.

  3. Seleccione All API connectors (Todos los conectores de API) y New API connector (Nuevo conector de API).

    Captura de pantalla de la adición de un nuevo conector de API a id. externa.

  4. Escriba el nombre para mostrar de la llamada. Por ejemplo, Comprobar el estado de aprobación.

  5. Proporcione el valor de Dirección URL del punto de conexión de la llamada API.

  6. Elija el tipo de autenticación y configure la información de autenticación para llamar a la API. Obtenga más información sobre la Protección de un conector de API.

    Captura de pantalla de la configuración de un conector de API.

  7. Seleccione Guardar.

Solicitud enviada a la API

Un conector de API se materializa como una solicitud HTTP POST y envía los atributos de usuario ("claims") como pares de clave y 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"
}

En la solicitud solo se pueden enviar las propiedades de usuario y los atributos personalizados que se enumeran en la experiencia Identidad>Identidades externas>Información general>Atributos de usuario personalizados.

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 acerca de los atributos personalizados, consulte cómo definir atributos personalizados para flujos de autoservicio de registro.

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

  • Configuraciones regionales de interfaz de usuario ("ui_locales"): configuraciones regionales de un usuario final configuradas en su dispositivo. La API puede usar esto para devolver respuestas internacionalizadas.
  • Dirección de correo electrónico ("email") o identidades ("identidades"): la API puede usar estas notificaciones para identificar al usuario final que se autentica en la aplicación.

Importante

Si una notificación no tiene un valor en el momento en que se llama al punto de conexión de la API, la notificación no se enviará a la API. La API debe estar diseñada para comprobar y controlar explícitamente el caso en el que una notificación no está 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.

  1. Inicie sesión en el Centro de administración de Microsoft Entra al menos como Administrador de usuario.

  2. Vaya a Identidad> Identidades externas>Información general.

  3. Seleccione Flujos de usuario y, después, seleccione el flujo de usuario para el que desea habilitar el conector de API.

  4. Seleccione Conectores de API y, después, seleccione los puntos de conexión de API que desea invocar en los pasos siguientes del flujo de usuario:

    • Después de la federación con un proveedor de identidades durante el registro
    • Antes de crear el usuario

    Selección del conector de API que se va a usar para un paso del flujo de usuario, como

  5. Seleccione Guardar.

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

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 recopilación de atributos, que es el formulario que se muestra al usuario para recopilar los 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 notificaciones. Si la API devuelve una notificación, esta realiza lo siguiente:

  • 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 emitirla intencionadamente para detener el flujo de usuario y mostrar 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 notificaciones. Si la API devuelve una notificación, esta realiza lo siguiente:

  • Invalida cualquier valor que ya se haya asignado a la notificación 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 emitirla intencionadamente para detener el flujo de usuario y mostrar 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.

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 Type Obligatorio Descripción
version String Sí Versión de la API.
action String Sí El valor debe ser Continue.
<builtInUserAttribute> <attribute-type> No Los valores se pueden almacenar en el directorio si están seleccionados como Claim to receive (Notificación para recibir) en la configuración del conector de API y User attribute (Atributo de usuario) de un flujo de usuario. Los valores se pueden devolver en el token si están seleccionados como Application claim (Notificación de aplicación).
<extension_{extensions-app-id}_CustomAttribute> <attribute-type> 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 Type Obligatorio Descripción
version String Sí Versión de la API.
action String Sí El valor debe ser ShowBlockPage.
userMessage String Sí Mensaje que se va a mostrar al usuario.

Experiencia del usuario final con una respuesta de bloqueo

Una imagen de ejemplo de cómo es la experiencia del usuario final después de que una API devuelve 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 Type Obligatorio Descripción
version String Sí Versión de la API.
action String Sí El valor debe ser ValidationError.
status Entero/cadena Sí Debe ser un valor 400 o "400" para una respuesta ValidationError.
userMessage String 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

Una imagen de ejemplo del aspecto de la experiencia del usuario final después de que una API devuelve 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 de 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 de nube sin servidor para, por ejemplo, crear la lógica de validación y limitar los registros a dominios 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 de la API, tal y como se describe anteriormente.
  • La URL del punto de conexión del conector de API apunta al punto de conexión de API correcto.
  • 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 de un 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 ninguna, realiza un intento más (reintento) de llamada 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. En 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 obtener más información, consulte Requisitos de TLS y del conjunto de cifrado.

Uso del registro

En general, resulta útil usar las herramientas de registro que habilita el servicio de API web, como Application Insights, para supervisar la API en busca de códigos de error inesperados, excepciones y 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