Acerca de los conectores de API en Azure AD B2C

2025-05-06

Importante

A partir del 1 de mayo de 2025, Azure AD B2C ya no estará disponible para ser adquirido por nuevos clientes. Obtenga más información en nuestras preguntas más frecuentes.

Antes de empezar, use el selector Elegir un tipo de directiva en la parte superior de esta página para elegir el tipo de directiva que está configurando. Azure Active Directory B2C ofrece dos métodos para definir cómo interactúan los usuarios con las aplicaciones: a través de flujos de usuario predefinidos o mediante directivas personalizadas totalmente configurables. Los pasos necesarios en este artículo son diferentes para cada método.

Información general

Como desarrollador o administrador de TI, puede usar conectores de API para integrar los flujos de usuario de registro con las API REST para personalizar la experiencia de registro e integrarse con sistemas externos. Por ejemplo, con los conectores de API, puede:

Validar los datos de entrada del usuario. Haga una validación de los datos de usuario mal formados o no válidos. Por ejemplo, puede validar los datos proporcionados por el usuario frente a los datos existentes en un almacén de datos externo o una lista de valores permitidos. Si los datos no son válidos, puede pedirle al usuario que proporcione datos válidos o impedir que el usuario continúe con el flujo de registro.
Compruebe la identidad del usuario. Use un servicio de comprobación de identidad o orígenes de datos de identidad externos para agregar un nivel adicional de seguridad a las decisiones de creación de cuentas.
Integración con un flujo de trabajo de aprobación personalizado. Conéctese a un sistema de aprobaciones personalizado para administrar y limitar la creación de cuentas.
Aumente los tokens con atributos de orígenes externos. Enriquecer tokens con atributos de usuario de orígenes externos a Azure AD B2C, como sistemas en la nube, almacenes de usuarios personalizados, sistemas de permisos personalizados, servicios de identidad heredados, etc.
Sobrescribir atributos de usuario. Asigne un valor a un atributo recopilado del usuario o cámbiele el formato. Por ejemplo, si un usuario escribe el nombre con mayúsculas o minúsculas, se le puede dar un formato en el que solo la primera letra esté en mayúscula.
Ejecutar una lógica de negocios personalizada. Puede desencadenar eventos descendentes en los sistemas de la nube para enviar notificaciones push, actualizar las bases de datos corporativas, administrar permisos, auditar bases de datos y realizar otras acciones personalizadas.

Un conector de API proporciona a Azure AD B2C la información necesaria para llamar al punto de conexión de API mediante la definición de la dirección URL del punto de conexión HTTP y la autenticación de la llamada API. Una vez que configure un conector de API, puede habilitarlo para un paso específico de un flujo de usuario. Cuando un usuario llega a ese paso en el flujo de registro, el conector de API se invoca y materializa como una solicitud HTTP POST a la API, enviando información del usuario ("notificaciones") como pares clave-valor en un cuerpo JSON. La respuesta de la API puede afectar a la ejecución del flujo de usuario. Por ejemplo, la respuesta de la API puede impedir que un usuario se registre, pida al usuario que vuelva a escribir información o sobrescriba los atributos de usuario.

Dónde se puede habilitar un conector de API en un flujo de usuario

Hay tres lugares en un flujo de usuario donde puede habilitar un conector de API:

Después de la federación con un proveedor de identidades durante el registro: solo se aplica a las experiencias de registro
Antes de crear el usuario , solo se aplica a las experiencias de registro
Antes de enviar el token (versión preliminar): se aplica a los registros y los inicios de sesión

En este paso, se invoca un conector de API en el proceso de registro inmediatamente después de que el usuario se autentique con un proveedor de identidades (como Google, Facebook y Microsoft Entra ID). 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. Este paso no se invoca si un usuario se registra con una cuenta local. A continuación, se muestran ejemplos de escenarios del conector de API que se pueden habilitar en este paso:

Use el correo electrónico o la identidad federada que el usuario proporcionó para buscar notificaciones en un sistema existente. Devuelva estas notificaciones del sistema existente, rellene previamente la página de recopilación de atributos y haga que estén disponibles para que se devuelvan en el token.
Implemente una lista de permitidos o bloqueados según la identidad social.

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. A continuación, se muestran ejemplos de escenarios que se pueden habilitar en este momento del registro:

Validar datos introducidos por el usuario y pedirle que vuelva a enviarlos.
Bloquear un registro de usuario en función de los datos especificados por el usuario.
Compruebe la identidad del usuario.
Consultar en sistemas externos los datos existentes sobre el usuario para devolverlos en el token de aplicación o almacenarlos en Microsoft Entra ID.

Antes de enviar el token (versión preliminar)

Nota:

Esta característica está en versión preliminar pública.

En este paso, se invoca un conector de API en el proceso de registro o de inicio de sesión antes de emitir un token. A continuación se muestran ejemplos de escenarios que puede habilitar en este paso:

Enriquecer el token con atributos sobre el usuario de orígenes diferentes al directorio, incluidos sistemas de identidad heredados, sistemas de RR. HH. , almacenes de usuarios externos, etc.
Enriquecer el token con atributos de grupo o rol que se almacenan y administran en su propio sistema de permisos.
Aplicar transformaciones o manipulaciones de notificaciones a los valores de las notificaciones del directorio.

El Marco de Experiencia de Identidad, que subyace a Azure Active Directory B2C (Azure AD B2C), se puede integrar con las APIs RESTful dentro del recorrido del usuario. En este artículo se muestra cómo crear un recorrido de usuario que interactúe con un servicio RESTful mediante un perfil técnico RESTful.

Con Azure AD B2C, puede agregar su propia lógica de negocios a un recorrido del usuario llamando a su propio servicio RESTful. Identity Experience Framework puede enviar y recibir datos de su servicio RESTful para intercambiar afirmaciones. Por ejemplo, puede hacer lo siguiente:

Use el origen de datos de identidad externo para validar los datos de entrada del usuario. Por ejemplo, puede comprobar que la dirección de correo electrónico proporcionada por el usuario existe en la base de datos del cliente y, si no es así, presenta un error. También puede pensar en los conectores de API como una forma de admitir webhooks salientes porque la llamada se realiza cuando se produce un evento, por ejemplo, un registro.
Procesar reclamaciones. Si un usuario escribe su nombre en minúsculas o en todas las letras mayúsculas, la API REST puede dar formato al nombre solo con la primera letra en mayúscula y devolverla a Azure AD B2C. Sin embargo, cuando se usa una directiva personalizada, se prefiere ClaimsTransformations en lugar de llamar a una API RESTful.
Enriquecer dinámicamente los datos de usuario mediante la integración adicional con aplicaciones de línea de negocio corporativas. El servicio RESTful puede recibir la dirección de correo electrónico del usuario, consultar la base de datos del cliente y devolver el número de fidelidad del usuario a Azure AD B2C. Después, las notificaciones de devolución se pueden almacenar en la cuenta de Microsoft Entra del usuario, evaluarse en los pasos de orquestación siguientes o incluirse en el token de acceso.
Ejecutar una lógica de negocios personalizada. Puede enviar notificaciones push, actualizar bases de datos corporativas, ejecutar un proceso de migración de usuarios, administrar permisos, auditar bases de datos y realizar cualquier otro flujo de trabajo.

Diagrama de un intercambio de reclamaciones de servicio RESTful

Nota:

Las solicitudes HTTP se pueden cancelar si hay una respuesta lenta o ninguna desde el servicio RESTful a Azure AD B2C. El tiempo de espera predeterminado es de 10 segundos para las directivas personalizadas y 5 segundos para los flujos de usuario. El recuento de reintentos predeterminado es uno (lo que significa que hay 2 intentos en total).

Llamar a un servicio de tipo RESTful

La interacción incluye un intercambio de reclamaciones entre la API REST y Azure AD B2C. Puede diseñar la integración con los servicios RESTful de las maneras siguientes:

Perfil técnico de validación. La llamada al servicio RESTful tiene lugar dentro de un perfil técnico de validación del perfil técnico autoafirmado especificado o un control de visualización de verificación de un control de visualización. El perfil técnico de validación valida los datos proporcionados por el usuario antes de que el recorrido del usuario avance. Con el perfil técnico de validación, puede hacer lo siguiente:
- Envíe reclamaciones a su API REST.
- Valide las reclamaciones y lance mensajes de error personalizados que se muestran al usuario.
- Devolver notificaciones de la API REST a los pasos de orquestación siguientes.
Intercambio de reclamaciones. Un intercambio de reclamaciones directo se puede configurar mediante una llamada a un perfil técnico de la API REST directamente desde un paso de orquestación de un viaje del usuario. Esta definición está limitada a:
- Envíe reclamaciones a su API REST.
- Valide las reclamaciones y arroje mensajes de error personalizados que se devuelven a la aplicación.
- Devolver notificaciones de la API REST a los pasos de orquestación siguientes.

Puede agregar una llamada a la API REST en cualquier paso del recorrido del usuario definido por una directiva personalizada. Por ejemplo, puede llamar a una API REST:

Durante el inicio de sesión, justo antes de que Azure AD B2C valide las credenciales.
Inmediatamente después del inicio de sesión.
Antes de que Azure AD B2C cree una nueva cuenta en el directorio.
Después de que Azure AD B2C cree una cuenta en el directorio.
Antes de que Azure AD B2C emite un token de acceso.

Envío de datos

En el perfil técnico de RESTful, el elemento InputClaims contiene una lista de notificaciones que se enviarán al servicio RESTful. Puede asignar el nombre de la notificación al nombre definido en el servicio RESTful, establecer un valor predeterminado y usar solucionadores de notificaciones.

Puede configurar cómo se envían las notificaciones de entrada al proveedor de notificaciones RESTful mediante el atributo SendClaimsIn. Los valores posibles son:

Body, se envía en el cuerpo de la solicitud HTTP POST en formato JSON.
Form, se envía en el cuerpo de la solicitud HTTP POST en un formato de valor de clave separado por "&" (Y comercial).
Header, se envía en el encabezado de la solicitud HTTP GET.
QueryString, enviado en la cadena de consulta HTTP GET.

Cuando se configura la opción Cuerpo , el perfil técnico de la API REST le permite enviar una carga JSON compleja a un punto de conexión. Para más información, consulte Envío de una carga JSON.

Recibir datos

El OutputClaims elemento del perfil técnico RESTful contiene una lista de notificaciones devueltas por la API REST. Es posible que tenga que asignar el nombre de la notificación definida en la directiva al nombre definido en la API REST. También puede incluir notificaciones que no devuelve el proveedor de identidades de la API de REST, siempre que establezca el atributo DefaultValue.

Las notificaciones de salida analizadas por el proveedor de notificaciones RESTful siempre esperan analizar una respuesta de Body de JSON plana, como:

{
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "loyaltyNumber":  1234
}

Las notificaciones de salida deben tener un aspecto similar al siguiente fragmento de código XML:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" />
</OutputClaims>

Tratamiento de valores NULL

Se usa un valor NULL en una base de datos cuando el valor de una columna es desconocido o falta. No incluya claves JSON con un null valor. En el siguiente ejemplo, el correo electrónico devuelve el valor null.

{
  "name": "Emily Smith",
  "email": null,
  "loyaltyNumber":  1234
}

Cuando un elemento es NULL, puede:

Omita el par clave-valor del JSON.
Devolver un valor que corresponda al tipo de datos de la notificación de Azure AD B2C. Por ejemplo, para un string tipo de datos, devuelva una cadena ""vacía. Para un integer tipo de datos, devuelva un valor 0cero . Para un dateTime tipo de datos, devuelva un valor 0001-01-01T00:00:00.0000000Zmínimo.

En el ejemplo siguiente se muestra cómo controlar un valor NULL. El correo electrónico se omite de JSON:

{
  "name": "Emily Smith",
  "loyaltyNumber":  1234
}

Análisis de un cuerpo JSON anidado

Para analizar una respuesta de un cuerpo JSON anidado, establezca los metadatos de ResolveJsonPathsInJsonTokens en true. En una notificación de salida, establezca PartnerClaimType en el elemento de la ruta de acceso JSON que quiere generar.

"contacts": [
  {
    "id": "MAINCONTACT_1",
    "person": {
      "name": "Emily Smith",
      "loyaltyNumber":  1234,
      "emails": [
        {
          "id": "EMAIL_1",
          "type": "WORK",
          "email": "email@domain.com"
        }
      ]
    }
  }
],

Las notificaciones de salida deben tener un aspecto similar al siguiente fragmento de código XML:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="contacts[0].person.name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="contacts[0].person.emails[0].email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="contacts[0].person.loyaltyNumber" />
</OutputClaims>

Localización de la API REST

En un perfil técnico RESTful, es posible que desee enviar el idioma o la configuración regional de la sesión actual y, si es necesario, genere un mensaje de error localizado. Con el gestor de reclamaciones, puede enviar una reclamación contextual, como el idioma del usuario. En el ejemplo siguiente se muestra un perfil técnico RESTful que muestra este escenario.

<TechnicalProfile Id="REST-ValidateUserData">
  <DisplayName>Validate user input data</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

Control de mensajes de error

Es posible que la API REST tenga que devolver un mensaje de error, como "El usuario no se encontró en el sistema CRM". Si se produce un error, la API REST debe devolver un mensaje de error HTTP 409 (código de estado de respuesta en conflicto). Para obtener más información, consulte el perfil técnico de RESTful.

Este comportamiento solo se puede lograr mediante una llamada a un perfil técnico de la API REST desde un perfil técnico de validación. Permitir al usuario corregir los datos de la página y volver a ejecutar la validación tras el envío de la página.

Si hace referencia directamente a un perfil técnico de la API REST desde una trayectoria del usuario, el usuario es redirigido nuevamente a la aplicación de confianza con el mensaje de error correspondiente.

Desarrollo de la API REST

La API REST se puede desarrollar en cualquier plataforma y escribirse en cualquier lenguaje de programación, siempre que sea segura y pueda enviar y recibir notificaciones en formato JSON.

La solicitud al servicio de API REST procede de los servidores de Azure AD B2C. El servicio de API REST debe publicarse en un punto de conexión HTTPS accesible públicamente. La llamada a la API REST llega desde una dirección IP del centro de datos de Azure.

Puede usar funciones en la nube sin servidor, como desencadenadores HTTP en Azure Functions para facilitar el desarrollo.

Debe diseñar el servicio de API REST y sus componentes subyacentes (como la base de datos y el sistema de archivos) para que sean de alta disponibilidad.

Importante

Los puntos de conexión deben cumplir los requisitos de seguridad de Azure AD B2C. Las versiones anteriores de TLS y los cifrados están en desuso. Para obtener más información, consulte Requisitos de TLS y del conjunto de cifrado de Azure AD B2C.

Pasos siguientes

Aprenda a agregar un conector de API para modificar las experiencias de registro
Aprenda a agregar un conector de API para enriquecer tokens con reclamaciones externas
Aprenda a proteger el conector de API.
Introducción a nuestros ejemplos

Consulte los artículos siguientes para obtener ejemplos de uso de un perfil técnico RESTful:

Aprenda a crear resistencia al interactuar con procesos externos
Más información sobre cómo crear resistencia mediante los procedimientos recomendados para desarrolladores.