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
FoxIDs synchronizuje dane na żądanie, gdy użytkownik podaje identyfikator podczas logowania lub odzyskiwania dostępu. Przed sprawdzeniem konta wywołuje synchronise-user, w razie potrzeby tworzy użytkownika FoxIDs i aktualizuje identyfikatory, właściwości oraz claims zarządzane przez katalog.
Synchronizacja jest częścią włączenia Directory Connector. FoxIDs synchronizuje dane na początku logowania, odzyskiwania dostępu i sprawdzania kont istniejących sesji oraz przy użyciu refresh tokena dla konta powiązanego z katalogiem. Dalsze kroki z kodami potwierdzającymi, MFA i Extended UI korzystają z wybranego konta i standardowych kontroli FoxIDs. Nieudana synchronizacja zatrzymuje proces.
Odpowiedź musi zawierać stabilny, unikatowy directoryUserId. Użyj trwałego ID konta w katalogu zamiast adresu e-mail, telefonu lub nazwy użytkownika. Dzięki temu powiązaniu FoxIDs odnajduje to samo konto po zmianie identyfikatorów. Zarejestrowane aplikacje uwierzytelniające i przypisania dostępu FoxIDs zostają zachowane.
Gdy użytkownik podaje identyfikator, FoxIDs wysyła wyłącznie ten adres e-mail, numer telefonu lub nazwę użytkownika. Przy ponownym użyciu sesji i żądaniach z refresh tokenem FoxIDs wczytuje powiązanego użytkownika i synchronizuje według zapisanego na nim ID katalogowego. Operacje na hasłach również używają ID wczytanego użytkownika. Nie jest ono zapisywane osobno w sekwencji logowania.
Konektor zwraca komplet aktualnych danych użytkownika. FoxIDs zastępuje identyfikatory, właściwości i claims zarządzane przez katalog, w tym stan wyłączenia konta, wymagania zmiany hasła i ustawienia początkowego nadania hasła. Stosuje takie same kontrole konta, odzyskiwania dostępu i MFA jak dla użytkowników wewnętrznych. Użytkownicy wewnętrzni bez powiązania z katalogiem nie są synchronizowani ani automatycznie wiązani.
Odpowiedź synchronizacji z disableAccount: true wyłącza użytkownika FoxIDs i unieważnia jego aktywne sesje oraz refresh-token grants. Jeśli przy synchronizacji według ID katalogowego konektor zwróci user_deleted, FoxIDs usuwa użytkownika wewnętrznego i unieważnia aktywne sesje oraz refresh tokeny. Jeśli wyszukiwanie wyłącznie po identyfikatorze nie znajdzie konta, przed kontynuacją FoxIDs sprawdza istniejące powiązanie katalogowe, aby nieaktualne dane lokalne nie umożliwiały logowania ani odzyskiwania dostępu. Sam kod user_not_exists nie usuwa konta.
Żądania z refresh tokenem sprawdzają konto pierwotne oraz konto lokalne używane w ramach impersonacji, jeśli są powiązane z katalogiem. Wykrycie konta wyłączonego lub usuniętego podczas synchronizacji powoduje unieważnienie aktywnych sesji i refresh-token grants oraz odrzucenie bieżącego odnowienia tokena. Zwykła kontrola aktywnej sesji sprawdza jej stan w FoxIDs; sama nie kontaktuje się z katalogiem. Aplikacja lokalnie weryfikująca wydany access token uwzględnia jego wygaśnięcie, a nie unieważnienie sesji FoxIDs.
Zmiany są uwzględniane przy następnej kontroli konta na żądanie. Nie ma procesu synchronizacji w tle.
Directory Connector może służyć jako stała integracja, w której użytkownicy i hasła są zarządzani w katalogu zewnętrznym, lub do stopniowej migracji do FoxIDs. Podczas migracji pozostaw konektor włączony w trakcie tworzenia użytkowników i włącz lokalną kopię hasła, aby zapisywać hasła po udanym uwierzytelnieniu, zmianie lub zresetowaniu przez FoxIDs.
Po zakończeniu migracji wyłącz Directory Connector i zarządzaj użytkownikami oraz hasłami bezpośrednio w FoxIDs. Przed przełączeniem utwórz użytkowników, którzy jeszcze nie istnieją, i zapewnij ustawienie lub odzyskanie hasła osobom bez aktualnej kopii lokalnej. Kopia odzwierciedla ostatnie udane uwierzytelnienie, zmianę lub reset przez FoxIDs; późniejsze zmiany wyłącznie w katalogu zewnętrznym nie są uwzględniane.
Ochrona wyszukiwania
Gdy użytkownik wpisuje e-mail, telefon lub nazwę użytkownika w interfejsie logowania bądź odzyskiwania dostępu, wyszukiwanie katalogowe wlicza się do wspólnego limitu wszystkich identyfikatorów bieżącej sekwencji. Limit używa ustawień środowiska Failed login attempt limit, czasu życia licznika i okresu obserwacji. Liczą się zarówno udane wyszukiwania, jak i nieudane wywołania konektora; udane uwierzytelnienie hasłem nie zeruje tego licznika. Po osiągnięciu limitu trzeba odczekać okres obserwacji lub rozpocząć nową sekwencję. Synchronizacja przy ponownym użyciu sesji i żądaniach z refresh tokenem nie używa tego licznika. Ochrona haseł i kodów potwierdzających nadal korzysta z istniejących oddzielnych liczników.
Identyfikatory logowania i powiązanie z katalogiem
Użytkownicy mogą logować się aktualnym adresem e-mail, telefonem lub nazwą użytkownika, zgodnie z typami włączonymi w metodzie logowania. Przed uwierzytelnieniem hasłem wpisany identyfikator musi odpowiadać jednemu z aktualnych identyfikatorów zwróconych przez konektor. FoxIDs usuwa białe znaki na początku i końcu. E-maile i nazwy użytkowników są porównywane bez rozróżniania wielkości liter. Telefony używają wymaganego formatu międzynarodowego.
Logowanie po zmianie identyfikatorów
Po podaniu identyfikatora FoxIDs synchronizuje e-mail, telefon i nazwę użytkownika z katalogu. Stabilne ID katalogowe utrzymuje powiązanie z tym samym kontem FoxIDs, nawet gdy zmieni się jeden lub wszystkie identyfikatory. Aplikacje uwierzytelniające i przypisania dostępu zostają zachowane, a istniejące ograniczenia dostępu i wymagania MFA nadal obowiązują.
| Sytuacja | Co dzieje się podczas synchronizacji |
|---|---|
| Użytkownik loguje się niezmienioną nazwą użytkownika, ale jego e-mail lub telefon zmienił się w katalogu. | FoxIDs aktualizuje to samo konto aktualnymi identyfikatorami z konektora. |
| Użytkownik loguje się nowym identyfikatorem, którego FoxIDs jeszcze nie zna. | Jeśli katalog zwróci nowy identyfikator i to samo stabilne ID, użytkownik kontynuuje na istniejącym koncie FoxIDs. Działa to również po zmianie wszystkich identyfikatorów. |
| Użytkownik loguje się starym identyfikatorem, którego konektor już nie zwraca. | Logowanie jest odrzucane ze zwykłym błędem, nawet jeśli użytkownik nadal zna hasło. Musi użyć aktualnego identyfikatora włączonego typu. |
| Konektor przestaje zwracać e-mail, telefon lub nazwę użytkownika. | Ten identyfikator jest usuwany z konta FoxIDs podczas synchronizacji. Konektor musi zwrócić przynajmniej jeden aktualny identyfikator. |
Na przykład po zmianie e-maila z old@example.org na new@example.org użytkownik może zalogować się przez new@example.org, zanim FoxIDs pozna ten adres. Konektor musi zwrócić new@example.org i niezmienione ID katalogowe. Konto i zarejestrowane aplikacje uwierzytelniające zostają zachowane. Można też użyć niezmienionej nazwy użytkownika, jeśli takie logowanie jest włączone.
Konektor musi zwracać wszystkie aktualne identyfikatory, które FoxIDs ma zachować. Pominięte lub puste wartości oznaczają usunięte identyfikatory; wcześniejsze wartości nie pozostają aliasami logowania. Logować można się tylko typami włączonymi w metodzie logowania.
Konflikty kont
Każdy użytkownik katalogowy musi mieć stabilne, unikatowe ID, a jego identyfikatory nie mogą należeć do innego konta FoxIDs. FoxIDs najpierw wyszukuje wpisany identyfikator w katalogu, a następnie używa zwróconego ID do znalezienia lub utworzenia konta lokalnego. Jeśli zapis identyfikatorów powoduje konflikt z innym kontem, proces zostaje zatrzymany. Administrator musi poprawić konfigurację katalogu lub konta FoxIDs; konta nie są automatycznie scalane ani przypisywane ponownie.
Istniejący użytkownik wewnętrzny bez powiązania katalogowego nie może logować się przez Directory Connector. Włączenie konektora nie wiąże automatycznie konta z użytkownikiem katalogowym tylko dlatego, że e-mail, telefon lub nazwa użytkownika są zgodne.
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
Tworzenie użytkowników i operacje związane z cyklem życia hasła są delegowane do API Directory Connector:
- Uwierzytelnianie hasłem wywołuje endpoint
authentication. - Tworzenie użytkownika w procesie logowania wywołuje endpoint
create-user. - Zmiana hasła użytkownika wywołuje endpoint
change-password. - Przepływy ustawiania hasła i resetowania hasła wywołują endpoint
set-password.
Endpointy haseł otrzymują stabilny directoryUserId wczytanego użytkownika. Katalog sprawdza aktualny stan konta i dane uwierzytelniające podczas operacji. Uwierzytelnianie, zmiana i reset hasła zwracają sukces lub błąd. Utworzenie użytkownika zwraca ID katalogowe nowego konta, używane przez FoxIDs do osobnej synchronizacji.
Operacje na hasłach używają ID katalogowego zapisanego na wczytanym użytkowniku FoxIDs. Konektor sprawdza stan konta i wymagane dane uwierzytelniające lub upoważnienie do resetu, wykonuje działanie i zwraca sukces albo błąd. Identyfikatory, atrybuty i claims są zwracane wyłącznie przez synchronizację.
Po udanej zmianie lub resecie FoxIDs zapisuje bieżący czas zmiany i usuwa wymagania zmiany lub ustawienia hasła. Jeśli tak skonfigurowano, zapisuje również lokalną kopię. Aktywna sekwencja kontynuuje standardową obsługę konta, odzyskiwania dostępu i MFA.
Jeśli działanie się nie powiedzie lub FoxIDs nie może zapisać znanych zmian hasła, proces zostaje zatrzymany. Zmiana zaakceptowana już przez katalog nie jest wycofywana, a FoxIDs nie ponawia automatycznie działania po przekroczeniu czasu lub nieudanej odpowiedzi. Następna synchronizacja odświeży konto lokalne.
Gdy Enable password policy jest włączone, FoxIDs weryfikuje aktualne hasło katalogowe przed zastosowaniem kontroli nowego hasła. Może to wymagać dodatkowego wywołania uwierzytelniania przed change-password.
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.
Ustawianie i odzyskiwanie hasła
Przy pierwszym logowaniu użytkownik katalogowy może ustawić hasło za pomocą kodu potwierdzającego z e-maila lub SMS-a, ponieważ zapomniał hasła albo musi wybrać nowe.
Aby użyć Forgot your password?, podaj aktualny identyfikator katalogowy typu włączonego w metodzie logowania. FoxIDs synchronizuje i tworzy konto przed wysłaniem kodu. Odzyskiwanie przez e-mail lub SMS musi być włączone, a użytkownik musi mieć dostęp do aktualnego kontaktu odzyskiwania zwróconego przez katalog.
Po weryfikacji kodu i przesłaniu nowego hasła FoxIDs wywołuje set-password ze stabilnym ID katalogowym. Zwróć setPasswordEmail lub setPasswordSms i odpowiedni identyfikator kontaktu, aby wymagać tego sposobu ustawienia hasła. FoxIDs używa standardowego procesu ustawiania hasła.
Kody potwierdzające są związane z kontem, dla którego je wydano. Konta zarządzane przez konektor katalogowy używają tej samej weryfikacji kodów co inni użytkownicy wewnętrzni. FoxIDs zachowuje zwykłą obsługę błędów odzyskiwania bez ujawniania diagnostyki konektora.
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 URL i pięć endpointów:
synchronise-userwyszukuje użytkownika i zwraca aktualny stan konta, identyfikatory i claims.authenticationwaliduje bieżące hasło użytkownika.create-usertworzy użytkownika w katalogu zewnętrznym i zwraca jego trwałe ID katalogowe.change-passwordwaliduje bieżące hasło i zmienia je na nowe.set-passwordustawia 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/synchronise-userhttps://somewhere.org/directory/authenticationhttps://somewhere.org/directory/create-userhttps://somewhere.org/directory/change-passwordhttps://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.
FoxIDs wysyła wybrany język w nagłówku Accept-Language, na przykład Accept-Language: da-DK. Przy logowaniu wynika on z ui_locales lub przeglądarki; językiem zastępczym FoxIDs jest angielski. API może używać tego nagłówka do lokalizacji komunikatów i musi wybrać własny język zastępczy, jeśli nie obsługuje żądanego języka. Nagłówek jest wysyłany do wszystkich pięciu endpointów.
Żądanie synchronizacji
Endpoint synchronise-user otrzymuje identyfikator użytkownika lub znane ID katalogowe. Pierwsze wyszukiwanie podczas logowania lub odzyskiwania używa wpisanego identyfikatora. FoxIDs używa zapisanego directoryUserId do kontroli istniejących sesji i żądań z refresh tokenem, a po create-user używa zwróconego ID.
Początkowe wyszukiwanie po e-mailu:
{
"email": "user1@somewhere.org"
}
Późniejsza kontrola konta:
{
"directoryUserId": "a1b2c3d4"
}
Jeśli podano directoryUserId, używaj go jako nadrzędnego klucza wyszukiwania. W przeciwnym razie wyszukaj dokładnie jedno z email, phone lub username. Zwróć HTTP 200 z pełnymi danymi użytkownika, także dla kont wyłączonych. Zwróć user_deleted, gdy znane ID nie istnieje, i user_not_exists, gdy wyszukiwanie po samym identyfikatorze nie znajduje konta. Podany identyfikator nigdy nie jest dowodem własności konta.
FoxIDs wybiera identyfikator żądania według włączonych typów logowania. Jeśli włączona jest tylko nazwa użytkownika, wejście w formacie e-mail jest wysyłane jako username. Białe znaki na początku i końcu są usuwane. Wejście musi pasować do aktualnego identyfikatora włączonego typu w odpowiedzi; przypuszczalne pole żądania nie ogranicza pola odpowiedzi, które może pasować.
Informacje o błędach: Odpowiedź błędu.
Odpowiedź po powodzeniu
Endpoint synchronise-user zwraca HTTP 200 z pełnymi aktualnymi danymi użytkownika. Jeśli żądanie zawiera ID katalogowe, odpowiedź musi zawierać to samo ID. FoxIDs sprawdza to przed zapisem danych. HTTP 204 lub niepełne dane są odrzucane.
{
"directoryUserId": "a1b2c3d4",
"email": "user1@somewhere.org",
"phone": "+4511223344",
"username": "user1",
"confirmAccount": true,
"disableAccount": false,
"changePassword": false,
"setPasswordEmail": false,
"setPasswordSms": false,
"disableSetPasswordEmail": false,
"disableSetPasswordSms": false,
"passwordLastChanged": 1760000000,
"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:
directoryUserIdjest wymagane. Musi być stabilne i unikalne w katalogu zewnętrznym i jest zapisywane przy użytkowniku wewnętrznym FoxIDs.email,phoneiusernamesą 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.phonemusi zawierać numer kierunkowy kraju w formacie międzynarodowym, na przykład+4511223344.confirmAccountokreśla, czy FoxIDs ma uruchomić przepływ potwierdzenia dla użytkownika wewnętrznego.disableAccountsteruje bezpośrednim stanem wyłączenia konta. Przejście do wyłączonego unieważnia sesje FoxIDs i refresh-token grants użytkownika.changePasswordwymaga zmiany hasła po poprawnej weryfikacji danych uwierzytelniających.setPasswordEmailisetPasswordSmswymagają ustawienia hasła przez odpowiedni proces kodu potwierdzającego. Identyfikator kontaktu musi istnieć, a metoda odzyskiwania być włączona.disableSetPasswordEmailidisableSetPasswordSmswyłączają odpowiednie metody odzyskiwania.passwordLastChangedto opcjonalny nieujemny znacznik czasu Unix w sekundach. Podany podczas synchronizacji aktualizuje wiek hasła używany przez FoxIDs. Jeśli go pominięto, zachowywany jest istniejący znacznik. Udana zmiana lub reset zapisuje aktualny czas w FoxIDs; kolejna synchronizacja może podać nadrzędny znacznik czasu katalogu.emailVerifiedokreśla, czy adres e-mail użytkownika wewnętrznego ma zostać oznaczony jako zweryfikowany.phoneVerifiedokreśla, czy numer telefonu użytkownika wewnętrznego ma zostać oznaczony jako zweryfikowany.disableTwoFactorAppwyłącza uwierzytelnianie dwuskładnikowe przy użyciu aplikacji authenticator dla użytkownika wewnętrznego.disableTwoFactorSmswyłącza uwierzytelnianie dwuskładnikowe SMS dla użytkownika wewnętrznego.disableTwoFactorEmailwyłącza uwierzytelnianie dwuskładnikowe e-mail dla użytkownika wewnętrznego.requireMultiFactorokreśla, czy użytkownik wewnętrzny musi używać uwierzytelniania wieloskładnikowego.claimssą opcjonalne. FoxIDs zapisuje zwrócone claims przy użytkowniku wewnętrznym.
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.
Chronione claims, takie jak sid i auth_time, również są usuwane z odpowiedzi synchronizacji.
Żądanie authentication
Endpoint authentication otrzymuje wymagane stabilne ID katalogowe i aktualne hasło.
{
"directoryUserId": "a1b2c3d4",
"password": "testpass1"
}
Sprawdź aktualny stan konta w katalogu i hasło przed zwróceniem sukcesu. Zweryfikuj hasło przed podaniem wskazówek polityki specyficznych dla konta.
Informacje o błędach: Odpowiedź błędu.
Odpowiedź po powodzeniu
Po powodzeniu zwróć HTTP 204 bez treści odpowiedzi.
Żądanie utworzenia użytkownika
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" }
]
}
Pola:
- Wysyłane jest dokładnie jedno z pól
email,phonelubusername. passwordjest 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.confirmAccountirequireMultiFactorto żądane ustawienia tworzenia użytkownika w FoxIDs.claimszawiera oświadczenia niebędące identyfikatorami, zebrane podczas tworzenia użytkownika w FoxIDs.
Informacje o błędach: Odpowiedź błędu.
Odpowiedź po powodzeniu
Po powodzeniu zwróć HTTP 200 z trwałym ID katalogowym utworzonego konta:
{
"directoryUserId": "a1b2c3d4"
}
FoxIDs następnie wywołuje synchronise-user z tym ID, aby pobrać całe konto i utworzyć użytkownika wewnętrznego FoxIDs.
Żądanie change-password
Endpoint change-password otrzymuje wymagane ID katalogowe oraz aktualne i nowe hasło. Zweryfikuj aktualne hasło przed podaniem wskazówek polityki specyficznych dla konta.
{
"directoryUserId": "a1b2c3d4",
"currentPassword": "oldpass1",
"newPassword": "newpass1"
}
Informacje o błędach: Odpowiedź błędu.
Odpowiedź po powodzeniu
Po powodzeniu zwróć HTTP 204 bez treści. Zmiana musi spełnić wymaganie dotyczące hasła w katalogu.
Żądanie set-password
Endpoint set-password otrzymuje wymagane ID katalogowe i nowe hasło. FoxIDs wywołuje go po autoryzacji resetu lub ustawienia hasła, w tym po sprawdzeniu kodów w odzyskiwaniu dostępu. Konektor musi ponownie sprawdzić aktualny stan konta przed zmianą hasła.
{
"directoryUserId": "a1b2c3d4",
"password": "newpass1"
}
Informacje o błędach: Odpowiedź błędu.
Odpowiedź po powodzeniu
Po powodzeniu zwróć HTTP 204 bez treści. Reset lub ustawienie musi spełnić wymaganie dotyczące hasła w katalogu.
Odpowiedź błędu
Wszystkie endpointy używają tego samego formatu błędu JSON. Zwróć obsługiwany przez endpoint kod w error, a szczegóły diagnostyczne w errorMessage. Przykład odrzuconego hasła z authentication:
{
"error": "invalid_password",
"errorMessage": "Invalid password."
}
Używaj następujących kodów stanu HTTP:
- 401 z
invalid_api_id_secret, gdy uwierzytelnianie HTTP Basic zostanie odrzucone. - 400, 401 lub 403 dla pozostałych obsługiwanych kodów z tabeli endpointów poniżej.
- 500 przy awarii technicznej konektora.
Pole errorMessage zawiera tekst diagnostyczny przeznaczony do dzienników FoxIDs i nie jest wyświetlane użytkownikowi końcowemu. Podaj przyczynę błędu, ale nigdy nie umieszczaj haseł, sekretów API ani kluczy prywatnych.
Tylko authentication może zwrócić login_rejected, po sprawdzeniu identyfikatora i hasła użytkownika. Może zawierać opcjonalny uiErrorMessage, który FoxIDs pokazuje jako zwykły tekst w formularzu logowania. API dostarcza komunikat w języku wybranym przez Accept-Language:
{
"error": "login_rejected",
"errorMessage": "Credentials verified; login rejected by directory policy.",
"uiErrorMessage": "You cannot log in here. Contact support."
}
Jeśli uiErrorMessage pominięto, jest null, pusty lub zawiera tylko białe znaki, FoxIDs pokazuje ten sam zlokalizowany ogólny komunikat co przy invalid_password i operation_rejected. Przy innych obsługiwanych kodach FoxIDs ignoruje uiErrorMessage i wybiera komunikat z własnych tekstów lokalizowanych. Diagnostyka errorMessage nigdy nie zastępuje komunikatu dla użytkownika. Wymagania weryfikacji opisano w Błędach uwierzytelniania i prywatności.
Błędy z authentication, change-password i set-password nie zwracają danych użytkownika, nie zmieniają konta wewnętrznego ani nie unieważniają istniejących sesji i refresh tokenów. Synchronizacja stosuje zmiany konta z katalogu. Odrzucone próby uwierzytelniania i zmiany hasła nadal liczą się do istniejącego limitu nieudanych logowań.
Obsługiwane kody błędów według endpointu:
| Kod błędu | synchronise-user |
authentication |
create-user |
change-password |
set-password |
Znaczenie |
|---|---|---|---|---|---|---|
invalid_api_id_secret |
Tak | Tak | Tak | Tak | Tak | Nazwa użytkownika API lub sekret dla HTTP Basic authentication jest nieprawidłowy. |
user_exists |
Nie | Nie | Tak | Nie | Nie | Użytkownik o podanym identyfikatorze już istnieje w katalogu zewnętrznym. |
user_not_exists |
Bez ID katalogowego | Nie | Nie | Nie | Nie | Żaden użytkownik katalogowy nie pasuje do wyszukiwania po samym identyfikatorze. |
invalid_password |
Nie | Tak | Nie | Nie | Nie | Katalog odrzucił hasło w żądaniu uwierzytelnienia. |
login_rejected |
Nie | Tak | Nie | Nie | Nie | Logowanie zostało odrzucone po weryfikacji identyfikatora użytkownika i hasła. Opcjonalny uiErrorMessage jest wyświetlany w formularzu logowania. |
invalid_current_password |
Nie | Nie | Nie | Tak | Nie | Katalog odrzucił bieżące hasło w żądaniu zmiany hasła. |
create_user_not_supported |
Nie | Nie | Tak | Nie | Nie | Konektor nie obsługuje tworzenia użytkowników w katalogu zewnętrznym. |
operation_rejected |
Nie | Tak | Nie | Tak | Tak | Operacji nie można ukończyć, na przykład dlatego, że konto jest niedostępne. FoxIDs zapisuje errorMessage w logach, ignoruje uiErrorMessage i pokazuje ogólny zlokalizowany błąd bez zmiany stanu konta. |
user_deleted |
Z ID katalogowym | Nie | Nie | Nie | Nie | Znane ID katalogowe już nie istnieje. FoxIDs odbiera dostęp i usuwa użytkownika podczas synchronizacji. |
password_not_accepted |
Nie | Tak | Tak | Tak | Tak | Hasło weryfikowane, używane podczas tworzenia użytkownika, zmieniane lub ustawiane zostało odrzucone przez regułę haseł w katalogu, której nie odpowiada bardziej szczegółowy kod. |
password_min_length |
Nie | Tak | Tak | Tak | Tak | Hasło weryfikowane, używane podczas tworzenia użytkownika, zmieniane lub ustawiane jest krótsze niż minimalna długość hasła w katalogu. |
password_max_length |
Nie | Tak | Tak | Tak | Tak | Hasło weryfikowane, używane podczas tworzenia użytkownika, zmieniane lub ustawiane jest dłuższe niż maksymalna długość hasła w katalogu. |
password_banned_characters |
Nie | Tak | Tak | Tak | Tak | Hasło weryfikowane, używane podczas tworzenia użytkownika, zmieniane lub ustawiane zawiera co najmniej jeden znak lub wyraz odrzucany przez katalog. |
password_complexity |
Nie | Tak | Tak | Tak | Tak | Starszy błąd złożoności znaków, interpretowany przez FoxIDs jako password_character_variation. W nowych integracjach używaj jednego z dwóch szczegółowych kodów błędów dotyczących znaków. |
password_character_repeat |
Nie | Tak | Tak | Tak | Tak | Hasło weryfikowane, używane podczas tworzenia użytkownika, zmieniane lub ustawiane zawiera zbyt wiele powtórzeń znaków. |
password_character_variation |
Nie | Tak | Tak | Tak | Tak | Hasło weryfikowane, używane podczas tworzenia użytkownika, zmieniane lub ustawiane nie zawiera wystarczająco zróżnicowanych znaków. |
password_email_text_complexity |
Nie | Tak | Tak | Tak | Tak | Hasło weryfikowane, używane podczas tworzenia użytkownika, zmieniane lub ustawiane zawiera adres e-mail użytkownika lub jego część. |
password_phone_text_complexity |
Nie | Tak | Tak | Tak | Tak | Hasło weryfikowane, używane podczas tworzenia użytkownika, zmieniane lub ustawiane zawiera numer telefonu użytkownika lub jego część. |
password_username_text_complexity |
Nie | Tak | Tak | Tak | Tak | Hasło weryfikowane, używane podczas tworzenia użytkownika, zmieniane lub ustawiane zawiera nazwę użytkownika lub jej część. |
password_url_text_complexity |
Nie | Tak | Tak | Tak | Tak | Hasło weryfikowane, używane podczas tworzenia użytkownika, zmieniane lub ustawiane zawiera tekst związany z adresem URL FoxIDs. |
password_risk |
Nie | Tak | Tak | Tak | Tak | Hasło weryfikowane, używane podczas tworzenia użytkownika, zmieniane lub ustawiane jest znane jako ryzykowne, ujawnione lub niebezpieczne z innego powodu. |
password_history |
Nie | Nie | Nie | Tak | Tak | Nowe hasło zostało odrzucone, ponieważ było już używane. |
password_expired |
Nie | Tak | Nie | Nie | Nie | Podane hasło zweryfikowano, ale wygasło; użytkownik musi je zmienić przed kontynuacją uwierzytelniania. |
new_password_equals_current |
Nie | Nie | Nie | Tak | Nie | Nowe hasło jest takie samo jak bieżące. set-password nie może zwrócić tego błędu, ponieważ nie otrzymuje bieżącego hasła. |
Jeśli przed zmianą hasła FoxIDs musi sprawdzić własną politykę, najpierw wywołuje authentication, aby zweryfikować aktualne hasło. Jeśli konektor zwróci tam password_expired, zmiana może być kontynuowana. Endpoint change-password musi akceptować zweryfikowane wygasłe aktualne hasło i zwracać tylko błędy obsługiwane przez operację zmiany.
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.
Zwracaj tylko kody obsługiwane przez endpoint i podany directoryUserId, zgodnie z tabelą. Nieobsługiwany kod, nieprawidłowa odpowiedź lub nieoczekiwany stan HTTP są błędem integracji i prowadzą do ogólnej strony błędu. Zobacz Rozwiązywanie błędów przeglądarki, aby znaleźć diagnostykę na podstawie identyfikatorów ze strony błędu.
Błędy uwierzytelniania i prywatność użytkowników
Nieuwierzytelniony podmiot wywołujący nie może na podstawie błędu logowania ustalić, czy istnieje dana nazwa użytkownika lub adres e-mail. Podczas uwierzytelniania hasłem FoxIDs przetwarza obsługiwane błędy w następujący sposób:
| Błąd konektora | Wynik widoczny dla użytkownika |
|---|---|
invalid_password, operation_rejected lub niedostępne konto wykryte podczas synchronizacji |
Ten sam ogólny komunikat logowania, na przykład Nieprawidłowy adres e-mail lub hasło., przetłumaczony na aktywny język i dostosowany do włączonych identyfikatorów logowania. |
login_rejected |
Podany uiErrorMessage lub ten sam ogólny komunikat logowania, jeśli go brakuje albo jest pusty, w tym samym miejscu formularza logowania. |
password_not_accepted |
Strona zmiany hasła z ogólnymi wskazówkami dotyczącymi polityki haseł. |
password_expired lub inny szczegółowy błąd polityki haseł |
Strona zmiany hasła z odpowiednimi zlokalizowanymi wskazówkami dotyczącymi polityki haseł. |
Konektor musi zweryfikować podane bieżące hasło przed zwróceniem błędu polityki haseł z authentication. W przeciwnym razie inna strona lub komunikat może umożliwić atakującemu odkrywanie użytkowników i potwierdzanie ich identyfikatorów przez odgadywanie nazw użytkowników lub adresów e-mail. W przypadku change-password zweryfikuj bieżące hasło przed zwróceniem wskazówek dotyczących nowego hasła, które są specyficzne dla konta. Ogólne kontrole formatu nie mogą ujawniać, czy konto istnieje.
Jeśli użytkownik z jakiegokolwiek powodu nie może użyć tego procesu logowania, najpierw sprawdź podany identyfikator i hasło. Odrzuć dostęp z powodu ograniczenia dopiero po weryfikacji obu, aby nie ujawnić, czy odgadnięty identyfikator należy do rzeczywistego użytkownika. Zwróć login_rejected z authentication, podaj diagnostyczny powód w errorMessage i opcjonalnie bezpieczne wskazówki w uiErrorMessage. Jeśli danych nie można zweryfikować, zwróć zwykły błąd uwierzytelnienia bez ujawniania ograniczenia.
FoxIDs polega na weryfikacji danych uwierzytelniających przez konektor przed zwróceniem login_rejected; znalezienie konta lub znajomość directoryUserId nie wystarcza. Przed weryfikacją instrukcje i przyciski alternatywnych metod logowania muszą być widoczne niezależnie od tego, czy identyfikator pasuje do konta.
Tylko synchronise-user raportuje stan konta: zwróć pełne dane z disableAccount: true dla konta wyłączonego lub user_deleted, gdy znane ID już nie istnieje. Endpointy haseł zwracają operation_rejected, jeśli konto jest niedostępne. W odróżnieniu od login_rejected nie wymaga to zweryfikowanego hasła, ponieważ nigdy nie przekazuje przeglądarce wskazówek specyficznych dla konta.
Obsługuj błędy w spójny sposób dla znanych i nieznanych identyfikatorów, uwzględniając obserwowalne czasy odpowiedzi i ochronę przed powtarzanymi próbami. Sam ogólny komunikat nie zapobiega odkrywaniu użytkowników, jeśli inne przekierowanie, status lub czas odpowiedzi ujawnia wynik. Przy implementacji konektora przestrzegaj wytycznych OWASP dotyczących błędów uwierzytelniania.
Przykład API
Przykład DirectoryConnectorApiSample pokazuje, jak zaimplementować API Directory Connector w ASP.NET Core.
Implementacje i klienci testowi muszą przestrzegać powyższych kontraktów: HTTP 200 z pełnymi danymi użytkownika dla synchronise-user, HTTP 200 z utworzonym ID dla create-user i HTTP 204 bez treści dla udanych operacji na hasłach.
Komponent Active Directory
FoxIDs zawiera wdrażalny w IIS Directory Connector dla Active Directory. Komponent implementuje API dla jednej domeny AD/LDAP i umożliwia synchronizację kont, sprawdzanie, zmianę i ustawianie haseł oraz zwracanie skonfigurowanych atrybutów AD i zagnieżdżonych członkostw grup AD jako claims.
Konfiguracja
Skonfiguruj Directory Connector w ustawieniach środowiska w FoxIDs Control Client.
- Wybierz kartę Ustawienia.
- Wybierz kartę Środowisko.
- Znajdź sekcję Directory Connector.
- Włącz Directory Connector.
- Dodaj bazowy adres URL API bez folderu endpointu w polu API URL.
- Dodaj API secret.
- Zdecyduj, czy lokalna kopia hasła ma być zapisywana.
- Skonfiguruj politykę haseł środowiska tak, aby odpowiadała polityce haseł katalogu zewnętrznego.
- Kliknij Update.
