Compartir a través de

Llamada a una API REST mediante la directiva personalizada de Azure Active Directory B2C

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.

La directiva personalizada de Azure Active Directory B2C (Azure AD B2C) permite interactuar con la lógica de aplicación que implementa fuera de Azure AD B2C. Para ello, realice una llamada HTTP a un punto de conexión. Las directivas personalizadas de Azure AD B2C proporcionan un perfil técnico RESTful para este propósito. Con esta funcionalidad, puede implementar características que no están disponibles en la directiva personalizada de Azure AD B2C.

En este artículo aprenderá a:

  • Cree e implemente una aplicación de Node.js de ejemplo para su uso como servicio RESTful.

  • Realice una llamada HTTP al servicio RESTful Node.js mediante el perfil técnico de RESTful.

  • Controle o informe de un error que devuelve un servicio RESTful a su directiva personalizada.

Información general sobre el escenario

En Crear bifurcación en el recorrido del usuario mediante directivas personalizadas de Azure AD B2C, los usuarios que seleccionan Cuenta personal deben proporcionar un código de acceso de invitación válido para continuar. Usamos un código de acceso estático, pero las aplicaciones del mundo real no funcionan de esta manera. Si el servicio que emite los códigos de acceso es externo a la directiva personalizada, debe realizar una llamada a ese servicio y pasar la entrada del código de acceso por parte del usuario para su validación. Si el código de acceso es válido, el servicio devuelve una respuesta HTTP 200 OK y Azure AD B2C emite JWT. De lo contrario, el servicio devuelve una respuesta HTTP 4xx y el usuario debe volver a escribir un código de acceso.

Un diagrama de flujo de llamada a una API de REST.

Prerrequisitos

Nota:

Este artículo forma parte de la serie de guías paso a paso Crear y ejecutar sus propias directivas personalizadas en Azure Active Directory B2C. Se recomienda iniciar esta serie desde el primer artículo.

Paso 1: Creación e implementación de una aplicación de Node.js

Debe implementar una aplicación, que actúa como aplicación externa. A continuación, la directiva personalizada realiza una llamada HTTP a esta aplicación.

Paso 1.1: Creación de la aplicación de Node.js

  1. Cree una carpeta para hospedar la aplicación de nodo, como access-code-app.

  2. En el terminal, cambie el directorio a la carpeta de la aplicación Node, como cd access-code-appy ejecute npm init -y. Este comando crea un archivo package.json predeterminado para el proyecto de Node.js.

  3. En el terminal, ejecute npm install express body-parser. Este comando instala el marco express y el paquete del analizador de cuerpo .

  4. En el proyecto, cree un archivo index.js.

  5. En VS Code, abra el index.js archivo y agregue el código siguiente:

        const express = require('express');
    let bodyParser = require('body-parser')
    //Create an express instance
    const app = express();

    app.use( bodyParser.json() );       // to support JSON-encoded bodies
    app.use(bodyParser.urlencoded({     // to support URL-encoded bodies
      extended: true
    }));


    app.post('/validate-accesscode', (req, res) => {
        let accessCode = '88888';
        if(accessCode == req.body.accessCode){
            res.status(200).send();
        }else{
            let errorResponse = {
                "version" :"1.0",
                "status" : 409,
                "code" : "errorCode",
                "requestId": "requestId",
                "userMessage" : "The access code you entered is incorrect. Please try again.",
                "developerMessage" : `The provided code ${req.body.accessCode} does not match the expected code for user.`,
                "moreInfo" :"https://learn.microsoft.com/en-us/azure/active-directory-b2c/string-transformations"
            };
            res.status(409).send(errorResponse);                
        }
    });

    app.listen(80, () => {
        console.log(`Access code service listening on port !` + 80);
    });

    Puede observar que cuando un usuario envía un código de acceso incorrecto, puede devolver un error directamente desde la API REST. Las directivas personalizadas permiten devolver un mensaje de error HTTP 4xx, como, 400 (solicitud incorrecta) o código de estado de respuesta 409 (conflicto) con un cuerpo JSON de respuesta con formato como se muestra en errorResponse la variable . El origen del accessCode en la aplicación podría leerse desde una base de datos. Obtenga más información sobre cómo devolver el mensaje de error de validación.

  6. Para probar que la aplicación funciona según lo previsto, siga estos pasos:

    1. En el terminal, ejecute el comando para iniciar el node index.js servidor de aplicaciones.
    2. Para realizar una solicitud POST similar a la que se muestra en este ejemplo, puede usar un cliente HTTP como Microsoft PowerShell.
        POST http://localhost/validate-accesscode HTTP/1.1
    Host: localhost
    Content-Type: application/x-www-form-urlencoded

    accessCode=user-code-code

    Reemplace user-code-code con un código de acceso introducido por el usuario, como 54321. Si usa PowerShell, ejecute el siguiente script.

        $accessCode="54321"
    $endpoint="http://localhost/validate-accesscode"
    $body=$accessCode
    $response=Invoke-RestMethod -Method Post -Uri $endpoint -Body $body
    echo $response

    Si usa un código de acceso incorrecto, la respuesta es similar al siguiente fragmento de código JSON:

        {
        "version": "1.0",
        "status": 409,
        "code": "errorCode",
        "requestId": "requestId",
        "userMessage": "The access code you entered is incorrect. Please try again.",
        "developerMessage": "The provided code 54321 does not match the expected code for user.",
        "moreInfo": "https://learn.microsoft.com/en-us/azure/active-directory-b2c/string-transformations"
    }

El servicio REST puede devolver código de estado HTTP 4xx, pero el valor de status en la respuesta JSON debe ser 409.

En este momento, está listo para implementar la aplicación de Node.js.

Paso 1.2: Implementación de la aplicación de Node.js en Azure App Service

Para que la directiva personalizada llegue a la aplicación de Node.js, debe ser accesible, por lo que necesita implementarla. En este artículo, implementará la aplicación mediante Azure App Service, pero usará un enfoque de hospedaje alternativo.

Siga los pasos descritos en Implementación de la aplicación en Azure para implementar la aplicación de Node.js en Azure. Para el nombre de la aplicación, use un nombre descriptivo como custompolicyapi. Por lo tanto:

  • La dirección URL de la aplicación es similar a https://custompolicyapi.azurewebsites.net.

  • El punto de conexión de servicio es similar a https://custompolicyapi.azurewebsites.net/validate-accesscode.

Puede probar la aplicación que ha implementado mediante un cliente HTTP como Microsoft PowerShell. Esta vez, use https://custompolicyapi.azurewebsites.net/validate-accesscode la dirección URL como punto de conexión.

Paso 2: Llamada a la API REST

Ahora que la aplicación se está ejecutando, debe realizar una llamada HTTP desde la directiva personalizada. La directiva personalizada de Azure AD B2C proporciona un perfil técnico RESTful que se usa para llamar a un servicio externo.

Paso 2.1: Definición de un perfil técnico RESTful

En el ContosoCustomPolicy.XML archivo, busque la ClaimsProviders sección y defina un nuevo perfil técnico de RESTful mediante el código siguiente:

    <!--<ClaimsProviders>-->
        <ClaimsProvider>
            <DisplayName>HTTP Request Technical Profiles</DisplayName>
            <TechnicalProfiles>
                <TechnicalProfile Id="ValidateAccessCodeViaHttp">
                    <DisplayName>Check that the user has entered a valid access code by using Claims Transformations</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://custompolicyapi.azurewebsites.net/validate-accesscode</Item>
                        <Item Key="SendClaimsIn">Body</Item>
                        <Item Key="AuthenticationType">None</Item>
                        <Item Key="AllowInsecureAuthInProduction">true</Item>
                    </Metadata>
                    <InputClaims>
                        <InputClaim ClaimTypeReferenceId="accessCode" PartnerClaimType="accessCode" />
                    </InputClaims>
                </TechnicalProfile>
            </TechnicalProfiles>
        </ClaimsProvider>
    <!--</ClaimsProviders>-->

En el protocolo, puede observar que configuramos el perfil técnico para usar RestfulProvider. También puede observar la siguiente información en la sección de metadatos:

  • ServiceUrl representa el punto de conexión de LA API. Su valor es https://custompolicyapi.azurewebsites.net/validate-accesscode. Si ha implementado la aplicación de Node.js mediante un método alternativo, asegúrese de actualizar el valor del punto de conexión.

  • SendClaimsIn especifica cómo se envían las notificaciones de entrada al proveedor de notificaciones RESTful. Valores posibles: Body (default), Form, HeaderUrl o QueryString. Cuando usas Body, como en este artículo, invocas el verbo HTTP POST y los datos que envías a la API están formateados como pares de clave-valor en el cuerpo de la solicitud. Obtenga información sobre cómo invocar el verbo HTTP GET y pasar datos como cadena de consulta.

  • AuthenticationType especifica el tipo de autenticación que realiza el proveedor de notificaciones RESTful. Nuestro proveedor de afirmaciones RESTful llama a un punto de conexión desprotegido, por lo que establecemos nuestro AuthenticationType en Ninguno. Si establece el tipo de autenticación en Bearer, debe agregar un elemento CryptographicKeys, que especifica el almacenamiento del token de acceso. Obtenga más información sobre los tipos de autenticación que admite el proveedor de notificaciones RESTful.

  • El atributo PartnerClaimType de InputClaim especifica cómo recibe los datos en la API.

Paso 2.2: Actualización del perfil técnico de validación

En Crear bifurcación en el recorrido del usuario mediante la directiva personalizada de Azure AD B2C, validó accessCode mediante una transformación de notificaciones. En este artículo, validará el accessCode mediante la realización de una llamada HTTP a un servicio externo. Por lo tanto, deberá actualizar la directiva personalizada para reflejar el nuevo enfoque.

Busque el perfil técnico AccessCodeInputCollector y actualice el ReferenceId del elemento ValidationTechnicalProfile a ValidateAccessCodeViaHttp:

de:

    <ValidationTechnicalProfile ReferenceId="CheckAccessCodeViaClaimsTransformationChecker"/>

a:

    <ValidationTechnicalProfile ReferenceId="ValidateAccessCodeViaHttp"/>

En este momento, el perfil técnico con IdCheckAccessCodeViaClaimsTransformationChecker no es necesario y se puede quitar.

Paso 3: Carga del archivo de directiva personalizado

Asegúrese de que la aplicación de Node.js se está ejecutando y, a continuación, siga los pasos descritos en Cargar archivo de directiva personalizado para cargar el archivo de directiva. Si va a cargar un archivo con el mismo nombre que el que ya está en el portal, asegúrese de seleccionar Sobrescribir la directiva personalizada si ya existe.

Paso 4: Probar la directiva personalizada

Siga los pasos descritos en Probar la directiva personalizada para probar la directiva personalizada:

  1. En Tipo de cuenta, seleccione Cuenta personal.
  2. Escriba el resto de los detalles según sea necesario y, a continuación, seleccione Continuar. Verá una nueva pantalla.
  3. En Código de acceso, escriba 88888 y, a continuación, seleccione Continuar. Una vez finalizada la ejecución de la directiva, se le redirigirá a https://jwt.msy verá un JWT descodificado. Si repite el procedimiento y escribe un código de acceso diferente, distinto de 88888, verá un error: el código de acceso que especificó es incorrecto. Inténtelo de nuevo.

Paso 5: Habilitación del modo de depuración

En desarrollo, es posible que desee ver errores detallados enviados por la API, como developerMessage y moreInfo. En este caso, debe habilitar el modo de depuración en el proveedor técnico RESTful.

  1. Busque su proveedor técnico ValidateAccessCodeViaHttp y agregue el siguiente elemento en su metadata.

        <Item Key="DebugMode">true</Item>

  2. Guarde los cambios y cargue el archivo de directiva.

  3. Prueba tu directiva personalizada. Asegúrese de usar una entrada incorrecta para el código de acceso. Verá un error similar al que se muestra en esta captura de pantalla:

    Error de captura de pantalla al habilitar el modo de depuración.

Control de cargas JSON de solicitud compleja

Si la API de REST a la que llama requiere que envíe una carga JSON compleja, puede crear la carga mediante transformaciones de notificaciones JSON de GenerateJson. Una vez que genere la carga, puede usar ClaimUsedForRequestPayload la opción de metadatos para el nombre de la notificación que contiene la carga JSON.

Por ejemplo, use la siguiente transformación de declaraciones para generar una carga JSON.

    <ClaimsTransformation Id="GenerateRequestBodyClaimsTransformation" TransformationMethod="GenerateJson">
        <InputClaims>
            <InputClaim ClaimTypeReferenceId="email" TransformationClaimType="customerEntity.email" />
            <InputClaim ClaimTypeReferenceId="objectId" TransformationClaimType="customerEntity.userObjectId" />
            <InputClaim ClaimTypeReferenceId="givenName" TransformationClaimType="customerEntity.firstName" />
            <InputClaim ClaimTypeReferenceId="surname" TransformationClaimType="customerEntity.lastName" />
            <InputClaim ClaimTypeReferenceId="accessCode" TransformationClaimType="customerEntity.accessCode" />
        </InputClaims>
        <InputParameters>
            <InputParameter Id="customerEntity.role.name" DataType="string" Value="Administrator" />
            <InputParameter Id="customerEntity.role.id" DataType="long" Value="1" />
        </InputParameters>
        <OutputClaims>
            <OutputClaim ClaimTypeReferenceId="requestBodyPayload" TransformationClaimType="outputClaim" />
        </OutputClaims>
    </ClaimsTransformation>

ClaimsTransformation genera el siguiente objeto JSON:

{
   "customerEntity":{
      "email":"john.s@contoso.com",
      "userObjectId":"aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
      "firstName":"John",
      "lastName":"Smith",
      "accessCode":"88888",
      "role":{
         "name":"Administrator",
         "id": 1
      }
   }
}

A continuación, actualice el Metadata, InputClaimsTransformations y InputClaims de su proveedor técnico RESTful, como se muestra a continuación.

    <Metadata>
        <Item Key="ClaimUsedForRequestPayload">requestBodyPayload</Item>
        <!--Other Metadata items -->
    </Metadata>
    
    <!--Execute your InputClaimsTransformations to generate your request Payload-->
    <InputClaimsTransformations>
        <InputClaimsTransformation ReferenceId="GenerateRequestBodyClaimsTransformation" />
    </InputClaimsTransformations>
    
    <InputClaims>
        <InputClaim ClaimTypeReferenceId="requestBodyPayload" />
    </InputClaims>

Recepción de datos de la API REST

Si la API REST devuelve datos que desea incluir como reclamos en la directiva, puede recibirlos especificando estos reclamos en el elemento OutputClaims del perfil técnico RESTful. Si el nombre de la reclamación definida en su política es diferente del nombre definido en la API REST, debe asignar estos nombres utilizando el atributo PartnerClaimType.

Siga los pasos descritos en Recepción de datos para obtener información sobre cómo dar formato a los datos que espera la directiva personalizada, cómo controlar los valores NULL y cómo analizar el cuerpo JSON anidado de la API.

Contenido relacionado

A continuación, aprenda: