Aufrufen einer REST-API mithilfe einer benutzerdefinierten Azure Active Directory B2C-Richtlinie

2025-05-08

Von Bedeutung

Ab dem 1. Mai 2025 steht Azure AD B2C nicht mehr für neue Kunden zur Verfügung. Weitere Informationen finden Sie in unseren HÄUFIG gestellten Fragen.

Mit benutzerdefinierten Azure Active Directory B2C-Richtlinien (Azure AD B2C) können Sie mit Anwendungslogik interagieren, die Sie außerhalb von Azure AD B2C implementieren. Dazu führen Sie einen HTTP-Aufruf an einen Endpunkt durch. Benutzerdefinierte Azure AD B2C-Richtlinien stellen zu diesem Zweck ein RESTful-technisches Profil bereit. Mithilfe dieser Funktion können Sie Features implementieren, die in der benutzerdefinierten Azure AD B2C-Richtlinie nicht verfügbar sind.

In diesem Artikel erfahren Sie, wie Sie:

Erstellen und Bereitstellen eines Beispiels Node.js App für die Verwendung als RESTful-Dienst.
Führen Sie einen HTTP-Aufruf des Node.js RESTful-Diensts mithilfe des technischen Profils RESTful durch.
Behandeln oder melden Sie einen Fehler, den ein RESTful-Dienst an Ihre benutzerdefinierte Richtlinie zurückgibt.

Beschreibung des Szenarios

Bei „Verzweigungen im Benutzerablauf erstellen“ mithilfe von benutzerdefinierten Azure AD B2C-Richtlinien müssen Benutzer, die „Persönliches Konto“ auswählen, einen gültigen Einladungszugriffscode bereitstellen, um fortzufahren. Wir verwenden einen statischen Zugriffscode, aber echte Apps funktionieren nicht auf diese Weise. Wenn der Dienst, der die Zugriffscodes ausgibt, außerhalb Ihrer benutzerdefinierten Richtlinie liegt, müssen Sie einen Aufruf an diesen Dienst vornehmen und die Zugriffscodeeingabe des Benutzers zur Überprüfung übergeben. Wenn der Zugriffscode gültig ist, gibt der Dienst eine HTTP-Antwort 200 OK zurück, und Azure AD B2C gibt JWT aus. Andernfalls gibt der Dienst eine HTTP 4xx-Antwort zurück, und der Benutzer muss einen Zugriffscode erneut eingeben.

Ein Flussdiagramm des Aufrufs einer REST-API

Voraussetzungen

Wenn Sie noch keins haben, erstellen Sie einen Azure AD B2C-Mandanten , der mit Ihrem Azure-Abonnement verknüpft ist.
Registrieren Sie eine Webanwendung.
Sie müssen Node.js auf Ihrem Computer installiert haben.
Sie müssen Visual Studio Code (VS Code) auf Ihrem Computer installiert haben.
Führen Sie die Schritte unter Überprüfen von Benutzereingaben mithilfe der benutzerdefinierten Azure AD B2C-Richtlinie aus. Dieser Artikel ist Teil von Create and run your own custom policies how-to guide series.

Hinweis

Dieser Artikel ist Teil der Anleitungsreihe "Erstellen und Ausführen eigener benutzerdefinierter Richtlinien" in Azure Active Directory B2C. Es wird empfohlen, diese Reihe aus dem ersten Artikel zu starten.

Schritt 1 : Erstellen und Bereitstellen einer Node.js-App

Sie müssen eine App bereitstellen, die als externe App dient. Ihre benutzerdefinierte Richtlinie führt dann einen HTTP-Aufruf an diese App aus.

Schritt 1.1 – Erstellen der Node.js-App

Erstellen Sie einen Ordner zum Hosten Ihrer Knotenanwendung, wie access-code-app.
Wechseln Sie in Ihrem Terminal in das Verzeichnis Ihres Node-App-Ordners, zum Beispiel cd access-code-app, und führen Sie npm init -y aus. Mit diesem Befehl wird eine package.json-Standarddatei für Ihr Node.js-Projekt erstellt.
Führen Sie in Ihrem Terminal npm install express body-parser aus. Mit diesem Befehl werden das Express-Framework und das Body-Parser-Paket installiert.
Erstellen Sie in Ihrem Projekt eine index.js-Datei.

Öffnen Sie in VS Code die index.js Datei, und fügen Sie dann den folgenden Code hinzu:

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

Wenn ein Benutzer einen falschen Zugriffscode sendet, können Sie einen Fehler direkt aus der REST-API zurückgeben. Mit benutzerdefinierten Richtlinien können Sie eine HTTP 4xx-Fehlermeldung zurückgeben, z. B. 400 (ungültige Anforderung) oder den Antwortstatuscode 409 (Konflikt) mit einem JSON-Antworttext, der wie in errorResponse der Variablen dargestellt formatiert ist. Die Quelle des accessCode in der App könnte aus einer Datenbank gelesen werden. Weitere Informationen zum Zurückgeben einer Überprüfungsfehlermeldung.

Führen Sie die folgenden Schritte aus, um die App wie erwartet zu testen:

Führen Sie in Ihrem Terminal den node index.js Befehl aus, um den App-Server zu starten.
Um eine POST-Anforderung ähnlich wie in diesem Beispiel zu erstellen, können Sie einen HTTP-Client wie Microsoft PowerShell verwenden.

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

    accessCode=user-code-code

Ersetzen Sie user-code-code durch einen Zugriffscode, der vom Benutzer eingegeben wird, z. B. 54321. Wenn Sie PowerShell verwenden, führen Sie das folgende Skript aus.

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

Wenn Sie einen falschen Zugriffscode verwenden, sieht die Antwort ähnlich wie der folgende JSON-Codeausschnitt aus:

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

Ihr REST-Dienst kann HTTP 4xx-Statuscode zurückgeben, aber der Wert status in der JSON-Antwort muss sein 409.

An diesem Punkt können Sie Ihre Node.js-App bereitstellen.

Schritt 1.2 – Bereitstellen der Node.js-App in Azure App Service

Damit Ihre benutzerdefinierte Richtlinie Ihre Node.js-App erreicht, muss sie erreichbar sein, deshalb müssen Sie sie bereitstellen. In diesem Artikel stellen Sie die App mithilfe von Azure App Service bereit, verwenden jedoch einen alternativen Hostingansatz.

Führen Sie die Schritte in "Bereitstellen Ihrer App in Azure " aus, um Ihre Node.js-App in Azure bereitzustellen. Verwenden Sie für den Namen der App einen beschreibenden Namen, wie custompolicyapi z.B. Daher:

App-URL sieht ähnlich aus wie https://custompolicyapi.azurewebsites.net.
Der Dienstendpunkt sieht ähnlich aus wie https://custompolicyapi.azurewebsites.net/validate-accesscode.

Sie können die App testen, die Sie mithilfe eines HTTP-Clients wie Microsoft PowerShell bereitgestellt haben. Verwenden Sie diesmal die URL https://custompolicyapi.azurewebsites.net/validate-accesscode als Endpunkt.

Schritt 2 : Aufrufen der REST-API

Nachdem Ihre App ausgeführt wird, müssen Sie einen HTTP-Aufruf aus Ihrer benutzerdefinierten Richtlinie ausführen. Die benutzerdefinierte Azure AD B2C-Richtlinie stellt ein RESTful-technisches Profil bereit, das Sie zum Aufrufen eines externen Diensts verwenden.

Schritt 2.1 – Definieren eines RESTful-technischen Profils

Suchen Sie in Ihrer ContosoCustomPolicy.XML Datei den ClaimsProviders Abschnitt, und definieren Sie ein neues technisches PROFIL mit dem folgenden 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>-->

Aus dem Protokoll können Sie feststellen, dass wir das technische Profil so konfigurieren, dass der RestfulProvider verwendet wird. Sie können auch die folgenden Informationen im Metadatenabschnitt beobachten:

Dies ServiceUrl stellt den API-Endpunkt dar. Der Wert ist https://custompolicyapi.azurewebsites.net/validate-accesscode. Wenn Sie Ihre Node.js-App mit einer alternativen Methode bereitgestellt haben, müssen Sie den Endpunktwert aktualisieren.
SendClaimsIn Gibt an, wie die Eingabeansprüche an den RESTful-Anspruchsanbieter gesendet werden. Mögliche Werte: Body (default), Form, , Header, Url oder QueryString. Wenn Sie Body verwenden, wie in diesem Artikel, rufen Sie das POST-HTTP-Verb auf, und die Daten, die Sie an die API senden, sind im Anforderungstext als Schlüssel-Wert-Paare formatiert. Erfahren Sie, wie Sie das GET-HTTP-Verb aufrufen und Daten als Abfragezeichenfolge übergeben.
AuthenticationType Gibt den Authentifizierungstyp an, den der RESTful-Anspruchsanbieter ausführt. Unser RESTful-Anspruchsanbieter ruft einen ungeschützten Endpunkt auf, daher setzen wir unser AuthenticationType auf None. Wenn Sie den Authentifizierungstyp auf Bearer"" festlegen, müssen Sie ein CryptographicKeys-Element hinzufügen, das den Speicher für Ihr Zugriffstoken angibt. Erfahren Sie mehr über die Authentifizierungstypen, die der RESTful-Anspruchsanbieter unterstützt.
Das PartnerClaimType-Attribut im InputClaim spezifiziert, wie Sie Ihre Daten in der API erhalten.

Schritt 2.2 – Aktualisieren des technischen Profils der Validierung

Unter Verzweigung in User Journey mithilfe der benutzerdefinierten Azure AD B2C-Richtlinie erstellen haben Sie den accessCode mithilfe einer Anspruchstransformation überprüft. In diesem Artikel überprüfen Sie den accessCode , indem Sie einen HTTP-Aufruf an einen externen Dienst ausführen. Daher müssen Sie Ihre benutzerdefinierte Richtlinie aktualisieren, um den neuen Ansatz widerzuspiegeln.

Suchen Sie das technische Profil von AccessCodeInputCollector, und aktualisieren Sie die ReferenceId des ValidationTechnicalProfile-Elements auf ValidateAccessCodeViaHttp:

Von:

    <ValidationTechnicalProfile ReferenceId="CheckAccessCodeViaClaimsTransformationChecker"/>

in:

    <ValidationTechnicalProfile ReferenceId="ValidateAccessCodeViaHttp"/>

Zu diesem Zeitpunkt ist das technische Profil mit IdCheckAccessCodeViaClaimsTransformationChecker nicht erforderlich und kann entfernt werden.

Schritt 3 – Hochladen der benutzerdefinierten Richtliniendatei

Stellen Sie sicher, dass Ihre Node.js-App ausgeführt wird, und führen Sie dann die Schritte in der Datei "Benutzerdefinierte Richtlinien hochladen " aus, um Ihre Richtliniendatei hochzuladen. Wenn Sie eine Datei mit demselben Namen wie die datei hochladen, die sich bereits im Portal befindet, stellen Sie sicher, dass Sie die benutzerdefinierte Richtlinie überschreiben, falls sie bereits vorhanden ist.

Schritt 4: Testen der benutzerdefinierten Richtlinie

Führen Sie die Schritte unter "Testen der benutzerdefinierten Richtlinie " aus, um Ihre benutzerdefinierte Richtlinie zu testen:

Wählen Sie für "Kontotyp" die Option "Persönliches Konto" aus.
Geben Sie die restlichen Details nach Bedarf ein, und wählen Sie dann "Weiter" aus. Ein neuer Bildschirm wird angezeigt.
Geben Sie für Access Code88888 ein, und wählen Sie dann "Weiter" aus. Nachdem die Richtlinie die Ausführung abgeschlossen hat, werden Sie umgeleitet nach https://jwt.ms, und es wird ein dekodiertes JWT angezeigt. Wenn Sie die Prozedur wiederholen und einen anderen Zugriffscode als 88888 eingeben, wird ein Fehler angezeigt, der eingegebene Zugriffscode ist falsch. Versuchen Sie es bitte erneut.

Schritt 5 : Aktivieren des Debugmodus

In der Entwicklung möchten Sie möglicherweise detaillierte Fehler sehen, die von der API gesendet wurden, z. B. developerMessage und moreInfo. In diesem Fall müssen Sie den Debugmodus in Ihrem RESTful-Dienstanbieter aktivieren.

Suchen Sie Ihren technischen Anbieter ValidateAccessCodeViaHttp, und fügen Sie das folgende Element zu den metadata des technischen Anbieters hinzu:
```
    <Item Key="DebugMode">true</Item>
```
Speichern Sie die Änderungen, und laden Sie Ihre Richtliniendatei hoch.
Testen Sie Ihre benutzerdefinierte Richtlinie. Stellen Sie sicher, dass Sie für Ihren Access-Code eine falsche Eingabe verwenden. Es wird ein Fehler angezeigt, der dem in diesem Screenshot gezeigten fehler ähnelt:

Behandeln komplexer JSON-Anforderungsnutzlasten

Wenn die von Ihnen aufgerufene REST-API erfordert, dass Sie eine komplexe JSON-Nutzlast senden, können Sie die Nutzlast mithilfe von GenerateJson JSON-Anspruchstransformationen erstellen. Nachdem Sie die Nutzlast generiert haben, können Sie die Metadatenoption für den Namen des Anspruchs verwendenClaimUsedForRequestPayload, der die JSON-Nutzlast enthält.

Verwenden Sie beispielsweise die folgende Anspruchstransformation, um eine JSON-Nutzlast zu generieren:

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

Die ClaimsTransformation generiert das folgende 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
      }
   }
}

Aktualisieren Sie dann die Metadaten, InputClaimsTransformations und InputClaims Ihres RESTful-technischen Anbieters wie unten dargestellt:

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

Empfangen von Daten aus der REST-API

Wenn Ihre REST-API Daten zurückgibt, die Sie als Ansprüche in Ihre Richtlinie einschließen möchten, können Sie sie empfangen, indem Sie Ansprüche im OutputClaims Element des RESTful-technischen Profils angeben. Wenn sich der Name des in Ihrer Richtlinie definierten Anspruchs vom in der REST-API definierten Namen unterscheidet, müssen Sie diese Namen mithilfe des PartnerClaimType Attributs zuordnen.

Verwenden Sie die Schritte beim Empfangen von Daten , um zu erfahren, wie die von der benutzerdefinierten Richtlinie erwarteten Daten formatiert werden, wie Nullwerte behandelt werden, und wie REST der geschachtelten JSON-Textkörper der API analysiert wird.

Als Nächstes lernen Sie: