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.

Usa Directory Connector quando:

  • Vuoi che gli utenti effettuino il login con il normale metodo di autenticazione login.
  • 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 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.
  • Il cambio password dell'utente chiama l'endpoint change-password.
  • I flussi set-password e reset-password chiamano l'endpoint set-password.

FoxIDs chiama gli endpoint del ciclo di vita della password solo quando l'utente interno e noto e ha un directoryUserId. Questo impedisce a FoxIDs di chiamare la directory esterna senza il collegamento stabile all'utente esterno.

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.

L'API ha un URL base e tre endpoint:

  • authentication valida la password corrente di un utente.
  • 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/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.

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 e abilitato solo username e l'utente inserisce user1@somewhere.org, FoxIDs lo invia come username.

Richiesta change-password

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

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

Campi:

  • directoryUserId viene inviato e dovrebbe essere usato come legame stabile alla directory.
  • 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,
  "disableAccount": false,
  "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 facoltativi singolarmente, ma almeno uno deve essere presente. FoxIDs salva i valori restituiti come identificatori dell'utente interno.
  • 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.
  • disableAccount controlla se l'utente interno viene disabilitato in FoxIDs dopo la sincronizzazione.
  • 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.

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 la combinazione username/password viene rifiutata dall'endpoint authentication, restituisci HTTP status code 400, 401 o 403 e invalid_username_password.

{
  "error": "invalid_username_password",
  "errorMessage": "Invalid username or password."
}

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 viene registrato da FoxIDs e non viene mostrato all'utente finale.

Codici di errore supportati:

  • invalid_username_password - La combinazione identificatore utente e password e stata rifiutata dalla directory.
  • invalid_current_password - La password corrente in una richiesta change-password e stata rifiutata dalla directory.
  • user_disabled - L'utente esiste nella directory ma e disabilitato. FoxIDs disabilitera l'utente interno.
  • user_deleted - L'utente non esiste piu o e stato eliminato nella directory. FoxIDs eliminera l'utente interno.
  • password_not_accepted - La nuova password e stata rifiutata da una regola password della directory che non mappa a un codice piu specifico.
  • password_min_length - La nuova password e piu corta della lunghezza minima definita dalla directory.
  • password_max_length - La nuova password e piu lunga della lunghezza massima definita dalla directory.
  • password_banned_characters - La nuova password contiene uno o piu caratteri o parole rifiutati dalla directory.
  • password_complexity - La nuova password non soddisfa i requisiti di complessita della directory.
  • password_email_text_complexity - La nuova password contiene l'email dell'utente o una sua parte.
  • password_phone_text_complexity - La nuova password contiene il numero di telefono dell'utente o una sua parte.
  • password_username_text_complexity - La nuova password contiene lo username dell'utente o una sua parte.
  • password_url_text_complexity - La nuova password contiene testo relativo all'URL FoxIDs.
  • password_risk - La nuova password e nota come rischiosa, compromessa o altrimenti non sicura.
  • password_history - La nuova password e stata rifiutata perche e gia stata usata in precedenza.
  • password_expired - La password corrente e scaduta e deve essere cambiata prima che l'autenticazione possa continuare.
  • new_password_equals_current - La nuova password e uguale alla password corrente.

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.

Se si verificano altri errori, restituisci HTTP status code 500 o un altro codice di errore appropriato. Includi un errorMessage tecnico quando utile per la diagnostica.

Esempio di API

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

Il sample include:

  • Gli endpoint authentication, 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 Active Directory Directory Connector 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

La tua privacy

La tua privacy

Usiamo i cookie per migliorare la tua esperienza sui nostri siti. Fai clic sul pulsante 'Accetta tutti i cookie' per acconsentire all'uso dei cookie. Per rifiutare i cookie non essenziali, fai clic su 'Solo cookie necessari'.

Visita la nostra pagina di Informativa sulla privacy per saperne di più