Informace o konektorech ROZHRANÍ API v Azure AD B2C

Článek
09/22/2023

Než začnete, použijte selektor Zvolit typ zásady a zvolte typ zásady, kterou nastavujete. Azure Active Directory B2C nabízí dvě metody, jak definovat, jak uživatelé pracují 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 je s externími systémy. S konektory rozhraní API můžete například:

Ověřte vstupní data uživatele. Ověření proti chybně formátovaným nebo neplatným uživatelským datům Uživatelem poskytnutá data můžete například ověřit proti existujícím datům v externím úložišti dat nebo v seznamu povolených hodnot. Pokud je neplatný, můžete uživatele požádat o zadání platných dat nebo mu zablokovat pokračování v registraci.
Ověřte identitu uživatele. Pomocí služby ověření identity nebo externích zdrojů dat identity můžete při rozhodování o vytváření účtů přidat další úroveň zabezpečení.
Integrace s vlastním pracovním postupem schvalování Připojte se k vlastnímu schvalovacímu systému pro správu a omezení vytváření účtů.
Rozšiřte tokeny o atributy z externích zdrojů. Rozšiřte tokeny o atributy uživatele ze zdrojů, které jsou pro Azure AD B2C externí, jako jsou cloudové systémy, úložiště vlastních uživatelů, systémy vlastních oprávnění, starší služby 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 všemi velkými písmeny, můžete jméno naformátovat tak, aby bylo velké jenom první písmeno.
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 rozhraní API poskytuje Azure AD B2C informace potřebné 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 konektor rozhraní API nakonfigurujete, můžete ho povolit pro konkrétní krok v toku uživatele. Když uživatel dosáhne tohoto kroku v toku registrace, konektor rozhraní API se vyvolá a materializuje jako požadavek HTTP POST do vašeho rozhraní API, který odesílá informace o uživateli ("deklarace identity") jako páry klíč-hodnota v těle JSON. Odpověď rozhraní API může ovlivnit provádění toku uživatele. Odpověď rozhraní API může například zablokovat registraci uživatele, požádat ho o opětovné zadání informací nebo přepsat atributy uživatele.

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

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

Po federování se 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í.

Konektor ROZHRANÍ API v tomto kroku procesu registrace se vyvolá okamžitě poté, co se uživatel ověří u zprostředkovatele identity (jako je Google, Facebook a ID Microsoft Entra). Tento krok předchází stránce kolekce atributů, což je formulář, který se uživateli zobrazí ke shromažďování atributů uživatele. Tento krok se nevyvolá, pokud se uživatel registruje pomocí místního účtu. Níže jsou uvedené příklady scénářů konektorů rozhraní API, které můžete v tomto kroku povolit:

K vyhledání deklarací identity v existujícím systému použijte e-mailovou nebo federovanou identitu, kterou uživatel zadal. Vraťte tyto deklarace identity z existujícího systému, předvyplňte stránku kolekce atributů a zpřístupněte je k vrácení 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 procesu registrace se vyvolá po stránce kolekce atributů, pokud je zahrnutý. 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 během registrace povolit:

Ověřte vstupní data uživatele a požádejte uživatele, aby data znovu odeslal.
Blokování registrace uživatele na základě dat zadaných uživatelem
Ověřte identitu uživatele.
Zadejte dotaz na externí systémy na existující data o uživateli, aby se vrátila v tokenu aplikace, nebo je uložte 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 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 jiných zdrojů, než je adresář, včetně starších systémů identit, systémů personálního oddělení, úložišť externích 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 zavolá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 externí zdroj dat identity. Můžete například ověřit, že e-mailová adresa zadaná uživatelem existuje v databázi zákazníka, a pokud ne, zobrazí se chyba. Konektory rozhraní API si také můžete představit jako způsob podpory odchozích webhooků, protože volání se provádí při výskytu události, například při registraci.
Zpracování deklarací identity. Pokud uživatel zadá svoje křestní jméno malými nebo všemi velkými písmeny, může rozhraní REST API název naformátovat tak, aby bylo velké jenom první písmeno, a vrátit ho na Azure AD B2C. Při použití vlastních zásad se ale claimsTransformations upřednostňuje před voláním rozhraní RESTful API.
Dynamicky obohacovat uživatelská data další integrací s podnikovými obchodními aplikacemi. Vaše služba RESTful může obdržet e-mailovou adresu uživatele, zadat dotaz do databáze zákazníka a vrátit věrnostní číslo uživatele na Azure AD B2C. Vrácené deklarace identity je pak možné uložit do účtu Microsoft Entra uživatele, vyhodnotit v dalších krocích orchestrace nebo zahrnout do přístupového tokenu.
Spuštění vlastní obchodní logiky Můžete odesílat nabízená oznámení, aktualizovat podnikové databáze, spustit proces migrace uživatelů, spravovat oprávnění, auditovat databáze a provádět další pracovní postupy.

Diagram výměny deklarací identity služby RESTful

Poznámka

Pokud je služba RESTful pomalá nebo žádná odezva na Azure AD B2C, časový limit je 30 sekund a počet opakování je dvakrát (to znamená, že celkem došlo k 3 pokusům). V současné době není možné nakonfigurovat nastavení časového limitu a počtu opakování.

Volání služby RESTful

Tato interakce zahrnuje výměnu informací deklarací identity 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ěření zadaného technického profilu s vlastním potvrzením nebo v ovládacím prvku zobrazení ověření ovládacího prvku zobrazení. Ověřovací technický profil ověří data poskytnutá uživatelem před tím, než se přesune kupředu. S technickým profilem ověřování můžete:
- Odesílat deklarace identity do rozhraní REST API.
- Ověřte deklarace identity a vyvoláte vlastní chybové zprávy, které se zobrazí uživateli.
- Odesílání deklarací identity z rozhraní REST API do dalších kroků orchestrace
Výměna deklarací identity. Přímou výměnu deklarací identity je možné nakonfigurovat voláním technického profilu rozhraní REST API přímo z kroku orchestrace na cestě uživatele. Tato definice je omezená na:
- Odesílat deklarace identity do rozhraní REST API.
- Ověřte deklarace identity a vyvoláte vlastní chybové zprávy, které se vrátí do aplikace.
- Odesílání deklarací identity z rozhraní REST API do dalších kroků orchestrace

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

Během přihlášení těsně před tím, než Azure AD B2C přihlašovací údaje ověří.
Okamžitě po přihlášení.
Před Azure AD B2C vytvoří v adresáři nový účet.
Po 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 element obsahuje seznam deklarací identity, InputClaims které se mají odeslat do služby RESTful. Název vaší 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í identity RESTful můžete nakonfigurovat pomocí atributu SendClaimsIn. Možné hodnoty jsou:

Text odeslaný v textu požadavku HTTP POST ve formátu JSON.
Formulář odeslaný v textu požadavku HTTP POST ve formátu hodnoty klíče odděleném ampersandem&.
Hlavička odeslaná v hlavičce požadavku HTTP GET.
Řetězec dotazu odeslaný v řetězci dotazu požadavku HTTP GET.

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

Příjem dat

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

Výstupní deklarace identity analyzované zprostředkovatelem deklarací identity RESTful vždy očekávají, že budou parsovat plochou odpověď textu JSON, 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 e-mail vrátí null hodnotu:

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

Pokud má element hodnotu null, buď:

Vyněžte pár klíč-hodnota z JSON.
Vrátí hodnotu, která odpovídá datovému typu deklarace identity Azure AD B2C. Například pro string datový typ vraťte prázdný řetězec "". integer Pro datový typ vrátí nulovou hodnotu 0. dateTime Pro datový typ vrátí minimální hodnotu 1970-00-00T00:00:00.0000000Z.

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

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

Parsování vnořeného textu JSON

Pokud chcete parsovat vnořenou odpověď textu JSON, nastavte metadata ResolveJsonPathsInJsonTokens na hodnotu true. Ve výstupní deklaraci identity nastavte PartnerClaimType na element cesta JSON, který chcete vytvořit jako 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 podobně 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í překladače deklarací identity můžete odeslat kontextovou deklaraci identity, 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 možná bude muset vrátit chybovou zprávu typu Uživatel nebyl nalezen v systému CRM. Pokud dojde k chybě, rozhraní REST API by mělo vrátit chybovou zprávu HTTP 409 (stavový kód odpovědi na konflikt). Další informace najdete v technickém profilu RESTful.

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

Pokud odkazujete na technický profil rozhraní REST API přímo z cesty uživatele, bude uživatel přesměrován 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řijdou z IP adresy datacentra Azure.

Bezserverové cloudové funkce, jako jsou triggery HTTP, můžete v Azure Functions používat pro usnadnění vývoje.

Službu REST API a její základní komponenty (například databázi a systém souborů) byste měli navrhnout tak, 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 Azure AD požadavky na protokol TLS a šifrovací sadu B2C.

Další kroky

Zjistěte, jak přidat konektor ROZHRANÍ API pro úpravu možností registrace.
Zjistěte, jak přidat konektor rozhraní API pro obohacení tokenů o externí deklarace identity.
Informace o zabezpečení konektoru API
Začínáme s našimi ukázkami

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

Zjistěte, jak vytvořit odolnost při propojení s externími procesy.
Naučte se vytvářet odolnost proti chybám prostřednictvím osvědčených postupů pro vývojáře.

Použití konektorů rozhraní API k přizpůsobení a rozšíření toků uživatelů registrace a vlastních zásad o externí zdroje dat identit