Sdílet prostřednictvím

Volání rozhraní REST API pomocí vlastních zásad Azure Active Directory B2C

  • Článek

Vlastní zásady Azure Active Directory B2C (Azure AD B2C) umožňují pracovat s logikou aplikace, kterou implementujete mimo Azure AD B2C. Provedete to tak, že provedete volání HTTP do koncového bodu. Vlastní zásady Azure AD B2C poskytují pro tento účel technický profil RESTful. Pomocí této funkce můžete implementovat funkce, které nejsou dostupné ve vlastních zásadách Azure AD B2C.

V tomto článku získáte informace o těchto tématech:

  • Vytvořte a nasaďte ukázkovou aplikaci Node.js pro použití jako službu RESTful.

  • Proveďte volání HTTP do služby Node.js RESTful pomocí technického profilu RESTful.

  • Zpracování nebo nahlášení chyby, kterou služba RESTful vrací do vlastních zásad.

Přehled scénáře

V části Vytvoření větvení na cestě uživatele pomocí vlastních zásad Azure AD B2C musí uživatelé, kteří vyberou osobní účet , poskytnout platný přístupový kód pozvánky, aby mohli pokračovat. Používáme statický přístupový kód, ale reálné aplikace tímto způsobem nefungují. Pokud služba, která vydává přístupové kódy, je pro vaši vlastní zásadu externí, musíte provést volání této služby a předat vstup přístupového kódu pro ověření uživatelem. Pokud je přístupový kód platný, služba vrátí odpověď HTTP 200 OK a Azure AD B2C vydá token JWT. Jinak služba vrátí odpověď HTTP 409 Conflict a uživatel musí znovu zadat přístupový kód.

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

Požadavky

Poznámka:

Tento článek je součástí řady s návody k vytvoření a spuštění vlastních zásad v Azure Active Directory B2C. Doporučujeme spustit tuto řadu z prvního článku.

Krok 1 : Vytvoření a nasazení aplikace Node.js

Potřebujete nasadit aplikaci, která slouží jako vaše externí aplikace. Vaše vlastní zásada pak provede volání HTTP této aplikace.

Krok 1.1 – Vytvoření aplikace Node.js

  1. Vytvořte složku pro hostování aplikace uzlu, například access-code-app.

  2. V terminálu změňte adresář do složky aplikace Node, například cd access-code-appa spusťte npm init -y. Tento příkaz vytvoří výchozí package.json soubor pro váš projekt Node.js.

  3. V terminálu spusťte npm install express body-parser. Tento příkaz nainstaluje architekturu Express a balíček body-parser .

  4. V projektu vytvořte index.js soubor.

  5. Ve VS Code otevřete index.js soubor a přidejte následující kód:

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

    Můžete si všimnout, že když uživatel odešle nesprávný přístupový kód, můžete vrátit chybu přímo z rozhraní REST API. Vlastní zásady umožňují vrátit chybovou zprávu HTTP 4xx, například 400 (chybný požadavek) nebo stavový kód odpovědi 409 (konfliktní) s textem JSON odpovědi formátovaným v errorResponse proměnné. Zdroj přístupového kódu v aplikaci by mohl být načten z databáze. Přečtěte si další informace o vrácení chybové zprávy ověření.

  6. Pokud chcete otestovat, že aplikace funguje podle očekávání, postupujte následovně:

    1. V terminálu spusťte node index.js příkaz pro spuštění aplikačního serveru.
    2. Pokud chcete vytvořit požadavek POST podobný požadavku uvedenému v tomto příkladu, můžete použít klienta HTTP, jako je Microsoft PowerShell nebo Postman:
        POST http://localhost/validate-accesscode HTTP/1.1
    Host: localhost
    Content-Type: application/x-www-form-urlencoded

    accessCode=user-code-code

    Nahraďte user-code-code vstupem přístupového kódu uživatelem, například 54321. Pokud používáte PowerShell, spusťte následující skript.

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

    Pokud použijete nesprávný přístupový kód, odpověď vypadá podobně jako následující fragment kódu 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"
    }

V tuto chvíli jste připraveni nasadit aplikaci Node.js.

Krok 1.2 – Nasazení aplikace Node.js ve službě Aplikace Azure Service

Aby se vaše vlastní zásady dostaly k aplikaci Node.js, musí být dostupné, takže je potřeba ji nasadit. V tomto článku nasadíte aplikaci pomocí služby Aplikace Azure Service, ale použijete alternativní přístup k hostování.

Postupujte podle kroků v části Nasazení aplikace do Azure a nasaďte aplikaci Node.js do Azure. Jako název aplikace použijte popisný název, například custompolicyapi. Proto:

  • Adresa URL aplikace vypadá podobně jako https://custompolicyapi.azurewebsites.net.

  • Koncový bod služby vypadá podobně jako https://custompolicyapi.azurewebsites.net/validate-accesscode.

Aplikaci, kterou jste nasadili, můžete otestovat pomocí klienta HTTP, jako je Microsoft PowerShell nebo Postman. Tentokrát jako koncový bod použijte https://custompolicyapi.azurewebsites.net/validate-accesscode adresu URL.

Krok 2 – volání rozhraní REST API

Teď, když je vaše aplikace spuštěná, musíte provést volání HTTP z vlastních zásad. Vlastní zásady Azure AD B2C poskytují technický profil RESTful, který používáte k volání externí služby.

Krok 2.1 – Definování technického profilu RESTful

V souboru vyhledejte ContosoCustomPolicy.XML ClaimsProviders oddíl a definujte nový technický profil RESTful pomocí následujícího kódu:

    <!--<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 protokolu můžete pozorovat, že technický profil nakonfigurujeme tak, aby používal RestfulProvider. Můžete také sledovat následující informace v části metadat:

  • Představuje ServiceUrl koncový bod rozhraní API. Její hodnota je https://custompolicyapi.azurewebsites.net/validate-accesscode. Pokud jste aplikaci Node.js nasadili pomocí alternativní metody, nezapomeňte aktualizovat hodnotu koncového bodu.

  • SendClaimsIn určuje, jak se vstupní deklarace identity odesílají zprostředkovateli deklarací RESTful. Možné hodnoty: Body (default), Form, HeaderUrl nebo QueryString. Při použití Body, například v tomto článku, vyvoláte příkaz POST HTTP a data, která odešlete do rozhraní API, pokud jsou formátována jako klíč, páry hodnot v textu požadavku. Zjistěte , jak vyvolat příkaz GET HTTP a předat data jako řetězec dotazu.

  • AuthenticationType určuje typ ověřování, které provádí zprostředkovatel deklarací RESTful. Náš poskytovatel deklarací identity RESTful volá nechráněný koncový bod, takže jsme nastavili hodnotu AuthenticationType Žádné. Pokud nastavíte typ ověřování na Bearer, musíte přidat element CryptographicKeys , který určuje úložiště pro váš přístupový token. Přečtěte si další informace o typech ověřování, které podporuje zprostředkovatel deklarací identity RESTful.

  • Atribut PartnerClaimType v InputClaim sadě Určuje, jak přijímáte data v rozhraní API.

Krok 2.2 – aktualizace technického profilu ověření

Při vytváření větví na cestě uživatele pomocí vlastních zásad Azure AD B2C jste ověřili přístupový kód pomocí transformace deklarací identity. V tomto článku ověříte přístupový kód provedením volání HTTP do externí služby. Proto budete muset aktualizovat vlastní zásady tak, aby odrážely nový přístup.

Vyhledejte technický profil AccessCodeInputCollector a aktualizujte ReferenceId elementu ValidationTechnicalProfile na ValidateAccessCodeViaHttp:

Z:

    <ValidationTechnicalProfile ReferenceId="CheckAccessCodeViaClaimsTransformationChecker"/>

na:

    <ValidationTechnicalProfile ReferenceId="ValidateAccessCodeViaHttp"/>

V tuto chvíli není potřeba technický profil CheckAccessCodeViaClaimsTransformationChecker Id a dá se odebrat.

Krok 3 : Nahrání souboru vlastních zásad

Ujistěte se, že je vaše aplikace Node.js spuštěná, a pak postupujte podle kroků v nahrání souboru vlastních zásad a nahrajte soubor zásad. Pokud nahráváte soubor se stejným názvem jako soubor, který už je na portálu, nezapomeňte vybrat Možnost Přepsat vlastní zásadu, pokud už existuje.

Krok 4 – Testování vlastních zásad

Postupujte podle kroků v části Otestování vlastních zásad a otestujte vlastní zásady :

  1. Jako typ účtu vyberte Osobní účet.
  2. Podle potřeby zadejte zbývající podrobnosti a pak vyberte Pokračovat. Zobrazí se nová obrazovka.
  3. Jako přístupový kód zadejte 88888 a pak vyberte Pokračovat. Po dokončení provádění zásady budete přesměrováni na https://jwt.msa zobrazí se dekódovaný token JWT. Pokud tento postup zopakujete a zadáte jiný přístupový kód, kromě 88888, zobrazí se chyba Přístupový kód, který jste zadali, není správný. Opakujte akci.

Krok 5 – povolení režimu ladění

Při vývoji můžete chtít zobrazit podrobné chyby odeslané rozhraním API, jako je developerMessage a moreInfo. V takovém případě musíte ve svém technickém poskytovateli RESTful povolit režim ladění.

  1. Vyhledejte svého technického poskytovatele ValidateAccessCodeViaHttp a do technického metadataposkytovatele přidejte následující položku:

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

  2. Uložte změny a nahrajte soubor zásad.

  3. Otestujte vlastní zásady. Ujistěte se, že pro přístupový kód používáte nesprávný vstup. Zobrazí se chyba podobná té, která se zobrazuje na tomto snímku obrazovky:

    A screenshot error when you enable debug mode.

Zpracování složitých datových částí JSON požadavků

Pokud rozhraní REST API, které voláte, vyžaduje, abyste odeslali složitou datovou část JSON, můžete datovou část vytvořit pomocí transformací deklarací identity GenerateJson JSON. Jakmile datovou část vygenerujete, můžete použít ClaimUsedForRequestPayload možnost metadat k názvu deklarace identity obsahující datovou část JSON.

K vygenerování datové části JSON použijte například následující transformaci deklarací identity:

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

Deklarace IdentityTransformation vygeneruje následující objekt JSON:

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

Potom aktualizujte metadata, InputClaimsTransformations a InputClaims vašeho technického poskytovatele RESTful, jak je znázorněno níže:

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

Příjem dat z rozhraní REST API

Pokud vaše rozhraní REST API vrací data, která chcete zahrnout jako deklarace identity do zásad, můžete je získat zadáním deklarací identity v OutputClaims prvku technického profilu RESTful. Pokud se název deklarace identity definované ve vaší zásadě liší od názvu definovaného v rozhraní REST API, musíte tyto názvy namapovat pomocí atributu PartnerClaimType .

Pomocí kroků v části Příjem dat se dozvíte, jak formátovat data, která vlastní zásada očekává, jak zpracovat hodnoty null a jak parsovat vnořený text JSON rozhraní REST v rozhraní API.

Další kroky

Dále se dozvíte: