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 i nazwy użytkownika są normalizowane do małych liter, a spacje na początku i końcu są usuwane.

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.

Operacje użytkownika

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

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.

Zarządzanie hasłami

Użyj PUT /!usersetpassword do administracji lub migracji:

• Podaj password, aby zastosować politykę i zaktualizować historię.
• Podaj passwordHashAlgorithm, passwordHash i passwordHashSalt, aby zaimportować obsługiwany hash bez walidacji polityki.
• Pomiń oba formaty, aby usunąć bieżące hasło.

passwordLastChanged to opcjonalny czas Unix w sekundach. changePassword wymaga nowego hasła przy następnym odpowiednim logowaniu. Użyj PUT /!userchangepassword, gdy znasz bieżące hasło; zostanie ono sprawdzone, a nowe zweryfikowane względem polityki i historii.

Endpoint historii służy do kontrolowanej migracji i odzyskiwania. Szczegóły zawierają materiał hashu, a PUT zastępuje całą historię. Chroń go jak importowane hashe i nie loguj request/response bodies.

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 lub zastępuje użytkowników; nie scala właściwości ani nie zmienia nazw identyfikatorów. Traktuj go jako import zastępujący. Użyj aktualizacji pojedynczej, aby zachować stan i trwały userId.

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.

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.

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