Extended UI

Możesz rozszerzyć przepływ logowania (UI) o niestandardowe strony logowania zbudowane z elementów dynamicznych. Extended UI w pełni obsługuje kulturę i wiele języków. Można tworzyć wiele niestandardowych UI z różnymi elementami dynamicznymi. Każda strona Extended UI może opcjonalnie wywołać API. Jeśli API zostanie wywołane, zwrócone oświadczenia są dodawane do kolekcji oświadczeń; w przeciwnym razie wartości wejściowe są dodawane jako typy oświadczeń wyjściowych zdefiniowane na elementach dynamicznych.

Elementy dynamiczne składają się z pól stałych, pola konfigurowalnego oraz elementów tekstowych i HTML. Dzięki temu łatwo możesz poprosić użytkownika o imię i nazwisko, użyć jednego lub więcej własnych pól i wyświetlić logo oraz link na stronie Extended UI.

Extended UI można dodać do następujących metod uwierzytelniania w zakładce Extended UI: login, external login, OpenID Connect, SAML 2.0 oraz environment link.

Wybór strony Extended UI Wybierasz stronę Extended UI w przepływie logowania, dodając typ oświadczenia open_extended_ui z nazwą strony Extended UI w transformacjach oświadczeń pierwszego poziomu. W metodzie uwierzytelniania SAML 2.0 wybierasz stronę Extended UI przy użyciu odpowiadającego oświadczenia SAML 2.0 http://schemas.foxids.com/ws/identity/claims/openextendedui w transformacjach oświadczeń pierwszego poziomu. Następnie kolejne strony Extended UI można wybierać w transformacjach oświadczeń Extended UI przez dodanie typu oświadczenia open_extended_ui (tylko oświadczenie JWT) z nazwą kolejnej strony Extended UI.

Przykład Ta strona prosi użytkownika o podanie numeru PESEL (pokazane w dwóch językach). Przykładowe Extended UI dodaje wartość wejściową do kolekcji oświadczeń jako typ oświadczenia social_security_number. W rzeczywistym scenariuszu prawdopodobnie wywołasz API w celu walidacji numeru PESEL. W języku angielskim: Extended UI with Social security number field in English

W języku duńskim: Extended UI with Social security number field in Danish

Przykładowa strona jest skonfigurowana w metodzie uwierzytelniania w zakładce Extended UI z trzema elementami.

Configure Extended UI with Social security number input field

Extended UI można dostosować CSS w metodzie uwierzytelniania login o nazwie Default login, chyba że utworzysz inną metodę login i użyjesz jej zamiast tego. Zapewnia to dużą elastyczność w projektowaniu okien dialogowych.

Tłumaczenia

Teksty (i komunikaty błędów) używane w elementach dynamicznych są automatycznie tłumaczone, jeśli są zdefiniowane jako teksty globalne z tłumaczeniami. W przeciwnym razie element tekstowy jest automatycznie tworzony w środowiskach, gdzie można dodać tłumaczenia. Jeśli chcesz obsługiwać wiele języków, powinieneś tworzyć teksty po angielsku i dodawać tłumaczenia.

Teksty i tłumaczenia znajdziesz w zakładce Settings, a następnie Texts. Configure Extended UI with Social security number input field

Implementacja API

Każda strona Extended UI może wywołać API z wynikiem elementów dynamicznych i wybranymi oświadczeniami. API może wtedy zweryfikować dane użytkownika i w przypadku sukcesu zwrócić oświadczenia albo zwrócić komunikat błędu.

Musisz zaimplementować proste API, które FoxIDs wywołuje, gdy użytkownik wyśle formularz. Zobacz kod przykładowy.

API ma bazowy URL, a funkcjonalność jest podzielona na foldery. Obecnie obsługiwany jest tylko folder validate (funkcjonalność) do walidacji elementów dynamicznych i wybranych oświadczeń. Inne foldery mogą zostać dodane w przyszłości.

Jeśli bazowy URL API to https://somewhere.org/mystore, URL folderu validate będzie https://somewhere.org/mystore/validate.

FoxIDs Cloud wywołuje Twoje API z adresu IP 57.128.60.142. Adresy IP wychodzące mogą się zmieniać i z czasem mogą zostać dodane kolejne.

Żądanie

Wywołanie API jest zabezpieczone HTTP Basic authentication, gdzie FoxIDs wysyła ID external_extended_ui jako nazwę użytkownika oraz skonfigurowany sekret jako hasło.

API jest wywoływane przez HTTP POST z ciałem JSON.

FoxIDs wysyła wybrany język w nagłówku żądania Accept-Language, na przykład Accept-Language: da-DK. W procesie logowania odpowiada on językowi wybranemu przez ui_locales lub przeglądarkę, a FoxIDs używa angielskiego jako języka zastępczego. API może użyć tego nagłówka do lokalizacji komunikatów dla użytkownika i musi wybrać własny język zastępczy, jeśli nie obsługuje żądanego języka.

To przykładowe ciało JSON z dwoma elementami dynamicznymi i dwoma oświadczeniami:

{
 "elements": [
        {
            "Name": "ne5uqp5z",
            "Type": "Email",
            "ClaimType": "email",
            "Value": "some@test.org"
        },
        {
            "Name": "ktvywqwc",
            "Type": "Custom",
            "ClaimType": "my_claim",
            "Value": "123456"
        }
    ],
 "claims": [
        {
            "type": "sub",
            "value": "1b1ac05e-5937-4939-a49c-0e84a89662df"
        },
        {
            "type": "email",
            "value": "some_other@test.org"
        }
    ]
}

Odpowiedź

Sukces W przypadku sukcesu API powinno zwrócić kod HTTP 200 i listę claims (lista może być pusta).

FoxIDs ignoruje oświadczenia, w których pole type lub value nie występuje, ma wartość null, jest puste lub zawiera wyłącznie białe znaki. Gdy rejestrowanie śladów komunikatów jest włączone, ślad odpowiedzi zawiera otrzymane oświadczenia przed ich filtrowaniem. Długie komunikaty śledzenia są obcinane.

Na przykład poprawne wartości wejściowe jako oświadczenia:

{
    "claims": [
        {
            "type": "email",
            "value": "some@test.org"
        },
        {
            "type": "my_claim",
            "value": "123456"
        }
    ]
}

Błąd API musi zwrócić kod HTTP 401 (Unauthorized) i error (wymagane), jeśli Basic auth zostanie odrzucone. Opcjonalnie dodaj opis błędu w ErrorMessage.

{
    "error": "invalid_api_id_secret",
    "ErrorMessage": "Invalid API ID or secret"
}

API może zwrócić kod HTTP 400 (401 i 403 również są obsługiwane) i error (wymagane), jeśli dane wejściowe są odrzucone. Opcjonalnie dodaj komunikat błędu dla użytkownika w UiErrorMessage oraz opis błędu w ErrorMessage. UiErrorMessage jest tłumaczone jako tekst i powinno być po angielsku, jeśli chcesz obsługiwać wiele języków.

Ogólny błąd walidacji:

{
    "error": "invalid",
    "ErrorMessage": "Something is not accepted.",
    "UiErrorMessage": "Please change the thing that is wrong."
}

Błąd walidacji powiązany z elementem dynamicznym po nazwie elementu:

{
    "error": "invalid",
    "elements": [
           {
               "Name": "ktvywqwc",
               "ErrorMessage": "The element is not valid because of something.",
               "UiErrorMessage": "Please change the value to the correct value."
           }
       ]
}

Jeśli wystąpią inne błędy, API powinno zwrócić kod HTTP 500 lub inny odpowiedni kod błędu. Zaleca się dodanie technicznego komunikatu błędu w ErrorMessage. Komunikat błędu będzie wtedy później dostępny w logach FoxIDs.

Komunikaty błędów zwrócone przez API w ErrorMessage NIE są wyświetlane użytkownikowi; są tylko logowane.

Przykład API

Przykład ExternalExtendedUiApiSample pokazuje, jak zaimplementować API w ASP.NET Core.

Możesz użyć tej kolekcji Postman do wywoływania i testowania API w Postman.

Konfiguracja

Skonfiguruj stronę Extended UI w metodzie uwierzytelniania, aby wywoływała Twoje API w FoxIDs Control Client.

Przejdź do zakładki Authentication, wybierz metodę uwierzytelniania, a następnie zakładkę Extended UI. Znajdź stronę Extended UI i skonfiguruj API.

Configure extended UI API

  • Opcjonalnie wybierz oświadczenia, które mają być wysyłane do API.
  • Dodaj bazowy URL API bez folderu validate w polu API URL
  • Dodaj API secret
  • Dodaj ogólny komunikat błędu wyświetlany użytkownikowi, jeśli API zwróci błąd bez UiErrorMessage