Używanie łączników interfejsu API do dostosowywania i rozszerzania przepływów użytkowników rejestracji oraz zasad niestandardowych za pomocą zewnętrznych źródeł danych tożsamości

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żytkownika lub w pełni konfigurowalnych zasad niestandardowych. Kroki wymagane w tym artykule są inne dla każdej metody.

Omówienie

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 w celu dostosowania środowiska rejestracji i integracji z systemami zewnętrznymi. Na przykład za pomocą łączników interfejsu API można wykonywać następujące czynności:

• Zweryfikuj dane wejściowe użytkownika. Zweryfikuj źle sformułowane lub nieprawidłowe dane użytkownika. Można na przykład zweryfikować dane dostarczone przez użytkownika względem istniejących danych w zewnętrznym magazynie danych lub na liście dozwolonych wartości. Jeśli jest to nieprawidłowe, możesz poprosić użytkownika o podanie prawidłowych danych lub zablokować użytkownikowi kontynuowanie przepływu rejestracji.
• Zweryfikuj tożsamość użytkownika. Użyj usługi weryfikacji tożsamości lub zewnętrznych źródeł danych tożsamości, aby dodać dodatkowy poziom zabezpieczeń do decyzji dotyczących tworzenia konta.
• Integracja z niestandardowym przepływem pracy zatwierdzania. Połącz się z niestandardowym systemem zatwierdzania w celu zarządzania tworzeniem konta i ograniczaniem go.
• Rozszerzanie tokenów za pomocą atrybutów ze źródeł zewnętrznych. Wzbogacanie tokenów o atrybuty użytkownika ze źródeł zewnętrznych do Azure AD B2C, takich jak systemy w chmurze, magazyny użytkowników niestandardowych, niestandardowe systemy uprawnień, starsze usługi tożsamości i inne.
• Zastąp atrybuty użytkownika. Przeformatuj lub przypisz wartość do atrybutu zebranego od użytkownika. Jeśli na przykład użytkownik wprowadzi imię we wszystkich małych lub wielkich literach, możesz sformatować nazwę tylko z pierwszą literą.
• Uruchamianie niestandardowej logiki biznesowej. Zdarzenia podrzędne w systemach w chmurze można wyzwalać w celu wysyłania powiadomień wypychanych, aktualizowania firmowych baz danych, zarządzania uprawnieniami, inspekcji baz danych i wykonywania innych akcji niestandardowych.

Łącznik interfejsu API udostępnia Azure AD B2C z informacjami wymaganymi do wywołania punktu końcowego interfejsu API przez zdefiniowanie adresu URL punktu końcowego HTTP i uwierzytelniania dla wywołania interfejsu API. Po skonfigurowaniu łącznika interfejsu API można go włączyć dla określonego kroku w przepływie użytkownika. Gdy użytkownik osiągnie ten krok w przepływie rejestracji, łącznik interfejsu API jest wywoływany i materializuje się jako żądanie HTTP POST do interfejsu API, wysyłając informacje o użytkowniku ("oświadczenia") jako pary klucz-wartość w treści JSON. Odpowiedź interfejsu API może mieć wpływ na wykonywanie przepływu użytkownika. Na przykład odpowiedź interfejsu API może zablokować użytkownikowi możliwość rejestracji, poprosić użytkownika o ponowne podanie informacji lub zastąpić atrybuty użytkownika.

Gdzie można włączyć łącznik interfejsu API w przepływie użytkownika

W przepływie użytkownika znajdują się trzy miejsca, w których można włączyć łącznik interfejsu API:

• Po sfederowaniu z dostawcą tożsamości podczas rejestracji — dotyczy tylko środowisk rejestracji
• Przed utworzeniem użytkownika — dotyczy tylko środowisk rejestracji
• Przed wysłaniem tokenu (wersja zapoznawcza) — dotyczy rejestracji i logowania

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

Łą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 identyfikator Microsoft Entra). 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. Poniżej przedstawiono przykłady scenariuszy łącznika interfejsu API, które można włączyć w tym kroku:

• Użyj wiadomości e-mail lub tożsamości federacyjnej udostępnionej przez użytkownika, aby wyszukać oświadczenia w istniejącym systemie. Zwróć te oświadczenia z istniejącego systemu, wstępnie wypełnij stronę kolekcji atrybutów i udostępnij je, aby zwrócić token.
• Zaimplementuj listę dozwolonych lub zablokowanych na podstawie tożsamości społecznościowej.

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. Poniżej przedstawiono przykłady scenariuszy, które można włączyć w tym momencie podczas rejestracji:

• Zweryfikuj dane wejściowe użytkownika i poproś użytkownika o ponowne przesłanie danych.
• Blokuj rejestrację użytkownika na podstawie danych wprowadzonych przez użytkownika.
• Zweryfikuj tożsamość użytkownika.
• Wykonywanie zapytań względem systemów zewnętrznych dla istniejących danych dotyczących użytkownika, aby zwrócić je w tokenie aplikacji lub zapisać je w identyfikatorze Microsoft Entra.

Przed wysłaniem tokenu (wersja zapoznawcza)

Uwaga

Ta funkcja jest dostępna w publicznej wersji zapoznawczej.

Łącznik interfejsu API w tym kroku w procesie rejestracji lub logowania jest wywoływany przed wystawieniem tokenu. Poniżej przedstawiono przykłady scenariuszy, które można włączyć w tym kroku:

• Wzbogacanie tokenu za pomocą atrybutów dotyczących użytkownika ze źródeł innych niż katalog, w tym starszych systemów tożsamości, systemów KADR, magazynów użytkowników zewnętrznych i nie tylko.
• Wzbogacanie tokenu za pomocą atrybutów grupy lub roli, które są przechowywane i zarządzane we własnym systemie uprawnień.
• Stosowanie przekształceń oświadczeń lub manipulacji do wartości oświadczeń w katalogu.

Struktura środowiska tożsamości, która stanowi strukturę azure Active Directory B2C (Azure AD B2C), może integrować się z interfejsami API RESTful w ramach podróży użytkownika. W tym artykule pokazano, jak utworzyć podróż użytkownika, która współdziała z usługą RESTful przy użyciu profilu technicznego RESTful.

Korzystając z Azure AD B2C, możesz dodać własną logikę biznesową do podróży użytkownika, wywołując własną usługę RESTful. Platforma obsługi tożsamości może wysyłać i odbierać dane z usługi RESTful w celu wymiany oświadczeń. Możesz na przykład:

• Użyj zewnętrznego źródła danych tożsamości, aby zweryfikować dane wejściowe użytkownika. Możesz na przykład sprawdzić, czy adres e-mail podany przez użytkownika istnieje w bazie danych klienta, a jeśli nie, wystąpi błąd. Łączniki interfejsu API można również traktować jako sposób obsługi wychodzących elementów webhook, ponieważ wywołanie jest wykonywane w przypadku wystąpienia zdarzenia, na przykład rejestracji.
• Przetwarzanie oświadczeń. Jeśli użytkownik wprowadzi swoje imię we wszystkich małych lub wielkich literach, interfejs API REST może sformatować nazwę tylko z pierwszą literą z wielkimi literami i zwrócić ją do Azure AD B2C. Jednak w przypadku korzystania z zasad niestandardowych preferowane jest użycie atrybutów ClaimsTransformations w przypadku wywoływania interfejsu API RESTful.
• Dynamiczne wzbogacanie danych użytkowników przez dalszą integrację z firmowymi aplikacjami biznesowymi. Usługa RESTful może otrzymać adres e-mail użytkownika, wysłać zapytanie do bazy danych klienta i zwrócić numer lojalnościowy użytkownika do Azure AD B2C. Następnie oświadczenia zwrotne mogą być przechowywane na koncie Microsoft Entra użytkownika, oceniane w następnych krokach aranżacji lub uwzględnione w tokenie dostępu.
• Uruchamianie niestandardowej logiki biznesowej. Powiadomienia wypychane, aktualizowanie firmowych baz danych, uruchamianie procesu migracji użytkowników, zarządzanie uprawnieniami, inspekcja baz danych i wykonywanie innych przepływów pracy.

Uwaga

Jeśli usługa RESTful działa wolno lub nie ma odpowiedzi na Azure AD B2C, limit czasu wynosi 30 sekund, a liczba ponownych prób wynosi dwa razy (co oznacza, że łączna liczba prób wynosi 3). Obecnie nie można skonfigurować ustawień limitu czasu i liczby ponownych prób.

Wywoływanie usługi RESTful

Interakcja obejmuje wymianę oświadczeń między oświadczeniami interfejsu API REST a Azure AD B2C. Integrację z usługami RESTful można zaprojektować w następujący sposób:

• Profil techniczny weryfikacji. Wywołanie usługi RESTful odbywa się w profilu technicznym weryfikacji określonego profilu technicznego asertywnego lub kontroli wyświetlania weryfikacji kontrolki wyświetlania. Profil techniczny weryfikacji weryfikuje dane dostarczone przez użytkownika, zanim podróż użytkownika przejdzie do przodu. Za pomocą profilu technicznego weryfikacji można wykonywać następujące czynności:

  • Wysyłanie oświadczeń do interfejsu API REST.
  • Zweryfikuj oświadczenia i zgłaszaj niestandardowe komunikaty o błędach wyświetlane użytkownikowi.
  • Wysyłanie oświadczeń z interfejsu API REST do następnych kroków aranżacji.

• Wymiana oświadczeń. Bezpośrednią wymianę oświadczeń można skonfigurować przez wywołanie profilu technicznego interfejsu API REST bezpośrednio z poziomu etapu aranżacji podróży użytkownika. Ta definicja jest ograniczona do:

  • Wysyłanie oświadczeń do interfejsu API REST.
  • Zweryfikuj oświadczenia i zgłaszaj niestandardowe komunikaty o błędach, które są zwracane do aplikacji.
  • Wysyłanie oświadczeń z interfejsu API REST do następnych kroków aranżacji.

Wywołanie interfejsu API REST można dodać w dowolnym kroku podróży użytkownika zdefiniowanej przez zasady niestandardowe. Na przykład można wywołać interfejs API REST:

• Podczas logowania, tuż przed Azure AD B2C weryfikuje poświadczenia.
• Natychmiast po zalogowaniu.
• Przed Azure AD B2C tworzy nowe konto w katalogu.
• Po Azure AD B2C tworzy nowe konto w katalogu.
• Przed Azure AD B2C wystawia token dostępu.

Wysyłanie danych

W profilu InputClaimstechnicznym RESTful element zawiera listę oświadczeń wysyłanych do usługi RESTful. Możesz zamapować nazwę oświadczenia na nazwę zdefiniowaną w usłudze RESTful, ustawić wartość domyślną i użyć funkcji rozpoznawania oświadczeń.

Możesz skonfigurować sposób wysyłania oświadczeń wejściowych do dostawcy oświadczeń RESTful przy użyciu atrybutu SendClaimsIn. Możliwe wartości są następujące:

• Treść wysłana w treści żądania HTTP POST w formacie JSON.
• Formularz, wysłany w treści żądania HTTP POST w formacie ampersand "&" oddzielonej wartości klucza.
• Nagłówek, wysłany w nagłówku żądania HTTP GET.
• QueryString, wysłane w ciągu zapytania ŻĄDANIA HTTP GET.

Po skonfigurowaniu opcji Treść profil techniczny interfejsu API REST umożliwia wysyłanie złożonego ładunku JSON do punktu końcowego. Aby uzyskać więcej informacji, zobacz Wysyłanie ładunku JSON.

Odbieranie danych

Element OutputClaimsprofilu technicznego RESTful zawiera listę oświadczeń zwróconych przez interfejs API REST. Może być konieczne mapowania nazwy oświadczenia zdefiniowanego w zasadach na nazwę zdefiniowaną w interfejsie API REST. Możesz również uwzględnić oświadczenia, które nie są zwracane przez dostawcę tożsamości interfejsu API REST, o ile ustawisz atrybut DefaultValue.

Oświadczenia wyjściowe analizowane przez dostawcę oświadczeń RESTful zawsze oczekują analizowania płaskiej odpowiedzi treść JSON, na przykład:

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

Oświadczenia wyjściowe powinny wyglądać podobnie do następującego fragmentu kodu XML:

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

Obsługa wartości null

Wartość null w bazie danych jest używana, gdy wartość w kolumnie jest nieznana lub brakuje. Nie dołączaj kluczy JSON z wartością null . W poniższym przykładzie wiadomość e-mail zwraca null wartość:

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

Gdy element ma wartość null, albo:

• Pomiń parę klucz-wartość z pliku JSON.
• Zwróć wartość odpowiadającą typowi danych oświadczenia B2C Azure AD. Na przykład w przypadku string typu danych zwracany jest pusty ciąg "". integer W przypadku typu danych zwróć wartość 0zero . dateTime W przypadku typu danych zwróć minimalną wartość 1970-00-00T00:00:00.0000000Z.

W poniższym przykładzie pokazano, jak obsłużyć wartość null. Wiadomość e-mail zostanie pominięta w formacie JSON:

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

Analizowanie zagnieżdżonej treści JSON

Aby przeanalizować zagnieżdżonych odpowiedzi treści JSON, ustaw metadane ResolveJsonPathsInJsonTokens na true. W oświadczeniu wyjściowym ustaw wartość PartnerClaimType na element ścieżki JSON, który chcesz wyświetlić.

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

Oświadczenia wyjściowe powinny wyglądać podobnie do następującego fragmentu kodu 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>

Lokalizowanie interfejsu API REST

W profilu technicznym RESTful możesz wysłać język/ustawienia regionalne bieżącej sesji, a w razie potrzeby zgłosić zlokalizowany komunikat o błędzie. Za pomocą narzędzia rozpoznawania oświadczeń można wysłać oświadczenie kontekstowe, takie jak język użytkownika. W poniższym przykładzie przedstawiono profil techniczny RESTful demonstrujący ten scenariusz.

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

Obsługa komunikatów o błędach

Interfejs API REST może wymagać zwrócenia komunikatu o błędzie, takiego jak "Użytkownik nie został znaleziony w systemie CRM". Jeśli wystąpi błąd, interfejs API REST powinien zwrócić komunikat o błędzie HTTP 409 (kod stanu odpowiedzi powodującej konflikt). Aby uzyskać więcej informacji, zobacz profil techniczny RESTful.

To zachowanie można osiągnąć tylko przez wywołanie profilu technicznego interfejsu API REST z profilu technicznego weryfikacji. Zezwalanie użytkownikowi na poprawianie danych na stronie i ponowne uruchamianie walidacji po przesłaniu strony.

Jeśli odwołujesz się do profilu technicznego interfejsu API REST bezpośrednio z podróży użytkownika, użytkownik zostanie przekierowany z powrotem do aplikacji jednostki uzależnionej z odpowiednim komunikatem o błędzie.

Tworzenie interfejsu API REST

Interfejs API REST można opracowywać na dowolnej platformie i zapisywać w dowolnym języku programowym, o ile jest bezpieczny i może wysyłać i odbierać oświadczenia w formacie JSON.

Żądanie usługi interfejsu API REST pochodzi z serwerów Azure AD B2C. Usługa interfejsu API REST musi zostać opublikowana w publicznie dostępnym punkcie końcowym HTTPS. Wywołania interfejsu API REST będą odbierane z adresu IP centrum danych platformy Azure.

Możesz używać funkcji chmury bezserwerowej, takich jak wyzwalacze HTTP w Azure Functions w celu ułatwienia programowania.

Usługa interfejsu API REST i jego podstawowe składniki (takie jak baza danych i system plików) powinny być wysoce dostępne.

Ważne

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

Następne kroki

• Dowiedz się, jak dodać łącznik interfejsu API w celu zmodyfikowania środowisk rejestracji
• Dowiedz się, jak dodać łącznik interfejsu API w celu wzbogacania tokenów za pomocą oświadczeń zewnętrznych
• Dowiedz się, jak zabezpieczyć łącznik interfejsu API
• Wprowadzenie do naszych przykładów

Zapoznaj się z następującymi artykułami, aby zapoznać się z przykładami użycia profilu technicznego RESTful:

• Przewodnik: dodawanie łącznika interfejsu API do przepływu użytkownika rejestracji
• Przewodnik: dodawanie oświadczeń interfejsu API REST do zasad niestandardowych w usłudze Azure Active Directory B2C
• Zabezpieczanie usług interfejsu API REST
• Dokumentacja: profil techniczny RESTful

• Dowiedz się, jak tworzyć odporność podczas łączenia się z procesami zewnętrznymi
• Dowiedz się, jak tworzyć odporność za pomocą najlepszych rozwiązań dla deweloperów.