Active Directory Directory Connector

Active Directory Directory Connector e un componente FoxIDs che implementa l'API Directory Connector per un dominio AD/LDAP.

Installa il componente all'interno dell'ambiente Windows del cliente, dove puo raggiungere i domain controllers. FoxIDs chiama il componente tramite HTTPS e il componente valida gli utenti, cambia password, imposta password e restituisce proprieta utente e claims da Active Directory.

Active Directory Directory Connector viene installato e configurato sul server Windows/IIS vicino ad Active Directory. In FoxIDs, il connector viene poi abilitato sull'ambiente FoxIDs in Settings > Environment > Directory connector settings, dove configuri il connector API URL e il secret.

Il componente viene rilasciato come zip Windows insieme alle versioni FoxIDs:

FoxIDs.DirectoryConnector.ActiveDirectory-{version}-win-x64.zip

Endpoints

Il componente espone:

GET /health
POST /authentication
POST /change-password
POST /set-password

L'endpoint /health non richiede autenticazione e restituisce solo uno stato minimo. Controlla configurazione richiesta, AD bind, accesso in lettura a user search-base e accesso in lettura facoltativo a group search-base. Non testa i permessi delegati set-password / password reset. Errori dettagliati e stack trace vengono registrati sul server e non vengono restituiti dall'endpoint.

La risposta include solo status, adBind, userSearch e groupSearch. status e ok quando la configurazione richiesta e valida, AD bind riesce, accesso alla user search-base riesce e accesso alla group search-base non e fallito. groupSearch e not_configured quando non e configurata una group search base. Se un controllo non puo essere eseguito perche un controllo precedente e fallito oppure manca configurazione, il campo viene restituito come unknown.

Prerequisiti

Windows Server con IIS.
ASP.NET Core Hosting Bundle per .NET 10.
Accesso di rete dal server IIS al domain controller configurato.
LDAPS oppure un altro canale sicuro per le operazioni sulle password.
Un dominio AD per ogni deployment del connector.
Un domain service account se vengono usate credenziali configurate.
Permesso delegato di AD password reset se set-password deve essere supportato.

Una configurazione raccomandata e un server IIS joined al dominio che esegue l'application pool come domain service account. Sono supportate anche bind credentials configurate tramite appsettings.json oppure environment variables.

Autenticazione

Configura una API key robusta in appsettings.json.

FoxIDs invia autenticazione HTTP Basic con API ID directory_connector e il secret configurato.

Usa l'header X-FoxIDs-Api-Key: <api-key> solo se un reverse proxy davanti al Directory Connector gestisce l'autenticazione Basic prima che la richiesta raggiunga il componente e riscrive l'api-key.

Ricerca AD e binding

Il componente cerca prima in AD con l'identita di servizio configurata. Supporta lookup tramite:

email
phone
username
directoryUserId quando FoxIDs lo conosce gia

L'utente viene identificato in FoxIDs con objectGUID di AD codificato in base64. Questo valore viene restituito come directoryUserId e rimane stabile se email, phone oppure username cambiano.

Per l'autenticazione password, il componente trova il distinguished name dell'utente e poi esegue il bind ad AD come quell'utente con la password inviata. Questo evita lookup utente ambigui e supporta tutti i tipi di identificatore configurati.

Per il cambio password, AD valida la password corrente e la password policy.

Se la password policy di FoxIDs e abilitata per Directory Connector, FoxIDs pre-valida lunghezza, complessita e cronologia della password prima di chiamare il connector. Questo fornisce all'utente feedback piu preciso per questi controlli. AD resta autoritativo e puo comunque rifiutare la password in seguito con password_not_accepted, ad esempio a causa di lunghezza minima, complessita, cronologia password, minimum password age, fine-grained password policy oppure un custom password filter.

Per set-password, l'identita di servizio configurata deve avere diritti delegati di reset-password.

Accesso dell'account di servizio AD

Il connector dovrebbe essere eseguito con una identita di servizio AD dedicata. Non rendere questa identita un domain administrator. Usa un normale utente di dominio, oppure un custom security group che contiene l'utente del connector, e delega solo i permessi richiesti sugli OUs usati dal connector.

Per user lookup e authentication, l'identità del connector deve essere autorizzata a cercare in ogni OU configurata in UserSearchBases e a leggere gli oggetti utente e gli attributi usati dal connector. Una nuova identità di servizio AD dedicata spesso dispone già di questo accesso in lettura per impostazione predefinita, a meno che le ACL di AD non siano state limitate.

Per password authentication, il connector prima trova l'utente con l'identita di servizio e poi esegue il bind ad AD come utente con la password inviata. Questo non richiede che l'identita di servizio conosca o resetti la password dell'utente.

Per password change, dove l'utente fornisce la password corrente, il connector usa il comportamento AD di password change e AD valida la password corrente e la password policy.

Per set-password / password reset, delega i diritti di password reset sugli user objects in ogni OU configurata in UserSearchBases dove il connector deve supportare password reset. In Active Directory Users and Computers, fai clic con il pulsante destro sulla user OU usata dal connector, seleziona Delegate Control..., seleziona l'identità del connector e, nello step Tasks to Delegate, seleziona Reset user passwords and force password change at next logon.

Delegare il permesso Reset user passwords and force password change at next logon all'identità del connector

Delega anche eventuali permessi aggiuntivi relativi alla password richiesti dalla domain policy, solo se l'ambiente usa quelle operazioni. Per group role claims, concedi all'identita del connector accesso in lettura sui GroupSearchBases configurati. Deve poter elencare il group OU e leggere attributi gruppo come cn, distinguishedName e member.

Configurazione

La configurazione usa la configurazione standard .NET. I valori possono essere impostati in appsettings.json, environment variables, configurazione IIS oppure un altro provider di configurazione .NET.

Esempio:

{
  "DirectoryConnector": {
    "ApiKey": "change-me",
    "ActiveDirectory": {
      "Domain": "example.local",
      "Server": "dc01.example.local",
      "Port": 636,
      "UseSsl": true,
      "Bind": {
        "Mode": "Integrated",
        "Username": "",
        "Password": ""
      },
      "UserSearchBases": [
        "OU=Users,DC=example,DC=local"
      ],
      "GroupSearchBases": [
        "OU=Groups,DC=example,DC=local"
      ],
      "UserIdentifiers": {
        "Username": "sAMAccountName",
        "Email": "mail",
        "Phone": "telephoneNumber"
      },
      "Claims": [
        {
          "Claim": "name",
          "Attribute": "displayName"
        },
        {
          "Claim": "given_name",
          "Attribute": "givenName"
        },
        {
          "Claim": "family_name",
          "Attribute": "sn"
        }
      ],
      "GroupClaims": [
        {
          "Claim": "role",
          "GroupDistinguishedName": "CN=Employees,OU=Groups,DC=example,DC=local",
          "IncludeNestedGroups": true,
          "Value": "employees"
        }
      ]
    }
  }
}

DirectoryUserId viene sempre mappato da objectGUID di AD e restituito codificato in base64. Non e configurabile.

UserIdentifiers controlla quali attributi AD possono essere usati per lookup tramite email, phone e username e restituiti come identificatori utente di primo livello. Almeno uno tra Email, Phone o Username deve essere configurato e restituito da AD per una risposta valida del connector. Rimuovi un mapping identifier se quel campo non deve essere usato per lookup o restituito a livello principale. Lo stesso attributo AD puo comunque essere configurato come claim in Claims.

Impostazioni importanti:

ApiKey: Shared secret usato da FoxIDs per autenticarsi verso il connector. FoxIDs lo invia come autenticazione HTTP Basic con API ID directory_connector. Usa un valore forte e univoco e, quando possibile, memorizzalo come environment variable oppure impostazione IIS.
ActiveDirectory:Domain: Nome del dominio AD usato quando ci si connette al dominio, ad esempio example.local.
ActiveDirectory:Server: Domain controller oppure endpoint LDAP facoltativo. Se omesso, il connector usa Domain.
ActiveDirectory:Port: Porta LDAP. Usa 636 per LDAPS.
ActiveDirectory:UseSsl: Abilita LDAPS. Mantienilo abilitato per le operazioni sulle password, a meno che non sia garantito un altro canale sicuro.
ActiveDirectory:Bind:Mode: Integrated usa l'identita dell'IIS application pool oppure l'identita del processo. ConfiguredCredentials usa Username e Password configurati.
ActiveDirectory:Bind:Username and ActiveDirectory:Bind:Password: Credenziali usate solo quando Mode e ConfiguredCredentials. Preferisci environment variables oppure configurazione IIS per la password.
ActiveDirectory:UserSearchBases: Uno o piu distinguished names dove cercare utenti, ad esempio OU=Users,DC=example,DC=local.
ActiveDirectory:GroupSearchBases: Uno o piu distinguished names dove cercare i gruppi di ruolo configurati.
ActiveDirectory:UserIdentifiers: Attributi AD facoltativi usati per lookup e identificatori utente di primo livello: Email, Phone e Username. Configurane almeno uno.
ActiveDirectory:Claims: Attributi utente restituiti come claims a FoxIDs, ad esempio name, given_name, family_name oppure email.
ActiveDirectory:GroupClaims: Membership AD di gruppo restituite come claims, tipicamente claims role. Vedi Claim di gruppo per i dettagli di configurazione.

Claim di gruppo

I group claims sono disabilitati per impostazione predefinita. Per abilitarli, aggiungi una o piu voci a ActiveDirectory:GroupClaims.

Ogni voce GroupClaims definisce il tipo di claim da restituire e quali membership di gruppi AD devono produrre quel claim. Claim e obbligatorio ed e tipicamente role.

Esistono tre configurazioni comuni:

"GroupClaims": [
  {
    "Claim": "role",
    "IncludeNestedGroups": true,
    "ValueAttribute": "cn"
  },
  {
    "Claim": "role",
    "GroupDistinguishedName": "CN=Employees,OU=Groups,DC=example,DC=local",
    "IncludeNestedGroups": true,
    "Value": "employees"
  },
  {
    "Claim": "role",
    "GroupName": "Administrators",
    "IncludeNestedGroups": true,
    "ValueAttribute": "cn"
  }
]

Se non e configurato ne GroupDistinguishedName ne GroupName, il connector cerca nei GroupSearchBases configurati e restituisce un claim per ogni gruppo corrispondente di cui l'utente e membro. In questa modalita non configurare Value; il valore del claim deve provenire da ValueAttribute. Con ValueAttribute predefinito impostato su cn, un gruppo con nome admin_access restituisce:

{ "type": "role", "value": "admin_access" }

Usa GroupDistinguishedName quando conosci il DN esatto del gruppo AD. Questo evita una ricerca per nome ed e l'opzione piu precisa.

Usa GroupName quando il connector deve trovare un singolo gruppo in base al suo valore cn in GroupSearchBases. La ricerca deve corrispondere a un solo gruppo. Se esiste piu di un gruppo con lo stesso cn nei GroupSearchBases configurati, la richiesta fallisce perche il mapping del gruppo e ambiguo.

Usa Value solo quando GroupDistinguishedName o GroupName e configurato e il claim restituito deve avere un valore fisso indipendente dal nome del gruppo AD. Ad esempio, un gruppo con DN CN=Employees,OU=Groups,DC=example,DC=local puo restituire il valore role employees.

Se Value non e impostato, il connector legge il ValueAttribute configurato dal gruppo AD corrispondente. Il ValueAttribute predefinito e cn, che restituisce il nome del gruppo AD come valore del claim. Configura un attributo di gruppo diverso solo se quell'attributo esiste sull'oggetto gruppo e contiene il valore da inviare a FoxIDs.

IncludeNestedGroups controlla come viene verificata la membership:

true usa la regola di matching ricorsivo di AD, quindi il claim viene restituito se l'utente e membro diretto oppure tramite gruppi annidati.
false verifica solo la membership diretta nel gruppo corrispondente.

Installazione IIS

Il componente viene distribuito con Xcopy. Non ha database ne installer; aggiornamento o rollback vengono eseguiti sostituendo i file nella cartella del sito IIS mantenendo la configurazione specifica dell'ambiente.

Installa il ASP.NET Core Hosting Bundle for .NET 10 (direct download) sul server Windows.
Crea una cartella per il componente, ad esempio C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.
Estrai lo zip della release nella cartella.
Configura appsettings.json oppure environment variables.
Crea un IIS application pool.
Imposta l'identita dell'app pool a un domain service account, oppure configura bind credentials in appsettings.json.
Crea un sito IIS oppure una application che punta alla cartella estratta.
Associa il sito a HTTPS.
Crea la cartella dei log C:\inetpub\logs\LogFiles\foxids-ad e concedi accesso in scrittura all'identita dell'application pool. Per esempio, se l'application pool IIS si chiama FoxIDs.DirectoryConnector.AD, concedi accesso in scrittura a IIS AppPool\FoxIDs.DirectoryConnector.AD.
Verifica GET /health.

Per un FoxIDs API URL, usa il connector base URL, ad esempio:

https://connector.example.com

FoxIDs aggiunge authentication, change-password e set-password a quel base URL.

Certificato TLS

FoxIDs chiama il connector tramite HTTPS, quindi il sito IIS dovrebbe avere un certificato TLS trusted. Puoi usare il tuo certificato oppure creare facoltativamente un certificato gratuito Let's Encrypt con win-acme.

Con win-acme, scarica l'ultima release win-acme.v2.x.x.x64.pluggable.zip, estraila in una cartella permanente, esegui wacs.exe da un Command Prompt elevato e seleziona il sito IIS che ospita il Directory Connector. Win-acme aggiunge il binding HTTPS e registra il rinnovo automatico del certificato in Windows Task Scheduler.

Vedi la FoxIDs Windows / IIS HTTP and HTTPS guide per il flusso completo di win-acme.

Configurazione dell'ambiente FoxIDs

Dopo che il connector e installato e raggiungibile tramite HTTPS, abilitalo nell'ambiente FoxIDs:

Apri FoxIDs Control Client.
Seleziona il tenant e l'ambiente che dovra usare il connector.
Vai a Settings > Environment.
Trova Directory connector settings.
Abilita il directory connector.
Inserisci il connector API URL, ad esempio https://connector.example.com.
Inserisci lo stesso secret del connector ApiKey.
Scegli se FoxIDs debba salvare una copia locale della password e se la password policy di FoxIDs debba essere applicata prima di chiamare il connector.

Quando la password policy di FoxIDs e abilitata, FoxIDs valida lunghezza, complessita e cronologia della password prima di chiamare il connector. Questo fornisce agli utenti feedback immediato sulla policy FoxIDs, ma AD resta autoritativo e puo comunque rifiutare una password con password_not_accepted a causa di lunghezza minima, complessita, cronologia password, minimum password age, fine-grained password policy oppure un custom password filter.

Impostazioni FoxIDs Directory Connector per Active Directory

L'API URL in FoxIDs deve puntare al base URL del connector. FoxIDs aggiunge i nomi degli endpoint quando chiama il connector.

Per impostazione predefinita, in Login authentication method è abilitato solo il login con indirizzo email. Se gli utenti devono poter accedere con username o numero di telefono, abilita i relativi identificatori utente in Login authentication method.

L'esempio seguente ha abilitati sia username sia email.

Identificatori utente di FoxIDs Login authentication method per Directory Connector

Patching e aggiornamenti

Scarica la nuova release FoxIDs.DirectoryConnector.ActiveDirectory-x.x.x-win-x64.zip e controlla le release notes.
Estrai lo zip in una cartella temporanea e copia i file correnti appsettings*.json, oppure mantieni i secrets nelle IIS environment variables.
Arresta il sito IIS oppure l'application pool.
Rinomina oppure copia la cartella corrente in una cartella di backup, ad esempio C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.2026-04-29.bak.
Esegui Xcopy dei nuovi file in C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory e verifica i permessi NTFS per l'identita dell'app pool.
Avvia l'application pool e verifica GET /health, poi testa un login Directory Connector oppure una operazione password.
Se serve rollback, arresta l'app pool, ripristina la cartella di backup nel path live e riavvia l'app pool.

Il web.config predefinito scrive i log ASP.NET Core stdout in C:\inetpub\logs\LogFiles\foxids-directory-connector-ad. Mantieni abilitato stdout logging finche il connector non e verificato e valuta di disabilitarlo oppure inoltrare i log al normale sistema di log dell'ambiente dopo la validazione in produzione.