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.

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

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