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

Artículo
01/22/2024

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) le permite integrar su servicio RESTful propio. Azure AD B2C envía datos al servicio RESTful en una colección de notificaciones de entrada y recibe los datos en una colección de notificaciones de salida. Para más información, vea Integración de intercambios de notificaciones de la 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 handler 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 de 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 para enviar a la API REST. También se puede asignar el nombre de la notificación al nombre definido en la API REST. En el ejemplo siguiente se muestra la asignación entre la directiva y la API REST. La notificación givenName se envía a la API REST como firstName, mientras que surname se envía como lastName. La notificación email 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 del envío a la API REST.

Envío de una carga de JSON

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

Para enviar una carga de JSON compleja:

Compile la carga de 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 notificaciones GenerateJson.
2. Establezca la opción de metadatos SendClaimsIn en body.
3. Establezca la opción de metadatos ClaimUsedForRequestPayload en el nombre de la notificación que contiene la carga de JSON.
4. En la notificación de entrada, agregue una referencia a la notificación de entrada que contiene la carga de JSON.

En el siguiente ejemplo, TechnicalProfile 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 devuelta 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 la API REST no devuelve, siempre que establezca el atributo DefaultValue.

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 REST:

La notificación MembershipId que se asigna al nombre de 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 REST.
AuthenticationType	Sí	El tipo de autenticación realizada por el proveedor de notificaciones RESTful. Valores posibles: `None`, `Basic`, `Bearer`, `ClientCertificate` o `ApiKeyHeader`. El valor `None` indica que la API de REST es anónima. El valor `Basic` indica que la API REST se protege con autenticación básica HTTP. Solo los usuarios verificados, incluido Azure AD B2C, pueden acceder a la API. El valor `ClientCertificate` (recomendado) indica que la API REST restringe el acceso mediante la autenticación de certificado de cliente. Solo pueden acceder a la API los servicios que tengan los certificados adecuados; por ejemplo, Azure AD B2C. El valor `Bearer` indica que la API REST restringe el acceso mediante el token de portador de OAuth2 de cliente. El valor `ApiKeyHeader` indica que la API REST está protegida con el encabezado HTTP de clave de API, como x-functions-key.
AllowInsecureAuthInProduction	No	Indica si `AuthenticationType` se puede establecer en `none` en el entorno de producción (el valor `DeploymentMode` de TrustFrameworkPolicy se establece en `Production` o no se especifica). Valores posibles: true o false (predeterminado).
SendClaimsIn	No	Especifica cómo se envían las notificaciones de entrada al proveedor de notificaciones RESTful. Valores posibles: `Body` (predeterminado), `Form`, `Header`, `Url` o `QueryString`. El valor `Body` es la notificación de entrada que se envía en el cuerpo de la solicitud en formato JSON. El valor `Form` 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 comercial). El valor `Header` es la notificación de entrada que se envía en el cuerpo de la solicitud. El valor `Url` es la notificación de entrada que se envía en la 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 valor `QueryString` es la notificación de entrada que se envía en la cadena de consulta de la solicitud. Los verbos HTTP invocados por cada uno de ellos son los siguientes: `Body`: POST `Form`: POST `Header`: GET `Url`: GET `QueryString`: GET
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 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 REST puede devolver más información. consulte la sección Devolución de mensajes 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 un objeto OutputClaim, establezca `PartnerClaimType` en el elemento de la ruta de acceso JSON que quiere 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 metadatos siguientes se pueden usar para configurar los mensajes de error que se muestran cuando se produce un error de API REST. Los mensajes de error se pueden localizar.

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

Claves de cifrado

Si el tipo de autenticación se establece en None, no se usa 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 atributos siguientes:

Atributo	Obligatorio	Descripción
BasicAuthenticationUsername	Sí	Nombre de usuario que se usa para la autenticación.
BasicAuthenticationPassword	Sí	Contraseña que se usa para la autenticación.

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 atributo siguiente:

Atributo	Obligatorio	Descripción
ClientCertificate	Sí	El certificado X509 (conjunto de claves RSA) que se va a usar para la autenticación.

<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 atributo siguiente:

Atributo	Obligatorio	Descripción
BearerAuthenticationToken	No	El token de 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 atributo siguiente:

Atributo	Obligatorio	Descripción
Nombre del encabezado HTTP, como `x-functions-key` o `x-api-key`.	Sí	Clave que se usa para la autenticación.

Nota:

En estos momentos, Azure AD B2C solo admite un encabezado HTTP para la autenticación. Si la llamada de RESTful requiere varios encabezados, como un identificador de cliente y un valor secreto de cliente, necesitará redirigir la solicitud mediante proxy 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>

Devolución del mensaje de error de validación

Es posible la API REST tenga que devolver un mensaje de error, como "No se encuentra el usuario en el sistema CRM". Si se produce un error, la API de REST debe devolver un mensaje de error HTTP 4xx, como los códigos 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
version	Sí	Su versión de la API de REST. Por ejemplo: 1.0.1
status	Sí	Un número similar a un número 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 archivado en el cuerpo de `status` la respuesta con formato JSON debe ser `409`.
code	No	Código de error del proveedor de punto de conexión RESTful, que se muestra cuando `DebugMode` está habilitado.
requestId	No	Identificador de solicitud del proveedor de punto de conexión RESTful, que se muestra cuando `DebugMode` está habilitado.
userMessage	Sí	Mensaje de error que se muestra al usuario.
developerMessage	No	Descripción detallada del problema y cómo corregirlo, que se muestra cuando `DebugMode` está habilitado.
moreInfo	No	URI que señala 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 siguientes artículos para obtener ejemplos del uso de un perfil técnico de RESTful:

Compartir vía