Dodawanie łączników interfejsu API w celu rejestrowania przepływów użytkowników

Artykuł
11/08/2023

Przed rozpoczęciem użyj selektora Wybierz typ zasad, aby wybrać typ konfigurowanych zasad. Usługa Azure Active Directory B2C oferuje dwie metody definiowania sposobu interakcji użytkowników z aplikacjami: za pomocą wstępnie zdefiniowanych przepływów użytkowników lub w pełni konfigurowalnych zasad niestandardowych. Kroki wymagane w tym artykule są różne dla każdej metody.

Jako deweloper lub administrator IT możesz użyć łączników interfejsu API, aby zintegrować przepływy użytkowników rejestracji z interfejsami API REST, aby dostosować środowisko rejestracji i zintegrować je z systemami zewnętrznymi. Na końcu tego przewodnika będziesz mieć możliwość utworzenia przepływu użytkownika usługi Azure AD B2C, który współdziała z usługami interfejsu API REST w celu modyfikowania środowisk rejestracji.

Punkt końcowy interfejsu API można utworzyć przy użyciu jednego z naszych przykładów.

W tym scenariuszu dodamy możliwość wprowadzenia numeru lojalnościowego dla użytkowników na stronie rejestracji usługi Azure AD B2C. Interfejs API REST sprawdza, czy kombinacja wiadomości e-mail i numeru lojalnościowego jest mapowana na kod promocyjny. Jeśli interfejs API REST znajdzie kod promocyjny dla tego użytkownika, zostanie zwrócony do usługi Azure AD B2C. Na koniec kod promocyjny zostanie wstawiony do oświadczeń tokenu używanych przez aplikację.

Możesz również zaprojektować interakcję jako krok aranżacji. Jest to odpowiednie, gdy interfejs API REST nie będzie weryfikował danych na ekranie i zawsze zwraca oświadczenia. Aby uzyskać więcej informacji, zobacz Walkthrough: Integrate REST API claims exchanges in your Azure AD B2C user journey as an orchestration step (Przewodnik: integrowanie wymiany oświadczeń interfejsu API REST w podróży użytkownika usługi Azure AD B2C jako krok aranżacji).

Wymagania wstępne

Utwórz przepływ użytkownika, aby użytkownicy mogli zarejestrować się i zalogować się do aplikacji.
Rejestrowanie aplikacji internetowej.

Wykonaj kroki opisane w artykule Wprowadzenie do zasad niestandardowych w usłudze Active Directory B2C
Rejestrowanie aplikacji internetowej.

Tworzenie łącznika interfejsu API

Aby użyć łącznika interfejsu API, należy najpierw utworzyć łącznik interfejsu API, a następnie włączyć go w przepływie użytkownika.

Zaloguj się w witrynie Azure Portal.
W obszarze Usługi platformy Azure wybierz pozycję Azure AD B2C.
Wybierz pozycję Łączniki interfejsu API, a następnie wybierz pozycję Nowy łącznik interfejsu API.
Podaj nazwę wyświetlaną wywołania. Na przykład zweryfikuj informacje o użytkowniku.
Podaj adres URL punktu końcowego dla wywołania interfejsu API.
Wybierz typ uwierzytelniania i skonfiguruj informacje uwierzytelniania na potrzeby wywoływania interfejsu API. Dowiedz się, jak zabezpieczyć Połączenie or interfejsu API.
Wybierz pozycję Zapisz.

Żądanie wysłane do interfejsu API

Łącznik interfejsu API materializuje się jako żądanie HTTP POST , wysyłając atrybuty użytkownika ('claims') jako pary klucz-wartość w treści JSON. Atrybuty są serializowane podobnie jak właściwości użytkownika programu Microsoft Graph .

Przykładowe żądanie

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

W żądaniu można wysyłać tylko właściwości użytkownika i atrybuty niestandardowe wymienione w środowisku atrybutów użytkownika usługi Azure AD B2C>.

Atrybuty niestandardowe istnieją w formacie extension_<extensions-app-id>_CustomAttribute w katalogu. Interfejs API powinien oczekiwać otrzymania oświadczeń w tym samym formacie serializowanym. Aby uzyskać więcej informacji na temat atrybutów niestandardowych, zobacz Definiowanie atrybutów niestandardowych w usłudze Azure AD B2C.

Ponadto te oświadczenia są zwykle wysyłane we wszystkich żądaniach:

Ustawienia regionalne interfejsu użytkownika ('ui_locales') — ustawienia regionalne użytkownika końcowego skonfigurowane na urządzeniu. Może to być używane przez interfejs API do zwracania międzynarodowych odpowiedzi.
Krok ('krok') — krok lub punkt przepływu użytkownika wywoływanego przez łącznik interfejsu API. Wartości obejmują:
- PostFederationSignup — odpowiada "Po sfederowaniu z dostawcą tożsamości podczas rejestracji"
- PostAttributeCollection — odpowiada "Przed utworzeniem użytkownika"
- PreTokenIssuance — odpowiada "Przed wysłaniem tokenu (wersja zapoznawcza)". Dowiedz się więcej o tym kroku
Identyfikator klienta ('client_id') — appId wartość aplikacji uwierzytelnianej przez użytkownika końcowego w przepływie użytkownika. Nie jest to aplikacja appId zasobów w tokenach dostępu.
Adres e-mail ("adres e-mail") lub tożsamości ("tożsamości") — te oświadczenia mogą być używane przez interfejs API do identyfikowania użytkownika końcowego, który uwierzytelnia aplikację.

Ważne

Jeśli oświadczenie nie ma wartości w momencie wywołania punktu końcowego interfejsu API, oświadczenie nie zostanie wysłane do interfejsu API. Interfejs API powinien być zaprojektowany tak, aby jawnie sprawdzać i obsługiwać przypadek, w którym oświadczenie nie znajduje się w żądaniu.

Włączanie łącznika interfejsu API w przepływie użytkownika

Wykonaj następujące kroki, aby dodać łącznik interfejsu API do przepływu użytkownika rejestracji.

Zaloguj się w witrynie Azure Portal.
W obszarze Usługi platformy Azure wybierz pozycję Azure AD B2C.
Wybierz pozycję Przepływy użytkownika, a następnie wybierz przepływ użytkownika, do którego chcesz dodać łącznik interfejsu API.
Wybierz pozycję Łączniki interfejsu API, a następnie wybierz punkty końcowe interfejsu API, które chcesz wywołać, wykonując następujące kroki w przepływie użytkownika:
- Po sfederowaniu z dostawcą tożsamości podczas rejestracji
- Przed utworzeniem użytkownika
- Przed wysłaniem tokenu (wersja zapoznawcza)
Wybierz pozycję Zapisz.

Te kroki istnieją tylko w przypadku rejestracji i logowania (zalecane) i rejestracji (zalecane), ale mają zastosowanie tylko do części rejestracji w środowisku.

Łącznik interfejsu API w tym kroku w procesie rejestracji jest wywoływany natychmiast po uwierzytelnieniu użytkownika za pomocą dostawcy tożsamości (takiego jak Google, Facebook i Microsoft Entra ID). Ten krok poprzedza stronę kolekcji atrybutów, która jest formularzem przedstawionym użytkownikowi w celu zbierania atrybutów użytkownika. Ten krok nie jest wywoływany, jeśli użytkownik rejestruje się przy użyciu konta lokalnego.

Przykładowe żądanie wysłane do interfejsu API w tym 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"
}

Dokładne oświadczenia wysyłane do interfejsu API zależą od informacji dostarczonych przez dostawcę tożsamości. Wiadomość e-mail jest zawsze wysyłana.

W tym kroku oczekiwano typów odpowiedzi z internetowego interfejsu API

Gdy internetowy interfejs API odbiera żądanie HTTP z identyfikatora Entra firmy Microsoft podczas przepływu użytkownika, może zwrócić następujące odpowiedzi:

Odpowiedź kontynuacji
Odpowiedź blokująca

Odpowiedź kontynuacji

Odpowiedź kontynuacji wskazuje, że przepływ użytkownika powinien przejść do następnego kroku: strony kolekcji atrybutów.

W odpowiedzi kontynuacji interfejs API może zwracać oświadczenia. Jeśli oświadczenie jest zwracane przez interfejs API, oświadczenie wykonuje następujące czynności:

Wstępnie wypełnia pole wejściowe na stronie kolekcji atrybutów.

Zobacz przykład odpowiedzi kontynuacji.

Odpowiedź blokująca

Blokująca odpowiedź kończy przepływ użytkownika. Interfejs API może celowo wydać go, aby zatrzymać kontynuację przepływu użytkownika, wyświetlając użytkownikowi stronę bloku. Na stronie bloku zostanie wyświetlona userMessage wartość podana przez interfejs API.

Zobacz przykład odpowiedzi blokującej.

Przed utworzeniem użytkownika

Łącznik interfejsu API w tym kroku w procesie rejestracji jest wywoływany po stronie kolekcji atrybutów, jeśli został uwzględniony. Ten krok jest zawsze wywoływany przed utworzeniem konta użytkownika.

Przykładowe żądanie wysłane do interfejsu API w tym 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"
}

Oświadczenia wysyłane do interfejsu API zależą od informacji zbieranych od użytkownika lub udostępniane przez dostawcę tożsamości.

W tym kroku oczekiwano typów odpowiedzi z internetowego interfejsu API

Gdy internetowy interfejs API odbiera żądanie HTTP z identyfikatora Entra firmy Microsoft podczas przepływu użytkownika, może zwrócić następujące odpowiedzi:

Odpowiedź kontynuacji
Odpowiedź blokująca
Odpowiedź na walidację

Odpowiedź kontynuacji

Odpowiedź kontynuacji wskazuje, że przepływ użytkownika powinien przejść do następnego kroku: utworzyć użytkownika w katalogu.

W odpowiedzi kontynuacji interfejs API może zwracać oświadczenia. Jeśli oświadczenie jest zwracane przez interfejs API, oświadczenie wykonuje następujące czynności:

Zastępuje wszystkie wartości, które zostały już udostępnione przez użytkownika na stronie kolekcji atrybutów.

Aby zapisać oświadczenia w katalogu podczas rejestracji, które nie powinny być zbierane od użytkownika, nadal należy wybrać oświadczenia w obszarze Atrybuty użytkownika przepływu użytkownika, co domyślnie poprosi użytkownika o wartości, ale można użyć niestandardowego kodu JavaScript lub CSS , aby ukryć pola wejściowe od użytkownika końcowego.

Zobacz przykład odpowiedzi kontynuacji.

Odpowiedź blokująca

Zobacz przykład odpowiedzi blokującej.

Odpowiedź na błąd walidacji

Gdy interfejs API odpowie z odpowiedzią na błąd weryfikacji, przepływ użytkownika pozostaje na stronie kolekcji atrybutów i userMessage jest wyświetlany użytkownikowi. Użytkownik może następnie edytować i ponownie przesłać formularz. Tego typu odpowiedzi można użyć do weryfikacji danych wejściowych.

Zobacz przykład odpowiedzi na błąd weryfikacji.

Przed wysłaniem tokenu (wersja zapoznawcza)

Ważne

Łączniki interfejsu API używane w tym kroku są w wersji zapoznawczej. Aby uzyskać więcej informacji na temat wersji zapoznawczych, zobacz Warunki dotyczące produktów dla usług online.

Łącznik interfejsu API w tym kroku jest wywoływany, gdy token ma zostać wystawiony podczas logowania i rejestracji. Łącznik interfejsu API dla tego kroku może służyć do wzbogacania tokenu przy użyciu wartości oświadczeń ze źródeł zewnętrznych.

Przykładowe żądanie wysłane do interfejsu API w tym 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",
}

Oświadczenia wysyłane do interfejsu API zależą od informacji zdefiniowanych dla użytkownika.

W tym kroku oczekiwano typów odpowiedzi z internetowego interfejsu API

Gdy internetowy interfejs API odbiera żądanie HTTP z identyfikatora Entra firmy Microsoft podczas przepływu użytkownika, może zwrócić następujące odpowiedzi:

Odpowiedź kontynuacji

Odpowiedź kontynuacji

Odpowiedź kontynuacji wskazuje, że przepływ użytkownika powinien przejść do następnego kroku: wydać token.

W odpowiedzi kontynuacji interfejs API może zwrócić dodatkowe oświadczenia. Oświadczenie zwrócone przez interfejs API, który ma zostać zwrócony w tokenie, musi być wbudowanym oświadczeniem lub zdefiniowanym jako atrybut niestandardowy i musi zostać wybrane w konfiguracji oświadczenia aplikacji przepływu użytkownika.

Wartość oświadczenia w tokenie będzie wartością zwracaną przez interfejs API, a nie wartością w katalogu. Niektóre wartości oświadczeń nie mogą zostać nadpisane przez odpowiedź interfejsu API. Oświadczenia, które mogą być zwracane przez interfejs API, odpowiadają zestawowi znalezionemu w obszarze Atrybuty użytkownika z wyjątkiem email.

Zobacz przykład odpowiedzi kontynuacji.

Uwaga

Interfejs API jest wywoływany tylko podczas początkowego uwierzytelniania. W przypadku używania tokenów odświeżania do dyskretnego uzyskiwania nowych tokenów dostępu lub identyfikatora token będzie zawierać wartości oceniane podczas początkowego uwierzytelniania.

Przykładowe odpowiedzi

Przykład odpowiedzi kontynuacji

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	Wymagani	opis
version	String	Tak	Wersja interfejsu API.
action	String	Tak	Wartość musi mieć wartość `Continue`.
<builtInUserAttribute>	<typ-atrybutu>	Nie.	Zwrócone wartości mogą zastępować wartości zebrane od użytkownika.
<extension_{extensions-app-id}_CustomAttribute>	<typ-atrybutu>	Nie.	Oświadczenie nie musi zawierać `_<extensions-app-id>_`elementu , jest opcjonalne. Zwrócone wartości mogą zastępować wartości zebrane od użytkownika.

Przykład odpowiedzi blokującej

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	Wymagani	opis
version	String	Tak	Wersja interfejsu API.
action	String	Tak	Wartość musi być `ShowBlockPage`
userMessage	String	Tak	Komunikat wyświetlany użytkownikowi.

Środowisko użytkownika końcowego z blokowaniem odpowiedzi

Example of a blocking response

Przykład odpowiedzi na błąd weryfikacji

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	Wymagani	opis
version	String	Tak	Wersja interfejsu API.
action	String	Tak	Wartość musi mieć wartość `ValidationError`.
stan	Liczba całkowita/ ciąg	Tak	Musi być wartością `400`lub `"400"` w przypadku odpowiedzi ValidationError.
userMessage	String	Tak	Komunikat wyświetlany użytkownikowi.

Uwaga

Kod stanu HTTP musi być "400" oprócz wartości "status" w treści odpowiedzi.

Środowisko użytkownika końcowego z odpowiedzią na błąd weryfikacji

Example of a validation-error response

Przygotowywanie punktu końcowego interfejsu API REST

W tym przewodniku należy mieć interfejs API REST, który sprawdza, czy adres e-mail jest zarejestrowany w systemie zaplecza przy użyciu identyfikatora lojalnościowego. W przypadku zarejestrowania interfejs API REST powinien zwrócić kod promocji rejestracji, którego klient może użyć do zakupu towarów w aplikacji. W przeciwnym razie interfejs API REST powinien zwrócić komunikat o błędzie HTTP 409: "Identyfikator lojalnościowy {identyfikator lojalności}" nie jest skojarzony z adresem e-mail {email}".

Poniższy kod JSON ilustruje dane, które usługa Azure AD B2C wyśle do punktu końcowego interfejsu API REST.

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

Gdy interfejs API REST zweryfikuje dane, musi zwrócić kod HTTP 200 (OK) z następującymi danymi JSON:

{
    "promoCode": "24534"
}

Jeśli walidacja nie powiodła się, interfejs API REST musi zwrócić http 409 (konflikt) z elementem userMessage JSON. IEF oczekuje userMessage oświadczenia, że interfejs API REST zwraca. To oświadczenie zostanie przedstawione użytkownikowi jako ciąg, jeśli walidacja zakończy się niepowodzeniem.

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

Konfiguracja punktu końcowego interfejsu API REST wykracza poza zakres tego artykułu. Utworzyliśmy przykład usługi Azure Functions . Pełny kod funkcji platformy Azure można uzyskać w witrynie GitHub.

Definiowanie oświadczeń

Oświadczenie zapewnia tymczasowe przechowywanie danych podczas wykonywania zasad usługi Azure AD B2C. Oświadczenia można zadeklarować w sekcji schematu oświadczeń.

Otwórz plik rozszerzeń zasad. Na przykład SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
Wyszukaj element BuildingBlocks. Jeśli element nie istnieje, dodaj go.
Znajdź element ClaimsSchema . Jeśli element nie istnieje, dodaj go.
Dodaj następujące oświadczenia do elementu ClaimsSchema .

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

Dodawanie profilu technicznego interfejsu API RESTful

Profil techniczny Restful zapewnia obsługę współdziałania z własną usługą RESTful. Usługa Azure AD B2C wysyła dane do usługi RESTful w InputClaims kolekcji i odbiera dane z powrotem w OutputClaims kolekcji. Znajdź element ClaimsProviders i dodaj nowego dostawcę oświadczeń w następujący sposób:

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

W tym przykładzie userLanguage element zostanie wysłany do usługi REST jako lang w ładunku JSON. Wartość userLanguage oświadczenia zawiera bieżący identyfikator języka użytkownika. Aby uzyskać więcej informacji, zobacz rozpoznawanie oświadczeń.

Konfigurowanie profilu technicznego interfejsu API RESTful

Po wdrożeniu interfejsu API REST ustaw metadane profilu technicznego REST-ValidateProfile , aby odzwierciedlały własny interfejs API REST, w tym:

ServiceUrl. Ustaw adres URL punktu końcowego interfejsu API REST.
SendClaimsIn. Określ sposób wysyłania oświadczeń wejściowych do dostawcy oświadczeń RESTful.
Typ uwierzytelniania. Ustaw typ uwierzytelniania wykonywanego przez dostawcę oświadczeń RESTful.
AllowInsecureAuthInProduction. W środowisku produkcyjnym upewnij się, że ustawiono te metadane na true

Aby uzyskać więcej konfiguracji, zobacz metadane profilu technicznego RESTful.

Powyższe AuthenticationType komentarze i AllowInsecureAuthInProduction określ zmiany, które należy wprowadzić podczas przechodzenia do środowiska produkcyjnego. Aby dowiedzieć się, jak zabezpieczyć interfejsy API RESTful dla środowiska produkcyjnego, zobacz Bezpieczny interfejs API RESTful.

Weryfikowanie danych wejściowych użytkownika

Aby uzyskać numer lojalnościowy użytkownika podczas rejestracji, musisz zezwolić użytkownikowi na wprowadzanie tych danych na ekranie. Dodaj oświadczenie wyjściowe loyaltyId do strony rejestracji, dodając je do istniejącego elementu profilu OutputClaims technicznego rejestracji. Określ całą listę oświadczeń wyjściowych, aby kontrolować kolejność prezentowania oświadczeń na ekranie.

Dodaj odwołanie do profilu technicznego weryfikacji do profilu technicznego rejestracji, który wywołuje element REST-ValidateProfile. Nowy profil techniczny weryfikacji zostanie dodany do góry <ValidationTechnicalProfiles> kolekcji zdefiniowanej w zasadach podstawowych. To zachowanie oznacza, że dopiero po pomyślnej weryfikacji usługa Azure AD B2C przechodzi do utworzenia konta w katalogu.

Znajdź element ClaimsProviders. Dodaj nowego dostawcę oświadczeń w następujący sposób:

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

Dołączanie oświadczenia do tokenu

Aby zwrócić oświadczenie kodu promocyjnego z powrotem do aplikacji jednostki uzależnionej, dodaj oświadczenie wyjściowe do SocialAndLocalAccounts/SignUpOrSignIn.xml pliku. Oświadczenie wyjściowe umożliwi dodanie oświadczenia do tokenu po pomyślnej podróży użytkownika i zostanie wysłane do aplikacji. Zmodyfikuj element profilu technicznego w sekcji jednostki uzależnionej, aby dodać promoCode element jako oświadczenie wyjściowe.

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

Testowanie zasad niestandardowych

Zaloguj się w witrynie Azure Portal.
Jeśli masz dostęp do wielu dzierżaw, wybierz ikonę Ustawienia w górnym menu, aby przełączyć się do dzierżawy Microsoft Entra ID z menu Katalogi i subskrypcje.
Wybierz pozycję Wszystkie usługi w lewym górnym rogu witryny Azure Portal, a następnie wyszukaj i wybierz pozycję Rejestracje aplikacji.
Wybierz pozycję Identity Experience Framework(Struktura obsługi tożsamości).
Wybierz pozycję Przekaż zasady niestandardowe, a następnie przekaż zmienione pliki zasad: TrustFrameworkExtensions.xml i SignUpOrSignin.xml.
Wybierz przekazane zasady rejestracji lub logowania, a następnie kliknij przycisk Uruchom teraz .
Powinno być możliwe zarejestrowanie się przy użyciu adresu e-mail.
Kliknij link Zarejestruj się teraz.
W polu Twój identyfikator lojalnościowy wpisz 1234, a następnie kliknij przycisk Kontynuuj. W tym momencie powinien zostać wyświetlony komunikat o błędzie weryfikacji.
Zmień wartość na inną, a następnie kliknij przycisk Kontynuuj.
Token wysłany z powrotem do aplikacji zawiera promoCode oświadczenie.

{
  "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"
  ...
}

Najlepsze rozwiązania i sposoby rozwiązywania problemów

Korzystanie z funkcji chmury bezserwerowej

Funkcje bezserwerowe, takie jak wyzwalacze HTTP w usłudze Azure Functions, umożliwiają tworzenie punktów końcowych interfejsu API do użycia z łącznikiem interfejsu API. Możesz użyć funkcji chmury bezserwerowej, aby na przykład wykonać logikę walidacji i ograniczyć rejestrację do określonych domen poczty e-mail. Funkcja chmury bezserwerowej może również wywoływać i wywoływać inne internetowe interfejsy API, magazyny danych i inne usługi w chmurze w przypadku złożonych scenariuszy.

Najlepsze rozwiązania

Upewnij się, że:

Twój interfejs API śledzi kontrakty żądań interfejsu API i odpowiedzi zgodnie z powyższym opisem.
Adres URL punktu końcowego łącznika interfejsu API wskazuje prawidłowy punkt końcowy interfejsu API.
Interfejs API jawnie sprawdza wartości null odebranych oświadczeń, od których zależy.
Interfejs API implementuje metodę uwierzytelniania opisaną w artykule Zabezpieczanie Połączenie or interfejsu API.
Interfejs API reaguje tak szybko, jak to możliwe, aby zapewnić płynne środowisko użytkownika.
- Usługa Azure AD B2C poczeka maksymalnie 20 sekund na odebranie odpowiedzi. Jeśli żadna z nich nie zostanie odebrana, podejmie jeszcze jedną próbę (ponów próbę) podczas wywoływania interfejsu API.
- Jeśli korzystasz z funkcji bezserwerowej lub skalowalnej usługi internetowej, użyj planu hostingu, który utrzymuje interfejs API "obudzić" lub "ciepły" w środowisku produkcyjnym. W przypadku usługi Azure Functions zaleca się użycie co najmniej planu Premium w środowisku produkcyjnym.
Zapewnij wysoką dostępność interfejsu API.
Monitorowanie i optymalizowanie wydajności podrzędnych interfejsów API, baz danych lub innych zależności interfejsu API.

Ważne

Punkty końcowe muszą być zgodne z wymaganiami dotyczącymi zabezpieczeń usługi Azure AD B2C. Starsze wersje protokołu TLS i szyfry są przestarzałe. Aby uzyskać więcej informacji, zobacz Wymagania dotyczące protokołu TLS i pakietu szyfrowania usługi Azure AD B2C.

Korzystanie z rejestrowania

Ogólnie rzecz biorąc, warto używać narzędzi rejestrowania włączonych przez usługę internetowego interfejsu API, takich jak application insights, do monitorowania interfejsu API pod kątem nieoczekiwanych kodów błędów, wyjątków i niskiej wydajności.

Monitoruj kody stanu HTTP, które nie są http 200 lub 400.
Kod stanu HTTP 401 lub 403 zwykle wskazuje, że występuje problem z uwierzytelnianiem. Dokładnie sprawdź warstwę uwierzytelniania interfejsu API i odpowiednią konfigurację w łączniku interfejsu API.
W razie potrzeby użyj bardziej agresywnych poziomów rejestrowania (na przykład "ślad" lub "debuguj").
Monitoruj interfejs API pod kątem długich czasów odpowiedzi.

Ponadto usługa Azure AD B2C rejestruje metadane dotyczące transakcji interfejsu API występujących podczas uwierzytelniania użytkowników za pośrednictwem przepływu użytkownika. Aby je znaleźć:

Przejdź do usługi Azure AD B2C.
W obszarze Działania wybierz pozycję Dzienniki inspekcji.
Filtruj widok listy: w polu Data wybierz żądany interwał czasu, a w polu Działanie wybierz pozycję Interfejs API został wywołany jako część przepływu użytkownika.
Sprawdź poszczególne dzienniki. Każdy wiersz reprezentuje łącznik interfejsu API, który próbuje zostać wywołany podczas przepływu użytkownika. Jeśli wywołanie interfejsu API zakończy się niepowodzeniem i nastąpi ponowna próba, nadal jest reprezentowana jako pojedynczy wiersz. Wskazuje numberOfAttempts liczbę wywołań interfejsu API. Może to być 1wartość lub 2. Inne informacje o wywołaniu interfejsu API są szczegółowe w dziennikach.

Example of an API connector transaction during user authentication

Korzystanie z funkcji chmury bezserwerowej

Funkcje chmury bezserwerowej, takie jak wyzwalacze HTTP w usłudze Azure Functions, zapewniają prosty, wysoce dostępny i wydajny sposób tworzenia punktów końcowych interfejsu API do użycia jako łączniki interfejsu API.

Najlepsze rozwiązania

Upewnij się, że:

Interfejs API jawnie sprawdza wartości null odebranych oświadczeń, od których zależy.
Interfejs API implementuje metodę uwierzytelniania opisaną w artykule Zabezpieczanie Połączenie or interfejsu API.
Interfejs API reaguje tak szybko, jak to możliwe, aby zapewnić płynne środowisko użytkownika.
- Jeśli korzystasz z funkcji bezserwerowej lub skalowalnej usługi internetowej, użyj planu hostingu, który utrzymuje interfejs API "obudzić" lub "ciepły" w środowisku produkcyjnym. W przypadku usługi Azure Functions zaleca się użycie co najmniej planu Premium
Zapewnij wysoką dostępność interfejsu API.
Monitorowanie i optymalizowanie wydajności podrzędnych interfejsów API, baz danych lub innych zależności interfejsu API.

Ważne

Korzystanie z rejestrowania

Monitoruj kody stanu HTTP, które nie są http 200 lub 400.
Kod stanu HTTP 401 lub 403 zwykle wskazuje, że występuje problem z uwierzytelnianiem. Dokładnie sprawdź warstwę uwierzytelniania interfejsu API i odpowiednią konfigurację w łączniku interfejsu API.
W razie potrzeby użyj bardziej agresywnych poziomów rejestrowania (na przykład "ślad" lub "debuguj").
Monitoruj interfejs API pod kątem długich czasów odpowiedzi.

Następne kroki

Rozpocznij pracę z naszymi przykładami.
Zabezpieczanie Połączenie or interfejsu API

Dodawanie łącznika interfejsu API do przepływu użytkownika rejestracji

Wymagania wstępne

Tworzenie łącznika interfejsu API

Żądanie wysłane do interfejsu API

Włączanie łącznika interfejsu API w przepływie użytkownika

Po sfederowaniu z dostawcą tożsamości podczas rejestracji

Przykładowe żądanie wysłane do interfejsu API w tym kroku

W tym kroku oczekiwano typów odpowiedzi z internetowego interfejsu API

Odpowiedź kontynuacji

Odpowiedź blokująca

Przed utworzeniem użytkownika

Przykładowe żądanie wysłane do interfejsu API w tym kroku

W tym kroku oczekiwano typów odpowiedzi z internetowego interfejsu API

Odpowiedź kontynuacji

Odpowiedź blokująca

Odpowiedź na błąd walidacji

Przed wysłaniem tokenu (wersja zapoznawcza)

Przykładowe żądanie wysłane do interfejsu API w tym kroku

W tym kroku oczekiwano typów odpowiedzi z internetowego interfejsu API

Odpowiedź kontynuacji

Przykładowe odpowiedzi

Przykład odpowiedzi kontynuacji

Przykład odpowiedzi blokującej

Przykład odpowiedzi na błąd weryfikacji

Przygotowywanie punktu końcowego interfejsu API REST

Definiowanie oświadczeń

Dodawanie profilu technicznego interfejsu API RESTful

Konfigurowanie profilu technicznego interfejsu API RESTful

Weryfikowanie danych wejściowych użytkownika

Dołączanie oświadczenia do tokenu

Testowanie zasad niestandardowych

Najlepsze rozwiązania i sposoby rozwiązywania problemów

Korzystanie z funkcji chmury bezserwerowej

Najlepsze rozwiązania

Korzystanie z rejestrowania

Korzystanie z funkcji chmury bezserwerowej

Najlepsze rozwiązania

Korzystanie z rejestrowania

Następne kroki

Dodatkowe zasoby