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.

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.

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

Fields:

  • Exactly one of email, phone, or username is sent.
  • password è obbligatoria. Creare un utente senza password non è supportato con Directory Connector, perché l'API Directory Connector autentica gli utenti con una password.
  • confirmAccount and requireMultiFactor are the requested FoxIDs create-user settings.
  • claims contains the non-identifier claims collected during the FoxIDs create-user flow.

On success, return a normal success response. FoxIDs stores the returned directoryUserId on the internal user created after the external directory user has been created.

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.

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, restituisci HTTP status code 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 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.

Supported error codes by endpoint:

Error code authentication create-user change-password set-password Meaning
invalid_api_id_secret Yes Yes Yes Yes The HTTP Basic API username or secret is invalid.
user_exists No Yes No No A user with the supplied identifier already exists in the external directory.
user_not_exists Yes, without DirectoryUserId No Yes, without DirectoryUserId No No external directory user matched the supplied user identifiers.
invalid_password Yes No No No The password in an authentication request was rejected by the directory.
invalid_current_password No No Yes No The current password in a change-password request was rejected by the directory.
create_user_not_supported No Yes No No The connector does not support creating users in the external directory.
user_disabled Yes No Yes Yes The user exists in the directory but is disabled. FoxIDs will disable the internal user.
user_deleted Yes, with DirectoryUserId No Yes, with DirectoryUserId Yes, with DirectoryUserId The external directory user linked by DirectoryUserId no longer exists or is deleted. FoxIDs will delete the internal user.
password_not_accepted Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set was rejected by a directory password rule that does not map to a more specific code.
password_min_length Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is shorter than the directory password minimum length.
password_max_length Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is longer than the directory password maximum length.
password_banned_characters Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains one or more characters or words rejected by the directory.
password_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set does not satisfy the directory complexity requirements.
password_email_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains the user's email or part of it.
password_phone_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains the user's phone number or part of it.
password_username_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains the user's username or part of it.
password_url_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains text related to the FoxIDs URL.
password_risk Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is known to be risky, compromised, or otherwise unsafe.
password_history Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set was rejected because it has been used before.
password_expired Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is expired and must be changed before authentication can continue.
new_password_equals_current No No Yes No The new password is the same as the current password. set-password cannot return this error because it does not receive the current password.

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, 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

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ù