Condividi tramite

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

  • Articolo

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 Node.js di esempio 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 ai criteri personalizzati.

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 il token JWT. In caso contrario, il servizio restituisce una risposta HTTP 409 Conflict e l'utente deve immettere nuovamente un codice di accesso.

A flowchart of calling a R E S T A P I.

Prerequisiti

Nota

Questo articolo fa parte della serie di procedure 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. I criteri personalizzati e 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 predefinito package.json 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://docs.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 dell'oggetto accessCode nell'app può essere letta da un database. Altre informazioni sulla restituzione del messaggio di errore di convalida.

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

    1. Nel terminale eseguire il comando per avviare il node index.js server app.
    2. Per effettuare una richiesta POST simile a quella illustrata in questo esempio, è possibile usare un client HTTP come Microsoft PowerShell o Postman:
        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://docs.microsoft.com/en-us/azure/active-directory-b2c/string-transformations"
    }

A questo punto, si è pronti per distribuire l'app Node.js.

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

Affinché i criteri personalizzati raggiungano l'app Node.js, deve essere raggiungibile, quindi è necessario distribuirlo. In questo articolo si distribuisce l'app usando app Azure Servizio, ma si usa un approccio di hosting alternativo.

Seguire la procedura descritta 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 o Postman. 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

ContosoCustomPolicy.XML Nel file individuare la ClaimsProviders sezione e definire 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:

  • Rappresenta ServiceUrl 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 usa Body, ad esempio in questo articolo, si richiama il verbo HTTP POST e i dati inviati all'API se formattati come chiave, coppie 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 provider di attestazioni RESTful chiama un endpoint non protetto, quindi viene impostato su AuthenticationTypeNessuno. 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 diramazione nel percorso utente usando i criteri personalizzati di Azure AD B2C è stato convalidato 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"/>

in:

    <ValidationTechnicalProfile ReferenceId="ValidateAccessCodeViaHttp"/>

A questo punto, il profilo tecnico con IdCheckAccessCodeClaimsTransformationChecker 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 la procedura descritta in Caricare il 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 del criterio, si viene reindirizzati a https://jwt.mse viene visualizzato un token 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:

    A screenshot error when you enable debug mode.

Gestire payload JSON di richiesta complessi

Se l'API REST chiamata richiede l'invio di un payload JSON complesso, è possibile creare il payload usando le trasformazioni delle attestazioni JSON GenerateJson. 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":"01234567-89ab-cdef-0123-456789abcdef",
      "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.

Passaggi successivi

A questo punto, vedere: