Přidání konektoru rozhraní API do toku registrace uživatele

  • Článek

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

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. Na konci tohoto názorného postupu budete moct vytvořit tok uživatelů Azure AD B2C, který komunikuje se službami REST API za účelem úpravy prostředí registrace.

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

V tomto scénáři přidáme možnost, aby uživatelé zadali číslo věrnosti na registrační stránku Azure AD B2C. Rozhraní REST API ověřuje, jestli je kombinace e-mailu a čísla věrnosti namapovaná na propagační kód. Pokud rozhraní REST API najde propagační kód pro tohoto uživatele, vrátí se do Azure AD B2C. Nakonec se propagační kód vloží do deklarací tokenů, které aplikace bude využívat.

Interakci můžete také navrhnout jako krok orchestrace. To je vhodné, když rozhraní REST API nebude ověřovat data na obrazovce a vždy vracet deklarace identity. Další informace najdete v tématu Návod: Integrace výměn deklarací identity rest API ve vaší cestě uživatele Azure AD B2C jako krok orchestrace.

Předpoklady

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 k portálu Azure.

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

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

    Screenshot of basic configuration for an API connector

  4. Zadejte zobrazovaný název hovoru. Můžete například ověřit informace o uživateli.

  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 rozhraní API Připojení or.

    Screenshot of authentication configuration for an API connector

  7. Zvolte Uložit.

Požadavek odeslaný do vašeho rozhraní API

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 .

Příklad požadavku

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "objectId": "11111111-0000-0000-0000-000000000000",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "step": "<step-name>",
 "client_id":"93fd07aa-333c-409d-955d-96008fd08dd9",
 "ui_locales":"en-US"
}

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:

  • 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. Mezi hodnoty patří:
    • PostFederationSignup – odpovídá po federaci se zprostředkovatelem identity během registrace.
    • PostAttributeCollection – odpovídá "Před vytvořením uživatele"
    • PreTokenIssuance – odpovídá "Před odesláním tokenu (Preview)". Další informace o tomto kroku
  • 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.
  • E-mailová adresa (e-mailová adresa) nebo identity (identity) – tyto deklarace identity může vaše rozhraní API použít k identifikaci koncového uživatele, který se ověřuje v aplikaci.

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.

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

  1. Přihlaste se k portálu Azure.

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

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

  4. Vyberte konektory rozhraní API a pak vyberte koncové body rozhraní API, které chcete vyvolat v následujícím postupu v toku uživatele:

    • Po federaci s zprostředkovatelem identity během registrace
    • Před vytvořením uživatele
    • Před odesláním tokenu (Preview)

    Selecting an API connector for a step in the user flow

  5. Zvolte Uložit.

Tyto kroky existují jenom pro registraci a přihlášení (doporučeno) a registraci (doporučeno), ale platí jenom pro registraci.

Po federaci s 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 kolekce atributů, což je formulář před uživatelem ke shromažďování atributů uživatele. Tento krok se nevyvolá, pokud se uživatel registruje k místnímu účtu.

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

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "step": "PostFederationSignup",
 "client_id":"<guid>",
 "ui_locales":"en-US"
}

Přesné deklarace identity odeslané do rozhraní API závisí na informacích, které poskytuje zprostředkovatel identity. E-mail je vždy odeslán.

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 tyto odpovědi:

  • Odpověď na pokračování
  • Blokující odpověď

Odpověď na pokračování

Odpověď na pokračování znamená, že tok uživatele by měl pokračovat dalším krokem: stránka kolekce atributů.

V odpovědi na pokračování může rozhraní API vracet deklarace identity. Pokud rozhraní API vrátí deklaraci identity, provede deklarace následující:

  • Předvyplní vstupní pole na stránce kolekce atributů.

Podívejte se na příklad odpovědi na pokračování.

Blokující odpověď

Blokující odpověď ukončí tok uživatele. Rozhraní API může být záměrně vydáno, aby zastavilo pokračování toku uživatele zobrazením stránky bloku pro uživatele. Na stránce bloku se userMessage zobrazí poskytnutá rozhraním API.

Podívejte se na příklad blokující odpovědi.

Před vytvořením uživatele

Konektor rozhraní API v tomto kroku v procesu registrace se vyvolá po stránce kolekce atributů, pokud je součástí. Tento krok se vždy vyvolá před vytvořením uživatelského účtu.

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

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "step": "PostAttributeCollection",
 "client_id":"93fd07aa-333c-409d-955d-96008fd08dd9",
 "ui_locales":"en-US"
}

Deklarace identity, které se odesílají do rozhraní API, závisí na informacích, které uživatel shromažďuje, nebo je poskytuje zprostředkovatel identity.

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 tyto odpovědi:

  • Odpověď na pokračování
  • Blokující odpověď
  • Odpověď na ověření

Odpověď na pokračování

Odpověď na pokračování znamená, že tok uživatele by měl pokračovat dalším krokem: vytvořte uživatele v adresáři.

V odpovědi na pokračování může rozhraní API vracet deklarace identity. Pokud rozhraní API vrátí deklaraci identity, provede deklarace následující:

  • Přepíše všechny hodnoty, které již uživatel zadal na stránce kolekce atributů.

Pokud chcete napsat deklarace identity do adresáře při registraci, který by neměl být shromažďován od uživatele, měli byste stále vybrat deklarace identity v rámci atributů uživatele toku uživatele, který ve výchozím nastavení požádá uživatele o hodnoty, ale můžete použít vlastní JavaScript nebo CSS ke skrytí vstupních polí od koncového uživatele.

Podívejte se na příklad odpovědi na pokračování.

Blokující odpověď

Blokující odpověď ukončí tok uživatele. Rozhraní API může být záměrně vydáno, aby zastavilo pokračování toku uživatele zobrazením stránky bloku pro uživatele. Na stránce bloku se userMessage zobrazí poskytnutá rozhraním API.

Podívejte se na příklad blokující odpovědi.

Odpověď na chybu ověření

Když rozhraní API odpoví odpovědí na chybu ověření, tok uživatele zůstane na stránce kolekce atributů a userMessage uživateli se zobrazí. Uživatel pak může formulář upravit a znovu odeslat. Tento typ odpovědi lze použít pro ověření vstupu.

Podívejte se na příklad odpovědi na chybu ověřování.

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

Důležité

Konektory rozhraní API použité v tomto kroku jsou ve verzi Preview. Další informace o verzích Preview najdete v části Podmínky produktu pro online služby.

Konektor rozhraní API v tomto kroku se vyvolá, když se token vydá během přihlašování a registrace. Konektor rozhraní API pro tento krok lze použít k obohacení tokenu o hodnoty deklarací identity z externích zdrojů.

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

POST <API-endpoint>
Content-type: application/json

{
 "clientId": "231c70e8-8424-48ac-9b5d-5623b9e4ccf3",
 "step": "PreTokenApplicationClaims",
 "ui_locales":"en-US",
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
}

Deklarace identity odeslané do rozhraní API závisí na informacích definovaných pro uživatele.

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 tyto odpovědi:

  • 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 k dalšímu kroku: 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 hodnota 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

Podívejte se na příklad odpovědi na pokračování.

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

Ukázkové 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 Vrácené hodnoty mohou přepsat hodnoty shromážděné od uživatele.
<extension_{extensions-app-id}_CustomAttribute> <attribute-type> No Deklarace identity nemusí obsahovat _<extensions-app-id>_, je volitelná. Vrácené hodnoty mohou přepsat hodnoty shromážděné od uživatele.

Příklad blokující odpovědi

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "There was a problem with your request. You are not able to sign up at this time. Please contact your system administrator",
}
Parametr Type Požaduje se Popis
version Řetězec Ano Verze vašeho rozhraní API.
action Řetězec Ano Hodnota musí být ShowBlockPage
userMessage Řetězec Ano Zpráva, která se zobrazí uživateli.

Prostředí koncového uživatele s blokující odpovědí

Example of a blocking response

Příklad odpovědi na chybu ověřování

HTTP/1.1 400 Bad Request
Content-type: application/json

{
    "version": "1.0.0",
    "status": 400,
    "action": "ValidationError",
    "userMessage": "Please enter a valid Postal Code."
}
Parametr Type Požaduje se Popis
version Řetězec Ano Verze vašeho rozhraní API.
action Řetězec Ano Hodnota musí být ValidationError.
status Celé číslo / řetězec Ano Musí být hodnota 400nebo "400" pro odpověď ValidationError.
userMessage Řetězec Ano Zpráva, která se zobrazí uživateli.

Poznámka:

Stavový kód HTTP musí být kromě hodnoty status v textu odpovědi 400.

Prostředí koncového uživatele s odpovědí na chybu ověřování

Example of a validation-error response

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 e-mailová adresa zaregistrovaná v back-endovém systému s id věrnosti. Pokud je zaregistrované, rozhraní REST API by mělo vrátit registrační propagační kód, který může zákazník použít k nákupu zboží v rámci vaší aplikace. V opačném případě by rozhraní REST API mělo vrátit chybovou zprávu HTTP 409: "Id věrnosti {id} není přidruženo k e-mailové adrese {email}".

Následující kód JSON znázorňuje data, která Azure AD B2C odešle do koncového bodu rozhraní REST API.

{
    "email": "User email address",
    "language": "Current UI language",
    "loyaltyId": "User loyalty ID"
}

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

{
    "promoCode": "24534"
}

Pokud se ověření nezdařilo, musí rozhraní REST API vrátit http 409 (konflikt) s elementem userMessage JSON. IEF očekává userMessage deklaraci identity, kterou rozhraní REST API vrátí. Tato deklarace identity se uživateli zobrazí jako řetězec, pokud ověření selže.

{
    "version": "1.0.1",
    "status": 409,
    "userMessage": "LoyaltyId ID '1234' is not associated with 'david@contoso.com' email address."
}

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.

  1. Otevřete soubor s příponami zásad. Například, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
  2. Vyhledejte element BuildingBlocks . Pokud prvek neexistuje, přidejte ho.
  3. Vyhledejte element ClaimsSchema . Pokud prvek neexistuje, přidejte ho.
  4. Do elementu ClaimsSchema přidejte následující deklarace identity.
<ClaimType Id="loyaltyId">
  <DisplayName>Your loyalty ID</DisplayName>
  <DataType>string</DataType>
  <UserInputType>TextBox</UserInputType>
</ClaimType>
<ClaimType Id="promoCode">
  <DisplayName>Your promo code</DisplayName>
  <DataType>string</DataType>
  <UserInputType>Paragraph</UserInputType>
</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 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-ValidateProfile">
      <DisplayName>Check loyaltyId 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/ValidateProfile?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="loyaltyId" />
        <InputClaim ClaimTypeReferenceId="email" />
        <InputClaim ClaimTypeReferenceId="userLanguage" PartnerClaimType="lang" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
      </InputClaims>
      <OutputClaims>
        <!-- Claims parsed from your REST API -->
        <OutputClaim ClaimTypeReferenceId="promoCode" />
      </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-ValidateProfile 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. Nastavte typ ověřování prováděné zprostředkovatelem deklarací identity RESTful.
  • AllowInsecureAuthInProduction. V produkčním prostředí nezapomeňte tato metadata nastavit na true

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.

Ověření vstupu uživatele

Pokud chcete získat číslo věrnosti uživatele během registrace, musíte uživateli povolit zadat tato data na obrazovce. Přidání deklarace výstupu id věrnosti na registrační stránku přidáním do existujícího prvku oddílu technického OutputClaims profilu registrace. Zadejte celý seznam výstupních deklarací identity pro řízení pořadí, ve kterém se deklarace identity zobrazují na obrazovce.

Přidejte odkaz na technický profil ověření do technického profilu registrace, který volá REST-ValidateProfile. Nový technický profil ověření se přidá do horní části <ValidationTechnicalProfiles> kolekce definované v základní zásadě. Toto chování znamená, že až po úspěšném ověření se Azure AD B2C přesune k vytvoření účtu v adresáři.

  1. Vyhledejte element ClaimsProviders . Přidejte nového zprostředkovatele deklarací identity následujícím způsobem:

    <ClaimsProvider>
  <DisplayName>Local Account</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="LocalAccountSignUpWithLogonEmail">
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="Verified.Email" Required="true"/>
        <OutputClaim ClaimTypeReferenceId="newPassword" Required="true"/>
        <OutputClaim ClaimTypeReferenceId="reenterPassword" Required="true"/>
        <OutputClaim ClaimTypeReferenceId="displayName"/>
        <OutputClaim ClaimTypeReferenceId="givenName"/>
        <OutputClaim ClaimTypeReferenceId="surName"/>
        <!-- Required to present the text box to collect the data from the user -->
        <OutputClaim ClaimTypeReferenceId="loyaltyId"/>
        <!-- Required to pass the promoCode returned from "REST-ValidateProfile" 
        to subsequent orchestration steps and token issuance-->
        <OutputClaim ClaimTypeReferenceId="promoCode" />
      </OutputClaims>
      <ValidationTechnicalProfiles>
        <ValidationTechnicalProfile ReferenceId="REST-ValidateProfile" />
      </ValidationTechnicalProfiles>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>
<ClaimsProvider>
  <DisplayName>Self Asserted</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="SelfAsserted-Social">
      <InputClaims>
        <InputClaim ClaimTypeReferenceId="email" />
      </InputClaims>
        <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" />
        <OutputClaim ClaimTypeReferenceId="displayName"/>
        <OutputClaim ClaimTypeReferenceId="givenName"/>
        <OutputClaim ClaimTypeReferenceId="surname"/>
        <!-- Required to present the text box to collect the data from the user -->
        <OutputClaim ClaimTypeReferenceId="loyaltyId"/>
        <!-- Required to pass the promoCode returned from "REST-ValidateProfile" 
        to subsequent orchestration steps and token issuance-->
        <OutputClaim ClaimTypeReferenceId="promoCode" />
      </OutputClaims>
      <ValidationTechnicalProfiles>
        <ValidationTechnicalProfile ReferenceId="REST-ValidateProfile"/>
      </ValidationTechnicalProfiles>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

Zahrnutí deklarace identity do tokenu

Pokud chcete vrátit deklaraci propagačního kódu zpět do aplikace předávající strany, přidejte do SocialAndLocalAccounts/SignUpOrSignIn.xml souboru výstupní deklaraci identity. Výstupní deklarace identity umožní přidání deklarace identity do tokenu po úspěšné cestě uživatele a odešle se do aplikace. Upravte prvek technického profilu v části předávající strany tak, aby se přidal promoCode 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="promoCode" DefaultValue="" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

Testování vlastních zásad

  1. Přihlaste se k portálu Azure.
  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 ID.
  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 pak nahrajte soubory zásad, které jste změnili: TrustFrameworkExtensions.xml a SignUpOrSignin.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.
  8. Klikněte na odkaz Pro registraci .
  9. Do pole Vaše id věrnosti zadejte 1234 a klikněte na Pokračovat. V tomto okamžiku byste měli zobrazit chybovou zprávu ověření.
  10. Přejděte na jinou hodnotu a klikněte na Pokračovat.
  11. Token odeslaný zpět do vaší aplikace obsahuje promoCode deklaraci identity.
{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584295703,
  "nbf": 1584292103,
  "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": 1584292103,
  "auth_time": 1584292103,
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "given_name": "Emily",
  "family_name": "Smith",
  "promoCode": "84362"
  ...
}

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. Pomocí funkce bezserverového cloudu můžete například provést logiku ověřování a omezit registrace na konkrétní e-mailové domény. 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í vašeho rozhraní API Připojení or.
  • 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 bezserverovou funkci 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í

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:

  1. Přejděte do Azure AD B2C.
  2. V části 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ý 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.

Example of an API connector transaction during user authentication

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

Bezserverové cloudové funkce, jako jsou triggery HTTP ve službě Azure Functions, poskytují jednoduchý, vysoce dostupný a vysoce výkonný způsob, jak vytvářet koncové body rozhraní API pro použití jako konektory rozhraní API.

Osvědčené postupy

Zajistěte následující:

  • 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í vašeho rozhraní API Připojení or.
  • Vaše rozhraní API reaguje co nejrychleji, aby se zajistilo prostředí pro uživatele s proměnlivým prostředím.
    • Pokud používáte bezserverovou funkci 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.
  • 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í

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.

Další kroky