Directory Connector

Directory Connector umożliwia FoxIDs używanie zewnętrznego katalogu jako autorytatywnego źródła haseł użytkowników wewnętrznych i wybranych danych użytkownika.

Użytkownicy nadal istnieją jako użytkownicy wewnętrzni w środowisku FoxIDs. Podczas uwierzytelniania hasłem i operacji w cyklu życia hasła FoxIDs wywołuje API Directory Connector zamiast walidować hasło wyłącznie względem wewnętrznego użytkownika FoxIDs.

Ponieważ FoxIDs utrzymuje wewnętrzny rekord użytkownika, obsługę uwierzytelniania wieloskładnikowego (MFA) w FoxIDs można dodać do użytkowników z zewnętrznego repozytorium. Connector może zwracać ustawienia użytkownika związane z MFA, takie jak requireMultiFactor i wyłączone metody two-factor, a FoxIDs stosuje te ustawienia do użytkownika wewnętrznego, podczas gdy zewnętrzne repozytorium pozostaje autorytatywne dla haseł i wybranych danych użytkownika.

Dla Active Directory FoxIDs zawiera komponent Directory Connector dla Active Directory wdrażalny w IIS.

Użyj Directory Connector, gdy:

  • chcesz, aby użytkownicy logowali się przy użyciu zwykłej metody uwierzytelniania login.
  • chcesz włączyć użytkowników z istniejącego katalogu dla aplikacji OpenID Connect i SAML 2.0 przez FoxIDs.
  • zewnętrzny katalog jest autorytatywny dla walidacji haseł i zmian haseł.
  • chcesz, aby FoxIDs utrzymywał wewnętrzny rekord użytkownika z identyfikatorami, właściwościami, claims, ustawieniami uwierzytelniania wieloskładnikowego (MFA), przydziałami dostępu i opcjonalnie lokalną kopią hasła.
  • chcesz mieć możliwość późniejszego przejścia na użytkowników wewnętrznych i walidację haseł w FoxIDs bez zmuszania wszystkich użytkowników do resetu hasła.

Na każde środowisko przypada jeden Directory Connector. Po włączeniu działa on na poziomie środowiska.

Jak to działa

Gdy użytkownik loguje się przy użyciu nazwy użytkownika i hasła, FoxIDs wywołuje API Directory Connector.

Po pomyślnej walidacji FoxIDs tworzy lub aktualizuje użytkownika wewnętrznego w środowisku na podstawie odpowiedzi API. Odpowiedź musi zawierać stabilne directoryUserId, które jest zapisywane przy użytkowniku wewnętrznym i służy do powiązania użytkownika FoxIDs z użytkownikiem w katalogu zewnętrznym.

directoryUserId nie jest identyfikatorem użytkownika znanym użytkownikowi końcowemu. Jest to oddzielny, stabilny identyfikator w katalogu zewnętrznym. Nie używaj adresu e-mail, telefonu ani nazwy użytkownika jako directoryUserId, ponieważ te wartości mogą się zmieniać. Wartość musi być stabilna i unikalna w katalogu zewnętrznym.

Jeśli FoxIDs zna już directoryUserId użytkownika wewnętrznego, jest ono wysyłane w żądaniu Directory Connector razem z dokładnie jednym z identyfikatorów użytkownika: adresem e-mail, telefonem lub nazwą użytkownika. Dzięki temu katalog zewnętrzny może zidentyfikować użytkownika nawet wtedy, gdy identyfikator się zmienił.

Jeśli API Directory Connector pomyślnie zweryfikuje użytkownika, FoxIDs aktualizuje użytkownika wewnętrznego o identyfikatory, wybrane właściwości i claims zwrócone przez API.

Jeśli connector zgłosi, że użytkownik jest wyłączony lub usunięty, FoxIDs wyłączy lub usunie użytkownika wewnętrznego w środowisku.

Lokalna kopia hasła

Katalog zewnętrzny jest autorytatywny tak długo, jak włączony jest Directory Connector. FoxIDs nie wraca do lokalnego hasha hasła, jeśli API Directory Connector jest tymczasowo niedostępne.

Domyślnie FoxIDs zapisuje lokalną kopię hasła przy użytkowniku wewnętrznym po pomyślnej walidacji hasła przez connector lub po operacji z cyklu życia hasła. Można to wyłączyć w ustawieniach środowiska.

Lokalna kopia hasła nie jest używana, gdy Directory Connector jest włączony. Istnieje po to, aby umożliwić późniejsze przejście na użytkowników wewnętrznych i walidację haseł w FoxIDs bez zmuszania wszystkich użytkowników do resetu hasła.

Cykl życia hasła

Operacje z cyklu życia hasła są delegowane do API Directory Connector:

  • Uwierzytelnianie hasłem wywołuje endpoint authentication.
  • Login create-user flow calls the create-user endpoint.
  • Zmiana hasła użytkownika wywołuje endpoint change-password.
  • Przepływy ustawiania hasła i resetowania hasła wywołują endpoint set-password.

FoxIDs zwykle wywołuje endpointy cyklu życia hasła tylko wtedy, gdy użytkownik wewnętrzny jest znany i ma directoryUserId. Wyjątkiem jest change-password podczas pierwszego logowania, gdy katalog zewnętrzny zwrócił password_expired, zanim FoxIDs utworzył użytkownika wewnętrznego. W takim przypadku FoxIDs wysyła identyfikator logowania i bieżące hasło bez directoryUserId; po pomyślnej zmianie hasła FoxIDs używa odpowiedzi sukcesu do utworzenia użytkownika wewnętrznego i zapisania zwróconego directoryUserId.

FoxIDs nie aktualizuje swojej wewnętrznej historii haseł, gdy używany jest Directory Connector, ponieważ FoxIDs nie musi znać wszystkich zmian haseł w katalogu zewnętrznym.

Polityka haseł i komunikaty o błędach

Katalog zewnętrzny egzekwuje politykę haseł. FoxIDs używa polityki haseł środowiska podczas wyświetlania komunikatów o błędach polityki haseł zwracanych przez connector.

Skonfiguruj politykę haseł środowiska tak, aby odpowiadała polityce haseł katalogu zewnętrznego. Jeśli nie są zgodne, użytkownicy mogą widzieć wskazówki dotyczące haseł, które nie odzwierciedlają rzeczywistych wymagań katalogu zewnętrznego.

Na przykład, jeśli katalog zewnętrzny odrzuci hasło, ponieważ jest zbyt krótkie, FoxIDs użyje minimalnej długości hasła z konfiguracji środowiska podczas renderowania komunikatu o błędzie.

Implementacja API

Implementujesz API Directory Connector i konfigurujesz FoxIDs za pomocą bazowego adresu URL i sekretu.

The API has a base URL and four endpoints:

  • authentication waliduje bieżące hasło użytkownika.
  • create-user creates a new user in the external directory and returns the created user.
  • change-password waliduje bieżące hasło i zmienia je na nowe.
  • set-password ustawia nowe hasło bez walidacji bieżącego hasła.

Jeśli bazowy adres URL to https://somewhere.org/directory, endpointy są następujące:

  • https://somewhere.org/directory/authentication
  • https://somewhere.org/directory/create-user
  • https://somewhere.org/directory/change-password
  • https://somewhere.org/directory/set-password

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

Bezpieczeństwo

Żądania są zabezpieczone za pomocą HTTP Basic authentication:

  • Nazwa użytkownika: directory_connector
  • Hasło: skonfigurowany sekret API

Wywołanie jest wykonywane metodą HTTP POST z ciałem JSON.

Żądanie authentication

Endpoint authentication otrzymuje hasło użytkownika i dokładnie jeden identyfikator użytkownika. FoxIDs wysyła directoryUserId, jeśli użytkownik wewnętrzny istnieje i wartość jest znana.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "password": "testpass1"
}

Pola:

  • directoryUserId jest opcjonalne. FoxIDs wysyła je, gdy użytkownik wewnętrzny istnieje i wartość jest znana.
  • Wysyłane jest dokładnie jedno z pól email, phone lub username.
  • password jest wymagane.

FoxIDs wybiera identyfikator na podstawie danych logowania podanych przez użytkownika i włączonych ustawień identyfikatorów. Na przykład, jeśli włączona jest tylko nazwa użytkownika, a użytkownik wpisze user1@somewhere.org, FoxIDs wyśle tę wartość jako username.

Create-user request

Endpoint create-user otrzymuje dokładnie jeden identyfikator użytkownika, wymagane hasło, wybrane właściwości create-user oraz claims zebrane podczas przepływu create-user w FoxIDs.

{
  "email": "user1@somewhere.org",
  "password": "testpass1",
  "confirmAccount": true,
  "requireMultiFactor": false,
  "claims": [
    { "type": "given_name", "value": "User" },
    { "type": "family_name", "value": "One" }
  ]
}

Fields:

  • Exactly one of email, phone, or username is sent.
  • password jest wymagane. Utwórz użytkownika bez hasła nie jest obsługiwane z Directory Connector, ponieważ API Directory Connector uwierzytelnia użytkowników hasłem.
  • confirmAccount and requireMultiFactor are the requested FoxIDs create-user settings.
  • claims contains the non-identifier claims collected during the FoxIDs create-user flow.

On success, return a normal success response. FoxIDs stores the returned directoryUserId on the internal user created after the external directory user has been created.

Żądanie change-password

Endpoint change-password otrzymuje dokładnie jeden identyfikator użytkownika, bieżące hasło i nowe hasło. FoxIDs wysyła directoryUserId, gdy użytkownik wewnętrzny istnieje i wartość jest znana.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "currentPassword": "oldpass1",
  "newPassword": "newpass1"
}

Pola:

  • directoryUserId jest opcjonalne. FoxIDs wysyła je, gdy użytkownik wewnętrzny istnieje i wartość jest znana. Może zostać pominięte podczas pierwszego logowania, jeśli katalog zewnętrzny wymaga zmiany hasła, zanim FoxIDs utworzy użytkownika wewnętrznego.
  • Wysyłane jest dokładnie jedno z pól email, phone lub username.
  • currentPassword i newPassword są wymagane.

Żądanie set-password

Endpoint set-password otrzymuje stabilne powiązanie użytkownika z katalogiem, dokładnie jeden identyfikator użytkownika oraz nowe hasło.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "password": "newpass1"
}

Pola:

  • directoryUserId jest wysyłane i powinno być używane jako stabilne powiązanie z katalogiem.
  • Wysyłane jest dokładnie jedno z pól email, phone lub username. FoxIDs wybiera pierwszy dostępny wewnętrzny identyfikator użytkownika w kolejności: e-mail, telefon, nazwa użytkownika.
  • password jest wymagane.

Odpowiedź sukcesu

W przypadku sukcesu API musi zwrócić kod stanu HTTP 200 oraz odpowiedź użytkownika.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "phone": "+4511223344",
  "username": "user1",
  "confirmAccount": true,
  "emailVerified": true,
  "phoneVerified": true,
  "disableTwoFactorApp": false,
  "disableTwoFactorSms": false,
  "disableTwoFactorEmail": false,
  "requireMultiFactor": false,
  "claims": [
    { "type": "name", "value": "User One" },
    { "type": "role", "value": "employee" }
  ]
}

FoxIDs używa odpowiedzi do utworzenia lub zaktualizowania użytkownika wewnętrznego w środowisku.

Pola:

  • directoryUserId jest wymagane. Musi być stabilne i unikalne w katalogu zewnętrznym i jest zapisywane przy użytkowniku wewnętrznym FoxIDs.
  • email, phone i username są opcjonalne indywidualnie, ale co najmniej jedno z nich musi być obecne. FoxIDs zapisuje zwrócone wartości jako identyfikatory użytkownika wewnętrznego. Zwrócone wartości identyfikatorów użytkownika muszą jednoznacznie identyfikować jednego użytkownika w katalogu zewnętrznym używanym przez connector.
  • phone musi zawierać numer kierunkowy kraju w formacie międzynarodowym, na przykład +4511223344.
  • confirmAccount określa, czy FoxIDs ma uruchomić przepływ potwierdzenia dla użytkownika wewnętrznego.
  • emailVerified określa, czy adres e-mail użytkownika wewnętrznego ma zostać oznaczony jako zweryfikowany.
  • phoneVerified określa, czy numer telefonu użytkownika wewnętrznego ma zostać oznaczony jako zweryfikowany.
  • disableTwoFactorApp wyłącza uwierzytelnianie dwuskładnikowe przy użyciu aplikacji authenticator dla użytkownika wewnętrznego.
  • disableTwoFactorSms wyłącza uwierzytelnianie dwuskładnikowe SMS dla użytkownika wewnętrznego.
  • disableTwoFactorEmail wyłącza uwierzytelnianie dwuskładnikowe e-mail dla użytkownika wewnętrznego.
  • requireMultiFactor określa, czy użytkownik wewnętrzny musi używać uwierzytelniania wieloskładnikowego.
  • claims są opcjonalne. FoxIDs zapisuje zwrócone claims przy użytkowniku wewnętrznym.

Odpowiedź błędu

Jeśli Basic authentication zostanie odrzucone, zwróć kod stanu HTTP 401 i invalid_api_id_secret.

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

Jeśli użytkownik nie istnieje podczas wywołania endpointu authentication, zwróć kod stanu HTTP 400, 401 lub 403 i user_not_exists.

{
  "error": "user_not_exists",
  "errorMessage": "User not found."
}

Jeśli hasło zostanie odrzucone przez endpoint authentication, zwróć kod stanu HTTP 400, 401 lub 403 i invalid_password.

{
  "error": "invalid_password",
  "errorMessage": "Invalid password."
}

Jeśli bieżące hasło zostanie odrzucone przez endpoint change-password, zwróć kod stanu HTTP 400, 401 lub 403 i invalid_current_password.

{
  "error": "invalid_current_password",
  "errorMessage": "Invalid current password."
}

Pole errorMessage jest logowane przez FoxIDs i nie jest pokazywane użytkownikowi końcowemu.

Supported error codes by endpoint:

Error code authentication create-user change-password set-password Meaning
invalid_api_id_secret Yes Yes Yes Yes The HTTP Basic API username or secret is invalid.
user_exists No Yes No No A user with the supplied identifier already exists in the external directory.
user_not_exists Yes, without DirectoryUserId No Yes, without DirectoryUserId No No external directory user matched the supplied user identifiers.
invalid_password Yes No No No The password in an authentication request was rejected by the directory.
invalid_current_password No No Yes No The current password in a change-password request was rejected by the directory.
create_user_not_supported No Yes No No The connector does not support creating users in the external directory.
user_disabled Yes No Yes Yes The user exists in the directory but is disabled. FoxIDs will disable the internal user.
user_deleted Yes, with DirectoryUserId No Yes, with DirectoryUserId Yes, with DirectoryUserId The external directory user linked by DirectoryUserId no longer exists or is deleted. FoxIDs will delete the internal user.
password_not_accepted Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set was rejected by a directory password rule that does not map to a more specific code.
password_min_length Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is shorter than the directory password minimum length.
password_max_length Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is longer than the directory password maximum length.
password_banned_characters Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains one or more characters or words rejected by the directory.
password_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set does not satisfy the directory complexity requirements.
password_email_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains the user's email or part of it.
password_phone_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains the user's phone number or part of it.
password_username_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains the user's username or part of it.
password_url_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains text related to the FoxIDs URL.
password_risk Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is known to be risky, compromised, or otherwise unsafe.
password_history Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set was rejected because it has been used before.
password_expired Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is expired and must be changed before authentication can continue.
new_password_equals_current No No Yes No The new password is the same as the current password. set-password cannot return this error because it does not receive the current password.

W przypadku błędów polityki haseł FoxIDs używa polityki haseł środowiska do wyświetlenia komunikatu o błędzie dla użytkownika. Zobacz Polityka haseł i komunikaty o błędach.

Jeśli wystąpią inne błędy, zwróć kod stanu HTTP 500 lub inny odpowiedni kod błędu. Dołącz techniczny errorMessage, jeśli jest przydatny diagnostycznie.

Przykład API

Przykład DirectoryConnectorApiSample pokazuje, jak zaimplementować API Directory Connector w ASP.NET Core.

Przykład obejmuje:

  • endpointy authentication, create-user, change-password i set-password.
  • HTTP Basic authentication z nazwą użytkownika API directory_connector.
  • mały katalog in-memory z użytkownikami demonstracyjnymi i stabilnymi wartościami directoryUserId.
  • przykłady błędów polityki haseł, takich jak password_min_length, password_banned_characters i new_password_equals_current.
  • przykład wyłączonego użytkownika, który zwraca user_disabled.

Kolekcji Postman directory-connector-api.postman_collection.json można użyć do wywoływania i testowania przykładowego API za pomocą Postman.

Komponent Active Directory

FoxIDs zawiera komponent Directory Connector dla Active Directory, który można wdrożyć w IIS. Komponent implementuje API Directory Connector dla jednej domeny AD/LDAP i może walidować hasła, zmieniać hasła, ustawiać hasła, zwracać skonfigurowane atrybuty AD jako claims oraz zwracać skonfigurowane zagnieżdżone członkostwa w grupach AD jako claims.

Konfiguracja

Skonfiguruj Directory Connector w ustawieniach środowiska w FoxIDs Control Client.

  1. Wybierz kartę Settings.
  2. Wybierz kartę Environment.
  3. Znajdź sekcję Directory Connector.
  4. Włącz Directory Connector.
  5. Dodaj bazowy adres URL API bez folderu endpointu w polu API URL.
  6. Dodaj API secret.
  7. Zdecyduj, czy lokalna kopia hasła ma być zapisywana.
  8. Skonfiguruj politykę haseł środowiska tak, aby odpowiadała polityce haseł katalogu zewnętrznego.
  9. Kliknij Update.

Ustawienia Directory Connector

Twoja prywatność

Twoja prywatność

Używamy plików cookie, aby poprawić korzystanie z naszych stron internetowych. Kliknij przycisk „Akceptuj wszystkie pliki cookie”, aby wyrazić zgodę na ich użycie. Aby zrezygnować z nieistotnych plików cookie, kliknij „Tylko niezbędne pliki cookie”.

Odwiedź naszą politykę prywatności, aby dowiedzieć się więcej