Zewnętrzne logowanie - API

Dzięki zewnętrznemu logowaniu możesz uwierzytelniać użytkowników w istniejącej bazie danych użytkowników przez wywołanie API. Implementujesz API; FoxIDs wywołuje je z nazwą użytkownika i hasłem, a API weryfikuje kombinację i zwraca sukces lub porażkę. Użyj metody uwierzytelniania External login, gdy chcesz wykorzystać istniejący magazyn użytkowników jako źródło uwierzytelniania w FoxIDs. Po pomyślnym logowaniu możesz tworzyć użytkowników zewnętrznych i opcjonalnie wyświetlić dialog do zebrania np. imienia lub adresu e-mail.

Jeśli chcesz, aby użytkownicy pozostali użytkownikami wewnętrznymi w środowisku FoxIDs, podczas gdy uwierzytelnianie hasłem i cykl życia hasła są delegowane do zewnętrznego katalogu, użyj zamiast tego Directory Connector.

Z czasem możesz migrować użytkowników do FoxIDs i wycofać zewnętrzne API oraz magazyn użytkowników.

Przegląd pojęć użytkowników (użytkownicy wewnętrzni, użytkownicy zewnętrzni i zewnętrzne magazyny użytkowników) znajdziesz w przeglądzie użytkowników.

Zewnętrzne logowanie obsługuje dwa typy identyfikatorów użytkownika (username):

  • Email - adres e-mail użytkownika
  • Text - dowolna nazwa użytkownika w formie tekstowej

Jeśli wybierzesz typ tekstowy, format nie jest walidowany w FoxIDs (dozwolone są formaty mieszane, w tym adresy e-mail). Home realm discovery (HRD) oparte na domenie jest dostępne tylko dla typu e-mail.

Domyślny interfejs zewnętrznego logowania z nazwą użytkownika typu tekstowego: Interfejs zewnętrznego logowania

Interfejs można dostosować.

Implementuj API

Musisz zaimplementować proste API, które FoxIDs wywołuje dla każdego żądania uwierzytelnienia (zobacz przykład).

API ma bazowy URL; funkcjonalność jest pogrupowana w foldery. Obecnie obsługiwany jest tylko folder authentication (walidacja nazwy użytkownika i hasła). Foldery do zmiany hasła i tworzenia użytkowników mogą zostać dodane później.

Jeśli bazowy URL to https://somewhere.org/mystore, punkt końcowy uwierzytelniania to: https://somewhere.org/mystore/authentication

FoxIDs Cloud wywołuje Twoje API z adresu IP 57.128.60.142. Adresy IP mogą się zmieniać lub zostać rozszerzone.

Żądanie

Zabezpieczone HTTP Basic auth: nazwa użytkownika external_login, hasło = skonfigurowany sekret.

Wywołanie jest HTTP POST z treścią JSON.

Możesz skonfigurować dodatkowe parametry; są one dołączane do ładunku JSON.

Żądanie dla typu e-mail:

{
  "usernameType": 100,
  "username": "user1@somewhere.org",
  "password": "testpass1"
}

Żądanie dla typu tekstowego:

{
  "usernameType": 200,
  "username": "user1",
  "password": "testpass1"
}

Kody typu nazwy użytkownika:

  • email = 100
  • text = 200

Odpowiedź

Sukces W przypadku sukcesu API powinno zwrócić kod HTTP 200 i opcjonalnie listę claims dla uwierzytelnionego użytkownika.

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 sub użytkownika (unikalny ID / nazwa użytkownika), imię, e-mail i np. rola:

{
  "claims": [
    { "type": "sub", "value": "somewhere/user2" },
    { "type": "given_name", "value": "Joe" },
    { "type": "family_name", "value": "Smith" },
    { "type": "email", "value": "user2@somewhere.org" },
    { "type": "role", "value": "some_access" }
  ]
}

Błąd API musi zwrócić kod HTTP 401 (Unauthorized) oraz error (wymagany), 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 musi zwrócić kod HTTP 400, 401 lub 403 oraz error (wymagany), jeśli kombinacja nazwy użytkownika i hasła zostanie odrzucona. Opcjonalnie dodaj opis błędu w ErrorMessage.

{
  "error": "invalid_username_password",
  "ErrorMessage": "Invalid username or password."
}

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 do diagnostyki (jest tylko logowany; nigdy nie jest pokazywany użytkownikowi końcowemu).

Przykład API

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

Kolekcja Postman external-login-api.postman_collection.json do wywoływania i testowania API w Postman.

Konfiguracja

Skonfiguruj metodę uwierzytelniania zewnętrznego logowania API w FoxIDs Control Client.

  1. Przejdź do karty Authentication
  2. Kliknij New authentication
  3. Wybierz Show advanced
  4. Wybierz External API Login
  5. Dodaj Name
  6. Wybierz Username type (np. Text)
  7. Dodaj bazowy URL API bez folderu authentication w API URL
  8. Dodaj API secret Skonfiguruj metodę uwierzytelniania zewnętrznego logowania
  9. Kliknij Create

Opcjonalnie kliknij Show advanced w prawym górnym rogu sekcji konfiguracji, aby dostosować interfejs logowania.