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.

Użyj Directory Connector, gdy:

  • chcesz, aby użytkownicy logowali się przy użyciu zwykłej metody uwierzytelniania login.
  • 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 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.
  • 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 wywołuje endpointy cyklu życia hasła tylko wtedy, gdy użytkownik wewnętrzny jest znany i ma directoryUserId. Zapobiega to wywoływaniu katalogu zewnętrznego bez stabilnego powiązania z użytkownikiem zewnętrznym.

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.

API ma bazowy adres URL i trzy endpointy:

  • authentication waliduje bieżące hasło użytkownika.
  • 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/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.

Żądanie change-password

Endpoint change-password otrzymuje stabilne powiązanie użytkownika z katalogiem, dokładnie jeden identyfikator użytkownika, bieżące hasło i nowe hasło.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "currentPassword": "oldpass1",
  "newPassword": "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.
  • 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,
  "disableAccount": false,
  "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 osobno, ale co najmniej jedno z nich musi być obecne. FoxIDs zapisuje zwrócone wartości jako identyfikatory użytkownika wewnętrznego.
  • 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.
  • disableAccount określa, czy użytkownik wewnętrzny zostanie wyłączony w FoxIDs po synchronizacji.
  • 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 kombinacja nazwy użytkownika i hasła zostanie odrzucona przez endpoint authentication, zwróć kod stanu HTTP 400, 401 lub 403 i invalid_username_password.

{
  "error": "invalid_username_password",
  "errorMessage": "Invalid username or 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.

Obsługiwane kody błędów:

  • invalid_username_password - Kombinacja identyfikatora użytkownika i hasła została odrzucona przez katalog.
  • invalid_current_password - Bieżące hasło w żądaniu change-password zostało odrzucone przez katalog.
  • user_disabled - Użytkownik istnieje w katalogu, ale jest wyłączony. FoxIDs wyłączy użytkownika wewnętrznego.
  • user_deleted - Użytkownik już nie istnieje lub został usunięty z katalogu. FoxIDs usunie użytkownika wewnętrznego.
  • password_not_accepted - Nowe hasło zostało odrzucone przez regułę haseł katalogu, której nie da się przypisać do bardziej szczegółowego kodu.
  • password_min_length - Nowe hasło jest krótsze niż minimalna długość hasła w katalogu.
  • password_max_length - Nowe hasło jest dłuższe niż maksymalna długość hasła w katalogu.
  • password_banned_characters - Nowe hasło zawiera jeden lub więcej znaków albo słów odrzucanych przez katalog.
  • password_complexity - Nowe hasło nie spełnia wymagań złożoności katalogu.
  • password_email_text_complexity - Nowe hasło zawiera adres e-mail użytkownika lub jego część.
  • password_phone_text_complexity - Nowe hasło zawiera numer telefonu użytkownika lub jego część.
  • password_username_text_complexity - Nowe hasło zawiera nazwę użytkownika użytkownika lub jej część.
  • password_url_text_complexity - Nowe hasło zawiera tekst odnoszący się do adresu URL FoxIDs.
  • password_risk - Nowe hasło jest znane jako ryzykowne, przejęte lub w inny sposób niebezpieczne.
  • password_history - Nowe hasło zostało odrzucone, ponieważ było już wcześniej używane.
  • password_expired - Bieżące hasło wygasło i musi zostać zmienione przed kontynuowaniem uwierzytelniania.
  • new_password_equals_current - Nowe hasło jest takie samo jak bieżące hasło.

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, 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 Active Directory Directory Connector, 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