Condividi tramite

Chiamare un'API REST usando criteri personalizzati di Azure Active Directory B2C

Importante

A partire dal 1° maggio 2025, Azure AD B2C non sarà più disponibile per l'acquisto per i nuovi clienti. Altre informazioni sono disponibili nelle domande frequenti.

I criteri personalizzati di Azure Active Directory B2C (Azure AD B2C) consentono di interagire con la logica dell'applicazione implementata all'esterno di Azure AD B2C. A tale scopo, si effettua una chiamata HTTP a un endpoint. I criteri personalizzati di Azure AD B2C forniscono un profilo tecnico RESTful a questo scopo. Usando questa funzionalità, è possibile implementare funzionalità non disponibili nei criteri personalizzati di Azure AD B2C.

In questo articolo vengono illustrate le operazioni seguenti:

  • Creare e distribuire un'app di esempio Node.js da usare come servizio RESTful.

  • Effettuare una chiamata HTTP al servizio RESTful Node.js usando il profilo tecnico RESTful.

  • Gestire o segnalare un errore che un servizio RESTful restituisce alla tua politica personalizzata.

Panoramica dello scenario

In Creare la diramazione nel percorso utente usando i criteri personalizzati di Azure AD B2C, gli utenti che selezionano Account personale devono fornire un codice di accesso di invito valido per continuare. Usiamo un codice di accesso statico, ma le app reali non funzionano in questo modo. Se il servizio che rilascia i codici di accesso è esterno ai criteri personalizzati, è necessario effettuare una chiamata a tale servizio e passare l'input del codice di accesso da parte dell'utente per la convalida. Se il codice di accesso è valido, il servizio restituisce una risposta HTTP 200 OK e Azure AD B2C rilascia JWT. In caso contrario, il servizio restituisce una risposta HTTP 4xx e l'utente deve immettere nuovamente un codice di accesso.

Diagramma di flusso di chiamata di R E S T A P I.

Prerequisiti

Annotazioni

Questo articolo fa parte della serie di guide su come Creare ed eseguire criteri personalizzati in Azure Active Directory B2C. È consigliabile iniziare questa serie dal primo articolo.

Passaggio 1: Creare e distribuire un'app Node.js

È necessario distribuire un'app, che funge da app esterna. La tua politica personalizzata quindi effettua una chiamata HTTP a questa app.

Passaggio 1.1: Creare l'app Node.js

  1. Creare una cartella per ospitare l'applicazione node, ad esempio access-code-app.

  2. Nel terminale modificare la directory nella cartella dell'app Node, ad esempio cd access-code-app, ed eseguire npm init -y. Questo comando crea un file di package.json predefinito per il progetto Node.js.

  3. Nel terminale eseguire npm install express body-parser. Questo comando installa il framework Express e il pacchetto body-parser .

  4. Nel progetto creare il index.js file.

  5. In VS Code aprire il index.js file e quindi aggiungere il codice seguente:

        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);
    });

    È possibile osservare che quando un utente invia un codice di accesso errato, è possibile restituire un errore direttamente dall'API REST. I criteri personalizzati consentono di restituire un messaggio di errore HTTP 4xx, ad esempio 400 (richiesta non valida) o 409 (Conflitto) con un corpo JSON della risposta formattato come illustrato nella errorResponse variabile. L'origine di accessCode nell'app può essere letta da un database. Ulteriori informazioni sul messaggio di errore di convalida restituito.

  6. Per testare il funzionamento dell'app come previsto, seguire questa procedura:

    1. Nel terminale, eseguire il comando node index.js per avviare il server dell'app.
    2. Per eseguire una richiesta POST simile a quella illustrata in questo esempio, è possibile usare un client HTTP come Microsoft PowerShell.
        POST http://localhost/validate-accesscode HTTP/1.1
    Host: localhost
    Content-Type: application/x-www-form-urlencoded

    accessCode=user-code-code

    Sostituire user-code-code con un input del codice di accesso da parte dell'utente, ad esempio 54321. Se si usa PowerShell, eseguire lo script seguente.

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

    Se si usa un codice di accesso non corretto, la risposta sarà simile al frammento JSON seguente:

        {
        "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"
    }

Il servizio REST può restituire il codice di stato HTTP 4xx, ma il valore di status nella risposta JSON deve essere 409.

A questo punto, sei pronto a distribuire l'app Node.js.

Passaggio 1.2: Distribuire l'app Node.js nel servizio app di Azure

Affinché la politica personalizzata raggiunga l'app Node.js, quest'ultima deve essere raggiungibile, quindi è necessario distribuirla. In questo articolo si distribuisce l'app usando servizio app di Azure, ma si usa un approccio di hosting alternativo.

Seguire i passaggi indicati in Distribuire l'app in Azure per distribuire l'app Node.js in Azure. Per Nome dell'app, usare un nome descrittivo, custompolicyapiad esempio . Quindi:

  • L'URL dell'app è simile a https://custompolicyapi.azurewebsites.net.

  • L'endpoint del servizio è simile a https://custompolicyapi.azurewebsites.net/validate-accesscode.

È possibile testare l'app distribuita usando un client HTTP, ad esempio Microsoft PowerShell. Questa volta usare https://custompolicyapi.azurewebsites.net/validate-accesscode l'URL come endpoint.

Passaggio 2: Chiamare l'API REST

Ora che l'app è in esecuzione, è necessario effettuare una chiamata HTTP dai criteri personalizzati. I criteri personalizzati di Azure AD B2C forniscono un profilo tecnico RESTful usato per chiamare un servizio esterno.

Passaggio 2.1 - Definire un profilo tecnico RESTful

Nel tuo file ContosoCustomPolicy.XML, trova la sezione ClaimsProviders e definisci un nuovo profilo tecnico RESTful usando il codice seguente:

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

Dal protocollo è possibile osservare che si configura il profilo tecnico per l'uso di RestfulProvider. È anche possibile osservare le informazioni seguenti nella sezione dei metadati:

  • ServiceUrl rappresenta l'endpoint API. Il valore è https://custompolicyapi.azurewebsites.net/validate-accesscode. Se l'app Node.js è stata distribuita usando un metodo alternativo, assicurarsi di aggiornare il valore dell'endpoint.

  • SendClaimsIn specifica il modo in cui le attestazioni di input vengono inviate al provider di attestazioni RESTful. Valori possibili: Body (default), Form, HeaderUrl o QueryString. Quando si utilizza Body, ad esempio in questo articolo, si richiama il verbo HTTP POST e i dati inviati all'API sono formattati come coppie di chiave-valore nel corpo della richiesta. Informazioni su come richiamare il verbo HTTP GET e passare i dati come stringa di query.

  • AuthenticationType specifica il tipo di autenticazione eseguita dal provider di attestazioni RESTful. Il nostro provider di attestazioni RESTful chiama un endpoint non protetto, quindi impostiamo il nostro AuthenticationType su Nessuno. Se si imposta il tipo di autenticazione su Bearer, è necessario aggiungere un elemento CryptographicKeys , che specifica la risorsa di archiviazione per il token di accesso. Altre informazioni sui tipi di autenticazione supportati dal provider di attestazioni RESTful.

  • L'attributo PartnerClaimType in InputClaim specifica come si ricevono i dati nell'API.

Passaggio 2.2 - Aggiornare il profilo tecnico di convalida

In Creare la ramificazione nel percorso utente utilizzando una policy personalizzata di Azure AD B2C, hai convalidato l'accessCode usando una trasformazione delle attestazioni. In questo articolo si convalida il codice di accesso effettuando una chiamata HTTP a un servizio esterno. Sarà quindi necessario aggiornare i criteri personalizzati per riflettere il nuovo approccio.

Individuare il profilo tecnico AccessCodeInputCollector e aggiornare il ReferenceId dell'elemento ValidationTechnicalProfile in ValidateAccessCodeViaHttp:

Da:

    <ValidationTechnicalProfile ReferenceId="CheckAccessCodeViaClaimsTransformationChecker"/>

A:

    <ValidationTechnicalProfile ReferenceId="ValidateAccessCodeViaHttp"/>

A questo punto, il profilo tecnico con IdCheckAccessCodeViaClaimsTransformationChecker non è necessario e può essere rimosso.

Passaggio 3 - Caricare un file di criteri personalizzato

Assicurarsi che l'app Node.js sia in esecuzione e quindi seguire i passaggi descritti in Caricare un file di criteri personalizzato per caricare il file dei criteri. Se si carica un file con lo stesso nome di quello già presente nel portale, assicurarsi di selezionare Sovrascrivi il criterio personalizzato, se già esistente.

Passaggio 4- Testare i criteri personalizzati

Seguire la procedura descritta in Testare i criteri personalizzati per testare i criteri personalizzati:

  1. Per Tipo di account selezionare Account personale
  2. Immettere il resto dei dettagli in base alle esigenze e quindi selezionare Continua. Viene visualizzata una nuova schermata.
  3. Per Codice di accesso immettere 88888 e quindi selezionare Continua. Al termine dell'esecuzione della politica, sarai reindirizzato a https://jwt.ms, e vedrai un JWT decodificato. Se si ripete la procedura e si immette un codice di accesso diverso, diverso da 88888, viene visualizzato un errore. Il codice di accesso immesso non è corretto. Riprovare.

Passaggio 5- Abilitare la modalità di debug

In fase di sviluppo, è possibile visualizzare errori dettagliati inviati dall'API, ad esempio developerMessage e moreInfo. In questo caso, è necessario abilitare la modalità di debug nel provider tecnico RESTful.

  1. Individuare il provider tecnico ValidateAccessCodeViaHttp e aggiungere l'elemento seguente nel provider metadatatecnico :

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

  2. Salvare le modifiche e caricare il file dei criteri.

  3. Testare i criteri personalizzati. Assicurarsi di usare un input errato per il codice di accesso. Viene visualizzato un errore simile a quello illustrato in questo screenshot:

    Errore di screenshot quando si abilita la modalità di debug.

Gestire payload JSON di richiesta complessi

Se l'API REST che chiami richiede l'invio di un payload JSON complesso, puoi creare il payload utilizzando GenerateJson per le trasformazioni delle attestazioni JSON. Dopo aver generato il payload, è possibile usare ClaimUsedForRequestPayload l'opzione metadati per il nome dell'attestazione contenente il payload JSON.

Ad esempio, usare la trasformazione delle attestazioni seguente per generare un payload 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 l'oggetto JSON seguente:

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

Aggiornare quindi i metadati, InputClaimsTransformations e InputClaims del provider tecnico RESTful, come illustrato di seguito:

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

Ricevere dati dall'API REST

Se l'API REST restituisce dati, che si desidera includere come attestazioni nei criteri, è possibile riceverli specificando le attestazioni nell'elemento OutputClaims del profilo tecnico RESTful. Se il nome dell'attestazione definita nei criteri è diverso dal nome definito nell'API REST, è necessario eseguire il mapping di questi nomi usando l'attributo PartnerClaimType .

Usare la procedura descritta in Ricezione di dati per informazioni su come formattare i dati previsti dai criteri personalizzati, come gestire i valori Null e come analizzare il corpo JSON annidato dell'API REST.

Contenuti correlati

Successivamente, imparare:

  • Last updated on