Enriquece tokens con afirmaciones de orígenes externos mediante conectores de API

Puede usar conectores de API aplicados al paso Antes de enviar el token (versión preliminar) para enriquecer los tokens de las aplicaciones con información de orígenes externos. Cuando un usuario inicia sesión o se registra, Azure AD B2C llamará al punto de conexión de API configurado en el conector de API, que puede consultar información sobre un usuario en servicios de nivel inferior, como servicios en la nube, almacenes de usuarios personalizados, sistemas de permisos personalizados, sistemas de identidad heredados, etc.

Puede crear un punto de conexión de API mediante uno de nuestros ejemplos.

Prerrequisitos

• Un punto de conexión de API. Puede crear un punto de conexión de API mediante uno de nuestros ejemplos.

Creación de un conector de API

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

1. Inicie sesión en Azure Portal.

2. En Servicios de Azure, seleccione Azure AD B2C.

3. Seleccione Conectores de API y, a continuación, seleccione Nuevo conector de API.

   

4. Escriba el nombre para mostrar de la llamada. Por ejemplo, Enriquecer token de origen externo.

5. Proporcione la URL del punto de conexión para la solicitud de API.

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

   

7. Haga clic en Guardar.

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

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

1. Inicie sesión en Azure Portal.

2. En Servicios de Azure, seleccione Azure AD B2C.

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, a continuación, seleccione el punto de conexión de API que desea invocar en el paso Antes de enviar el token (versión preliminar) en el flujo de usuario:

   

5. Haga clic en Guardar.

Este paso solo existe para flujos de usuario de registro e inicio de sesión (recomendado),Registro (recomendado) e Inicio de sesión (recomendado).

Solicitud de ejemplo enviada a la API en este paso

Se invoca un conector de API en este paso cuando un token está a punto de emitirse durante los inicios de sesión y los registros. 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.

POST <API-endpoint>
Content-type: application/json
{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "objectId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
 "step": "PreTokenIssuance",
 "ui_locales":"en-US"
}

Las reclamaciones que se envían a la API dependen de la información definida para el usuario. Solo se pueden enviar en la solicitud las propiedades de usuario y los atributos personalizados que se enumeran en la experiencia Azure AD B2C>Atributos de usuario. Los atributos personalizados existen en el formato extension_<extensions-app-id>_CustomAttribute 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 en Azure AD B2C. Además, estas notificaciones normalmente se envían en todas las solicitudes de este paso:

• 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.
• Paso ('paso'): paso o punto en el flujo de usuario para el que se invocó el conector de API. El valor de este paso es "
• ID de cliente ('client_id'): el valor appId de la aplicación a la que se autentica un usuario final en un flujo de usuario. No es el valor appId de la aplicación de recursos de los tokens de acceso.
• objectId : identificador del usuario. Puede usarlo para consultar a los servicios descendentes para obtener información del usuario.

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 una "respuesta de continuación".

Respuesta de continuación

Una respuesta de continuación indica que el flujo de usuario debe continuar con el paso siguiente: emitir el token. En una respuesta de continuación, la API puede devolver notificaciones adicionales. Una notificación devuelta por la API que desea devolver en el token debe ser una notificación integrada o definida como un atributo personalizado y debe seleccionarse en la configuración de notificaciones de aplicación del flujo de usuario. El valor de reclamación en el token será el devuelto por la API, no el valor en el directorio. La respuesta de la API no puede sobrescribir algunos valores de notificación. Las notificaciones que puede devolver la API corresponden al conjunto que se encuentra en Atributos de usuario, con la excepción de email.

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

En este escenario, enriquecemos los datos de token del usuario mediante la integración con un flujo de trabajo de línea de negocio corporativo. Durante el registro o el inicio de sesión con una cuenta local o federada, Azure AD B2C invoca una API REST para obtener los datos de perfil extendidos del usuario desde un origen de datos remoto. En este ejemplo, Azure AD B2C envía el identificador único del usuario, objectId. A continuación, la API REST devuelve el saldo de la cuenta del usuario (un número aleatorio). Use este ejemplo como punto de partida para integrarse con su propio sistema CRM, base de datos de marketing o cualquier flujo de trabajo de línea de negocio. También puede diseñar la interacción como perfil técnico de validación. Esto es adecuado cuando la API REST validará los datos en pantalla y devolverá reclamaciones. Para más información, consulte Tutorial: Adición de un conector de API a un flujo de usuario de registro.

Prerrequisitos

• Complete los pasos descritos en Introducción a las directivas personalizadas. Debe tener una directiva personalizada activa para registrar e iniciar sesión de cuentas locales.
• Aprenda a integrar intercambios de notificaciones de api REST en la directiva personalizada de Azure AD B2C.

Preparación de un punto de conexión de LA API REST

Para este tutorial, debe tener una API de REST que valide si el objectId de Azure AD B2C de un usuario está registrado en el sistema back-end. Si se registra, la API REST devuelve el saldo de la cuenta de usuario. De lo contrario, la API REST registra la nueva cuenta en el directorio y devuelve el saldo 50.00inicial. En el código JSON siguiente se muestran los datos que Azure AD B2C enviará al punto de conexión de la API REST.

{
    "objectId": "User objectId",
    "lang": "Current UI language"
}

Una vez que la API rest valida los datos, debe devolver un HTTP 200 (Correcto), con los siguientes datos JSON:

{
    "balance": "760.50"
}

La configuración del punto de conexión de la API REST está fuera del ámbito de este artículo. Hemos creado un ejemplo de Azure Functions . Puede acceder al código completo de la función de Azure en GitHub.

Definir reclamaciones

Una notificación proporciona un almacenamiento temporal de datos durante la ejecución de una directiva de Azure AD B2C. Puede declarar reclamaciones en la sección de esquema de reclamaciones.

1. Abra el archivo de extensiones de su política. Por ejemplo: SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
2. Busque el elemento BuildingBlocks . Si el elemento no existe, agréguelo.
3. Busque el elemento ClaimsSchema . Si el elemento no existe, agréguelo.
4. Agregue los siguientes reclamos al elemento ClaimsSchema.

<ClaimType Id="balance">
  <DisplayName>Your Balance</DisplayName>
  <DataType>string</DataType>
</ClaimType>
<ClaimType Id="userLanguage">
  <DisplayName>User UI language (used by REST API to return localized error messages)</DisplayName>
  <DataType>string</DataType>
</ClaimType>

Adición del perfil técnico de la API RESTful

Un perfil técnico RESTful proporciona soporte técnico para interactuar con su propio servicio RESTful. Azure AD B2C envía datos al servicio RESTful en una InputClaims colección y recibe los datos de nuevo en una OutputClaims colección. Busque el elemento ClaimsProviders en el TrustFrameworkExtensions.xml archivo y agregue un nuevo proveedor de notificaciones de la siguiente manera:

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-GetProfile">
      <DisplayName>Get user extended profile Azure Function web hook</DisplayName>
      <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <Metadata>
        <!-- Set the ServiceUrl with your own REST API endpoint -->
        <Item Key="ServiceUrl">https://your-account.azurewebsites.net/api/GetProfile?code=your-code</Item>
        <Item Key="SendClaimsIn">Body</Item>
        <!-- Set AuthenticationType to Basic or ClientCertificate in production environments -->
        <Item Key="AuthenticationType">None</Item>
        <!-- REMOVE the following line in production environments -->
        <Item Key="AllowInsecureAuthInProduction">true</Item>
      </Metadata>
      <InputClaims>
        <!-- Claims sent to your REST API -->
        <InputClaim ClaimTypeReferenceId="objectId" />
        <InputClaim ClaimTypeReferenceId="userLanguage" PartnerClaimType="lang" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
      </InputClaims>
      <OutputClaims>
        <!-- Claims parsed from your REST API -->
        <OutputClaim ClaimTypeReferenceId="balance" />
      </OutputClaims>
      <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

En este ejemplo, userLanguage se enviará al servicio REST como lang dentro de la carga JSON. El valor de la notificación userLanguage contiene el identificador de idioma del usuario actual. Para obtener más información, consulte resolución de reclamaciones.

Configuración del perfil técnico de la API RESTful

Después de implementar la API REST, establezca los metadatos del REST-GetProfile perfil técnico para reflejar su propia API REST, entre las que se incluyen:

• ServiceUrl. Establezca la dirección URL del punto de conexión de la API REST.
• SendClaimsIn. Especifique cómo se envían las notificaciones de entrada al proveedor de notificaciones RESTful.
• AuthenticationType. Establecer el tipo de autenticación que realiza el proveedor de notificaciones RESTful, como Basic o ClientCertificate
• AllowInsecureAuthInProduction. En un entorno de producción, asegúrese de establecer este metadato en false.

Consulte los metadatos del perfil técnico RESTful para obtener más configuraciones. Los comentarios anteriores AuthenticationType y AllowInsecureAuthInProduction especifican los cambios que debe realizar al pasar a un entorno de producción. Para obtener información sobre cómo proteger las API de RESTful para producción, consulte Protección de la API RESTful.

Añadir un paso de orquestación

Los recorridos del usuario especifican rutas de acceso explícitas con las que una directiva permite que una aplicación de usuario de confianza obtenga las notificaciones deseadas para un usuario. El recorrido del usuario se representa como una secuencia de orquestación por la que hay que pasar para lograr una transacción correcta. Puede agregar o restar pasos de orquestación. En este caso, añadirá un nuevo paso de orquestación que se utiliza para ampliar la información proporcionada a la aplicación después de que el usuario se registre o inicie sesión a través de la llamada a la API REST.

1. Abra el archivo base de su política. Por ejemplo: SocialAndLocalAccounts/TrustFrameworkBase.xml.
2. Busque el <UserJourneys> elemento . Copie todo el elemento y, a continuación, elimínelo.
3. Abra el archivo de extensiones de su política. Por ejemplo: SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
4. Pegue el <UserJourneys> en el archivo de extensiones, después del cierre del elemento <ClaimsProviders>.
5. Localice el <UserJourney Id="SignUpOrSignIn"> y agregue el siguiente paso de orquestación antes del último.

   <OrchestrationStep Order="7" Type="ClaimsExchange">
     <ClaimsExchanges>
       <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
     </ClaimsExchanges>
   </OrchestrationStep>
   

6. Refactorice el último paso de orquestación cambiando el Order por 8. Los dos pasos finales de orquestación deben ser similares a los siguientes:

   <OrchestrationStep Order="7" Type="ClaimsExchange">
     <ClaimsExchanges>
       <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
     </ClaimsExchanges>
   </OrchestrationStep>
   <OrchestrationStep Order="8" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="JwtIssuer" />
   

7. Repita los dos últimos pasos para las rutas de usuario ProfileEdit y PasswordReset.

Incluir una reclamación en el token

Para devolver la notificación balance a la aplicación de usuario de confianza, agregue una notificación de salida al archivo SocialAndLocalAccounts/SignUpOrSignIn.xml. La incorporación de una notificación de salida emitirá la notificación al token después de un recorrido del usuario correcto y se enviará a la aplicación. Modifique el elemento de perfil técnico en la sección de usuario de confianza para agregar balance como una notificación de salida.

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
      <OutputClaim ClaimTypeReferenceId="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
      <OutputClaim ClaimTypeReferenceId="balance" DefaultValue="" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

Repita este paso para los recorridos del usuario ProfileEdit.xml y PasswordReset.xml. Guarde los archivos que ha cambiado: TrustFrameworkBase.xmly TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xmly PasswordReset.xml.

Prueba la política personalizada

1. Inicie sesión en Azure Portal.
2. Si tiene acceso a varios inquilinos, seleccione el icono Configuración del menú superior para cambiar al inquilino de Microsoft Entra en el menú Directorios y suscripciones .
3. Elija Todos los servicios en la esquina superior izquierda de Azure Portal y busque y seleccione Registros de aplicaciones.
4. Seleccione Marco de experiencia de identidad.
5. Seleccione Cargar directiva personalizada y, a continuación, cargue los archivos de directiva que ha cambiado: TrustFrameworkBase.xmly TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xmly PasswordReset.xml.
6. Seleccione la directiva de registro o de inicio de sesión que cargó y haga clic en el botón Ejecutar ahora .
7. Debería poder registrarse con una dirección de correo electrónico o una cuenta de Facebook.
8. El token enviado de vuelta a la aplicación contiene la notificación balance.

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584961516,
  "nbf": 1584957916,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/",
  "aud": "11112222-bbbb-3333-cccc-4444dddd5555",
  "acr": "b2c_1a_signup_signin",
  "nonce": "defaultNonce",
  "iat": 1584957916,
  "auth_time": 1584957916,
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "given_name": "Emily",
  "family_name": "Smith",
  "balance": "202.75"
  ...
}

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. 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úrate 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 verifica explícitamente los valores null de las declaraciones 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.
  • Azure AD B2C esperará un máximo de 20 segundos para recibir una respuesta. Si no se recibe ninguna, realiza un intento más (reintento) de 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 "activa" en producción. Para Azure Functions, se recomienda usar como mínimo el plan Premium en producción.
• 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.

Uso del registro

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

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.
• Monitoree la API en busca de tiempos de respuesta prolongados.

Además, Azure AD B2C registra metadatos sobre las transacciones de API que se producen durante las autenticaciones de usuario a través de un flujo de usuario. Para encontrarlos:

1. Vaya a Azure AD B2C.
2. En Actividades, seleccione Registros de auditoría.
3. Filtre la vista de lista: en Fecha, seleccione el intervalo de tiempo que desee y, en Actividad, seleccione An API was called as part of a user flow (Una API se llamó como parte de un flujo de usuario).
4. Inspeccione los registros individuales. Cada fila representa un conector de API que intenta llamarse durante un flujo de usuario. Si se produce un error en una llamada API y se produce un reintento, todavía se representa como una sola fila. numberOfAttempts indica el número de veces que se llamó a la API. Este valor puede ser 1o 2. En los registros se detalla otra información sobre la llamada API.

• Empiece a trabajar con nuestros ejemplos.
• Protección del conector de API

Para obtener información sobre cómo proteger las API, consulte los artículos siguientes:

• Tutorial: Integración de intercambios de notificaciones de API de REST en los recorridos de usuario de Azure AD B2C como un paso de orquestación
• Protección de la API RESTful
• Referencia: Perfil técnico RESTful