Udostępnij za pośrednictwem

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

  • Artykuł

Dotyczy:Zielony okrąg z białym symbolem znacznika wyboru. Dzierżawcy siły roboczej — dzierżawcy zewnętrzni Biały okrąg z szarym symbolem X. (dowiedz się więcej)

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

Ważne

  • Od 12 lipca 2021 r., jeśli klienci firmy Microsoft Entra B2B skonfigurowali nowe integracje Google do użycia z rejestracją samoobsługową dla swoich niestandardowych lub biznesowych aplikacji, uwierzytelnianie przy użyciu tożsamości Google nie będzie działać, dopóki uwierzytelnianie nie zostanie przeniesione do systemowych widoków internetowych. Dowiedz się więcej.
  • Od 30 września 2021 r. firma Google wycofa obsługę logowania osadzonego widoku internetowego. Jeśli aplikacje uwierzytelniają użytkowników za pomocą osadzonego widoku internetowego i korzystasz z federacji Google z usługą Azure AD B2C lub Microsoft Entra B2B w przypadku zaproszeń użytkowników zewnętrznych lub rejestracji samoobsługowej, użytkownicy usługi Google Gmail nie będą mogli się uwierzytelniać. Dowiedz się więcej.

Tworzenie łącznika interfejsu API

Napiwek

Kroki opisane w tym artykule mogą się nieznacznie różnić w zależności od portalu, od którego zaczynasz.

  1. Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako administrator użytkowników.

  2. Przejdź do sekcji Identity External Identities>Overview (Przegląd tożsamości>zewnętrznych).

  3. Wybierz pozycję Wszystkie łączniki interfejsu API, a następnie wybierz pozycję Nowy łącznik interfejsu API.

    Zrzut ekranu przedstawiający dodawanie nowego łącznika interfejsu API do identyfikatora zewnętrznego.

  4. Podaj nazwę wyświetlaną wywołania. Na przykład Sprawdź stan zatwierdzenia.

  5. Podaj adres URL punktu końcowego dla wywołania interfejsu API.

  6. Wybierz typ uwierzytelniania i skonfiguruj informacje uwierzytelniania na potrzeby wywoływania interfejsu API. Dowiedz się, jak zabezpieczyć łącznik interfejsu API.

    Zrzut ekranu przedstawiający konfigurowanie łącznika interfejsu API.

  7. 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": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "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",
 "ui_locales":"en-US"
}

W żądaniu dostępne są tylko właściwości użytkownika i atrybuty niestandardowe wymienione w środowisku Niestandardowe atrybuty użytkownika przeglądu>tożsamości>>zewnętrznych.

Atrybuty niestandardowe istnieją w formacie extension_<extensions-app-id>_AttributeName 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 dla przepływów rejestracji samoobsługowej.

Ponadto 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.
  • 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 samoobsługowej.

  1. Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako administrator użytkowników.

  2. Przejdź do sekcji Identity External Identities>Overview (Przegląd tożsamości>zewnętrznych).

  3. Wybierz pozycję Przepływy użytkownika, a następnie wybierz przepływ użytkownika, do którego chcesz dodać łącznik interfejsu API.

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

    Wybranie łącznika interfejsu API do użycia w ramach kroku przepływu użytkownika, takiego jak

  5. Wybierz pozycję Zapisz.

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 lub Microsoft Entra ID). Ten krok poprzedza stronę kolekcji atrybutów, która jest formularzem przedstawionym użytkownikowi w celu zbierania atrybutów 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": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

Dokładne oświadczenia wysyłane do interfejsu API zależą od tego, które informacje są dostarczane 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 w identyfikatorze Entra firmy Microsoft.

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

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

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "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",
 "ui_locales":"en-US"
}

Dokładne oświadczenia wysyłane do interfejsu API zależą od tego, które informacje są zbierane od użytkownika lub są dostarczane 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ż przypisane do oświadczenia ze strony 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.

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.

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 Wymagania Opis
version Ciąg Tak Wersja interfejsu API.
action String Tak Wartość musi mieć wartość Continue.
<builtInUserAttribute> <typ-atrybutu> Nie. Wartości mogą być przechowywane w katalogu, jeśli zostały wybrane jako oświadczenie do odbierania w konfiguracji łącznika interfejsu API i atrybuty użytkownika dla przepływu użytkownika. Wartości mogą być zwracane w tokenie, jeśli wybrano je jako oświadczenie aplikacji.
<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 an error with your request. Please try again or contact support.",
}
Parametr Type Wymagania Opis
version Ciąg 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

Przykładowy obraz przedstawiający wygląd środowiska użytkownika końcowego po zwracaniu odpowiedzi blokującej przez interfejs API.

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 Wymagania Opis
version Ciąg Tak Wersja interfejsu API.
action String Tak Wartość musi mieć wartość ValidationError.
status Liczba całkowita/ ciąg Tak Musi być wartością 400lub "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

Przykładowy obraz przedstawiający wygląd środowiska użytkownika końcowego po zwracaniu odpowiedzi na błąd weryfikacji przez interfejs API.

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 temacie Zabezpieczanie łącznika interfejsu API.
  • Interfejs API reaguje tak szybko, jak to możliwe, aby zapewnić płynne środowisko użytkownika.
    • Identyfikator Entra firmy Microsoft czeka maksymalnie 20 sekund na odebranie odpowiedzi. Jeśli żadna z nich nie zostanie odebrana, spowoduje to 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 zalecamy 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.
  • Punkty końcowe muszą być zgodne z wymaganiami firmy Microsoft dotyczącymi protokołu TLS i zabezpieczeń szyfrowania. Aby uzyskać więcej informacji, zobacz Wymagania dotyczące protokołu TLS i pakietu szyfrowania.

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.

Następne kroki