Definición de un perfil técnico RESTful en una directiva personalizada de Azure Active Directory B2C

2025-05-08

Importante

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

Nota:

En Azure Active Directory B2C, las directivas personalizadas se han diseñado principalmente para abordar escenarios complejos. Para la mayoría de los escenarios, se recomienda usar flujos de usuario integrados. Si no lo ha hecho, obtenga información sobre el paquete de inicio de directivas personalizadas en Introducción a las directivas personalizadas en Active Directory B2C.

Azure Active Directory B2C (Azure AD B2C) proporciona compatibilidad para integrar su propio servicio RESTful. Azure AD B2C envía datos al servicio RESTful en una colección de notificaciones de entrada y recibe datos en una colección de notificaciones de salida. Para obtener más información, consulte Integración de intercambios de notificaciones de API de REST en la directiva personalizada de Azure AD B2C.

Protocolo

El atributo Name del elemento Protocol tiene que establecerse en Proprietary. El atributo de controlador debe contener el nombre completo del ensamblado de controlador de protocolo que usa Azure AD B2C: Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.

En el ejemplo siguiente se muestra un perfil técnico RESTful:

<TechnicalProfile Id="REST-UserMembershipValidator">
  <DisplayName>Validate user input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  ...

Notificaciones de entrada

El elemento InputClaims contiene una lista de notificaciones que se van a enviar a la API de REST. También puede asignar el nombre de la notificación al nombre definido en la API de REST. En el ejemplo siguiente se muestra la asignación entre la política y la API de REST. La notificación givenName se envía a la API de REST como firstName, mientras que surname se envía como lastName. La notificación de correo electrónico se establece tal cual.

<InputClaims>
  <InputClaim ClaimTypeReferenceId="email" />
  <InputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="firstName" />
  <InputClaim ClaimTypeReferenceId="surname" PartnerClaimType="lastName" />
</InputClaims>

El elemento InputClaimsTransformations puede contener una colección de elementos InputClaimsTransformation que se usan para modificar las notificaciones de entrada o generar otras nuevas antes de enviarlas a la API de REST.

Envío de una carga JSON

El perfil técnico de la API de REST le permite enviar una carga JSON compleja a un punto de conexión.

Para enviar una carga JSON compleja:

Compile la carga JSON con la transformación de notificaciones GenerateJson .
En el perfil técnico de la API REST:
1. Agregue una transformación de notificaciones de entrada con una referencia a la transformación de GenerateJson notificaciones.
2. Establezca la opción de SendClaimsIn metadatos en body
3. Establezca la ClaimUsedForRequestPayload opción metadata en el nombre de la notificación que contiene la carga JSON.
4. En la notificación de entrada, agregue una referencia a la notificación de entrada que contiene la carga JSON.

En el ejemplo TechnicalProfile siguiente se envía un correo electrónico de verificación mediante un servicio de correo electrónico de terceros (en este caso, SendGrid).

<TechnicalProfile Id="SendGrid">
  <DisplayName>Use SendGrid's email API to send the code to the user</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://api.sendgrid.com/v3/mail/send</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="ClaimUsedForRequestPayload">sendGridReqBody</Item>
    <Item Key="DefaultUserMessageIfRequestFailed">Cannot process your request right now, please try again later.</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_SendGridApiKey" />
  </CryptographicKeys>
  <InputClaimsTransformations>
    <InputClaimsTransformation ReferenceId="GenerateSendGridRequestBody" />
  </InputClaimsTransformations>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="sendGridReqBody" />
  </InputClaims>
</TechnicalProfile>

Notificaciones de salida

El elemento OutputClaims contiene una lista de notificaciones devueltas por la API de 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 devuelva la API de REST, siempre y cuando establezca el DefaultValue atributo.

El elemento OutputClaimsTransformations puede contener una colección de elementos OutputClaimsTransformation que se usan para modificar las notificaciones de salida o para generar nuevas.

En el ejemplo siguiente se muestra la notificación devuelta por la API de REST:

La notificación MembershipId que se asigna al nombre de la notificación loyaltyNumber .

El perfil técnico también devuelve notificaciones, que no son devueltas por el proveedor de identidades:

La notificación loyaltyNumberIsNew que tiene un valor predeterminado establecido en true.

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="MembershipId" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumberIsNew" DefaultValue="true" />
</OutputClaims>

Metadatos

Atributo	Obligatorio	Descripción
ServiceUrl	Sí	La dirección URL del punto de conexión de la API de REST.
Tipo de Autenticación	Sí	El tipo de autenticación que realiza el proveedor de notificaciones RESTful. Valores posibles: `None`, `Basic`, `Bearer`, `ClientCertificate`o `ApiKeyHeader`. El `None` valor indica que la API de REST es anónima. El `Basic` valor indica que la API de REST está protegida con autenticación básica HTTP. Solo los usuarios comprobados, incluido Azure AD B2C, pueden acceder a la API. El `ClientCertificate` valor (recomendado) indica que la API de REST restringe el acceso mediante la autenticación de certificado de cliente. Solo los servicios que tienen los certificados adecuados, por ejemplo, Azure AD B2C, pueden acceder a la API. El `Bearer` valor indica que la API de REST restringe el acceso mediante el token de portador OAuth2 del cliente. El `ApiKeyHeader` valor indica que la API de REST está protegida con un encabezado HTTP de clave de API, como x-functions-key.
AllowInsecureAuthInProduction	No	Indica si se puede establecer `AuthenticationType` en el `none` entorno de producción (`DeploymentMode` de TrustFrameworkPolicy está establecido en `Production`, o no se especifica). Valores posibles: verdadero o falso (valor predeterminado).
SendClaimsIn	No	Especifica cómo se envían las notificaciones de entrada al proveedor de notificaciones RESTful. Valores posibles: `Body` (predeterminado), `Form`, `HeaderUrl` , o `QueryString`. El `Body` valor es la notificación de entrada que se envía en el cuerpo de la solicitud en formato JSON. El `Form` valor es la notificación de entrada que se envía en el cuerpo de la solicitud en un formato de valor de clave separado por && y ampersand. El `Header` valor es la notificación de entrada que se envía en el encabezado de la solicitud. El `Url` valor es la notificación de entrada que se envía en la dirección URL, por ejemplo, `https://api.example.com/{claim1}/{claim2}?{claim3}={claim4}`. La parte del nombre de host de la URL no puede contener notificaciones. El `QueryString` valor es la notificación de entrada que se envía en la cadena de consulta de solicitud. Los verbos HTTP invocados por cada uno son los siguientes: `Body`:EXPONER `Form`:EXPONER `Header`:OBTENER `Url`:OBTENER `QueryString`:OBTENER
ClaimsFormat	No	No se usa actualmente, se puede omitir.
ClaimUsedForRequestPayload	No	Nombre de una notificación de cadena que contiene la carga que se va a enviar a la API de REST.
DebugMode	No	Ejecuta el perfil técnico en modo de depuración. Valores posibles: `true` o `false` (valor predeterminado). En el modo de depuración, la API de REST puede devolver más información. Consulte la sección Devolver mensaje de error .
IncludeClaimResolvingInClaimsHandling	No	En el caso de las notificaciones de entrada y salida, especifica si se incluye la resolución de notificaciones en el perfil técnico. Valores posibles: `true` o `false` (valor predeterminado). Si desea utilizar un solucionador de notificaciones en el perfil técnico, establézcalo en `true`.
ResolveJsonPathsInJsonTokens	No	Indica si el perfil técnico resuelve las rutas de acceso JSON. Valores posibles: `true` o `false` (valor predeterminado). Use estos metadatos para leer datos de un elemento JSON anidado. En outputClaim, establezca en `PartnerClaimType` el elemento de ruta de acceso JSON que desea generar. Por ejemplo: `firstName.localized` o `data[0].to[0].email`.
UseClaimAsBearerToken	No	Nombre de la notificación que contiene el token de portador.

Control de errores

Los siguientes metadatos se pueden usar para configurar los mensajes de error que se muestran en caso de error de la API de REST. Los mensajes de error se pueden localizar.

Atributo	Obligatorio	Descripción
DefaultUserMessageIfRequestFailed	No	Un mensaje de error personalizado predeterminado para todas las excepciones de la API de REST.
UserMessageIfCircuitOpen	No	Mensaje de error cuando no se puede acceder a la API de REST. Si no se especifica, se devolverá DefaultUserMessageIfRequestFailed.
UserMessageIfDnsResolutionFailed	No	Mensaje de error para la excepción de resolución DNS. Si no se especifica, se devolverá DefaultUserMessageIfRequestFailed.
UserMessageIfRequestTimeout	No	Mensaje de error cuando se agota el tiempo de espera de la conexión. Si no se especifica, se devolverá DefaultUserMessageIfRequestFailed.

Claves criptográficas

Si el tipo de autenticación se establece en None, no se utiliza el elemento CryptographicKeys .

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
</TechnicalProfile>

Si el tipo de autenticación se establece en Basic, el elemento CryptographicKeys contiene los siguientes atributos:

Atributo	Obligatorio	Descripción
BasicAuthenticationUsername	Sí	El nombre de usuario que se utiliza para autenticarse.
BasicAuthenticationPassword	Sí	La contraseña que se usa para autenticarse.

En el ejemplo siguiente se muestra un perfil técnico con autenticación básica:

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">Basic</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BasicAuthenticationUsername" StorageReferenceId="B2C_1A_B2cRestClientId" />
    <Key Id="BasicAuthenticationPassword" StorageReferenceId="B2C_1A_B2cRestClientSecret" />
  </CryptographicKeys>
</TechnicalProfile>

Si el tipo de autenticación se establece en ClientCertificate, el elemento CryptographicKeys contiene el siguiente atributo:

Atributo	Obligatorio	Descripción
CertificadoDeCliente	Sí	El certificado X509 (conjunto de claves RSA) que se va a utilizar para autenticarse.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">ClientCertificate</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="ClientCertificate" StorageReferenceId="B2C_1A_B2cRestClientCertificate" />
  </CryptographicKeys>
</TechnicalProfile>

Si el tipo de autenticación se establece en Bearer, el elemento CryptographicKeys contiene el siguiente atributo:

Atributo	Obligatorio	Descripción
BearerAuthenticationToken	No	El token al portador de OAuth 2.0.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_B2cRestClientAccessToken" />
  </CryptographicKeys>
</TechnicalProfile>

Si el tipo de autenticación se establece en ApiKeyHeader, el elemento CryptographicKeys contiene el siguiente atributo:

Atributo	Obligatorio	Descripción
El nombre del encabezado HTTP, como `x-functions-key`, o `x-api-key`.	Sí	La clave que se usa para autenticarse.

Nota:

En este momento, Azure AD B2C solo admite un encabezado HTTP para la autenticación. Si la llamada RESTful requiere varios encabezados, como un ID de cliente y un valor de secreto de cliente, deberá redirigir la solicitud de alguna manera.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">ApiKeyHeader</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="x-functions-key" StorageReferenceId="B2C_1A_RestApiKey" />
  </CryptographicKeys>
</TechnicalProfile>

Devolver un mensaje de error de validación

Es posible que la API de REST deba devolver un mensaje de error, como "No se encontró al usuario en el sistema CRM". Si se produce un error, la API de REST debe devolver un mensaje de error HTTP 4xx, como el código de estado de respuesta 400 (solicitud incorrecta) o 409 (conflicto). El cuerpo de la respuesta contiene un mensaje de error con formato JSON:

{
  "version": "1.0.0",
  "status": 409,
  "code": "API12345",
  "requestId": "50f0bd91-2ff4-4b8f-828f-00f170519ddb",
  "userMessage": "Message for the user",
  "developerMessage": "Verbose description of problem and how to fix it.",
  "moreInfo": "https://restapi/error/API12345/moreinfo"
}

Atributo	Obligatorio	Descripción
Versión	Sí	La versión de la API de REST. Por ejemplo: 1.0.1
estado	Sí	Un número similar a códigos de estado de respuesta HTTP y debe ser 409. El servicio REST puede devolver un código de estado HTTP 4XX, pero el valor del archivo en el cuerpo de `status` la respuesta con formato JSON debe ser `409`.
código	No	Un código de error del proveedor de puntos de conexión RESTful, que se muestra cuando `DebugMode` está habilitado.
ID de solicitud	No	Un identificador de solicitud del proveedor de puntos de conexión RESTful, que se muestra cuando `DebugMode` está habilitado.
mensajeDeUsuario	Sí	Mensaje de error que se muestra al usuario.
developerMessage	No	La descripción detallada del problema y cómo solucionarlo, que se muestra cuando `DebugMode` está habilitado.
másInfo	No	Un URI que apunta a información adicional, que se muestra cuando `DebugMode` está habilitado.

En el ejemplo siguiente se muestra una clase de C# que devuelve un mensaje de error:

public class ResponseContent
{
  public string Version { get; set; }
  public int Status { get; set; }
  public string Code { get; set; }
  public string UserMessage { get; set; }
  public string DeveloperMessage { get; set; }
  public string RequestId { get; set; }
  public string MoreInfo { get; set; }
}

Pasos siguientes

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