Použijte konektory API k přizpůsobení a rozšíření uživatelských toků při registraci a vlastních politik pomocí externích zdrojů identity.

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ší.

Přehled

Jako vývojář nebo správce IT můžete pomocí konektorů rozhraní API integrovat toky uživatelů registrace s rozhraními REST API, abyste přizpůsobili prostředí registrace a integrovali se s externími systémy. S konektory rozhraní API můžete například:

• Ověřte vstupní data uživatele. Ověřte, jestli nejsou poškozená nebo neplatná uživatelská data. Můžete například ověřit uživatelsky poskytnutá data proti existujícím datům v externím úložišti dat nebo v seznamu povolených hodnot. Pokud je neplatný, můžete požádat uživatele, aby zadal platná data nebo ho zablokoval v pokračování v toku registrace.
• Ověřte identitu uživatele. Pomocí služby ověřování identity nebo externích zdrojů dat identity můžete k rozhodování o vytváření účtů přidat další úroveň zabezpečení.
• Integrace do vlastního pracovního postupu schvalování Připojte se k vlastnímu schvalovacímu systému pro správu a omezení vytváření účtů.
• Rozšiřte tokeny pomocí atributů z externích zdrojů. Obohacení tokenů o atributy uživatele ze zdrojů, které jsou externí pro Azure AD B2C, jako jsou cloudové systémy, vlastní úložiště uživatelů, vlastní systémy oprávnění, starší verze služeb identit a další.
• Přepsat atributy uživatele. Přeformátujte nebo přiřaďte hodnotu atributu shromážděnému od uživatele. Pokud například uživatel zadá křestní jméno malými nebo velkými písmeny, můžete ho naformátovat jenom velkým písmenem.
• Spuštění vlastní obchodní logiky V cloudových systémech můžete aktivovat podřízené události, které odesílají nabízená oznámení, aktualizují podnikové databáze, spravují oprávnění, auditují databáze a provádějí další vlastní akce.

Konektor API poskytuje Azure AD B2C s informacemi potřebnými k volání koncového bodu rozhraní API definováním adresy URL koncového bodu HTTP a ověřováním pro volání rozhraní API. Jakmile nakonfigurujete konektor rozhraní API, můžete ho povolit pro konkrétní krok v toku uživatele. Když uživatel dosáhne tohoto kroku v procesu registrace, konektor API se aktivuje a projeví se jako HTTP POST požadavek na vaše API, přičemž odešle uživatelské údaje ("nároky") jako páry klíč-hodnota v těle JSON. Odpověď rozhraní API může ovlivnit průběh toku uživatele. Odpověď rozhraní API může například blokovat registraci uživatele, požádat uživatele, aby se znovu přihlásil k informacím nebo přepsal atributy uživatele.

Kde můžete povolit konektor rozhraní API v toku uživatele

V toku uživatele existují tři místa, kde můžete povolit konektor rozhraní API:

• Po federaci s zprostředkovatelem identity během registrace – platí jenom pro prostředí registrace.
• Před vytvořením uživatele – platí pouze pro prostředí registrace.
• Před odesláním tokenu (Preview) – platí pro registrace a přihlášení.

Po propojení se zprostředkovatelem identity během registrace

Konektor rozhraní API v tomto kroku v procesu registrace se vyvolá okamžitě po ověření uživatele u zprostředkovatele identity (jako je Google, Facebook a Microsoft Entra ID). Tento krok předchází stránce pro sběr atributů, což je formulář, který se uživateli zobrazuje pro sběr uživatelských atributů. Tento krok se nevyvolá, pokud se uživatel registruje pomocí místního účtu. Tady jsou příklady scénářů konektorů rozhraní API, které můžete v tomto kroku povolit:

• Použijte e-mailovou nebo federovanou identitu, kterou uživatel zadal, k vyhledání nároků v existujícím systému. Vraťte tyto nároky z existujícího systému, předvyplňte stránku pro sběr atributů, aby byly k dispozici pro návrat v tokenu.
• Implementujte seznam povolených nebo blokovaných na základě sociální identity.

Před vytvořením uživatele

Konektor rozhraní API v tomto kroku přihlašovacího procesu se vyvolá po sběru atributů, pokud je to součástí tohoto procesu. Tento krok se vždy vyvolá před vytvořením uživatelského účtu. Tady jsou příklady scénářů, které můžete v tomto okamžiku povolit při registraci:

• Ověřte vstupní data uživatele a požádejte uživatele o opětovné odeslání dat.
• Zablokujte registraci uživatele na základě dat zadaných uživatelem.
• Ověřte identitu uživatele.
• Dotazování externích systémů na stávající údaje o uživateli s cílem zahrnout je do tokenu aplikace nebo je uložit do Microsoft Entra ID.

Před odesláním tokenu (Preview)

Poznámka:

Tato funkce je ve verzi Public Preview.

Konektor rozhraní API v tomto kroku v procesu registrace nebo přihlášení se vyvolá před vydáním tokenu. Tady jsou příklady scénářů, které můžete v tomto kroku povolit:

• Obohacení tokenu o atributy uživatele z různých zdrojů, než je adresář, včetně starších systémů identit, personálních systémů, externích úložišť uživatelů a dalších.
• Obohacení tokenu o atributy skupiny nebo role, které ukládáte a spravujete ve vlastním systému oprávnění.
• Použití transformací deklarací identity nebo manipulace s hodnotami deklarací identity v adresáři

Architektura prostředí identit, která je základem Azure Active Directory B2C (Azure AD B2C), se může integrovat s rozhraními RESTful API v rámci cesty uživatele. Tento článek ukazuje, jak vytvořit cestu uživatele, která komunikuje se službou RESTful pomocí technického profilu RESTful.

Pomocí Azure AD B2C můžete do cesty uživatele přidat vlastní obchodní logiku voláním vlastní služby RESTful. Architektura prostředí identit může odesílat a přijímat data z vaší služby RESTful za účelem výměny deklarací identity. Můžete například:

• K ověření uživatelských vstupních dat použijte zdroj dat externí identity. Můžete například ověřit, že e-mailová adresa poskytnutá uživatelem existuje v databázi zákazníka a pokud ne, zobrazí se chyba. Konektory rozhraní API si můžete představit jako způsob podpory odchozích webhooků, protože volání probíhá, když dojde k události, například registraci.
• Zpracování deklarací identity Pokud uživatel zadá křestní jméno malými nebo velkými písmeny, rozhraní REST API může název naformátovat jenom s velkými písmeny a vrátit ho do Azure AD B2C. Při použití vlastní zásady se však deklarace IdentityTransformations upřednostňuje před voláním rozhraní RESTful API.
• Dynamické rozšiřování uživatelských dat prostřednictvím další integrace s podnikovými obchodními aplikacemi. Vaše služba RESTful může obdržet e-mailovou adresu uživatele, dotazovat se na databázi zákazníka a vrátit číslo věrnosti uživatele do Azure AD B2C. Poté mohou být nároky vráceny a uloženy v uživatelském účtu Microsoft Entra, vyhodnoceny v následujících krocích orchestrace, nebo zahrnuty do přístupového tokenu.
• Spuštění vlastní obchodní logiky Můžete odesílat nabízená oznámení, aktualizovat podnikové databáze, spouštět proces migrace uživatelů, spravovat oprávnění, auditovat databáze a provádět další pracovní postupy.

Poznámka:

Požadavky HTTP se můžou zrušit, pokud dojde k pomalé nebo žádné odpovědi ze služby RESTful do Azure AD B2C. Výchozí časový limit je 10 sekund pro vlastní zásady a 5 sekund pro toky uživatelů. Výchozí počet opakování je jeden (což znamená, že celkem je 2 pokusy).

Volání služby RESTful

Interakce zahrnuje výměnu informací mezi deklaracemi rest API a Azure AD B2C. Integraci se službami RESTful můžete navrhnout následujícími způsoby:

• Technický profil ověření Volání služby RESTful probíhá v rámci technického profilu ověřování specifikovaného samoobslužného technického profilu nebo v ovládacím prvku ověřeníovládacího prvku zobrazení. Technický profil ověření ověří data poskytnutá uživatelem před tím, než se cesta uživatele posune vpřed. Pomocí technického profilu ověření můžete:

  • Odešlete nároky do vaší REST API.
  • Ověřte nároky a vyvolávejte vlastní chybové zprávy, které se uživateli zobrazí.
  • Odeslat nároky z rozhraní REST API do následných kroků orchestrace.

• Výměna deklarací. Přímá výměna deklarací identity se dá nakonfigurovat voláním technického profilu rozhraní REST API přímo z kroku orchestrace cesty uživatele. Tato definice je omezená na:

  • Odešlete nároky do vaší REST API.
  • Ověřte deklarace identity a vyvolte vlastní chybové zprávy, které se vrátí do aplikace.
  • Odeslat nároky z rozhraní REST API do následných kroků orchestrace.

Volání rozhraní REST API můžete přidat v libovolném kroku na cestě uživatele definované vlastní zásadou. Můžete například volat rozhraní REST API:

• Během přihlašování těsně před tím, než Azure AD B2C ověří přihlašovací údaje.
• Hned po přihlášení.
• Než Azure AD B2C vytvoří v adresáři nový účet.
• Jakmile Azure AD B2C vytvoří v adresáři nový účet.
• Než Azure AD B2C vydá přístupový token.

Odesílání dat

V technickém profilu RESTful prvek InputClaims obsahuje seznam nároků, které se mají odeslat do služby RESTful. Název deklarace identity můžete namapovat na název definovaný ve službě RESTful, nastavit výchozí hodnotu a použít překladače deklarací identity.

Způsob odesílání vstupních deklarací identity do zprostředkovatele deklarací RESTful můžete nakonfigurovat pomocí atributu SendClaimsIn. Možné hodnoty:

• Text odeslaný v textu požadavku HTTP POST ve formátu JSON
• Formulář odeslaný v textu požadavku HTTP POST ve formátu klíč-hodnota odděleného ampersandem.
• Hlavička odeslaná v rámci hlavičky požadavku HTTP GET.
• Řetězec dotazu, který se odešle v řetězci dotazu požadavku HTTP GET.

Když je nakonfigurovaná možnost Text , technický profil rozhraní REST API umožňuje odeslat složitou datovou část JSON do koncového bodu. Další informace najdete v tématu Odeslání datové části JSON.

Příjem dat

Prvek OutputClaimstechnického profilu RESTful obsahuje seznam nároků vrácených rozhraním REST API. Možná budete muset propojit název nároku definovaného ve vaší zásadě s názvem definovaným v rozhraní REST API. Můžete také zahrnout deklarace identity, které nevrací zprostředkovatel identity REST API, pokud nastavíte atribut DefaultValue.

Výstupy nároků zpracovávané zprostředkovatelem nároků typu RESTful vždy očekávají parsování plochého JSON těla odpovědi, například:

{
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "loyaltyNumber":  1234
}

Výstupní deklarace identity by měly vypadat jako následující fragment kódu XML:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" />
</OutputClaims>

Zpracování hodnot null

Hodnota null v databázi se používá, pokud je hodnota ve sloupci neznámá nebo chybí. Nezahrnujte klíče JSON s null hodnotou. V následujícím příkladu vrátí e-mail hodnotu null:

{
  "name": "Emily Smith",
  "email": null,
  "loyaltyNumber":  1234
}

Pokud je element null, buď:

• Vynechte dvojici klíč-hodnota z JSON.
• Vrátí hodnotu, která odpovídá datovému typu deklarace identity Azure AD B2C. Například, pokud je datový typ string, vraťte prázdný řetězec "". U datového typu integer vraťte nulovou hodnotu 0. Pro datový typ dateTime vrátit minimální hodnotu 0001-01-01T00:00:00.0000000Z.

Následující příklad ukazuje, jak zpracovat hodnotu null. E-mail se vynechá z JSON:

{
  "name": "Emily Smith",
  "loyaltyNumber":  1234
}

Parsování vnořeného textu JSON

Pokud chcete parsovat vnořenou základní odpověď JSON, nastavte metadata ResolveJsonPathsInJsonTokens na hodnotu true. Ve výstupní deklaraci identity nastavte PartnerClaimType na prvek cesty JSON, který chcete použít pro výstup.

"contacts": [
  {
    "id": "MAINCONTACT_1",
    "person": {
      "name": "Emily Smith",
      "loyaltyNumber":  1234,
      "emails": [
        {
          "id": "EMAIL_1",
          "type": "WORK",
          "email": "email@domain.com"
        }
      ]
    }
  }
],

Výstupní deklarace identity by měly vypadat jako následující fragment kódu XML:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="contacts[0].person.name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="contacts[0].person.emails[0].email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="contacts[0].person.loyaltyNumber" />
</OutputClaims>

Lokalizace rozhraní REST API

V technickém profilu RESTful můžete chtít odeslat jazyk nebo národní prostředí aktuální relace a v případě potřeby vyvolat lokalizovanou chybovou zprávu. Pomocí řešitele nároků můžete odeslat kontextový nárok, například jazyk uživatele. Následující příklad ukazuje technický profil RESTful demonstrující tento scénář.

<TechnicalProfile Id="REST-ValidateUserData">
  <DisplayName>Validate user input data</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://your-app.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

Zpracování chybových zpráv

Vaše rozhraní REST API může potřebovat vrátit chybovou zprávu, například "Uživatel nebyl v systému CRM nalezen". Pokud dojde k chybě, rozhraní REST API by mělo vrátit chybovou zprávu HTTP 409 (stavový kód konfliktní odpovědi). Další informace najdete v technickém profilu RESTful.

Toto chování lze dosáhnout pouze voláním technického profilu rozhraní REST API z technického profilu ověření. Umožňuje uživateli opravit data na stránce a znovu spustit ověření při odeslání stránky.

Pokud odkazujete na technický profil rozhraní REST API přímo z cesty uživatele, uživatel se přesměruje zpět do aplikace předávající strany s příslušnou chybovou zprávou.

Vývoj rozhraní REST API

Rozhraní REST API je možné vyvíjet na libovolné platformě a psát v libovolném programovacím jazyce, pokud je zabezpečené a může odesílat a přijímat deklarace identity ve formátu JSON.

Požadavek na službu REST API pochází ze serverů Azure AD B2C. Služba REST API musí být publikovaná do veřejně přístupného koncového bodu HTTPS. Volání rozhraní REST API přichází z IP adresy datového centra Azure.

Pro usnadnění vývoje můžete používat serverless cloudové funkce, například triggery HTTP ve službě Azure Functions.

Měli byste navrhnout službu REST API a její základní komponenty (jako je databáze a systém souborů), aby byly vysoce dostupné.

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.

Další kroky

• Zjistěte, jak přidat konektor rozhraní API pro úpravu prostředí registrace.
• Zjistěte, jak přidat konektor rozhraní API pro rozšiřování tokenů pomocí externích deklarací identity.
• Informace o zabezpečení konektoru rozhraní API
• Začněte s našimi ukázkami

Příklady použití technického profilu RESTful najdete v následujících článcích:

• Návod: Přidání API konektoru do registračního toku uživatelů
• Návod: Přidání výměny deklarací REST API do vlastních zásad v Azure Active Directory B2C
• Zabezpečení služeb REST API
• volání rozhraní REST API pomocí vlastních zásad Azure Active Directory B2C

• Naučte se vytvářet odolnost při vzájemné spolupráci s externími procesy.
• Naučte se vytvářet Odolnost prostřednictvím osvědčených postupů pro vývojáře.