Wywoływanie interfejsu API REST przy użyciu zasad niestandardowych usługi Azure Active Directory B2C

Artykuł
01/11/2024

Niestandardowe zasady usługi Azure Active Directory B2C (Azure AD B2C) umożliwiają interakcję z logiką aplikacji implementaną poza usługą Azure AD B2C. W tym celu należy wykonać wywołanie HTTP do punktu końcowego. Niestandardowe zasady usługi Azure AD B2C zapewniają profil techniczny RESTful w tym celu. Korzystając z tej funkcji, można zaimplementować funkcje, które nie są dostępne w ramach niestandardowych zasad usługi Azure AD B2C.

W tym artykule omówiono sposób wykonywania następujących zadań:

Utwórz i wdróż przykładową aplikację Node.js do użycia jako usługę RESTful.
Wykonaj wywołanie HTTP do usługi Node.js RESTful przy użyciu profilu technicznego RESTful.
Obsługa lub zgłaszanie błędu zwracanego przez usługę RESTful do zasad niestandardowych.

Omówienie scenariusza

W obszarze Tworzenie rozgałęziania w podróży użytkownika przy użyciu zasad niestandardowych usługi Azure AD B2C użytkownicy, którzy wybierają pozycję Konto osobiste, muszą podać prawidłowy kod dostępu z zaproszeniem, aby kontynuować. Używamy kodu dostępu statycznego, ale aplikacje w świecie rzeczywistym nie działają w ten sposób. Jeśli usługa, która wystawia kody dostępu, jest zewnętrzna dla niestandardowych zasad, musisz wykonać wywołanie tej usługi i przekazać kod dostępu wejściowy przez użytkownika w celu weryfikacji. Jeśli kod dostępu jest prawidłowy, usługa zwraca odpowiedź HTTP 200 OK , a usługa Azure AD B2C wystawia token JWT. W przeciwnym razie usługa zwraca odpowiedź HTTP 409 Conflict , a użytkownik musi ponownie wyentować kod dostępu.

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

Wymagania wstępne

Jeśli jeszcze go nie masz, utwórz dzierżawę usługi Azure AD B2C połączoną z subskrypcją platformy Azure.
Zarejestruj aplikację internetową i włącz niejawne przyznanie tokenu identyfikatora. W przypadku identyfikatora URI przekierowania użyj polecenia https://jwt.ms.
Na komputerze musi być zainstalowany plik Node.js .
Na komputerze musi być zainstalowany program Visual Studio Code (VS Code ).
Wykonaj kroki opisane w artykule Weryfikowanie danych wejściowych użytkownika przy użyciu niestandardowych zasad usługi Azure AD B2C. Ten artykuł jest częścią serii Instrukcje tworzenia i uruchamiania własnych zasad niestandardowych.

Uwaga

Ten artykuł jest częścią serii Instrukcje tworzenia i uruchamiania własnych zasad niestandardowych w usłudze Azure Active Directory B2C. Zalecamy rozpoczęcie tej serii od pierwszego artykułu.

Krok 1. Tworzenie i wdrażanie aplikacji Node.js

Musisz wdrożyć aplikację, która służy jako aplikacja zewnętrzna. Następnie zasady niestandardowe wykonuje wywołanie HTTP do tej aplikacji.

Krok 1.1 . Tworzenie aplikacji Node.js

Utwórz folder do hostowania aplikacji węzła, na przykład access-code-app.
W terminalu zmień katalog na folder aplikacji Node, taki jak cd access-code-app, i uruchom polecenie npm init -y. To polecenie tworzy plik domyślny package.json dla projektu Node.js.
W terminalu uruchom polecenie npm install express body-parser. To polecenie instaluje platformę Express i pakiet body-parser .
W projekcie utwórz index.js plik.

W programie VS Code otwórz index.js plik, a następnie dodaj następujący 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);
    });

Możesz zauważyć, że gdy użytkownik prześle nieprawidłowy kod dostępu, możesz zwrócić błąd bezpośrednio z interfejsu API REST. Zasady niestandardowe umożliwiają zwrócenie komunikatu o błędzie HTTP 4xx, takiego jak 400 (nieprawidłowe żądanie) lub kod stanu odpowiedzi 409 (konflikt) z treścią odpowiedzi JSON sformatowaną w errorResponse zmiennej. Źródło kodu dostępu w aplikacji może być odczytywane z bazy danych. Dowiedz się więcej o zwracaniu komunikatu o błędzie weryfikacji.

Aby przetestować aplikację zgodnie z oczekiwaniami, wykonaj następujące kroki:

W terminalu node index.js uruchom polecenie , aby uruchomić serwer aplikacji.
Aby wysłać żądanie POST podobne do przedstawionego w tym przykładzie, możesz użyć klienta HTTP, takiego jak Microsoft PowerShell lub Postman:

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

    accessCode=user-code-code

Zastąp user-code-code element danymi wejściowymi kodu dostępu przez użytkownika, na przykład 54321. Jeśli używasz programu PowerShell, uruchom następujący skrypt.

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

Jeśli używasz nieprawidłowego kodu dostępu, odpowiedź wygląda podobnie do następującego fragmentu kodu JSON:

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

Na tym etapie możesz wdrożyć aplikację Node.js.

Krok 1.2 — Wdrażanie aplikacji Node.js w usłudze aplikacja systemu Azure

Aby zasady niestandardowe dotarły do aplikacji Node.js, muszą być dostępne, dlatego należy je wdrożyć. W tym artykule wdrożysz aplikację przy użyciu usługi aplikacja systemu Azure Service, ale używasz alternatywnego podejścia do hostingu.

Wykonaj kroki opisane w artykule Wdrażanie aplikacji na platformie Azure , aby wdrożyć aplikację Node.js na platformie Azure. W polu Nazwa aplikacji użyj nazwy opisowej, takiej jak custompolicyapi. Stąd:

Adres URL aplikacji wygląda podobnie do https://custompolicyapi.azurewebsites.net.
Punkt końcowy usługi wygląda podobnie do https://custompolicyapi.azurewebsites.net/validate-accesscode.

Możesz przetestować wdrożona aplikację przy użyciu klienta HTTP, takiego jak Microsoft PowerShell lub Postman. Tym razem użyj https://custompolicyapi.azurewebsites.net/validate-accesscode adresu URL jako punktu końcowego.

Krok 2. Wywoływanie interfejsu API REST

Teraz, gdy aplikacja jest uruchomiona, musisz wykonać wywołanie HTTP z zasad niestandardowych. Niestandardowe zasady usługi Azure AD B2C udostępniają profil techniczny RESTful używany do wywoływania usługi zewnętrznej.

Krok 2.1 — Definiowanie profilu technicznego RESTful

ContosoCustomPolicy.XML W pliku znajdź sekcję ClaimsProviders i zdefiniuj nowy profil techniczny RESTful przy użyciu następującego kodu:

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

Z poziomu protokołu można zaobserwować, że skonfigurujemy profil techniczny tak, aby używał restfulProvider. Możesz również obserwować następujące informacje w sekcji metadanych:

Obiekt ServiceUrl reprezentuje punkt końcowy interfejsu API. Jego wartość to https://custompolicyapi.azurewebsites.net/validate-accesscode. Jeśli aplikacja Node.js została wdrożona przy użyciu alternatywnej metody, pamiętaj o zaktualizowaniu wartości punktu końcowego.
SendClaimsIn określa sposób wysyłania oświadczeń wejściowych do dostawcy oświadczeń RESTful. Możliwe wartości: Body (default), , HeaderFormlub UrlQueryString. W przypadku użycia elementu Body, takiego jak w tym artykule, wywołasz czasownik HTTP POST i dane wysyłane do interfejsu API, jeśli są sformatowane jako klucz, pary wartości w treści żądania. Dowiedz się , jak wywołać czasownik HTTP GET i przekazać dane jako ciąg zapytania.
AuthenticationType Określa typ uwierzytelniania wykonywanego przez dostawcę oświadczeń RESTful. Nasz dostawca oświadczeń RESTful wywołuje niechroniony punkt końcowy, dlatego ustawiliśmy wartość AuthenticationTypeBrak. Jeśli ustawisz typ uwierzytelniania na Bearer, musisz dodać element CryptographicKeys , który określa magazyn tokenu dostępu. Dowiedz się więcej o typach uwierzytelniania obsługiwanego przez dostawcę oświadczeń RESTful.
Atrybut PartnerClaimType w pliku InputClaim określa sposób odbierania danych w interfejsie API.

Krok 2.2 — Aktualizowanie profilu technicznego weryfikacji

W obszarze Tworzenie rozgałęziania w podróży użytkownika przy użyciu zasad niestandardowych usługi Azure AD B2C zweryfikowano kod dostępu przy użyciu przekształcenia oświadczeń. W tym artykule zweryfikujesz kod accessCode , wykonując wywołanie HTTP do usługi zewnętrznej. Dlatego należy zaktualizować zasady niestandardowe, aby odzwierciedlały nowe podejście.

Znajdź profil techniczny AccessCodeInputCollector i zaktualizuj identyfikator ReferenceId elementu ValidationTechnicalProfile na ValidateAccessCodeViaHttp:

    <ValidationTechnicalProfile ReferenceId="CheckAccessCodeViaClaimsTransformationChecker"/>

na:

    <ValidationTechnicalProfile ReferenceId="ValidateAccessCodeViaHttp"/>

W tym momencie profil techniczny z IdcheckAccessCodeViaClaimsTransformationChecker nie jest potrzebny i można go usunąć.

Krok 3. Przekazywanie pliku zasad niestandardowych

Upewnij się, że aplikacja Node.js jest uruchomiona, a następnie wykonaj kroki opisane w temacie Przekazywanie pliku zasad niestandardowych, aby przekazać plik zasad. Jeśli przekazujesz plik o tej samej nazwie co plik już w portalu, upewnij się, że wybierzesz pozycję Zastąp zasady niestandardowe, jeśli już istnieje.

Krok 4. Testowanie zasad niestandardowych

Wykonaj kroki opisane w artykule Testowanie zasad niestandardowych, aby przetestować zasady niestandardowe:

W polu Typ konta wybierz pozycję Konto osobiste
Wprowadź pozostałe szczegóły zgodnie z potrzebami, a następnie wybierz pozycję Kontynuuj. Zostanie wyświetlony nowy ekran.
W polu Kod dostępu wprowadź wartość 88888, a następnie wybierz pozycję Kontynuuj. Po zakończeniu wykonywania zasad nastąpi przekierowanie do https://jwt.mselementu i zostanie wyświetlony zdekodowany token JWT. Jeśli powtórzysz procedurę i wprowadzisz inny kod dostępu, inny niż 88888, zostanie wyświetlony błąd. Wprowadzony kod dostępu jest niepoprawny. Spróbuj ponownie.

Krok 5. Włączanie trybu debugowania

Podczas programowania możesz zobaczyć szczegółowe błędy wysyłane przez interfejs API, takie jak developerMessage i więcej Informacji. W takim przypadku należy włączyć tryb debugowania u dostawcy technicznego RESTful.

Znajdź dostawcę technicznego ValidateAccessCodeViaHttp i dodaj następujący element w dostawcy metadatatechnicznym:
```
    <Item Key="DebugMode">true</Item>
```
Zapisz zmiany i przekaż plik zasad.
Przetestuj zasady niestandardowe. Upewnij się, że używasz nieprawidłowych danych wejściowych dla kodu dostępu. Zostanie wyświetlony błąd podobny do tego pokazanego na tym zrzucie ekranu:

Obsługa złożonych ładunków JSON żądań

Jeśli wywoływany interfejs API REST wymaga wysłania złożonego ładunku JSON, możesz utworzyć ładunek przy użyciu przekształceń oświadczeń JSON GenerateJson. Po wygenerowaniu ładunku możesz użyć ClaimUsedForRequestPayload opcji metadanych do nazwy oświadczenia zawierającego ładunek JSON.

Na przykład użyj następującego przekształcenia oświadczeń, aby wygenerować ładunek JSON:

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

Funkcja ClaimsTransformation generuje następujący obiekt JSON:

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

Następnie zaktualizuj metadane, InputClaimsTransformations i InputClaims dostawcy technicznego RESTful, jak pokazano poniżej:

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

Odbieranie danych z interfejsu API REST

Jeśli interfejs API REST zwraca dane, które mają zostać uwzględnione jako oświadczenia w zasadach, możesz je otrzymać, określając oświadczenia w OutputClaims elemecie profilu technicznego RESTful. Jeśli nazwa oświadczenia zdefiniowanego w zasadach różni się od nazwy zdefiniowanej w interfejsie API REST, musisz zamapować te nazwy przy użyciu atrybutu PartnerClaimType .

Wykonaj kroki opisane w temacie Odbieranie danych , aby dowiedzieć się, jak formatować dane oczekiwane przez zasady niestandardowe, jak obsługiwać wartości null oraz jak analizować zagnieżdżone treść JSON interfejsu API.

Następne kroki

Następnie dowiedz się:

Informacje o przekształceniach oświadczeń JSON.
Informacje o profilu technicznym RESTful.
Jak utworzyć i odczytać konto użytkownika przy użyciu niestandardowych zasad usługi Azure Active Directory B2C