Delen via

Een REST API aanroepen met behulp van aangepast Azure Active Directory B2C-beleid

  • Artikel

Met aangepast azure Active Directory B2C-beleid (Azure AD B2C) kunt u communiceren met toepassingslogica die u buiten Azure AD B2C implementeert. Hiervoor maakt u een HTTP-aanroep naar een eindpunt. Aangepast azure AD B2C-beleid biedt hiervoor RESTful-technisch profiel. Met deze mogelijkheid kunt u functies implementeren die niet beschikbaar zijn in aangepast Azure AD B2C-beleid.

In dit artikel leert u het volgende:

  • Maak en implementeer een voorbeeld van een Node.js-app voor gebruik als een RESTful-service.

  • Maak een HTTP-aanroep naar de RESTful-service Node.js met behulp van het RESTful-technische profiel.

  • Verwerkt of rapporteert een fout die een RESTful-service retourneert naar uw aangepaste beleid.

Overzicht van scenario

In Vertakking maken in gebruikerstraject met behulp van aangepast azure AD B2C-beleid, moeten gebruikers die persoonlijk account selecteren, een geldige toegangscode voor uitnodigingen opgeven om door te gaan. We gebruiken een statische toegangscode, maar echte apps werken niet op deze manier. Als de service die de toegangscodes uitgeeft zich buiten uw aangepaste beleid bevindt, moet u een aanroep naar die service maken en de invoer van de toegangscode doorgeven door de gebruiker voor validatie. Als de toegangscode geldig is, retourneert de service een HTTP-antwoord 200 OK en geeft Azure AD B2C JWT-token uit. Anders retourneert de service een HTTP-antwoord 409 Conflict en moet de gebruiker een toegangscode opnieuw invoeren.

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

Vereisten

Notitie

Dit artikel maakt deel uit van de reeks instructies voor het maken en uitvoeren van uw eigen aangepaste beleidsregels in Azure Active Directory B2C. We raden u aan deze reeks te starten vanuit het eerste artikel.

Stap 1: een Node.js-app maken en implementeren

U moet een app implementeren die fungeert als uw externe app. Uw aangepaste beleid maakt vervolgens een HTTP-aanroep naar deze app.

Stap 1.1: de Node.js-app maken

  1. Maak een map voor het hosten van uw knooppunttoepassing, zoals access-code-app.

  2. Wijzig in de terminal de map van de Node-app, zoals cd access-code-appen voer deze uit npm init -y. Met deze opdracht maakt u een standaardbestand package.json voor uw Node.js-project.

  3. Voer npm install express body-parser uit in uw terminal. Met deze opdracht installeert u het Express-framework en het body-parser-pakket .

  4. Maak index.js een bestand in uw project.

  5. Open het index.js bestand in VS Code en voeg de volgende code toe:

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

    U kunt zien dat wanneer een gebruiker een verkeerde toegangscode indient, u rechtstreeks vanuit de REST API een fout kunt retourneren. Met aangepast beleid kunt u een HTTP 4xx-foutbericht retourneren, zoals 400 (ongeldige aanvraag) of 409 -antwoordstatuscode met een JSON-antwoordtekst die is opgemaakt in errorResponse de variabele. De bron van de accessCode in de app kan worden gelezen uit een database. Meer informatie over het retourneren van een validatiefoutbericht.

  6. Als u wilt testen of de app werkt zoals verwacht, gebruikt u de volgende stappen:

    1. Voer in de terminal de opdracht uit om de node index.js app-server te starten.
    2. Als u een POST-aanvraag wilt maken die vergelijkbaar is met de aanvraag die in dit voorbeeld wordt weergegeven, kunt u een HTTP-client zoals Microsoft PowerShell of Postman gebruiken:
        POST http://localhost/validate-accesscode HTTP/1.1
    Host: localhost
    Content-Type: application/x-www-form-urlencoded

    accessCode=user-code-code

    Vervang user-code-code door een invoer van een toegangscode door de gebruiker, zoals 54321. Als u PowerShell gebruikt, voert u het volgende script uit.

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

    Als u een onjuiste toegangscode gebruikt, lijkt het antwoord op het volgende JSON-fragment:

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

Op dit moment bent u klaar om uw Node.js-app te implementeren.

Stap 1.2: de Node.js-app implementeren in Azure-app Service

Uw aangepaste beleid moet bereikbaar zijn om uw Node.js-app te bereiken. Daarom moet u het beleid implementeren. In dit artikel implementeert u de app met behulp van Azure-app Service, maar u gebruikt een alternatieve hostingbenadering.

Volg de stappen in Uw app implementeren in Azure om uw Node.js-app in Azure te implementeren. Gebruik voor de naam van de app een beschrijvende naam, zoals custompolicyapi. Vandaar:

  • App-URL ziet er ongeveer als https://custompolicyapi.azurewebsites.netvolgt uit.

  • Service-eindpunt ziet er ongeveer als https://custompolicyapi.azurewebsites.net/validate-accesscodevolgt uit.

U kunt de app testen die u hebt geïmplementeerd met behulp van een HTTP-client zoals Microsoft PowerShell of Postman. Gebruik deze keer https://custompolicyapi.azurewebsites.net/validate-accesscode de URL als het eindpunt.

Stap 2: de REST API aanroepen

Nu uw app wordt uitgevoerd, moet u een HTTP-aanroep uitvoeren vanuit uw aangepaste beleid. Aangepast Azure AD B2C-beleid biedt een RESTful-technisch profiel dat u gebruikt om een externe service aan te roepen.

Stap 2.1: een RESTful-technisch profiel definiëren

Zoek in het ContosoCustomPolicy.XML bestand de ClaimsProviders sectie en definieer een nieuw RESTful-technisch profiel met behulp van de volgende code:

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

Vanuit het protocol kunt u zien dat we het technische profiel zo configureren dat de RestfulProvider wordt gebruikt. U kunt ook de volgende informatie bekijken in de sectie met metagegevens:

  • Het ServiceUrl vertegenwoordigt het API-eindpunt. De waarde is https://custompolicyapi.azurewebsites.net/validate-accesscode. Als u uw Node.js-app hebt geïmplementeerd met een alternatieve methode, moet u de eindpuntwaarde bijwerken.

  • SendClaimsIn geeft aan hoe de invoerclaims worden verzonden naar de RESTful-claimprovider. Mogelijke waarden: Body (default), Form, , Headerof QueryStringUrl . Wanneer u Body, zoals in dit artikel, de POST HTTP-term aanroept en de gegevens die u naar de API verzendt als deze zijn opgemaakt als sleutel, waardeparen in de hoofdtekst van de aanvraag. Meer informatie over het aanroepen van het GET HTTP-werkwoord en het doorgeven van gegevens als querytekenreeks.

  • AuthenticationType geeft het type verificatie op dat de RESTful-claimprovider uitvoert. Onze RESTful-claimprovider roept een niet-beveiligd eindpunt aan, dus stellen we onze AuthenticationType in op Geen. Als u het verificatietype Bearerinstelt op, moet u een Cryptografischekeys-element toevoegen, waarmee de opslag voor uw toegangstoken wordt opgegeven. Meer informatie over de typen verificatie die door de RESTful-claimprovider worden ondersteund.

  • Het kenmerk PartnerClaimType in de InputClaim geeft aan hoe u uw gegevens in de API ontvangt.

Stap 2.2: technisch profiel voor validatie bijwerken

In Vertakking maken in gebruikerstraject met behulp van aangepast Azure AD B2C-beleid hebt u de accessCode gevalideerd met behulp van een claimtransformatie. In dit artikel valideert u de toegangscode door een HTTP-aanroep naar een externe service uit te voeren. Daarom moet u uw aangepaste beleid bijwerken om de nieuwe benadering weer te geven.

Zoek het technische profiel AccessCodeInputCollector en werk de ReferenceId van het element ValidationTechnicalProfile bij naar ValidateAccessCodeViaHttp:

Van:

    <ValidationTechnicalProfile ReferenceId="CheckAccessCodeViaClaimsTransformationChecker"/>

in:

    <ValidationTechnicalProfile ReferenceId="ValidateAccessCodeViaHttp"/>

Op dit moment is het technische profiel met IdCheckAccessCodeViaClaimsTransformationChecker niet nodig en kan het worden verwijderd.

Stap 3: Aangepast beleidsbestand uploaden

Zorg ervoor dat uw Node.js-app wordt uitgevoerd en volg de stappen in het aangepaste beleidsbestand uploaden om uw beleidsbestand te uploaden. Als u een bestand met dezelfde naam uploadt als het bestand dat zich al in de portal bevindt, moet u het aangepaste beleid overschrijven selecteren als dit al bestaat.

Stap 4: het aangepaste beleid testen

Volg de stappen in Het aangepaste beleid testen om uw aangepaste beleid te testen:

  1. Voor accounttype selecteert u Persoonlijk account
  2. Voer de rest van de details in zoals vereist en selecteer Vervolgens Doorgaan. U ziet een nieuw scherm.
  3. Voor toegangscode voert u 88888 in en selecteert u Doorgaan. Nadat het beleid is uitgevoerd, wordt u omgeleid naar https://jwt.msen ziet u een gedecodeerd JWT-token. Als u de procedure herhaalt en een andere toegangscode invoert dan 88888, ziet u een foutmelding: De ingevoerde toegangscode is onjuist. Probeer het opnieuw.

Stap 5: foutopsporingsmodus inschakelen

In ontwikkeling wilt u mogelijk gedetailleerde fouten zien die door de API worden verzonden, zoals developerMessage en moreInfo. In dit geval moet u de foutopsporingsmodus inschakelen in uw RESTful-technische provider.

  1. Zoek de technische provider ValidateAccessCodeViaHttp en voeg het volgende item toe aan de technische provider metadata:

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

  2. Sla de wijzigingen op en upload het beleidsbestand.

  3. Test uw aangepaste beleid. Zorg ervoor dat u een verkeerde invoer voor uw toegangscode gebruikt. Er wordt een fout weergegeven die vergelijkbaar is met de fout die in deze schermafbeelding wordt weergegeven:

    A screenshot error when you enable debug mode.

JSON-nettoladingen van complexe aanvragen verwerken

Als voor de REST API die u aanroept, een complexe JSON-nettolading moet worden verzonden, kunt u de nettolading maken met behulp van transformaties van GenerateJson JSON-claims. Zodra u de nettolading hebt gegenereerd, kunt u de optie metagegevens gebruiken ClaimUsedForRequestPayload om de naam van de claim met de JSON-nettolading te gebruiken.

Gebruik bijvoorbeeld de volgende claimtransformatie om een JSON-nettolading te genereren:

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

De ClaimsTransformation genereert het volgende JSON-object:

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

Werk vervolgens de metagegevens, InputClaimsTransformations en InputClaims van uw RESTful-technische provider bij, zoals hieronder wordt weergegeven:

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

Gegevens ontvangen van REST API

Als uw REST API gegevens retourneert die u wilt opnemen als claims in uw beleid, kunt u deze ontvangen door claims op te geven in het OutputClaims element van het RESTful-technische profiel. Als de naam van de claim die in uw beleid is gedefinieerd, verschilt van de naam die is gedefinieerd in de REST API, moet u deze namen toewijzen met behulp van het PartnerClaimType kenmerk.

Gebruik de stappen in Ontvangen van gegevens om te leren hoe u de gegevens opmaakt die door het aangepaste beleid worden verwacht, hoe null-waarden moeten worden verwerkt en hoe u REST de geneste JSON-hoofdtekst van de API kunt parseren.

Volgende stappen

Vervolgens leert u: