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

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 en 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 lär du dig att:

• Skapa och distribuera ett exempel Node.js app för användning som en RESTful-tjänst.

• Gör ett HTTP-anrop till Node.js RESTful-tjänsten med hjälp av den tekniska RESTful-profilen.

• Hantera eller rapportera ett fel som en RESTful-tjänst returnerar till din egen policy.

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 tjänsten som utfärdar åtkomstkoderna är extern i förhållande till din anpassade policy måste du göra ett anrop till den tjänsten och skicka åtkomstkod som angetts av användaren för validering. Om åtkomstkoden är giltig returnerar tjänsten ett HTTP-svar 200 OK och Azure AD B2C utfärdar JWT. Annars returnerar tjänsten ett HTTP 4xx-svar och användaren måste ange en åtkomstkod igen.

Förutsättningar

• Om du inte redan har en, skapa en Azure AD B2C-klientenhet som är länkad till din Azure-prenumeration.

• Registrera ett webbprogram.

• Du måste ha Node.js installerat på datorn.

• Du måste ha Visual Studio Code (VS Code) 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 Skapa och köra egna anpassade policyguide.

Steg 1 – Skapa och distribuera en Node.js app

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

Steg 1.1 – Skapa Node.js-appen

1. Skapa en mapp som är värd för nodprogrammet, till exempel access-code-app.

2. 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 för package.json för ditt Node.js projekt.

3. Kör npm install express body-parser i terminalen. Det här kommandot installerar Express-ramverket och body-parser-paketet .

4. I ditt projekt, skapa index.js fil.

5. Ö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://free.blessedness.top/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.

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

   1. Kör kommandot i terminalen node index.js för att starta appservern.
   2. 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, till exempel Microsoft PowerShell.

       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://free.blessedness.top/en-us/azure/active-directory-b2c/string-transformations"
       }
   

REST-tjänsten kan returnera HTTP 4xx-statuskod, men värdet status för i JSON-svaret måste vara 409.

Nu är du redo att distribuera din Node.js app.

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

För att din anpassade policy ska nå din Node.js-app måste den vara åtkomlig, så du måste 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 din Node.js app 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. Den här gången använder du https://custompolicyapi.azurewebsites.net/validate-accesscode URL:en som slutpunkt.

Steg 2 – Anropa REST-API:et

Eftersom din app nu körs behöver du göra ett HTTP-anrop från din anpassade policy. Azure AD B2C-anpassad policy 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 distribuerade din Node.js-app med en alternativ metod bör du uppdatera slutpunktsvärdet.

• SendClaimsIn anger hur indataanspråken skickas till RESTful-anspråksprovidern. Möjliga värden: Body (default), Form, Headereller UrlQueryString. 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 genom att använda en anpassad Azure AD B2C-princip validerade du accessCode genom en kravtransformation. 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 ValidationTechnicalProfile-elementets ReferenceId 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 din Node.js app körs och följ sedan stegen i Ladda upp en anpassad principfil för att ladda upp din principfil. Om du laddar upp en fil med samma namn som den som redan finns i portalen kontrollerar du att du väljer Skriva över den anpassade principen om den redan finns.

Steg 4 – Testa den anpassade policyn

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

1. För Kontotyp väljer du Personligt konto
2. Ange resten av informationen efter behov och välj sedan Fortsätt. Du ser en ny skärm.
3. För Åtkomstkod anger du 88888 och väljer sedan Fortsätt. När policyn har slutfört körningen omdirigeras du till https://jwt.ms och du ser en avkodad JWT. 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.

1. Leta upp den tekniska providern ValidateAccessCodeViaHttp och lägg till följande objekt i den tekniska providerns metadata:

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

2. Spara ändringarna och ladda upp principfilen.

3. Testa din anpassade policy. 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 förfrågningar

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":"aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
      "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 din REST-API returnerar data som du vill inkludera som anspråk i din policy, kan du ta emot dem genom att specificera anspråk i OutputClaims-elementet i den tekniska RESTful-profilen. Om namnet på anspråket i din policy skiljer sig från det namn som definierats i REST-API:et måste du mappa dessa namn med hjälp av PartnerClaimType-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.

Relaterat innehåll

Lär dig sedan:

• Om JSON-anspråkstransformeringar.

• Om RESTful teknisk profil.

• Skapa och läs ett användarkonto med hjälp av en anpassad Azure Active Directory B2C-policy