Control API - utenti e app di autenticazione

Usa FoxIDs Control API per effettuare il provisioning degli utenti interni e gestire le app di autenticazione registrate da ciascun utente. Questa guida descrive le operazioni utilizzabili per sincronizzare le registrazioni tra deployment FoxIDs.

Prima di chiamare queste operazioni, configura l'autenticazione e i diritti di accesso Control API. Swagger rimane il riferimento esatto per tutte le proprietà utente, i filtri, le regole di validazione e gli schemi di response:

• Swagger (OpenAPI) JSON
• Swagger UI

Base degli endpoint

Gli esempi usano FoxIDs Cloud:

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

Sostituisci {tenant_name} con il nome del tenant e {track_name} con il nome tecnico dell'ambiente. Modifica l'host per un deployment self-hosted. Invia l'access token Control API nell'header Authorization: Bearer {access_token}.

Le operazioni su utenti e app di autenticazione richiedono un diritto utente per l'ambiente di destinazione. Concedi solo l'operazione read, create, update o delete necessaria tramite la gerarchia dei diritti Control API.

Identificatori utente

Ogni utente interno deve avere almeno un identificatore di accesso: e-mail, telefono o nome utente. E-mail e nomi utente vengono normalizzati in minuscolo e gli spazi iniziali e finali vengono rimossi.

Le operazioni singole identificano l'utente con il query parameter email, phone o username. La response contiene anche un userId generato dal server. È unico e persistente anche se cambia un identificatore e va usato per associare app di autenticazione o altre risorse.

Operazioni utente

Le operazioni singole sono raggruppate sotto tenant users in Swagger.

Usa phone={phone} o username={username} invece di email={email} quando appropriato. Aggiungi ogni endpoint alla base degli endpoint.

Elencare e filtrare gli utenti

GET /!users accetta filterEmail, filterPhone, filterUsername, filterUserId e filterClaimValue. Ogni filtro cerca corrispondenze parziali senza distinzione tra maiuscole e minuscole. Con più filtri, l'utente viene restituito se uno qualsiasi corrisponde.

La response contiene una collection data e un paginationToken opaco. Ripeti lo stesso request con il valore restituito come paginationToken per la pagina successiva. Continua finché non viene più restituito un token. Non interpretarlo né modificarlo.

La response indica se è configurata una password e quando è stata cambiata, ma non restituisce mai la password o il relativo hash corrente.

Creare un utente

Il create-request supporta stato account, identificatori verificati, claims personalizzati, policy password, configurazione via e-mail o SMS e impostazioni MFA per utente. Questo esempio crea un utente senza password e richiede di configurarla via 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"] }]
}

Un create-request può contenere una password in chiaro, campi hash supportati o nessuna credenziale. Non inviare entrambi i formati. Le password in chiaro sono verificate rispetto alla policy; gli hash importati no. Senza credenziali, usa setPasswordEmail o setPasswordSms se l'utente deve creare una password durante l'accesso.

Creare un utente esistente restituisce 409 Conflict e si applica il limite utenti del piano del tenant. Un'operazione utente simultanea può bloccare temporaneamente la creazione; riprova 423 Locked dopo poco.

Aggiornare un utente

PUT /!user è un aggiornamento completo, non una patch. Leggi l'utente attuale, conserva le proprietà invariate, applica le modifiche e invia l'intera rappresentazione modificabile. La collection claims e i flag account/MFA vengono sostituiti. Password e registrazioni delle app hanno operazioni dedicate.

Identifica l'utente con email, phone o username. Per cambiare un identificatore, mantieni il valore attuale e imposta updateEmail, updatePhone o updateUsername. Una stringa vuota rimuove l'identificatore; omettere la proprietà lo lascia invariato. Mantieni almeno un identificatore di accesso.

Cambiare disableAccount da false a true revoca refresh token grants e sessioni attive. Riabilitare l'account consente nuovi accessi ma non ripristina le sessioni revocate.

Gestire le password

Usa PUT /!usersetpassword per amministrazione o migrazione:

• Fornisci password per applicare la policy e aggiornare la cronologia.
• Fornisci passwordHashAlgorithm, passwordHash e passwordHashSalt per importare un hash supportato senza validazione della policy.
• Ometti entrambi i formati per rimuovere la password corrente.

passwordLastChanged è un orario Unix facoltativo in secondi. changePassword richiede una nuova password al successivo accesso applicabile. Usa PUT /!userchangepassword quando conosci quella attuale; viene verificata e la nuova è validata rispetto a policy e cronologia.

L'endpoint della cronologia è destinato a migrazione e ripristino controllati. Il dettaglio contiene materiale hash e PUT sostituisce l'intera cronologia. Proteggilo come gli hash importati e non registrare request/response bodies.

Provisioning in blocco

PUT /!users accetta da 1 a 1.000 utenti per request. Al massimo 100 entries possono includere password in chiaro. I requests senza password in chiaro, inclusi hash precalcolati supportati, possono includere 1.000 utenti.

Il caricamento in blocco crea o sostituisce utenti; non unisce proprietà e non può rinominare identificatori. Trattalo come importazione sostitutiva. Usa l'aggiornamento singolo per conservare stato e userId persistente.

DELETE /!users accetta da 1 a 1.000 e-mail, telefoni o nomi utente in userIdentifiers. Consulta Carica molti utenti per formati, prestazioni e seed tool.

Eliminare utenti e revocare l'accesso

L'eliminazione singola o in blocco revoca refresh token grants e sessioni attive prima di eliminare l'account. È permanente. Usa le operazioni delete delle app di autenticazione per rimuovere solo le registrazioni.

I requests di creazione, aggiornamento, password ed eliminazione sono inclusi nell'audit log Control. Le letture non sono scritte come audit-events.

Registrazioni delle app di autenticazione

Le operazioni delle app di autenticazione sono raggruppate sotto tenant user authenticator apps in Swagger. Un'operazione elenco restituisce riepiloghi sicuri, mentre l'operazione dettaglio restituisce i dati sensibili necessari per una sincronizzazione controllata.

Aggiungi ogni endpoint alla base degli endpoint. Esempio:

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

Risorsa di registrazione

Creazione e aggiornamento usano la risorsa di registrazione completa:

{
  "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"
  }
}

Le proprietà si comportano nel modo seguente:

• userId è l'ID utente FoxIDs stabile.
• id è un ID di registrazione persistente fornito dal client durante la creazione. Seleziona la registrazione durante l'aggiornamento e non può essere modificato.
• createTime è espresso in secondi Unix. È facoltativo in creazione e per impostazione predefinita usa l'ora corrente. Se omesso in aggiornamento, conserva il valore esistente.
• secret è il TOTP secret condiviso ed è obbligatorio durante creazione e aggiornamento.
• recoveryCode contiene i dati hash del recovery code ed è omesso quando non è configurato alcun recovery code.

Un utente può avere al massimo cinque registrazioni di app di autenticazione. La creazione con un ID esistente restituisce 409 Conflict; la creazione dopo il raggiungimento del limite restituisce 400 Bad Request.

Sincronizzare le registrazioni

Un servizio di sincronizzazione può combinare l'Authenticator App notification API interattiva con queste operazioni Control API:

1. Ricevi la notification registered contenente user_id e registration_id.
2. Ottieni la registrazione dal source deployment con l'operazione dettaglio.
3. Crea la registrazione nel target deployment o aggiornala se esiste già lo stesso ID.

Le operazioni Control API di creazione, aggiornamento ed eliminazione non chiamano l'Authenticator App notification API. La sincronizzazione non genera quindi un ciclo di notification.

Sicurezza

Le operazioni dettaglio, creazione e aggiornamento espongono o accettano un secret dell'app di autenticazione e i dati hash del recovery code. Concedi il diritto utente richiesto solo a client affidabili, usa TLS, proteggi i payloads archiviati e non registrare request o response bodies.

Usa l'operazione elenco quando servono solo gli ID di registrazione e le date di creazione. Non restituisce il secret né i dati hash del recovery code.

Proprietà di compatibilità

La proprietà activeTwoFactorApp dell'API utente generale è deprecated e la rimozione è prevista dopo il 1° agosto 2027. In una update-request, false elimina ancora tutte le registrazioni per compatibilità; true o un valore omesso le lascia invariate. Le nuove integrazioni devono usare gli endpoint delle app di autenticazione.

Response di errore

Le response di errore comuni per utenti e app di autenticazione sono:

• 400 Bad Request se identificatori, credenziali, filtri o dati non sono validi oppure è stato raggiunto il limite.
• 401 Unauthorized se l'access token manca o non è valido.
• 403 Forbidden se il client non dispone del diritto utente richiesto per l'ambiente.
• 404 Not Found se l'utente o la registrazione dell'app non esiste.
• 409 Conflict se l'utente esiste già o viene riutilizzato un ID di registrazione.
• 423 Locked se creazione o importazione in blocco sono temporaneamente bloccate. Riprova dopo poco.

Usa il response body per i dettagli di validazione. Consulta Swagger UI per le response dichiarate per ogni operazione.

Documentazione correlata

• Autenticazione e diritti di accesso Control API
• Panoramica di FoxIDs Control
• Utenti interni
• Autenticazione a due fattori e multifattore
• Carica molti utenti