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

Quando un utente effettua il login con username e password, FoxIDs chiama l'API di Directory Connector.

In caso di validazione riuscita, FoxIDs crea o aggiorna l'utente interno nell'ambiente in base alla risposta dell'API. La risposta deve includere un directoryUserId stabile, che viene salvato sull'utente interno e usato per collegare l'utente FoxIDs all'utente della directory esterna.

Il directoryUserId non e un identificatore utente noto all'utente finale. E un ID separato e stabile della directory esterna. Non usare email, telefono o username come directoryUserId, perche questi valori possono cambiare. Il valore deve essere stabile e univoco nella directory esterna.

Se FoxIDs conosce gia il directoryUserId dell'utente interno, questo valore viene inviato nella richiesta Directory Connector insieme a esattamente uno tra email, telefono o username dell'utente. Questo consente alla directory esterna di identificare l'utente anche se un identificatore e cambiato.

Se l'API di Directory Connector valida correttamente l'utente, FoxIDs aggiorna l'utente interno con identificatori, proprieta selezionate e claim restituiti dall'API.

Se il connector segnala che l'utente e disabilitato o eliminato, FoxIDs disabilitera o eliminera l'utente interno nell'ambiente.

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

Le operazioni del ciclo di vita della password vengono delegate all'API di Directory Connector:

  • L'autenticazione password chiama l'endpoint authentication.
  • Login create-user flow calls the create-user endpoint.
  • Il cambio password dell'utente chiama l'endpoint change-password.
  • I flussi set-password e reset-password chiamano l'endpoint set-password.

FoxIDs normalmente chiama gli endpoint del ciclo di vita della password solo quando l'utente interno e noto e ha un directoryUserId. L'eccezione e change-password durante il primo login, quando la directory esterna ha restituito password_expired prima che FoxIDs abbia creato l'utente interno. In questo caso FoxIDs invia l'identificatore di login e la password corrente senza directoryUserId; dopo un cambio password riuscito, FoxIDs usa la risposta di successo per creare l'utente interno e salvare il directoryUserId restituito.

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.

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.

The API has a base URL and four endpoints:

  • authentication valida la password corrente di un utente.
  • create-user creates a new user in the external directory and returns the created user.
  • 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 base e https://somewhere.org/directory, gli endpoint sono:

  • 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 della richiesta Accept-Language, ad esempio Accept-Language: da-DK. In un flusso di accesso, corrisponde alla lingua selezionata tramite ui_locales o il browser, con l’inglese come lingua di ripiego in FoxIDs. L’API può usare questo header per localizzare i messaggi destinati all’utente e deve scegliere una propria lingua di ripiego se non supporta quella richiesta. Questo header viene inviato a tutti e quattro gli endpoint.

Richiesta di autenticazione

L'endpoint authentication riceve la password dell'utente e esattamente un identificatore utente. FoxIDs invia directoryUserId se l'utente interno esiste e il valore e noto.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "password": "testpass1"
}

Campi:

  • directoryUserId e facoltativo. FoxIDs lo invia quando l'utente interno esiste e il valore e noto.
  • Viene inviato esattamente uno tra email, phone o username.
  • password e obbligatoria.

FoxIDs seleziona l'identificatore in base all'input di login dell'utente e alle impostazioni degli identificatori abilitati. Ad esempio, se è abilitato solo username e l'utente inserisce user1@somewhere.org, FoxIDs lo invia come username. FoxIDs rimuove gli spazi circostanti prima di inviare lo username al connector.

Create-user request

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 dei campi 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.

In caso di esito positivo, restituisci una normale risposta di successo. FoxIDs memorizza il directoryUserId restituito nell’utente interno creato dopo la creazione dell’utente nella directory esterna.

Richiesta change-password

L'endpoint change-password riceve esattamente un identificatore utente, la password corrente e la nuova password. FoxIDs invia directoryUserId quando l'utente interno esiste e il valore e noto.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "currentPassword": "oldpass1",
  "newPassword": "newpass1"
}

Campi:

  • directoryUserId e facoltativo. FoxIDs lo invia quando l'utente interno esiste e il valore e noto. Puo essere omesso durante il primo login se la directory esterna richiede un cambio password prima che FoxIDs abbia creato l'utente interno.
  • Viene inviato esattamente uno tra email, phone o username.
  • currentPassword e newPassword sono obbligatori.

Richiesta set-password

L'endpoint set-password riceve il legame stabile dell'utente alla directory, esattamente un identificatore utente e la nuova password.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "password": "newpass1"
}

Campi:

  • directoryUserId viene inviato e dovrebbe essere usato come legame stabile alla directory.
  • Viene inviato esattamente uno tra email, phone o username. FoxIDs seleziona il primo identificatore interno disponibile in questo ordine: email, telefono, username.
  • password e obbligatoria.

Risposta di successo

In caso di successo, l'API deve restituire HTTP status code 200 e una risposta utente.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "phone": "+4511223344",
  "username": "user1",
  "confirmAccount": true,
  "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.
  • 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.

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.

Risposta di errore

Se l'autenticazione Basic viene rifiutata, restituisci HTTP status code 401 e invalid_api_id_secret.

{
  "error": "invalid_api_id_secret",
  "errorMessage": "Invalid API ID or secret."
}

Se l’utente non esiste quando viene chiamato l’endpoint authentication senza un directoryUserId, restituisci il codice di stato HTTP 400, 401 o 403 e user_not_exists.

{
  "error": "user_not_exists",
  "errorMessage": "User not found."
}

Se la password viene rifiutata dall'endpoint authentication, restituisci HTTP status code 400, 401 o 403 e invalid_password.

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

Se l’identificatore utente e la password sono validi, ma l’accesso viene rifiutato per un altro motivo, restituisci il codice di stato HTTP 400, 401 o 403 e login_rejected da authentication. È supportato sia con sia senza directoryUserId. Il campo facoltativo uiErrorMessage viene visualizzato come testo semplice nel modulo di accesso. L’API fornisce il messaggio tradotto in base ad Accept-Language.

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

Se uiErrorMessage viene omesso, è null, è vuoto o contiene solo caratteri di spazio bianco, FoxIDs mostra lo stesso messaggio generico di accesso localizzato usato per invalid_password, user_not_exists, user_disabled e user_deleted. Un accesso rifiutato viene conteggiato dalla protezione esistente contro i tentativi di accesso falliti ripetuti. Non crea, aggiorna, disabilita o elimina l’utente interno.

Se la password corrente viene rifiutata dall'endpoint change-password, restituisci HTTP status code 400, 401 o 403 e invalid_current_password.

{
  "error": "invalid_current_password",
  "errorMessage": "Invalid current password."
}

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.

FoxIDs mostra un uiErrorMessage restituito solo per login_rejected. Per gli altri codici di errore supportati, FoxIDs seleziona il messaggio destinato all’utente dalle proprie risorse di testo localizzate. Il testo diagnostico in errorMessage non viene mai usato come alternativa a un messaggio destinato all’utente.

Codici di errore supportati per endpoint:

Codice di errore authentication create-user change-password set-password Significato
invalid_api_id_secret Sì Sì Sì Sì Il nome utente o il segreto dell’API per HTTP Basic authentication non è valido.
user_exists No Sì No No Un utente con l’identificatore fornito esiste già nella directory esterna.
user_not_exists Sì, senza directoryUserId No Sì, senza directoryUserId No Nessun utente nella directory esterna corrisponde agli identificatori utente forniti.
invalid_password Sì No No No La directory ha rifiutato la password di una richiesta di autenticazione.
login_rejected 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 Sì No La directory ha rifiutato la password attuale di una richiesta di modifica della password.
create_user_not_supported No Sì No No Il connettore non supporta la creazione di utenti nella directory esterna.
user_disabled Sì No Sì Sì L’utente esiste nella directory ma è disabilitato. FoxIDs disabilita l’utente interno.
user_deleted Sì, con directoryUserId No Sì, con directoryUserId Sì, con directoryUserId L’utente della directory esterna collegato tramite directoryUserId non esiste più o è stato eliminato. FoxIDs elimina l’utente interno.
password_not_accepted 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 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 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 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 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 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 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 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 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 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 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 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 Sì Sì Sì Sì La password che viene verificata, usata per creare un utente, modificata o impostata è stata rifiutata perché è già stata usata.
password_expired Sì Sì Sì Sì La password che viene verificata, usata per creare un utente, modificata o impostata è scaduta e deve essere modificata prima che l’autenticazione possa continuare.
new_password_equals_current No No Sì No La nuova password è uguale a quella attuale. set-password non può restituire questo errore perché non riceve la password attuale.

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.

Restituisci solo un codice di errore supportato dall’endpoint e dal directoryUserId fornito, come indicato sopra. Un codice non supportato, una risposta malformata o uno stato HTTP imprevisto costituisce un errore di integrazione e porta alla pagina di errore generica. In caso di errore tecnico nel connettore, restituisci il codice di stato HTTP 500. Consulta Risoluzione degli errori del browser per trovare i dettagli diagnostici tramite gli identificatori presenti nella pagina di errore.

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, user_not_exists, user_disabled o user_deleted 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 per qualsiasi motivo un utente non è autorizzato ad accedere tramite questo flusso di accesso, convalida prima l’identificatore utente e la password forniti. Restituisci un rifiuto basato su questa restrizione solo dopo aver verificato entrambi, in modo che la restrizione non riveli se un identificatore indovinato appartiene a un utente reale. Restituisci login_rejected da authentication, indica il motivo diagnostico in errorMessage e, se necessario, fornisci indicazioni sicure all’utente in uiErrorMessage. Se le credenziali non possono essere verificate, restituisci il normale errore di autenticazione senza rivelare la restrizione.

FoxIDs si affida al connettore per verificare le credenziali prima di restituire login_rejected; una ricerca dell’account riuscita o la conoscenza di directoryUserId non sono sufficienti. Prima che le credenziali siano state verificate, mostra eventuali istruzioni o pulsanti per metodi di accesso alternativi indipendentemente dal fatto che l’identificatore fornito corrisponda a un account.

Usa user_disabled e user_deleted solo per segnalare il corrispondente stato dell’account nella directory. Disabilitano o eliminano anche l’utente interno e ne revocano l’accesso; non sono codici generici per rifiutare l’accesso.

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.

Il sample include:

  • Gli endpoint authentication, create-user, change-password e set-password.
  • HTTP Basic authentication con username API directory_connector.
  • Una piccola directory in-memory con utenti demo e valori stabili di directoryUserId.
  • Esempi di errori di policy password come password_min_length, password_banned_characters e new_password_equals_current.
  • Un esempio di utente disabilitato che restituisce user_disabled.

Postman collection directory-connector-api.postman_collection.json puo essere usata per chiamare e testare l'API sample con Postman.

Componente Active Directory

FoxIDs include un componente Directory Connector per Active Directory distribuibile su IIS. Il componente implementa l'API di Directory Connector per un dominio AD/LDAP e puo validare password, cambiare password, impostare password, restituire attributi AD configurati come claim e restituire membership configurate di gruppi AD annidati come claim.

Configurare

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

  1. Seleziona la scheda Settings.
  2. Seleziona la scheda Environment.
  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