Anropa ett REST-API med hjälp av en anpassad princip för Azure Active Directory B2C

Artikel
01/11/2024

Med anpassad princip för Azure Active Directory B2C (Azure AD B2C) kan du interagera med programlogik som du implementerar utanför Azure AD B2C. För att göra det gör du ett HTTP-anrop till en slutpunkt. Anpassade azure AD B2C-principer tillhandahåller restful teknisk profil för detta ändamål. Med den här funktionen kan du implementera funktioner som inte är tillgängliga i den anpassade Azure AD B2C-principen.

I den här artikeln kan du se hur du:

Skapa och distribuera en Node.js-exempelapp för användning som en RESTful-tjänst.
Gör ett HTTP-anrop till TJÄNSTEN Node.js RESTful med hjälp av den tekniska RESTful-profilen.
Hantera eller rapportera ett fel som en RESTful-tjänst returnerar till din anpassade princip.

Scenarioöversikt

I Skapa förgrening i användarresan med hjälp av anpassade Azure AD B2C-principer måste användare som väljer Personligt konto ange en giltig åtkomstkod för inbjudan för att fortsätta. Vi använder en statisk åtkomstkod, men verkliga appar fungerar inte på det här sättet. Om den tjänst som utfärdar åtkomstkoderna är extern för din anpassade princip måste du göra ett anrop till tjänsten och skicka åtkomstkodens indata från användaren för validering. Om åtkomstkoden är giltig returnerar tjänsten ett HTTP-svar 200 OK och Azure AD B2C utfärdar JWT-token. Annars returnerar tjänsten ett HTTP-svar 409 Conflict och användaren måste ange en åtkomstkod igen.

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

Förutsättningar

Om du inte redan har en skapar du en Azure AD B2C-klientorganisation som är länkad till din Azure-prenumeration.
Registrera ett webbprogram och aktivera implicit beviljande av ID-token. För omdirigerings-URI använder du https://jwt.ms.
Node.js måste vara installerat på datorn.
Visual Studio Code (VS Code) måste vara installerat på datorn.
Slutför stegen i Verifiera användarindata med hjälp av en anpassad Azure AD B2C-princip. Den här artikeln är en del av guideserien Skapa och kör egna anpassade principer.

Kommentar

Den här artikeln är en del av guideserien Skapa och köra egna anpassade principer i Azure Active Directory B2C. Vi rekommenderar att du startar den här serien från den första artikeln.

Steg 1 – Skapa och distribuera en Node.js-app

Du måste distribuera en app som fungerar som din externa app. Din anpassade princip gör sedan ett HTTP-anrop till den här appen.

Steg 1.1 – Skapa node.js-appen

Skapa en mapp som är värd för nodprogrammet, till exempel access-code-app.
I terminalen ändrar du katalogen till din Node-appmapp, till exempel cd access-code-app, och kör npm init -y. Det här kommandot skapar en standardfil package.json för node.js-projektet.
Kör npm install express body-parser i terminalen. Det här kommandot installerar Express-ramverket och body-parser-paketet .
Skapa en fil i projektet index.js .

Öppna filen i index.js VS Code och lägg sedan till följande kod:

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

Du kan observera att när en användare skickar en felaktig åtkomstkod kan du returnera ett fel direkt från REST-API:et. Med anpassade principer kan du returnera ett HTTP 4xx-felmeddelande, till exempel 400 (felaktig begäran) eller 409 (konflikt) svarsstatuskod med en JSON-svarstext formaterad enligt errorResponse variabeln. Källan till accessCode i appen kan läsas från en databas. Läs mer om att returnera ett verifieringsfelmeddelande.

Om du vill testa appen fungerar som förväntat använder du följande steg:

Kör kommandot i terminalen node index.js för att starta appservern.
Om du vill göra en POST-begäran som liknar den som visas i det här exemplet kan du använda en HTTP-klient som Microsoft PowerShell eller Postman:

    POST http://localhost/validate-accesscode HTTP/1.1
    Host: localhost
    Content-Type: application/x-www-form-urlencoded

    accessCode=user-code-code

Ersätt user-code-code med en åtkomstkodsindata från användaren, till exempel 54321. Om du använder PowerShell kör du följande skript.

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

Om du använder en felaktig åtkomstkod ser svaret ut ungefär som följande JSON-kodfragment:

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

Nu är du redo att distribuera node.js-appen.

Steg 1.2 – Distribuera Node.js-appen i Azure App Service

För att din anpassade princip ska nå din Node.js-app måste den kunna nås, så du behöver distribuera den. I den här artikeln distribuerar du appen med hjälp av Azure App Service, men du använder en alternativ värdmetod.

Följ stegen i Distribuera din app till Azure för att distribuera node.js-appen till Azure. För appens namn använder du ett beskrivande namn, till exempel custompolicyapi. Därför:

App-URL:en ser ut ungefär som https://custompolicyapi.azurewebsites.net.
Tjänstslutpunkten ser ut ungefär som https://custompolicyapi.azurewebsites.net/validate-accesscode.

Du kan testa appen som du har distribuerat med hjälp av en HTTP-klient, till exempel Microsoft PowerShell eller Postman. Den här gången använder du https://custompolicyapi.azurewebsites.net/validate-accesscode URL:en som slutpunkt.

Steg 2 – Anropa REST-API:et

Nu när appen körs måste du göra ett HTTP-anrop från din anpassade princip. Azure AD B2C-anpassad princip tillhandahåller en RESTful-teknisk profil som du använder för att anropa en extern tjänst.

Steg 2.1 – Definiera en RESTful-teknisk profil

ContosoCustomPolicy.XML Leta upp avsnittet i ClaimsProviders filen och definiera en ny teknisk RESTful-profil med hjälp av följande kod:

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

Från protokollet kan du observera att vi konfigurerar den tekniska profilen så att den använder RestfulProvider. Du kan också se följande information i metadataavsnittet:

ServiceUrl Representerar API-slutpunkten. Dess värde är https://custompolicyapi.azurewebsites.net/validate-accesscode. Om du har distribuerat node.js-appen med en alternativ metod måste du uppdatera slutpunktsvärdet.
SendClaimsIn anger hur indataanspråken skickas till RESTful-anspråksprovidern. Möjliga värden: Body (default), Form, Headereller Url QueryString. När du använder Body, till exempel i den här artikeln, anropar du POST HTTP-verbet och de data som du skickar till API:et om de formateras som nyckel, värdepar i brödtexten i begäran. Lär dig hur du anropar GET HTTP-verbet och skickar data som frågesträng.
AuthenticationType anger vilken typ av autentisering som RESTful-anspråksprovidern utför. Vår RESTful-anspråksprovider anropar en oskyddad slutpunkt, så vi ställer in vår AuthenticationType på Ingen. Om du anger autentiseringstyp till Bearermåste du lägga till ett CryptographicKeys-element som anger lagringen för din åtkomsttoken. Läs mer om de typer av autentisering som RESTful-anspråksprovidern stöder.
Attributet PartnerClaimType i InputClaim anger hur du tar emot dina data i API:et.

Steg 2.2 – Uppdatera teknisk profil för validering

I Skapa förgrening i användarresan med hjälp av en anpassad Azure AD B2C-princip verifierade du accessCode med hjälp av en anspråkstransformering. I den här artikeln validerar du accessCode genom att göra ett HTTP-anrop till en extern tjänst. Därför måste du uppdatera din anpassade princip så att den återspeglar den nya metoden.

Leta upp den tekniska profilen AccessCodeInputCollector och uppdatera Elementet ValidationTechnicalProfile till ValidateAccessCodeViaHttp:

Från:

    <ValidationTechnicalProfile ReferenceId="CheckAccessCodeViaClaimsTransformationChecker"/>

till:

    <ValidationTechnicalProfile ReferenceId="ValidateAccessCodeViaHttp"/>

Nu behövs inte den tekniska profilen med IdCheckAccessCodeViaClaimsTransformationChecker och kan tas bort.

Steg 3 – Ladda upp anpassad principfil

Kontrollera att node.js-appen körs och följ sedan stegen i Ladda upp en anpassad principfil för att ladda upp principfilen. Om du laddar upp en fil med samma namn som den som redan finns i portalen kontrollerar du att du väljer Skriv över den anpassade principen om den redan finns.

Steg 4 – Testa den anpassade principen

Följ stegen i Testa den anpassade principen för att testa din anpassade princip:

För Kontotyp väljer du Personligt konto
Ange resten av informationen efter behov och välj sedan Fortsätt. Du ser en ny skärm.
För Åtkomstkod anger du 88888 och väljer sedan Fortsätt. När principen har slutfört körningen omdirigeras du till https://jwt.msoch du ser en avkodad JWT-token. Om du upprepar proceduren och anger en annan åtkomstkod, förutom 88888, visas ett fel. Åtkomstkoden som du angav är felaktig. Försök igen.

Steg 5 – Aktivera felsökningsläge

Under utvecklingen kanske du vill se detaljerade fel som skickas av API:et, till exempel developerMessage och moreInfo. I det här fallet måste du aktivera felsökningsläge i din tekniska RESTful-provider.

Leta upp den tekniska providern ValidateAccessCodeViaHttp och lägg till följande objekt i den tekniska providerns metadata:
```
    <Item Key="DebugMode">true</Item>
```
Spara ändringarna och ladda upp principfilen.
Testa din anpassade princip. Se till att du använder fel indata för din åtkomstkod. Du ser ett fel som liknar det som visas i den här skärmbilden:

Hantera JSON-nyttolaster för komplexa begäranden

Om rest-API:et som du anropar kräver att du skickar en komplex JSON-nyttolast kan du skapa nyttolasten med hjälp av GenerateJson JSON-anspråkstransformeringar. När du har genererat nyttolasten kan du sedan använda ClaimUsedForRequestPayload metadataalternativet till namnet på anspråket som innehåller JSON-nyttolasten.

Använd till exempel följande anspråkstransformering för att generera en JSON-nyttolast:

    <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 genererar följande JSON-objekt:

{
   "customerEntity":{
      "email":"john.s@contoso.com",
      "userObjectId":"01234567-89ab-cdef-0123-456789abcdef",
      "firstName":"John",
      "lastName":"Smith",
      "accessCode":"88888",
      "role":{
         "name":"Administrator",
         "id": 1
      }
   }
}

Uppdatera sedan metadata, InputClaimsTransformations och InputClaims för din RESTful-tekniska provider enligt nedan:

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

Ta emot data från REST API

Om rest-API:et returnerar data, som du vill inkludera som anspråk i principen, kan du ta emot dem genom att ange anspråk i elementet OutputClaims i den tekniska RESTful-profilen. Om namnet på anspråket som definierats i principen skiljer sig från det namn som definierats i REST-API:et måste du mappa dessa namn med hjälp PartnerClaimType av attributet .

Använd stegen i Ta emot data för att lära dig hur du formaterar data som den anpassade principen förväntar sig, hur du hanterar nullvärden och hur du parsar REST API:ets kapslade JSON-brödtext.

Nästa steg

Lär dig sedan:

Dela via