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

Artikel
01/11/2024

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

In diesem Artikel werden folgende Vorgehensweisen behandelt:

Erstellen Sie ein Node.js-Beispielapp für die Verwendung als RESTful-Dienst, und stellen Sie sie bereit.
Führen Sie mithilfe des technischen RESTful-Profils einen HTTP-Aufruf an den Node.js RESTful-Dienst aus.
Behandeln oder melden Sie einen Fehler, den ein RESTful-Dienst an Ihre benutzerdefinierte Richtlinie zurückgibt.

Übersicht über das Szenario

Unter Mithilfe von benutzerdefinierten Azure AD B2C-Richtlinien Verzweigungen in User Journey erstellen müssen Benutzer, die persönliches Konto auswählen, einen gültigen Einladungszugriffscode angeben, um fortzufahren. Wir verwenden einen statischen Zugriffscode, aber echte Apps funktionieren anders. Wenn der Dienst, der die Zugriffscodes ausgibt, außerhalb Ihrer benutzerdefinierten Richtlinie liegt, müssen Sie einen Aufruf an diesen Dienst ausführen und den vom Benutzer eingegebenen Zugriffscode zur Überprüfung übergeben. Wenn der Zugriffscode gültig ist, gibt der Dienst die HTTP-Antwort 200 OK zurück, und Azure AD B2C gibt JWT-Token aus. Andernfalls gibt der Dienst die HTTP-Antwort 409 Conflict zurück, und der Zugriffscode muss erneut eingegeben werden.

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

Voraussetzungen

Wenn Sie noch nicht über einen Azure AD B2C-Mandanten verfügen, erstellen Sie einen, der mit Ihrem Azure-Abonnement verknüpft ist.
Registrieren Sie eine Webanwendung, und aktivieren Sie die implizite Gewährung von ID-Token. Verwenden Sie https://jwt.ms für den Umleitungs-URI.
Node.js muss auf Ihrem Computer installiert sein.
Visual Studio Code (VS Code) muss auf Ihrem Computer installiert sein.
Schließen Sie die Schritte unter Überprüfen von Benutzereingaben mithilfe der benutzerdefinierten Azure AD B2C-Richtlinie ab. Dieser Artikel ist Teil der Schrittanleitungsreihe „Erstellen und Ausführen eigener benutzerdefinierter Richtlinien“.

Hinweis

Dieser Artikel ist Teil der Schrittanleitungsreihe „Erstellen und Ausführen Ihrer eigenen benutzerdefinierten Richtlinien in Azure Active Directory B2C“. Wir empfehlen Ihnen, diese Reihe mit dem ersten Artikel zu beginnen.

Schritt 1: Eine Node.js-App erstellen und bereitstellen

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

Schritt 1.1: Die Node.js-App erstellen

Erstellen Sie einen Ordner zum Hosten Ihrer Node-Anwendung, z. B. access-code-app.
Wechseln Sie in Ihrem Terminal in das Verzeichnis Ihres Node-App-Ordners, z. B. 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 Textparser-Paket installiert.
Erstellen Sie in Ihrem Projekt eine index.js-Datei.

Öffnen Sie in VS Code die index.js-Datei, und fügen Sie anschließend 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://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);
    });

Wenn ein Benutzer einen falschen Zugriffscode übermittelt, können Sie einen Fehler direkt von der REST-API zurückgeben. Mit benutzerdefinierten Richtlinien können Sie eine HTTP 4xx-Fehlermeldung zurückgeben, z. B. 400 (ungültige Anforderung) oder 409 (Konflikt) mit einem JSON-Antworttext, wie in der errorResponse-Variable dargestellt. Die Quelle des Zugriffscodes in der App kann aus einer Datenbank gelesen werden. Weitere Informationen finden Sie unter Zurückgegebene Validierungsfehler.

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

Führen Sie in Ihrem Terminal den node index.js-Befehl aus, um den App-Server zu starten.
Um eine POST-Anforderung ähnlich der in diesem Beispiel gezeigten zu stellen, können Sie einen HTTP-Client wie Microsoft PowerShell oder Postman 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 eine Zugriffscodeeingabe des Benutzers, 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, ähnelt die Antwort dem folgenden JSON-Codeschnipsel:

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

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

Schritt 1.2: Die Node.js-App in Azure App Service bereitstellen

Damit Ihre benutzerdefinierte Richtlinie Ihre Node.js-App erreichen kann, muss sie erreichbar sein. Also müssen Sie sie bereitstellen. In diesem Artikel erfahren Sie, wie Sie die App mithilfe von Azure App Service bereitstellen. Sie werden jedoch einen alternativen Hostingansatz verwenden.

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

Die App-URL ähnelt https://custompolicyapi.azurewebsites.net.
Der Dienstendpunkt ähnelt https://custompolicyapi.azurewebsites.net/validate-accesscode.

Sie können die bereitgestellte App mithilfe eines HTTP-Clients wie Microsoft PowerShell oder Postman testen. Verwenden Sie dieses Mal die URL „https://custompolicyapi.azurewebsites.net/validate-accesscode“ als Endpunkt.

Schritt 2: Die REST-API aufrufen

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

Schritt 2.1: Ein technisches RESTful-Profil definieren

Suchen Sie in Ihrer ContosoCustomPolicy.XML-Datei nach dem Abschnitt „ClaimsProviders“, und definieren Sie mithilfe des folgenden Codes ein neues technisches RESTful-Profil:

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

An dem Protokoll können Sie sehen, dass wir das technische Profil so konfigurieren, dass es RestfulProviders verwendet. Außerdem können Sie die folgenden Informationen im Metadatenabschnitt sehen:

ServiceUrl stellt den API-Endpunkt dar. Sein Wert lautet 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 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 und die Daten, die Sie an die API senden, wenn sie als Schlüssel formatiert sind, als Wertepaare im Textkörper der Anforderung auf. 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, sodass wir unsere AuthenticationType auf Keine festlegen. 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 in InputClaim gibt an, wie Sie Ihre Daten in der API erhalten.

Schritt 2.2: Das technische Validierungsprofil aktualisieren

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

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

von:

    <ValidationTechnicalProfile ReferenceId="CheckAccessCodeViaClaimsTransformationChecker"/>

in:

    <ValidationTechnicalProfile ReferenceId="ValidateAccessCodeViaHttp"/>

An diesem Punkt wird das technische Profil mit IdCheckAccessCodeViaClaimsTransformationChecker nicht benötigt und kann entfernt werden.

Schritt 3: Benutzerdefinierte Richtliniendatei hochladen

Stellen Sie sicher, dass Ihre Node.js-App ausgeführt wird, und führen Sie dann die Schritte unter Benutzerdefinierte Richtliniendatei hochladen aus, um Ihre Richtliniendatei hochzuladen. Wenn Sie eine Datei mit dem gleichen Namen wie eine Datei hochladen, die bereits im Portal vorhanden ist, stellen Sie sicher, dass Sie Benutzerdefinierte Richtlinie überschreiben, sofern sie bereits vorhanden ist auswählen.

Schritt 4: Benutzerdefinierte Richtlinie testen

Führen Sie die Schritte unter Benutzerdefinierte Richtlinie testen aus, um Ihre benutzerdefinierte Richtlinie zu testen:

Wählen Sie unter Kontotyp die Option Persönliches Konto aus.
Geben Sie die restlichen Details nach Bedarf ein, und wählen Sie dann Weiter aus. Ihnen wird ein neuer Bildschirm angezeigt.
Geben Sie unter Zugriffscode88888 ein, und wählen Sie dann Weiter aus. Nachdem die Ausführung der Richtlinie abgeschlossen ist, werden Sie zu https://jwt.ms weitergeleitet, und es wird ein decodiertes JWT-Token angezeigt. Wenn Sie die Prozedur wiederholen und einen anderen Zugriffscode als 88888 eingeben, wird der Folgende Fehler angezeigt: Der eingegebene Zugriffscode ist falsch. Bitte versuchen Sie es später noch einmal.

Schritt 5: Debugmodus aktivieren

In der Entwicklungsphase möchten Sie wahrscheinlich detaillierte Fehler sehen, die von der API gesendet werden, z. B. developerMessage und moreInfo. In diesem Fall müssen Sie den Debugmodus in Ihrem technischen RESTful-Anbieter aktivieren.

Suchen Sie Ihren technischen Anbieter ValidateAccessCodeViaHttp, und fügen Sie das folgende Element zu der 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 eine falsche Eingabe für Ihren Zugriffscode verwenden. Es wird ein Fehler angezeigt, der dem in diesem Screenshot ähnelt.

Komplexe JSON-Nutzlastanforderung verarbeiten

Wenn die aufgerufene REST-API das Senden einer komplexen JSON-Nutzlast erfordert, können Sie die Nutzlast mithilfe von GenerateJson JSON-Anspruchstransformationen erstellen. Nachdem Sie die Nutzlast generiert haben, können Sie die Metadatenoption „ClaimUsedForRequestPayload“ für den Namen des Anspruchs verwenden, 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":"01234567-89ab-cdef-0123-456789abcdef",
      "firstName":"John",
      "lastName":"Smith",
      "accessCode":"88888",
      "role":{
         "name":"Administrator",
         "id": 1
      }
   }
}

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

    <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 von der REST-API

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

Verwenden Sie die Schritte unter Empfangen von Daten, um zu erfahren, wie Sie die von der benutzerdefinierten Richtlinie erwarteten Daten formatieren, wie Sie NULL-Werte behandeln und wie Sie den geschachtelten JSON-Textkörper der REST-API analysieren.

Nächste Schritte

Das behandeln Sie als Nächstes:

Teilen über