Sdílet prostřednictvím


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

Důležité

Od 1. května 2025 už nebude Azure AD B2C k dispozici k nákupu pro nové zákazníky. Další informace najdete v našich nejčastějších dotazech.

Než začnete, pomocí selektoru Zvolit typ zásady v horní části této stránky 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.

Požadavky

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

  1. Přihlaste se do Azure Portalu.

  2. V části Služby Azure vyberte Azure AD B2C.

  3. Vyberte konektory rozhraní API a pak vyberte Nový konektor rozhraní API.

    Snímek obrazovky zobrazující stránku konektorů rozhraní API na webu Azure Portal se zvýrazněným tlačítkem Nový konektor rozhraní API

  4. Zadejte zobrazovaný název hovoru. Například token enrich z externího zdroje.

  5. Zadejte adresu URL koncového bodu pro volání rozhraní API.

  6. Zvolte typ ověřování a nakonfigurujte ověřovací informace pro volání rozhraní API. Zjistěte, jak zabezpečit konektor ROZHRANÍ API.

    Snímek obrazovky znázorňující ukázkovou konfiguraci ověřování pro konektor rozhraní API

  7. Vyberte Uložit.

Povolení konektoru rozhraní API v uživatelském toku

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

  1. Přihlaste se do Azure Portalu.

  2. V části Služby Azure vyberte Azure AD B2C.

  3. Vyberte Toky uživatelů a poté vyberte tok uživatele, do kterého chcete přidat konektor rozhraní API.

  4. 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:

    Snímek obrazovky s výběrem konektoru rozhraní API pro krok toku uživatele

  5. Vyberte 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ž má být token vydán 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": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
 "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 Azure AD B2C>atributech uživatelů. 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í. Vaše rozhraní API může použít k vrácení internacionalizovaný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ženo tak, aby explicitně kontrolovalo a zpracovávalo případ, kdy nárok 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í

Reakce na pokračování znamená, že průběh uživatelského procesu má pokračovat dalším krokem: vydání tokenu. V pokračující odpovědi může rozhraní API vrátit další nároky. Deklarace vrácena rozhraním API, kterou chcete vrátit v tokenu, musí být vestavěná deklarace nebo definována jako vlastní atribut a musí být vybrána v konfiguraci nároků aplikace uživatelského toku. Hodnota deklarace identity v tokenu bude ta, kterou vrátí rozhraní API, nikoli hodnota v adresáři. Některé hodnoty nároků nelze přepsat odpovědí rozhraní API. Nároky, které mohou být vráceny rozhraním API, odpovídají sadě nalezené v uživatelských atributů s výjimkou email.

Poznámka:

Rozhraní API je aktivováno pouze po úvodní autentizaci. 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 Typ Povinné Popis
verze Řetězec Ano Verze vašeho rozhraní API.
akce Řetězec Ano Hodnota musí být Continue.
<vestavěnáUživatelskáAtributa> <atribut-typ> Ne Je možné je vrátit v tokenu, pokud je vybraná jako deklarace identity aplikace.
<extension_{extensions-app-id}_CustomAttribute> <atribut-typ> Ne Nárok 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 obohacujeme uživatelská data tokenu integrací s podnikovým workflowem obchodních procesů. 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.

Požadavky

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.

Definice nároků

Nárok poskytuje dočasné úložiště dat během provádění zásad Azure AD B2C. Můžete uvést nároky v rámci oddílu schématu nároků.

  1. Otevřete soubor s rozšířeními zásad. Například: SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
  2. Vyhledejte prvek BuildingBlocks. Pokud prvek neexistuje, přidejte ho.
  3. Vyhledejte prvek ClaimsSchema. Pokud prvek neexistuje, přidejte ho.
  4. Do elementu ClaimsSchema přidejte následující claimy.
<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 souboru element TrustFrameworkExtensions.xml 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 bude userLanguage odesláno ke službě REST jako lang v datové části JSON. Hodnota userLanguage deklarace obsahuje aktuální ID jazyka uživatele. Další informace najdete v tématu řešitel nároků.

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:

  • Adresa URL služby. Nastavte adresu URL koncového bodu rozhraní REST API.
  • SendClaimsIn. Určete, jak se vstupní nároky odesílají zprostředkovateli nároků RESTful.
  • Typ ověřování. Nastavte typ ověřování, které provádí poskytovatel RESTful deklarací, jako je Basic 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.

  1. Otevřete základní soubor zásad. Například: SocialAndLocalAccounts/TrustFrameworkBase.xml.
  2. Vyhledejte <UserJourneys> prvek. Zkopírujte celý prvek a odstraňte ho.
  3. Otevřete soubor s rozšířeními zásad. Například: SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
  4. Vložte <UserJourneys> do souboru rozšíření, za uzavírací značku elementu <ClaimsProviders>.
  5. Vyhledejte ten <UserJourney Id="SignUpOrSignIn"> a přidejte následující krok orchestrace před poslední.
    <OrchestrationStep Order="7" Type="ClaimsExchange">
      <ClaimsExchanges>
        <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
      </ClaimsExchanges>
    </OrchestrationStep>
    
  6. Přepracovat poslední krok orchestrace 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" />
    
  7. Opakujte poslední dva kroky pro ProfileEdit a PasswordReset uživatelské cesty.

Zahrnutí deklarace identity do tokenu

Chcete-li vrátit balance deklaraci zpět do aplikace spoléhající strany, přidejte do souboru SocialAndLocalAccounts/SignUpOrSignIn.xml výstupní deklaraci. Přidání výstupního nároku vydá nárok do tokenu po úspěšném průchodu uživatele a odešle ho do aplikace. Upravte prvek technického profilu v oddílu spoléhající strany tak, aby se přidal balance jako výstupní nárok.

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

Opakujte tento krok pro uživatelské cesty ProfileEdit.xml a PasswordReset.xml. Uložte změněné soubory: TrustFrameworkBase.xmla TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xmla PasswordReset.xml.

Otestujte vlastní zásady

  1. Přihlaste se do Azure Portalu.
  2. 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 tenanta Microsoft Entra.
  3. V levém horním rohu webu Azure Portal zvolte Všechny služby a pak vyhledejte a vyberte Registrace aplikací.
  4. Vyberte Architekturu prostředí identit.
  5. Vyberte Nahrát vlastní zásady a potom nahrajte soubory zásad, které jste změnili: TrustFrameworkBase.xmla TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xmla PasswordReset.xml.
  6. Vyberte zásadu registrace nebo přihlášení, kterou jste nahráli, a klikněte na tlačítko Spustit.
  7. Měli byste se zaregistrovat pomocí e-mailové adresy nebo facebookového účtu.
  8. Token odeslaný zpět do vaší aplikace obsahuje nárok balance.
{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584961516,
  "nbf": 1584957916,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/",
  "aud": "11112222-bbbb-3333-cccc-4444dddd5555",
  "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 cloudu bez serverů může také integrovat 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 dodržuje smlouvy o požadavcích a odpovědích API, 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 atributů, na které závisí.
  • Vaše rozhraní API implementuje metodu ověřování popsanou v zabezpečeném konektoru rozhraní API.
  • Vaše API reaguje co nejrychleji, aby zajistilo plynulý uživatelský zážitek.
    • 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í

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 cloudu bez serverů může také integrovat webová rozhraní API, úložiště dat a další cloudové služby pro složité scénáře.

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í, jako jsou například úrovně trace nebo debug, při vývoji.
  • Sledujte rozhraní API pro dlouhé doby 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:

  1. Přejít do Azure AD B2C
  2. Pod Aktivity vyberte protokoly auditu.
  3. 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.
  4. Zkontrolujte jednotlivé protokoly. Každý řádek představuje konektor rozhraní API, který je volán během uživatelského toku. 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. Snímek obrazovky s ukázkovým protokolem auditu s transakcí konektoru rozhraní API

Další kroky