Control API - użytkownicy i aplikacje uwierzytelniające

Użyj FoxIDs Control API do provisionowania użytkowników wewnętrznych i zarządzania aplikacjami uwierzytelniającymi zarejestrowanymi przez każdego użytkownika. Ten przewodnik koncentruje się na operacjach służących do synchronizacji rejestracji między deploymentami FoxIDs.

Przed wywołaniem tych operacji skonfiguruj uwierzytelnianie i uprawnienia Control API. Swagger pozostaje dokładną dokumentacją wszystkich właściwości użytkownika, filtrów, reguł walidacji i schematów response:

• Swagger (OpenAPI) JSON
• Swagger UI

Baza endpointu

Przykłady używają FoxIDs Cloud:

https://control.foxids.com/api/{tenant_name}/{track_name}

Zastąp {tenant_name} nazwą tenanta, a {track_name} techniczną nazwą środowiska. Zmień host dla self-hosted deployment. Wyślij access token Control API w nagłówku Authorization: Bearer {access_token}.

Operacje na użytkownikach i aplikacjach uwierzytelniających wymagają prawa użytkownika do środowiska docelowego. Nadaj tylko potrzebną operację read, create, update lub delete poprzez hierarchię praw Control API.

Identyfikatory użytkownika

Każdy użytkownik wewnętrzny musi mieć co najmniej jeden identyfikator logowania: e-mail, telefon lub nazwę użytkownika. Adresy e-mail mogą mieć do 100 znaków, a nazwy użytkowników do 60 znaków. Adresy e-mail i nazwy użytkownika są normalizowane do małych liter, a otaczające białe znaki są usuwane ze wszystkich identyfikatorów.

Operacje pojedynczego użytkownika identyfikują go przez query parameter email, phone lub username. Response zawiera także generowany przez serwer userId. Jest on unikalny i trwały również po zmianie identyfikatora i powinien służyć do wiązania aplikacji uwierzytelniających lub innych zasobów.

Dla użytkowników Directory Connector zachowaj stabilne powiązanie directoryUserId podczas aktualizacji konta. Synchronizacja na żądanie zastępuje identyfikatory, ustawienia i claims katalogu; zmieniaj je w katalogu nadrzędnym. Rejestracje aplikacji uwierzytelniających i przypisania dostępu FoxIDs pozostają zachowane.

Operacje użytkownika

Operacje pojedynczego użytkownika są w Swaggerze pogrupowane pod tenant users.

Niestandardowe claims mogą zawierać opcjonalny valueType: String, Boolean, Number, JsonObject lub JsonArray. Wszystkie wpisy w values pozostają ciągami znaków i mają wspólny wybrany typ. Pomiń valueType dla String. API odrzuca wartości niezgodne z wybranym typem; zachowuj typ podczas odczytu i aktualizacji claims. Te same opcje dotyczą claims węzłów struktur dostępu oraz claims pierwszego administratora podczas tworzenia tenanta. Zobacz typy wartości claims, aby poznać zakresy liczb i zachowanie w JWT/SAML.

W razie potrzeby użyj phone={phone} lub username={username} zamiast email={email}. Dołącz każdy endpoint do bazy endpointu.

Lista i filtrowanie użytkowników

GET /!users przyjmuje filterEmail, filterPhone, filterUsername, filterUserId i filterClaimValue. Każdy filtr wyszukuje częściowe dopasowania bez rozróżniania wielkości liter. Przy wielu filtrach użytkownik jest zwracany, jeśli pasuje dowolny z nich.

Response zawiera collection data i nieprzezroczysty paginationToken. Powtórz ten sam request z otrzymaną wartością jako paginationToken, aby pobrać następną stronę. Kontynuuj, aż token nie będzie zwracany. Nie interpretuj go ani nie modyfikuj.

Response użytkownika wskazuje, czy hasło jest skonfigurowane i kiedy je zmieniono, ale nigdy nie zwraca hasła ani jego bieżącego hashu.

Tworzenie użytkownika

Create-request obsługuje stan konta, zweryfikowane identyfikatory, własne claims, politykę hasła, konfigurację przez e-mail lub SMS i ustawienia MFA użytkownika. Przykład tworzy użytkownika bez hasła i wymaga konfiguracji przez e-mail:

POST https://control.foxids.com/api/{tenant_name}/{track_name}/!user
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "email": "alice@example.com",
  "emailVerified": true,
  "setPasswordEmail": true,
  "claims": [
    {
      "claim": "role",
      "values": ["employee"]
    }
  ]
}

Create-request może zawierać hasło jawne, obsługiwane pola hashu albo nie zawierać danych hasła. Nigdy nie wysyłaj obu formatów. Hasła jawne są sprawdzane względem polityki; importowane hashe nie. Bez danych użyj setPasswordEmail lub setPasswordSms, jeśli użytkownik ma utworzyć hasło podczas logowania.

Utworzenie istniejącego użytkownika zwraca 409 Conflict, a limit użytkowników w planie tenanta ma zastosowanie. Równoczesna operacja użytkownika może chwilowo zablokować tworzenie; ponów 423 Locked po krótkiej przerwie.

Aktualizowanie użytkownika

PUT /!user jest pełną aktualizacją, nie patchem. Pobierz bieżącego użytkownika, zachowaj niezmieniane właściwości, zastosuj zmiany i wyślij całą edytowalną reprezentację. Collection claims i flagi konta/MFA są zastępowane. Hasła i rejestracje aplikacji mają osobne operacje.

Identyfikuj użytkownika przez email, phone lub username. Aby zmienić identyfikator, zachowaj jego bieżącą wartość i ustaw updateEmail, updatePhone lub updateUsername. Pusty string usuwa identyfikator; pominięcie pola pozostawia go bez zmian. Zachowaj co najmniej jeden identyfikator logowania.

Zmiana disableAccount z false na true unieważnia refresh token grants i aktywne sesje. Ponowne włączenie pozwala na nowe logowania, ale nie przywraca sesji.

Niestandardowe oświadczenia użytkowników nie mogą używać chronionych nazw oświadczeń, takich jak sid i auth_time.

Zarządzanie hasłami

Użyj PUT /!usersetpassword do administracyjnego ustawienia hasła lub migracji. Obsługiwane są trzy tryby:

• Podaj password, aby zastosować wybraną politykę i zaktualizować historię haseł.
• Podaj passwordHashAlgorithm i passwordHash oraz passwordHashSalt, jeśli wymaga tego algorytm, aby zaimportować obsługiwany wstępnie obliczony skrót bez walidacji polityki.
• Pomiń oba formaty, aby usunąć aktualne hasło użytkownika.

Te same formaty skrótów są akceptowane podczas tworzenia użytkownika lub zbiorczego aprowizowania:

Na przykład to administracyjne żądanie hasła importuje syntetyczny skrót bcrypt:

{
  "email": "alice@example.com",
  "passwordHashAlgorithm": "bcrypt",
  "passwordHash": "$2b$10$..CA.uOD/eaGAOmJB.yMBu3YunYvFEoaS5IJZ/wiqfQ/EWx.HaqjC"
}

Nie łącz password z polami skrótu. Skrót lub sól bez algorytmu są odrzucane. Niepoprawne ciągi bcrypt, nieobsługiwane warianty, koszty poza obsługiwanym zakresem i oddzielne sole bcrypt są odrzucane przed zapisem. Zobacz haszowanie haseł dla parametrów i limitu hasła bcrypt wynoszącego 72 bajty.

Opcjonalne passwordLastChanged to czas Unix w sekundach. Użyj changePassword, aby wymagać wyboru nowego hasła przy następnym odpowiednim logowaniu. Import skrótu pomija kontrolę polityki haseł podczas importu; wybrana polityka nadal obowiązuje przy logowaniu. Logowanie zachowuje zaimportowany skrót i czas zmiany hasła. Ustawienie lub zmiana jawnego hasła używa domyślnego formatu PBKDF2.

Użyj PUT /!userchangepassword, gdy aktualne hasło jest znane. Operacja sprawdza je i weryfikuje nowe według polityki i historii użytkownika.

Punkt końcowy historii haseł jest przeznaczony do kontrolowanych scenariuszy migracji i odzyskiwania. Akceptuje również wpisy historii bcrypt z tymi samymi ograniczeniami formatu i kosztu oraz bez oddzielnej soli. Szczegółowa odpowiedź zawiera materiał skrótów haseł, a PUT zastępuje całą historię. Stosuj te same zabezpieczenia co dla importowanych skrótów haseł i nie zapisuj treści żądań ani odpowiedzi w logach.

Provisionowanie zbiorcze

PUT /!users przyjmuje od 1 do 1 000 użytkowników na request. Maksymalnie 100 entries może zawierać jawne hasła. Requests bez nich, w tym z obsługiwanymi wstępnie obliczonymi hashami, mogą zawierać 1 000 użytkowników.

Import zbiorczy tworzy nowych użytkowników lub zastępuje pasujących użytkowników; nie scala poszczególnych właściwości i nie może zmieniać identyfikatorów e-mail, telefonu ani nazwy użytkownika. Traktuj go jako import zastępujący. Przy zwykłych zmianach cyklu życia konta używaj operacji aktualizacji pojedynczego użytkownika, aby zachować istniejący stan i trwały identyfikator użytkownika.

DELETE /!users przyjmuje od 1 do 1 000 e-maili, telefonów lub nazw w userIdentifiers. Zobacz Prześlij wielu użytkowników, aby poznać formaty, wydajność i seed tool.

Usuwanie użytkowników i unieważnianie dostępu

Usuwanie pojedyncze lub zbiorcze unieważnia refresh token grants i aktywne sesje przed usunięciem konta. Jest trwałe. Użyj operacji delete aplikacji uwierzytelniających, aby usunąć tylko ich rejestracje.

Requests tworzenia, aktualizacji, hasła i usuwania trafiają do audit logu Control. Odczyty nie są zapisywane jako audit-events.

Blokady nieudanych logowań

Użyj operacji listy i szczegółów do sprawdzania blokad; usuń blokadę, gdy administrator zatwierdzi jej zakończenie.

Blokady użytkowników mają userIdentifier. Użyj tej wartości i typu błędu do pobrania lub zakończenia blokady. Filtr listy filterUserIdentifier porównuje identyfikatory bez rozróżniania wielkości liter.

Blokady DirectorySynchronisation mają sequenceId i pomijają userIdentifier. Użyj dokładnego sequenceId, z zachowaniem wielkości liter, oraz typu błędu do pobrania lub zakończenia blokady synchronizacji, bez parametru userIdentifier. Użyj filterSequenceId, aby znaleźć blokady tej sekwencji. Podanie filterUserIdentifier i filterSequenceId znajduje blokady pasujące do dowolnej z wartości; filtr typu błędu nadal dotyczy wszystkich wyników. Limit wyszukiwań jest wspólny dla wszystkich identyfikatorów wpisanych w tej samej sekwencji.

Rejestracje aplikacji uwierzytelniających

Operacje aplikacji uwierzytelniających są w Swaggerze pogrupowane pod tenant user authenticator apps. Operacja listy zwraca bezpieczne podsumowania rejestracji, a operacja szczegółowa zwraca wrażliwe dane wymagane do kontrolowanej synchronizacji.

Dołącz każdy endpoint do bazy endpointu. Przykład:

GET https://control.foxids.com/api/{tenant_name}/{track_name}/!userauthenticatorapps?userId=e061ed17-7b44-48a8-b224-ecdb800ed5cc
Authorization: Bearer {access_token}

Zasób rejestracji

Operacje tworzenia i aktualizacji używają pełnego zasobu rejestracji:

{
  "userId": "e061ed17-7b44-48a8-b224-ecdb800ed5cc",
  "id": "7a772286-76a2-4f17-a0f8-4e927bb1772d",
  "createTime": 1785769200,
  "secret": "TOTP-SHARED-SECRET",
  "recoveryCode": {
    "hashAlgorithm": "P2HS512:10",
    "hash": "RECOVERY-CODE-HASH",
    "hashSalt": "RECOVERY-CODE-SALT"
  }
}

Właściwości zachowują się następująco:

• userId to stabilny identyfikator użytkownika FoxIDs.
• id to trwały identyfikator rejestracji podawany przez klienta podczas tworzenia. Wybiera rejestrację podczas aktualizacji i nie może zostać zmieniony.
• createTime jest wyrażony w sekundach Unix. Podczas tworzenia jest opcjonalny i domyślnie przyjmuje bieżący czas. Pominięty podczas aktualizacji zachowuje istniejącą wartość.
• secret to współdzielony TOTP secret wymagany podczas tworzenia i aktualizacji.
• recoveryCode zawiera dane hashu recovery code i jest pomijany, gdy recovery code nie jest skonfigurowany.

Użytkownik może mieć maksymalnie pięć rejestracji aplikacji uwierzytelniających. Tworzenie z istniejącym ID rejestracji zwraca 409 Conflict; tworzenie po osiągnięciu limitu zwraca 400 Bad Request.

Synchronizowanie rejestracji

Usługa synchronizacji może połączyć interaktywną Authenticator App notification API z tymi operacjami Control API:

1. Odbierz notification registered zawierającą user_id i registration_id.
2. Pobierz rejestrację ze source deployment za pomocą operacji szczegółowej.
3. Utwórz rejestrację w target deployment lub zaktualizuj ją, jeśli istnieje już to samo ID rejestracji.

Operacje Control API do tworzenia, aktualizowania i usuwania nie wywołują Authenticator App notification API. Synchronizacja nie tworzy więc pętli notification.

Bezpieczeństwo

Operacje szczegółowe, tworzenia i aktualizacji ujawniają lub przyjmują secret aplikacji uwierzytelniającej i dane hashu recovery code. Przyznawaj wymagane uprawnienie użytkownika tylko zaufanym klientom, używaj TLS, chroń payloads podczas przechowywania i nie loguj request ani response bodies.

Użyj operacji listy, gdy potrzebne są tylko ID rejestracji i czasy utworzenia. Nie zwraca ona secret ani danych hashu recovery code.

Właściwość zgodności

Właściwość activeTwoFactorApp ogólnego API użytkownika jest deprecated i planowana do usunięcia po 1 sierpnia 2027 r. W update-request wartość false nadal usuwa wszystkie rejestracje ze względu na zgodność; true lub pominięta wartość pozostawia je bez zmian. Nowe integracje powinny używać endpointów aplikacji uwierzytelniających.

Odpowiedzi błędów

Typowe odpowiedzi błędów operacji użytkowników i aplikacji uwierzytelniających:

• 400 Bad Request, gdy identyfikatory, dane uwierzytelniające, filtry lub dane zasobu są nieprawidłowe albo osiągnięto limit rejestracji.
• 401 Unauthorized, gdy brakuje access tokenu lub jest on nieprawidłowy.
• 403 Forbidden, gdy klient nie ma wymaganego prawa użytkownika do środowiska.
• 404 Not Found, gdy użytkownik lub rejestracja aplikacji nie istnieje.
• 409 Conflict, gdy użytkownik już istnieje lub ponownie użyto ID rejestracji.
• 423 Locked, gdy tworzenie lub import zbiorczy są chwilowo zablokowane. Spróbuj ponownie po krótkiej przerwie.

Szczegóły walidacji znajdują się w response body. Zadeklarowane odpowiedzi każdej operacji sprawdzisz w Swagger UI.

Impersonowane sesje

Aktywne sesje zachowują identyfikatory pierwotnie uwierzytelnionego użytkownika. Szczegóły impersonacji identyfikują użytkownika docelowego oddzielnie, obejmując subject, format subject, e-mail, telefon, nazwę użytkownika i odwołanie do konta wewnętrznego, jeśli są dostępne. Aktywną sesję można znaleźć przy użyciu identyfikatorów dowolnego z tych użytkowników.

Claims tokenu odświeżania reprezentują tożsamość wydaną aplikacji; szczegóły impersonacji grantu identyfikują pierwotnie uwierzytelnionego użytkownika i wybranego użytkownika docelowego. Cofnięcie dostępu uwzględnia oba powiązane konta. Konfigurację przepływu i zachowanie sesji opisano w sekcji Impersonacja.

Powiązana dokumentacja

• Uwierzytelnianie i uprawnienia Control API
• Omówienie FoxIDs Control
• Użytkownicy wewnętrzni
• Uwierzytelnianie dwuetapowe i wieloskładnikowe
• Prześlij wielu użytkowników