Obohacení tokenů o deklarace identity z externích zdrojů pomocí konektorů rozhraní API

Článek
11/08/2023

Než začnete, pomocí selektoru Zvolit typ zásady zvolte typ zásady, kterou nastavujete. Azure Active Directory B2C nabízí dvě metody pro definování způsobu interakce uživatelů s vašimi aplikacemi: prostřednictvím předdefinovaných toků uživatelů nebo prostřednictvím plně konfigurovatelných vlastních zásad. Kroky vyžadované v tomto článku se pro každou metodu liší.

Azure Active Directory B2C (Azure AD B2C) umožňuje vývojářům identit integrovat interakci s rozhraním RESTful API do toku uživatele pomocí konektorů rozhraní API. Umožňuje vývojářům dynamicky načítat data z externích zdrojů identit. Na konci tohoto názorného postupu budete moct vytvořit tok uživatele Azure AD B2C, který komunikuje s rozhraními API za účelem obohacení tokenů o informace z externích zdrojů.

Konektory rozhraní API použité v kroku Před odesláním tokenu (Preview) můžete použít k obohacení tokenů pro vaše aplikace informacemi z externích zdrojů. Když se uživatel přihlásí nebo zaregistruje, Azure AD B2C zavolá koncový bod rozhraní API nakonfigurovaný v konektoru rozhraní API, který může dotazovat informace o uživateli v podřízených službách, jako jsou cloudové služby, vlastní úložiště uživatelů, vlastní systémy oprávnění, starší systémy identit a další.

Poznámka:

Tato funkce je ve verzi Public Preview.

Pomocí jedné z našich ukázek můžete vytvořit koncový bod rozhraní API.

Předpoklady

Vytvořte tok uživatele, aby se uživatelé mohli zaregistrovat a přihlásit k vaší aplikaci.
Zaregistrujte webovou aplikaci.

Dokončete kroky v tématu Začínáme s vlastními zásadami ve službě Active Directory B2C.
Zaregistrujte webovou aplikaci.

Koncový bod rozhraní API. Pomocí jedné z našich ukázek můžete vytvořit koncový bod rozhraní API.

Vytvoření konektoru rozhraní API

Pokud chcete použít konektor rozhraní API, nejprve vytvoříte konektor rozhraní API a pak ho povolíte v toku uživatele.

Přihlaste se k portálu Azure.
V části Služby Azure vyberte Azure AD B2C.
Vyberte konektory rozhraní API a pak vyberte Nový konektor rozhraní API.
Zadejte zobrazovaný název hovoru. Například token enrich z externího zdroje.
Zadejte adresu URL koncového bodu pro volání rozhraní API.
Zvolte typ ověřování a nakonfigurujte ověřovací informace pro volání rozhraní API. Zjistěte, jak zabezpečit rozhraní API Připojení or.
Zvolte Uložit.

Povolení konektoru rozhraní API v toku uživatele

Pokud chcete přidat konektor rozhraní API do toku registrace uživatele, postupujte podle těchto kroků.

Přihlaste se k portálu Azure.
V části Služby Azure vyberte Azure AD B2C.
Vyberte Toky uživatele a pak vyberte tok uživatele, do kterého chcete přidat konektor rozhraní API.
Vyberte konektory rozhraní API a pak vyberte koncový bod rozhraní API, který chcete vyvolat v kroku Před odesláním tokenu (Preview) v toku uživatele:
Zvolte Uložit.

Tento krok existuje jenom pro toky registrace a přihlášení (doporučeno), registrace (doporučeno) a přihlášení (doporučeno).

Příklad požadavku odeslaného do rozhraní API v tomto kroku

Konektor rozhraní API v tomto kroku se vyvolá, když se token vydá během přihlašování a registrace. Konektor rozhraní API se materializuje jako požadavek HTTP POST a odesílá atributy uživatele ('claims') jako páry klíč-hodnota v těle JSON. Atributy jsou serializovány podobně jako vlastnosti uživatele Microsoft Graphu .

POST <API-endpoint>
Content-type: application/json
{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "objectId": "ab3ec3b2-a435-45e4-b93a-56a005e88bb7",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "client_id": "231c70e8-8424-48ac-9b5d-5623b9e4ccf3",
 "step": "PreTokenIssuance",
 "ui_locales":"en-US"
}

Deklarace identity odeslané do rozhraní API závisí na informacích definovaných pro uživatele. V požadavku se dají odesílat pouze vlastnosti uživatelů a vlastní atributy uvedené v uživatelském prostředí Azure AD B2C>. Vlastní atributy existují ve formátu extension_<extensions-app-id>_CustomAttribute v adresáři. Vaše rozhraní API by mělo očekávat příjem deklarací identity ve stejném serializovaném formátu. Další informace o vlastních atributech najdete v tématu Definování vlastních atributů v Azure AD B2C. Kromě toho se tyto deklarace identity obvykle posílají ve všech požadavcích pro tento krok:

Národní prostředí uživatelského rozhraní (ui_locales) – národní prostředí koncového uživatele nakonfigurované na svém zařízení. Toto rozhraní API může použít k vrácení internationalizovaných odpovědí.
Krok (krok) – krok nebo bod v toku uživatele, pro který byl konektor rozhraní API vyvolán. Hodnota pro tento krok je '
ID klienta (client_id) – appId hodnota aplikace, pro kterou se koncový uživatel ověřuje v toku uživatele. Toto není aplikace appId prostředků v přístupových tokenech.
objectId – identifikátor uživatele. Můžete ho použít k dotazování podřízených služeb na informace o uživateli.

Důležité

Pokud deklarace identity nemá v době volání koncového bodu rozhraní API hodnotu, deklarace identity se do rozhraní API neodesílají. Vaše rozhraní API by mělo být navržené tak, aby explicitně kontrolovat a zpracovávat případ, ve kterém deklarace identity není v požadavku.

Očekávané typy odpovědí z webového rozhraní API v tomto kroku

Když webové rozhraní API obdrží požadavek HTTP z ID Microsoft Entra během toku uživatele, může vrátit "odpověď na pokračování".

Odpověď na pokračování

Odpověď na pokračování znamená, že tok uživatele by měl pokračovat dalším krokem: vydání tokenu. V odpovědi na pokračování může rozhraní API vrátit další deklarace identity. Deklarace identity vrácená rozhraním API, které chcete v tokenu vrátit, musí být předdefinovaná deklarace identity nebo definovaná jako vlastní atribut a musí být vybrána v konfiguraci deklarací identity aplikace toku uživatele. Hodnota deklarace identity v tokenu bude vrácená rozhraním API, nikoli hodnotou v adresáři. Některé hodnoty deklarací identity nelze přepsat odpovědí rozhraní API. Deklarace identity, které mohou být vráceny rozhraním API, odpovídají sadě nalezené v atributech user s výjimkou .email

Poznámka:

Rozhraní API se vyvolá pouze během počátečního ověřování. Při použití obnovovacích tokenů k tichému získání nových přístupových tokenů nebo tokenů ID bude token obsahovat hodnoty vyhodnocené během počátečního ověřování.

Příklad odpovědi

Příklad odpovědi na pokračování

HTTP/1.1 200 OK
Content-type: application/json
{
    "version": "1.0.0",
    "action": "Continue",
    "postalCode": "12349", // return claim
    "extension_<extensions-app-id>_CustomAttribute": "value" // return claim
}

Parametr	Type	Požaduje se	Popis
version	Řetězec	Ano	Verze vašeho rozhraní API.
action	Řetězec	Ano	Hodnota musí být `Continue`.
<builtInUserAttribute>	<attribute-type>	No	Je možné je vrátit v tokenu, pokud je vybraná jako deklarace identity aplikace.
<extension_{extensions-app-id}_CustomAttribute>	<attribute-type>	No	Deklarace identity nemusí obsahovat `_<extensions-app-id>_`, je volitelná. Je možné je vrátit v tokenu, pokud je vybraná jako deklarace identity aplikace.

V tomto scénáři rozšiřujeme data tokenu uživatele integrací s podnikovým pracovním postupem obchodního postupu. Během registrace nebo přihlášení pomocí místního nebo federovaného účtu azure AD B2C vyvolá rozhraní REST API, které získá rozšířená data profilu uživatele ze vzdáleného zdroje dat. V této ukázce Azure AD B2C odešle jedinečný identifikátor uživatele – objectId. Rozhraní REST API pak vrátí zůstatek účtu uživatele (náhodné číslo). Tuto ukázku použijte jako výchozí bod pro integraci s vlastním systémem CRM, marketingovou databází nebo jakýmkoli obchodním pracovním postupem. Interakci můžete také navrhnout jako technický profil ověření. To je vhodné, když rozhraní REST API bude ověřovat data na obrazovce a vracet deklarace identity. Další informace najdete v tématu Návod: Přidání konektoru rozhraní API do toku uživatele registrace.

Předpoklady

Dokončete kroky v části Začínáme s vlastními zásadami. Měli byste mít funkční vlastní zásady pro registraci a přihlášení pomocí místních účtů.
Zjistěte, jak integrovat výměny deklarací identity rest API ve vlastních zásadách Azure AD B2C.

Příprava koncového bodu rozhraní REST API

Pro účely tohoto názorného postupu byste měli mít rozhraní REST API, které ověřuje, jestli je v back-endovém systému zaregistrované ID objektu Azure AD B2C uživatele. Pokud je rozhraní REST API zaregistrované, vrátí zůstatek uživatelského účtu. V opačném případě rozhraní REST API zaregistruje nový účet v adresáři a vrátí počáteční zůstatek 50.00. Následující kód JSON znázorňuje data, která Azure AD B2C odešle do koncového bodu rozhraní REST API.

{
    "objectId": "User objectId",
    "lang": "Current UI language"
}

Jakmile rozhraní REST API ověří data, musí vrátit http 200 (OK) s následujícími daty JSON:

{
    "balance": "760.50"
}

Nastavení koncového bodu rozhraní REST API je mimo rozsah tohoto článku. Vytvořili jsme ukázku Azure Functions . Úplný kód funkce Azure můžete získat na GitHubu.

Definování deklarací identity

Deklarace identity poskytuje dočasné úložiště dat během provádění zásad Azure AD B2C. Deklarace identity můžete deklarovat v rámci oddílu schématu deklarací identity.

Otevřete soubor s příponami zásad. Například, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
Vyhledejte element BuildingBlocks . Pokud prvek neexistuje, přidejte ho.
Vyhledejte element ClaimsSchema . Pokud prvek neexistuje, přidejte ho.
Do elementu ClaimsSchema přidejte následující deklarace identity.

<ClaimType Id="balance">
  <DisplayName>Your Balance</DisplayName>
  <DataType>string</DataType>
</ClaimType>
<ClaimType Id="userLanguage">
  <DisplayName>User UI language (used by REST API to return localized error messages)</DisplayName>
  <DataType>string</DataType>
</ClaimType>

Přidání technického profilu rozhraní RESTful API

Technický profil Restful poskytuje podporu pro propojení s vaší vlastní službou RESTful. Azure AD B2C odesílá data do služby RESTful v InputClaims kolekci a přijímá data zpět v OutputClaims kolekci. Vyhledejte v TrustFrameworkExtensions.xml souboru element ClaimsProviders a přidejte nového zprostředkovatele deklarací následujícím způsobem:

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-GetProfile">
      <DisplayName>Get user extended profile Azure Function web hook</DisplayName>
      <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <Metadata>
        <!-- Set the ServiceUrl with your own REST API endpoint -->
        <Item Key="ServiceUrl">https://your-account.azurewebsites.net/api/GetProfile?code=your-code</Item>
        <Item Key="SendClaimsIn">Body</Item>
        <!-- Set AuthenticationType to Basic or ClientCertificate in production environments -->
        <Item Key="AuthenticationType">None</Item>
        <!-- REMOVE the following line in production environments -->
        <Item Key="AllowInsecureAuthInProduction">true</Item>
      </Metadata>
      <InputClaims>
        <!-- Claims sent to your REST API -->
        <InputClaim ClaimTypeReferenceId="objectId" />
        <InputClaim ClaimTypeReferenceId="userLanguage" PartnerClaimType="lang" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
      </InputClaims>
      <OutputClaims>
        <!-- Claims parsed from your REST API -->
        <OutputClaim ClaimTypeReferenceId="balance" />
      </OutputClaims>
      <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

V tomto příkladu userLanguage se služba REST odešle jako lang v datové části JSON. Hodnota userLanguage deklarace identity obsahuje aktuální ID jazyka uživatele. Další informace najdete v tématu Překladač deklarací identity.

Konfigurace technického profilu rozhraní RESTful API

Po nasazení rozhraní REST API nastavte metadata technického REST-GetProfile profilu tak, aby odrážela vaše vlastní rozhraní REST API, včetně následujících:

ServiceUrl. Nastavte adresu URL koncového bodu rozhraní REST API.
SendClaimsIn. Určete, jak se vstupní deklarace identity odesílají zprostředkovateli deklarací RESTful.
AuthenticationType. Nastavení typu ověřování prováděného poskytovatelem deklarací IDENTITY RESTful, jako Basic je nebo ClientCertificate
AllowInsecureAuthInProduction. V produkčním prostředí nezapomeňte tato metadata nastavit na false.

Další konfigurace najdete v metadatech technického profilu RESTful. Výše uvedené AuthenticationType komentáře a AllowInsecureAuthInProduction určují změny, které byste měli provést při přechodu do produkčního prostředí. Informace o zabezpečení rozhraní RESTful API pro produkční prostředí najdete v tématu Zabezpečení rozhraní RESTful API.

Přidání kroku orchestrace

Cesty uživatelů určují explicitní cesty, prostřednictvím kterých zásady umožňují aplikaci přijímající strany získat pro uživatele požadované deklarace identity. Cesta uživatele je reprezentována jako sekvence orchestrace, která musí být sledována pro úspěšnou transakci. Kroky orchestrace můžete přičíst nebo odečíst. V tomto případě přidáte nový krok orchestrace, který se použije k rozšíření informací poskytovaných aplikaci po registraci nebo přihlášení uživatele prostřednictvím volání rozhraní REST API.

Otevřete základní soubor zásad. Například, SocialAndLocalAccounts/TrustFrameworkBase.xml.
Vyhledejte <UserJourneys> prvek. Zkopírujte celý prvek a odstraňte ho.
Otevřete soubor s příponami zásad. Například, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
Vložte soubor <UserJourneys> přípony za zavření elementu <ClaimsProviders> .

Vyhledejte a <UserJourney Id="SignUpOrSignIn">přidejte následující krok orchestrace před poslední.

<OrchestrationStep Order="7" Type="ClaimsExchange">
  <ClaimsExchanges>
    <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
  </ClaimsExchanges>
</OrchestrationStep>

Refaktoring poslední orchestrace krok změnou Order na 8. Poslední dva kroky orchestrace by měly vypadat takto:

<OrchestrationStep Order="7" Type="ClaimsExchange">
  <ClaimsExchanges>
    <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
  </ClaimsExchanges>
</OrchestrationStep>
<OrchestrationStep Order="8" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="JwtIssuer" />

Opakujte poslední dva kroky pro cesty uživatele ProfileEdit a PasswordReset .

Zahrnutí deklarace identity do tokenu

Pokud chcete vrátit balance deklaraci identity zpět do aplikace předávající strany, přidejte do SocialAndLocalAccounts/SignUpOrSignIn.xml souboru výstupní deklaraci identity. Přidání výstupní deklarace identity vydá deklaraci identity do tokenu po úspěšné cestě uživatele a odešle se do aplikace. Upravte prvek technického profilu v oddílu předávající strany tak, aby se přidal balance jako výstupní deklarace identity.

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
      <OutputClaim ClaimTypeReferenceId="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
      <OutputClaim ClaimTypeReferenceId="balance" DefaultValue="" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

Tento krok opakujte pro cesty uživatele ProfileEdit.xml a PasswordReset.xml . Uložte změněné soubory: TrustFrameworkBase.xml a TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xml a PasswordReset.xml.

Testování vlastních zásad

Přihlaste se k portálu Azure.
Pokud máte přístup k více tenantům, v horní nabídce vyberte ikonu Nastavení a v nabídce Adresáře a předplatná přepněte do svého tenanta Azure AD B2C.
V levém horním rohu webu Azure Portal zvolte Všechny služby a pak vyhledejte a vyberte Registrace aplikací.
Vyberte Architekturu prostředí identit.
Vyberte Nahrát vlastní zásady a pak nahrajte soubory zásad, které jste změnili: TrustFrameworkBase.xml a TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xml a PasswordReset.xml.
Vyberte zásadu registrace nebo přihlášení, kterou jste nahráli, a klikněte na tlačítko Spustit.
Měli byste se zaregistrovat pomocí e-mailové adresy nebo facebookového účtu.
Token odeslaný zpět do vaší aplikace obsahuje balance deklaraci identity.

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584961516,
  "nbf": 1584957916,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/f06c2fe8-709f-4030-85dc-38a4bfd9e82d/v2.0/",
  "aud": "e1d2612f-c2bc-4599-8e7b-d874eaca1ee1",
  "acr": "b2c_1a_signup_signin",
  "nonce": "defaultNonce",
  "iat": 1584957916,
  "auth_time": 1584957916,
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "given_name": "Emily",
  "family_name": "Smith",
  "balance": "202.75"
  ...
}

Osvědčené postupy a postupy při řešení potíží

Použití bezserverových cloudových funkcí

Bezserverové funkce, jako jsou triggery HTTP ve službě Azure Functions, poskytují způsob, jak vytvářet koncové body rozhraní API pro použití s konektorem rozhraní API. Funkce bezserverového cloudu může také volat a volat další webová rozhraní API, úložiště dat a další cloudové služby pro složité scénáře.

Osvědčené postupy

Zajistěte následující:

Vaše rozhraní API sleduje kontrakty požadavků rozhraní API a odpovědí, jak je uvedeno výše.
Adresa URL koncového bodu konektoru rozhraní API odkazuje na správný koncový bod rozhraní API.
Vaše rozhraní API explicitně kontroluje hodnoty null přijatých deklarací identity, na které závisí.
Vaše rozhraní API implementuje metodu ověřování popsanou v zabezpečeném konektoru rozhraní API.
Vaše rozhraní API reaguje co nejrychleji, aby se zajistilo prostředí pro uživatele s proměnlivým prostředím.
- Azure AD B2C bude čekat na přijetí odpovědi maximálně 20 sekund . Pokud se žádná nepřijala, při volání rozhraní API se zobrazí ještě jeden pokus (zkuste to znovu).
- Pokud používáte funkci bez serveru nebo škálovatelnou webovou službu, použijte plán hostování, který udržuje rozhraní API vzhůru nebo "teplé" v produkčním prostředí. Pro Azure Functions se doporučuje použít minimálně plán Premium v produkčním prostředí.
Zajistěte vysokou dostupnost vašeho rozhraní API.
Monitorujte a optimalizujte výkon podřízených rozhraní API, databází nebo jiných závislostí vašeho rozhraní API.

Důležité

Vaše koncové body musí splňovat požadavky na zabezpečení Azure AD B2C. Starší verze protokolu TLS a šifry jsou zastaralé. Další informace najdete v tématu Požadavky na protokol TLS a šifrovací sadu Azure AD B2C.

Použití protokolování

Použití bezserverových cloudových funkcí

Použití protokolování

Obecně je užitečné použít nástroje protokolování povolené službou webového rozhraní API, jako je Application Insights, k monitorování neočekávaných kódů chyb, výjimek a nízkého výkonu.

Monitorujte stavové kódy HTTP, které nejsou HTTP 200 nebo 400.
Stavový kód HTTP 401 nebo 403 obvykle značí problém s ověřováním. Pečlivě zkontrolujte ověřovací vrstvu vašeho rozhraní API a odpovídající konfiguraci v konektoru rozhraní API.
V případě potřeby používejte agresivnější úrovně protokolování (například "trace" nebo "debug").
Monitorujte rozhraní API po dlouhou dobu odezvy. Kromě toho Azure AD B2C protokoluje metadata o transakcích rozhraní API, ke kterým dochází během ověřování uživatelů prostřednictvím toku uživatele. Pokud chcete tyto informace najít:

Přejít do Azure AD B2C
V části Aktivity vyberte Protokoly auditu.
Vyfiltrujte zobrazení seznamu: Jako datum vyberte požadovaný časový interval a jako aktivitu vyberte rozhraní API, které se volalo jako součást toku uživatele.
Zkontrolujte jednotlivé protokoly. Každý řádek představuje konektor rozhraní API, který se pokouší volat během toku uživatele. Pokud volání rozhraní API selže a dojde k opakování, bude stále reprezentován jako jeden řádek. Udává numberOfAttempts počet volání rozhraní API. Tato hodnota může být 1nebo 2. Další informace o volání rozhraní API jsou podrobně popsané v protokolech.

Další kroky

Začněte s našimi ukázkami.
Zabezpečení Připojení oru rozhraní API

Informace o zabezpečení rozhraní API najdete v následujících článcích:

Share via

Obohacení tokenů o deklarace identity z externích zdrojů pomocí konektorů rozhraní API

Předpoklady

Vytvoření konektoru rozhraní API

Povolení konektoru rozhraní API v toku uživatele

Příklad požadavku odeslaného do rozhraní API v tomto kroku

Očekávané typy odpovědí z webového rozhraní API v tomto kroku

Odpověď na pokračování

Příklad odpovědi

Příklad odpovědi na pokračování

Předpoklady

Příprava koncového bodu rozhraní REST API

Definování deklarací identity

Přidání technického profilu rozhraní RESTful API

Konfigurace technického profilu rozhraní RESTful API

Přidání kroku orchestrace

Zahrnutí deklarace identity do tokenu

Testování vlastních zásad

Osvědčené postupy a postupy při řešení potíží

Použití bezserverových cloudových funkcí

Osvědčené postupy

Použití protokolování

Použití bezserverových cloudových funkcí

Použití protokolování

Další kroky

Další materiály