Directory Connector

Directory Connector consente a FoxIDs di usare una directory esterna come fonte autorevole per le password degli utenti interni e per dati utente selezionati.

Gli utenti continuano a esistere come utenti interni nell'ambiente FoxIDs. Durante l'autenticazione password e le operazioni del ciclo di vita della password, FoxIDs chiama l'API di Directory Connector invece di validare la password solo contro l'utente interno FoxIDs.

Poiché FoxIDs mantiene un record utente interno, la gestione dell'autenticazione multi-factor (MFA) di FoxIDs può essere aggiunta agli utenti del repository esterno. Il connector può restituire impostazioni utente relative alla MFA, come requireMultiFactor e metodi two-factor disabilitati, e FoxIDs applica tali impostazioni all'utente interno mentre il repository esterno rimane autorevole per password e dati utente selezionati.

Per Active Directory, FoxIDs include un componente Directory Connector per Active Directory deployabile in IIS.

Usa Directory Connector quando:

  • Vuoi che gli utenti effettuino il login con il normale metodo di autenticazione login.
  • Vuoi abilitare utenti da una directory esistente per applicazioni OpenID Connect e SAML 2.0 tramite FoxIDs.
  • La tua directory esterna e autorevole per validazione password e cambio password.
  • Vuoi che FoxIDs mantenga un record utente interno con identificatori, proprieta, claim, impostazioni di autenticazione multi-factor (MFA), assegnazioni di accesso e, facoltativamente, una copia locale della password.
  • Vuoi un percorso per passare in seguito a utenti interni e validazione password in FoxIDs senza costringere tutti gli utenti a un reset della password.

Esiste un solo Directory Connector per ambiente. Quando e abilitato, si applica a livello di ambiente.

Come funziona

FoxIDs sincronizza su richiesta quando un utente inserisce un identificatore in un flusso di accesso o recupero. Chiama synchronise-user prima di verificare l’account, crea un utente FoxIDs se necessario e aggiorna identificatori, proprietà e claim gestiti dalla directory.

La sincronizzazione è parte dell’attivazione di Directory Connector. FoxIDs sincronizza all’inizio dell’accesso, del recupero e delle verifiche degli account nelle sessioni esistenti, nonché quando un refresh token viene usato per un account collegato alla directory. Le continuazioni con codici di conferma, MFA ed Extended UI usano l’account selezionato e i normali controlli FoxIDs. Se la sincronizzazione fallisce, il flusso si interrompe.

La risposta deve includere un directoryUserId stabile e univoco. Usare l’ID permanente dell’account nella directory, non email, telefono o nome utente. Questo collegamento permette a FoxIDs di ritrovare lo stesso account dopo modifiche agli identificatori. Le app di autenticazione registrate e le assegnazioni di accesso FoxIDs vengono mantenute.

Quando l’utente inserisce un identificatore, FoxIDs invia solo quell’email, telefono o nome utente. Per riutilizzare sessioni e gestire richieste con refresh token, FoxIDs carica l’utente associato e sincronizza tramite l’ID della directory memorizzato sull’utente. Anche le operazioni sulle password usano l’ID dell’utente caricato. Non viene memorizzato separatamente nella sequenza di accesso.

Il connettore restituisce tutti i dati utente correnti. FoxIDs sostituisce identificatori, proprietà e claim gestiti dalla directory, inclusi stato di disabilitazione, obbligo di cambio password e impostazioni per la prima definizione della password. Applica gli stessi controlli di account, recupero e MFA previsti per gli utenti interni. Gli utenti interni senza collegamento alla directory non vengono sincronizzati né collegati automaticamente.

Una risposta con disableAccount: true disabilita l’utente FoxIDs e revoca sessioni attive e refresh-token grant. Se il connettore restituisce user_deleted durante la sincronizzazione tramite ID della directory, FoxIDs elimina l’utente interno e revoca sessioni attive e refresh token. Se una ricerca per solo identificatore non trova account, FoxIDs controlla eventuali collegamenti esistenti alla directory prima di proseguire, evitando che dati locali obsoleti consentano accesso o recupero. Il solo codice user_not_exists non elimina un account.

Le richieste con refresh token verificano sia l’account originale sia un account locale usato tramite impersonificazione, se collegati alla directory. Se la sincronizzazione rileva un account disabilitato o eliminato, FoxIDs revoca sessioni attive e refresh-token grant e rifiuta il rinnovo corrente. La normale verifica delle sessioni attive convalida lo stato della sessione FoxIDs; non contatta direttamente la directory. Un’applicazione che convalida localmente un access token emesso ne rispetta la scadenza, non la revoca della sessione FoxIDs.

Le modifiche diventano disponibili alla successiva verifica dell’account su richiesta. Non esiste un processo di sincronizzazione in background.

Directory Connector può essere un’integrazione permanente, con utenti e password gestiti nella directory esterna, oppure uno strumento per migrare gradualmente gli utenti a FoxIDs. Durante la migrazione, mantenere attivo il connettore mentre vengono creati gli utenti e abilitare la copia locale della password per salvare le password dopo autenticazioni, modifiche o reimpostazioni riuscite tramite FoxIDs.

Terminata la migrazione, disabilitare Directory Connector e gestire utenti e password direttamente in FoxIDs. Prima del passaggio, creare gli utenti non ancora presenti e predisporre definizione o recupero della password per chi non dispone di una copia locale aggiornata. La copia riflette l’ultima autenticazione, modifica o reimpostazione riuscita tramite FoxIDs; le modifiche successive eseguite solo nella directory esterna non sono incluse.

Protezione delle ricerche

Quando un utente inserisce email, telefono o nome utente nell’interfaccia di accesso o recupero, la ricerca nella directory conta per un limite condiviso da tutti gli identificatori della sequenza corrente. Si usano le impostazioni dell’ambiente Failed login attempt limit, durata del contatore e periodo di osservazione. Contano sia le ricerche riuscite sia le chiamate fallite; un’autenticazione tramite password riuscita non azzera il contatore. Al limite occorre attendere il periodo di osservazione o avviare una nuova sequenza. La sincronizzazione per riuso delle sessioni e richieste con refresh token non usa questo contatore. Le protezioni di password e codici di conferma mantengono i propri contatori separati.

Identificatori di login e collegamento alla directory

Gli utenti possono accedere con email, telefono o nome utente correnti, secondo i tipi abilitati nel metodo di accesso. Prima dell’autenticazione tramite password, l’identificatore deve corrispondere a uno attuale restituito dal connettore. FoxIDs rimuove gli spazi iniziali e finali. Email e nomi utente vengono confrontati senza distinzione tra maiuscole e minuscole. I telefoni usano il formato internazionale richiesto.

Accesso dopo la modifica degli identificatori

Quando viene inserito un identificatore, FoxIDs sincronizza email, telefono e nome utente dalla directory. L’ID stabile mantiene il collegamento allo stesso account FoxIDs anche se cambia uno o tutti gli identificatori. App di autenticazione registrate e assegnazioni di accesso vengono mantenute; restrizioni e requisiti MFA esistenti continuano ad applicarsi.

Situazione Comportamento durante la sincronizzazione
L’utente accede con un nome utente invariato, mentre email o telefono sono cambiati nella directory. FoxIDs aggiorna lo stesso account con gli identificatori correnti restituiti dal connettore.
L’utente accede con un nuovo identificatore ancora sconosciuto a FoxIDs. Se la directory restituisce il nuovo identificatore e lo stesso ID stabile, l’utente continua con l’account FoxIDs esistente. Funziona anche se tutti gli identificatori sono cambiati.
L’utente accede con un vecchio identificatore che il connettore non restituisce più. L’accesso viene rifiutato con il normale errore, anche se l’utente conosce ancora la password. Deve usare un identificatore corrente di un tipo abilitato.
Il connettore smette di restituire email, telefono o nome utente. L’identificatore viene rimosso dall’account FoxIDs durante la sincronizzazione. Il connettore deve restituire almeno un identificatore corrente.

Ad esempio, un utente la cui email cambia da old@example.org a new@example.org può accedere con new@example.org prima che FoxIDs conosca l’indirizzo. Il connettore deve restituire new@example.org e l’ID della directory invariato. Account e app di autenticazione registrate vengono mantenuti. In alternativa si può usare un nome utente invariato, se questa modalità è abilitata.

Il connettore deve restituire tutti gli identificatori correnti da conservare in FoxIDs. Valori omessi o vuoti sono trattati come identificatori rimossi; i valori precedenti non vengono mantenuti come alias di accesso. Solo i tipi abilitati nel metodo di accesso possono essere utilizzati.

Conflitti tra account

Ogni utente della directory deve avere un ID stabile e univoco; i suoi identificatori non devono appartenere ad altri account FoxIDs. FoxIDs cerca prima l’identificatore nella directory, poi usa l’ID restituito per trovare o creare l’account locale. Se il salvataggio degli identificatori genera un conflitto, il flusso si interrompe. Un amministratore deve correggere la configurazione della directory o dell’account FoxIDs; gli account non vengono uniti o riassegnati automaticamente.

Un utente interno esistente senza collegamento alla directory non può accedere tramite Directory Connector. L’attivazione non collega automaticamente un account a un utente della directory solo perché email, telefono o nome utente coincidono.

Copia locale della password

La directory esterna e autorevole finche Directory Connector e abilitato. FoxIDs non usa fallback all'hash locale della password se l'API di Directory Connector e temporaneamente non disponibile.

Per impostazione predefinita, FoxIDs salva una copia locale della password sull'utente interno dopo una validazione password riuscita del connector o dopo un'operazione del ciclo di vita della password. Questo puo essere disabilitato nelle impostazioni dell'ambiente.

La copia locale della password non viene usata finche Directory Connector e abilitato. Esiste per supportare un futuro passaggio a utenti interni e validazione password in FoxIDs senza costringere tutti gli utenti a un reset della password.

Ciclo di vita della password

La creazione degli utenti e le operazioni del ciclo di vita della password vengono delegate all’API di Directory Connector:

  • L'autenticazione password chiama l'endpoint authentication.
  • La creazione di utenti nel flusso di accesso chiama l’endpoint create-user.
  • Il cambio password dell'utente chiama l'endpoint change-password.
  • I flussi set-password e reset-password chiamano l'endpoint set-password.

Gli endpoint delle password ricevono il directoryUserId stabile dell’utente caricato. La directory verifica stato corrente e credenziali durante l’operazione. Autenticazione, modifica e reimpostazione restituiscono successo o errore. La creazione restituisce l’ID della directory dell’account creato, che FoxIDs usa per una sincronizzazione separata.

Le operazioni sulle password usano l’ID della directory memorizzato sull’utente FoxIDs caricato. Il connettore controlla stato e credenziali o autorizzazione alla reimpostazione richieste, esegue l’azione e restituisce successo o errore. Identificatori, attributi e claim vengono restituiti solo dalla sincronizzazione.

Dopo una modifica o reimpostazione riuscita, FoxIDs registra l’ora corrente del cambiamento e rimuove gli obblighi di modificare o definire una password. Salva anche una copia locale, se configurato. La sequenza attiva prosegue con la normale gestione di account, recupero e MFA.

Se un’azione fallisce o FoxIDs non può salvare le modifiche note della password, il flusso si interrompe. Una modifica già accettata dalla directory non viene annullata e FoxIDs non ripete automaticamente l’azione dopo timeout o risposta fallita. La sincronizzazione successiva aggiorna l’account locale.

Con Enable password policy attivo, FoxIDs verifica la password corrente della directory prima di applicare i controlli alla nuova password. Può essere necessaria una chiamata di autenticazione aggiuntiva prima di change-password.

FoxIDs non aggiorna il proprio storico interno delle password quando viene usato Directory Connector, perche FoxIDs non conosce necessariamente tutti i cambi di password nella directory esterna.

Definizione e recupero della password

Al primo accesso, un utente della directory può definire una password con un codice di conferma via email o SMS, perché l’ha dimenticata o deve sceglierne una nuova.

Per usare Forgot your password?, inserire un identificatore corrente della directory di un tipo abilitato nel metodo di accesso. FoxIDs sincronizza e crea l’account prima di inviare il codice. Il recupero via email o SMS deve essere attivo e l’utente deve poter accedere al contatto corrente restituito dalla directory.

Dopo la verifica del codice e l’invio della nuova password, FoxIDs chiama set-password con l’ID stabile. Restituire setPasswordEmail o setPasswordSms e il relativo identificatore di contatto per imporre questo percorso. FoxIDs usa il normale flusso di definizione della password.

I codici di conferma sono legati all’account per cui sono stati emessi. Gli account gestiti da un connettore di directory usano la stessa verifica dei codici degli altri utenti interni. FoxIDs mantiene la normale gestione degli errori di recupero senza esporre la diagnostica del connettore.

Policy password e messaggi di errore

La directory esterna applica la policy password. FoxIDs usa la policy password dell'ambiente quando mostra i messaggi di errore di policy restituiti dal connector.

Configura la policy password dell'ambiente in modo che corrisponda alla policy password della directory esterna. Se non corrispondono, gli utenti possono vedere indicazioni sulle password che non riflettono i reali requisiti della directory esterna.

Ad esempio, se la directory esterna rifiuta una password perche troppo corta, FoxIDs usa la lunghezza minima della password dell'ambiente nel rendering del messaggio di errore.

Implementare API

Implementi una API di Directory Connector e configuri FoxIDs con il relativo URL base e secret.

L’API ha un URL di base e cinque endpoint:

  • synchronise-user cerca un utente e restituisce stato corrente dell’account, identificatori e claim.
  • authentication valida la password corrente di un utente.
  • create-user crea un utente nella directory esterna e restituisce il suo ID permanente.
  • change-password valida la password corrente e la cambia con una nuova password.
  • set-password imposta una nuova password senza validare quella corrente.

Se l’URL di base è https://somewhere.org/directory, gli endpoint sono:

  • https://somewhere.org/directory/synchronise-user
  • https://somewhere.org/directory/authentication
  • https://somewhere.org/directory/create-user
  • https://somewhere.org/directory/change-password
  • https://somewhere.org/directory/set-password

FoxIDs Cloud chiama la tua API dall'IP 57.128.60.142. Gli IP possono cambiare o essere ampliati.

Sicurezza

Le richieste sono protette con HTTP Basic authentication:

  • Username: directory_connector
  • Password: il secret API configurato

La chiamata e HTTP POST con un body JSON.

FoxIDs invia la lingua selezionata nell’header Accept-Language, ad esempio Accept-Language: da-DK. Nel flusso di accesso segue la lingua scelta da ui_locales o dal browser, con inglese come ripiego FoxIDs. L’API può usare l’header per localizzare i messaggi e deve scegliere un proprio ripiego se non supporta la lingua richiesta. L’header viene inviato a tutti e cinque gli endpoint.

Richiesta di sincronizzazione

L’endpoint synchronise-user riceve un identificatore utente o un ID noto della directory. La prima ricerca durante accesso o recupero usa l’identificatore inserito. FoxIDs usa il directoryUserId salvato per verifiche di sessioni esistenti e richieste con refresh token, e l’ID restituito dopo create-user.

Una ricerca iniziale per email:

{
  "email": "user1@somewhere.org"
}

Una successiva verifica dell’account:

{
  "directoryUserId": "a1b2c3d4"
}

Usare directoryUserId come chiave di ricerca autorevole quando presente. Altrimenti cercare esattamente uno tra email, phone o username. Restituire HTTP 200 con tutti i dati utente, anche per account disabilitati. Restituire user_deleted se l’ID noto manca e user_not_exists se una ricerca per solo identificatore non trova account. Un identificatore fornito non prova mai la proprietà dell’account.

FoxIDs sceglie l’identificatore della richiesta secondo i tipi abilitati per l’accesso. Se è attivo solo il nome utente, una stringa in formato email viene inviata come username. Gli spazi iniziali e finali vengono rimossi. L’input deve coincidere con un identificatore corrente di un tipo abilitato nella risposta; il campo ipotizzato nella richiesta non limita quale campo della risposta può corrispondere.

Per gli errori, vedere Risposta di errore.

Risposta in caso di esito positivo

L’endpoint synchronise-user restituisce HTTP 200 con tutti i dati utente correnti. Se la richiesta include un ID della directory, la risposta deve contenere lo stesso ID. FoxIDs lo verifica prima di salvare i dati. HTTP 204 o dati incompleti vengono rifiutati.

{
  "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 usa la risposta per creare o aggiornare l'utente interno nell'ambiente.

Campi:

  • directoryUserId e obbligatorio. Deve essere stabile e univoco nella directory esterna ed e salvato sull'utente interno FoxIDs.
  • email, phone e username sono opzionali singolarmente, ma almeno uno deve essere presente. FoxIDs memorizza i valori restituiti come identificatori dell’utente interno. I valori degli identificatori utente restituiti devono identificare in modo univoco un solo utente nella directory esterna usata dal connector.
  • phone deve includere il prefisso internazionale nel formato internazionale, ad esempio +4511223344.
  • confirmAccount controlla se FoxIDs deve eseguire un flusso di conferma per confermare l'utente interno.
  • disableAccount controlla lo stato diretto di disabilitazione. Il passaggio a disabilitato revoca le sessioni FoxIDs e i refresh-token grant dell’utente.
  • changePassword impone il cambio password dopo la verifica riuscita delle credenziali.
  • setPasswordEmail e setPasswordSms impongono la definizione della password tramite il rispettivo flusso di conferma. Devono essere presenti il contatto e il metodo di recupero abilitato.
  • disableSetPasswordEmail e disableSetPasswordSms disabilitano i rispettivi metodi di recupero.
  • passwordLastChanged è un timestamp Unix facoltativo non negativo, in secondi. Fornito dalla sincronizzazione, aggiorna l’età della password usata da FoxIDs. Se omesso, resta il timestamp esistente. Una modifica o reimpostazione riuscita registra l’ora corrente in FoxIDs; una sincronizzazione successiva può fornire il timestamp autorevole della directory.
  • emailVerified controlla se l'email dell'utente interno viene marcata come verificata.
  • phoneVerified controlla se il numero di telefono dell'utente interno viene marcato come verificato.
  • disableTwoFactorApp disabilita l'autenticazione a due fattori con app autenticatrice per l'utente interno.
  • disableTwoFactorSms disabilita l'autenticazione a due fattori via SMS per l'utente interno.
  • disableTwoFactorEmail disabilita l'autenticazione a due fattori via email per l'utente interno.
  • requireMultiFactor controlla se l'utente interno deve usare l'autenticazione multifattore.
  • claims e facoltativo. FoxIDs salva i claim restituiti sull'utente interno.

I claim supportano un valueType facoltativo: String, Boolean, Number, JsonObject o JsonArray. Il campo value rimane testo; omettere valueType per String. FoxIDs conserva il tipo selezionato e registra un avviso prima di ricorrere al testo per un valore non valido. Vedere tipi dei valori dei claim per esempi e limiti numerici. La stessa rappresentazione viene utilizzata per i claim inviati nelle richieste di creazione degli utenti e restituiti nelle risposte di sincronizzazione.

FoxIDs ignora i claim il cui type o value è assente, è null, è vuoto o contiene solo caratteri di spaziatura. Quando il tracciamento dei messaggi di log è attivo, la traccia della risposta include i claim ricevuti prima che vengano filtrati. I messaggi di traccia lunghi vengono troncati.

Anche i claim protetti, come sid e auth_time, vengono scartati dalle risposte di sincronizzazione.

Richiesta di autenticazione

L’endpoint authentication riceve l’ID stabile obbligatorio della directory e la password corrente.

{
  "directoryUserId": "a1b2c3d4",
  "password": "testpass1"
}

Verificare lo stato attuale dell’account nella directory e la password prima di restituire successo. Verificare la password prima di fornire indicazioni sui criteri specifiche dell’account.

Per gli errori, vedere Risposta di errore.

Risposta in caso di esito positivo

In caso di successo, restituire HTTP 204 senza corpo della risposta.

Richiesta di creazione utente

L'endpoint create-user riceve esattamente un identificatore utente, una password obbligatoria, le proprietà create-user selezionate e i claim raccolti durante il flusso create-user di FoxIDs.

{
  "email": "user1@somewhere.org",
  "password": "testpass1",
  "confirmAccount": true,
  "requireMultiFactor": false,
  "claims": [
    { "type": "given_name", "value": "User" },
    { "type": "family_name", "value": "One" }
  ]
}

Campi:

  • Viene inviato esattamente uno tra email, phone o username.
  • password è obbligatoria. Creare un utente senza password non è supportato con Directory Connector, perché l'API Directory Connector autentica gli utenti con una password.
  • confirmAccount e requireMultiFactor sono le impostazioni richieste per la creazione dell’utente in FoxIDs.
  • claims contiene i claim diversi dagli identificatori raccolti durante la creazione dell’utente in FoxIDs.

Per gli errori, vedere Risposta di errore.

Risposta in caso di esito positivo

In caso di successo, restituire HTTP 200 con l’ID permanente dell’account creato:

{
  "directoryUserId": "a1b2c3d4"
}

FoxIDs chiama quindi synchronise-user con questo ID per recuperare l’account completo e creare l’utente interno FoxIDs.

Richiesta change-password

L’endpoint change-password riceve l’ID obbligatorio della directory e le password corrente e nuova. Verificare quella corrente prima di fornire indicazioni sui criteri specifiche dell’account.

{
  "directoryUserId": "a1b2c3d4",
  "currentPassword": "oldpass1",
  "newPassword": "newpass1"
}

Per gli errori, vedere Risposta di errore.

Risposta in caso di esito positivo

In caso di successo, restituire HTTP 204 senza corpo. La modifica deve soddisfare il requisito di password nella directory.

Richiesta set-password

L’endpoint set-password riceve l’ID obbligatorio e la nuova password. FoxIDs lo chiama dopo l’autorizzazione alla reimpostazione o definizione, inclusa la verifica dei codici nei flussi di recupero. Il connettore deve ricontrollare lo stato corrente dell’account prima della modifica.

{
  "directoryUserId": "a1b2c3d4",
  "password": "newpass1"
}

Per gli errori, vedere Risposta di errore.

Risposta in caso di esito positivo

In caso di successo, restituire HTTP 204 senza corpo. La reimpostazione o definizione deve soddisfare il requisito di password nella directory.

Risposta di errore

Tutti gli endpoint usano lo stesso formato di errore JSON. Restituire un codice supportato dall’endpoint in error e i dettagli diagnostici in errorMessage. Ad esempio, una password rifiutata da authentication:

{
  "error": "invalid_password",
  "errorMessage": "Invalid password."
}

Usare questi codici di stato HTTP:

  • 401 con invalid_api_id_secret quando l’autenticazione HTTP Basic viene rifiutata.
  • 400, 401 o 403 per gli altri codici supportati nella tabella degli endpoint seguente.
  • 500 per un errore tecnico del connettore.

Il campo errorMessage contiene testo diagnostico per i log di FoxIDs e non viene mostrato all’utente finale. Indica la causa dell’errore, ma non includere mai password, segreti API o chiavi private.

Solo authentication può restituire login_rejected, dopo aver verificato identificatore e password. Può includere un uiErrorMessage facoltativo, mostrato da FoxIDs come testo semplice nel modulo di accesso. L’API fornisce il messaggio nella lingua selezionata tramite Accept-Language:

{
  "error": "login_rejected",
  "errorMessage": "Credentials verified; login rejected by directory policy.",
  "uiErrorMessage": "You cannot log in here. Contact support."
}

Se uiErrorMessage è omesso, null, vuoto o contiene solo spazi, FoxIDs mostra lo stesso messaggio generale localizzato di invalid_password e operation_rejected. Per gli altri codici supportati, FoxIDs ignora uiErrorMessage e sceglie il messaggio dai propri testi localizzati. La diagnostica errorMessage non viene mai usata come messaggio utente di ripiego. Vedere Errori di autenticazione e privacy per i requisiti di verifica.

Gli errori di authentication, change-password e set-password non restituiscono dati utente, non modificano l’account interno e non revocano sessioni o refresh token esistenti. La sincronizzazione applica le modifiche della directory. I tentativi rifiutati di autenticazione e cambio password continuano a contare per il limite esistente degli accessi falliti.

Codici di errore supportati per endpoint:

Codice di errore synchronise-user authentication create-user change-password set-password Significato
invalid_api_id_secret Sì Sì Sì Sì Sì Il nome utente o il segreto dell’API per HTTP Basic authentication non è valido.
user_exists No No Sì No No Un utente con l’identificatore fornito esiste già nella directory esterna.
user_not_exists Senza ID della directory No No No No Nessun utente della directory corrisponde alla ricerca per solo identificatore.
invalid_password No Sì No No No La directory ha rifiutato la password di una richiesta di autenticazione.
login_rejected No Sì No No No L’accesso è stato rifiutato dopo la verifica dell’identificatore utente e della password. Un uiErrorMessage facoltativo viene visualizzato nel modulo di accesso.
invalid_current_password No No No Sì No La directory ha rifiutato la password attuale di una richiesta di modifica della password.
create_user_not_supported No No Sì No No Il connettore non supporta la creazione di utenti nella directory esterna.
operation_rejected No Sì No Sì Sì L’operazione non può essere completata, ad esempio perché l’account non è disponibile. FoxIDs registra errorMessage, ignora uiErrorMessage e mostra un errore generale localizzato senza cambiare lo stato dell’account.
user_deleted Con ID della directory No No No No Un ID noto non esiste più. FoxIDs revoca l’accesso ed elimina l’utente durante la sincronizzazione.
password_not_accepted No Sì Sì Sì Sì La password che viene verificata, usata per creare un utente, modificata o impostata è stata rifiutata da una regola per le password della directory che non corrisponde a un codice più specifico.
password_min_length No Sì Sì Sì Sì La password che viene verificata, usata per creare un utente, modificata o impostata è più corta della lunghezza minima delle password della directory.
password_max_length No Sì Sì Sì Sì La password che viene verificata, usata per creare un utente, modificata o impostata è più lunga della lunghezza massima delle password della directory.
password_banned_characters No Sì Sì Sì Sì La password che viene verificata, usata per creare un utente, modificata o impostata contiene uno o più caratteri o parole rifiutati dalla directory.
password_complexity No Sì Sì Sì Sì Errore precedente di complessità dei caratteri che FoxIDs interpreta come password_character_variation. Usa uno dei due codici di errore specifici per i caratteri nelle nuove integrazioni.
password_character_repeat No Sì Sì Sì Sì La password che viene verificata, usata per creare un utente, modificata o impostata contiene troppe ripetizioni di caratteri.
password_character_variation No Sì Sì Sì Sì La password che viene verificata, usata per creare un utente, modificata o impostata non contiene una varietà sufficiente di caratteri.
password_email_text_complexity No Sì Sì Sì Sì La password che viene verificata, usata per creare un utente, modificata o impostata contiene l’indirizzo email dell’utente o parte di esso.
password_phone_text_complexity No Sì Sì Sì Sì La password che viene verificata, usata per creare un utente, modificata o impostata contiene il numero di telefono dell’utente o parte di esso.
password_username_text_complexity No Sì Sì Sì Sì La password che viene verificata, usata per creare un utente, modificata o impostata contiene il nome utente o parte di esso.
password_url_text_complexity No Sì Sì Sì Sì La password che viene verificata, usata per creare un utente, modificata o impostata contiene testo relativo all’URL di FoxIDs.
password_risk No Sì Sì Sì Sì La password che viene verificata, usata per creare un utente, modificata o impostata è nota per essere rischiosa, compromessa o altrimenti non sicura.
password_history No No No Sì Sì La nuova password è stata rifiutata perché già utilizzata in precedenza.
password_expired No Sì No No No La password fornita è stata verificata ma è scaduta; l’utente deve cambiarla prima di continuare l’autenticazione.
new_password_equals_current No No No Sì No La nuova password è uguale a quella attuale. set-password non può restituire questo errore perché non riceve la password attuale.

Se FoxIDs deve controllare i propri criteri prima di un cambio password, chiama prima authentication per verificare quella corrente. Se il connettore restituisce password_expired da questa autenticazione, il cambio può proseguire. L’endpoint change-password deve accettare una password corrente scaduta ma verificata e restituire solo errori supportati per la modifica.

Per gli errori di policy password, FoxIDs usa la policy password dell'ambiente per mostrare il messaggio di errore rivolto all'utente. Vedi Policy password e messaggi di errore.

Restituire solo codici supportati dall’endpoint e dal directoryUserId fornito, come indicato sopra. Codici non supportati, risposte malformate o stati HTTP inattesi sono errori di integrazione e portano alla pagina di errore generale. Vedere Risoluzione degli errori del browser per trovare i dettagli diagnostici con gli identificatori della pagina.

Errori di autenticazione e privacy degli utenti

Un chiamante non autenticato non deve poter determinare se un nome utente o un indirizzo email esiste sulla base di un errore di accesso. Durante l’autenticazione con password, FoxIDs gestisce gli errori supportati come segue:

Errore del connettore Risultato per l’utente
invalid_password, operation_rejected o un account non disponibile rilevato durante la sincronizzazione Lo stesso messaggio generico di accesso, ad esempio Email o password errata., tradotto nella lingua attiva e adattato agli identificatori di accesso abilitati.
login_rejected Il uiErrorMessage fornito, oppure lo stesso messaggio generico di accesso se manca o è vuoto, nella stessa posizione del modulo di accesso.
password_not_accepted La pagina di modifica della password con indicazioni generali sulla policy password.
password_expired o un altro errore specifico della policy password La pagina di modifica della password con le corrispondenti indicazioni localizzate sulla policy password.

Il connettore deve verificare la password attuale fornita prima di restituire un errore della policy password da authentication. Altrimenti, una pagina o un messaggio diverso può consentire a un attaccante di scoprire utenti e confermare i loro identificatori provando a indovinare nomi utente o indirizzi email. Per change-password, verifica la password attuale prima di restituire indicazioni specifiche per l’account sulla nuova password. I controlli generali sul formato non devono rivelare se un account esiste.

Se un utente non può usare questo flusso per qualsiasi motivo, verificare prima identificatore e password forniti. Rifiutare in base alla restrizione solo dopo averli verificati entrambi, affinché non riveli se un identificatore indovinato appartiene a un utente reale. Restituire login_rejected da authentication, indicare la ragione diagnostica in errorMessage ed eventualmente istruzioni sicure in uiErrorMessage. Se le credenziali non sono verificabili, restituire il normale errore senza rivelare la restrizione.

FoxIDs si affida al connettore per verificare le credenziali prima di login_rejected; una ricerca riuscita o la conoscenza di directoryUserId non basta. Prima della verifica, mostrare istruzioni o pulsanti per metodi alternativi indipendentemente dall’esistenza di un account corrispondente all’identificatore.

Solo synchronise-user comunica lo stato dell’account: restituire tutti i dati con disableAccount: true per un account disabilitato, oppure user_deleted quando un ID noto non esiste più. Gli endpoint di password restituiscono operation_rejected se l’account non è disponibile. Diversamente da login_rejected, non richiede una password verificata perché non fornisce mai indicazioni specifiche dell’account al browser.

Gestisci gli errori in modo coerente per gli identificatori noti e sconosciuti, compresi i tempi di risposta osservabili e la protezione dai tentativi ripetuti. Un messaggio generico da solo non impedisce la scoperta di utenti se un reindirizzamento, uno stato o un tempo di risposta diverso rivela il risultato. Segui le linee guida OWASP sugli errori di autenticazione durante l’implementazione del connettore.

Esempio di API

Il sample DirectoryConnectorApiSample mostra come implementare l'API di Directory Connector in ASP.NET Core.

Implementazioni e client di test devono seguire i contratti sopra: HTTP 200 con dati utente completi per synchronise-user, HTTP 200 con ID creato per create-user e HTTP 204 senza corpo per operazioni sulle password riuscite.

Componente Active Directory

FoxIDs include un Directory Connector per Active Directory distribuibile su IIS. Implementa l’API per un dominio AD/LDAP e può sincronizzare account, convalidare, modificare e impostare password, e restituire come claim attributi AD e appartenenze a gruppi AD annidati configurati.

Configurare

Configura Directory Connector nelle impostazioni dell'ambiente in FoxIDs Control Client.

  1. Selezionare la scheda Impostazioni.
  2. Selezionare la scheda Ambiente.
  3. Trova la sezione Directory Connector.
  4. Abilita Directory Connector.
  5. Aggiungi l'URL base dell'API senza la cartella dell'endpoint in API URL.
  6. Aggiungi API secret.
  7. Decidi se salvare una copia locale della password.
  8. Configura la policy password dell'ambiente in modo che corrisponda alla policy password della directory esterna.
  9. Fai clic su Update.

Directory Connector settings