Directory Connector voor Active Directory

Directory Connector voor Active Directory is een FoxIDs-component die de Directory Connector-API implementeert voor één AD/LDAP-domein.

Gebruik deze wanneer bestaande Active Directory-gebruikers zich via FoxIDs moeten aanmelden bij OpenID Connect- en SAML 2.0-applicaties, terwijl AD de gezaghebbende directory blijft voor wachtwoordvalidatie, wachtwoordwijzigingen, geselecteerde gebruikersattributen en groepsgebaseerde claims.

AD blijft gezaghebbend voor het wachtwoord, maar FoxIDs maakt en werkt nog steeds een interne FoxIDs-gebruiker bij die aan het AD-account is gekoppeld. Hierdoor kan FoxIDs multi-factor-authenticatie (MFA)-afhandeling worden toegevoegd aan AD-gebruikers, inclusief MFA-vereisten en de toegestane second-factor-methoden, terwijl gebruikers hun wachtwoord blijven authenticeren tegen AD.

Installeer de component in de Windows-omgeving van de klant, waar deze de domeincontrollers kan bereiken. FoxIDs roept de component aan via HTTPS, en de component valideert gebruikers, wijzigt wachtwoorden, zet wachtwoorden en retourneert gebruikerseigenschappen en claims uit Active Directory.

Architectuur en deployment van Directory Connector voor Active Directory

De connector wordt geïnstalleerd en geconfigureerd op de Windows/IIS-server dicht bij Active Directory. In FoxIDs wordt de connector daarna ingeschakeld op de FoxIDs-omgeving onder Settings > Environment > Directory connector settings, waar de API URL en secret van de connector worden geconfigureerd.

De component wordt uitgebracht als een Windows-zip samen met FoxIDs-releases:

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

Synchronisatie op aanvraag

Synchronisatie is verplicht wanneer Directory Connector is ingeschakeld. Aan het begin van aanmelden, herstel en controles van bestaande sessies en bij gebruik van een refresh token voor een directorygebonden account haalt FoxIDs actuele identificaties, attributen en groepsclaims op. Het FoxIDs account kan vóór de eerste succesvolle aanmelding worden aangemaakt, zodat wachtwoordherstel en eerste wachtwoordinstelling het actuele AD-herstelcontact kunnen gebruiken.

De connector gebruikt objectGUID als stabiele directory-ID. Synchronisatie meldt uitgeschakelde of verlopen accounts en een verwijderd account wanneer de bekende ID niet wordt gevonden. Wachtwoordbewerkingen gebruiken de directory-ID en retourneren HTTP 204 zonder inhoud. De connector controleert de accountstatus en voert de bewerking uit. Synchronisatie retourneert alle gebruikersattributen, wachtwoordstatus en geconfigureerde groepsclaims. Vervolgstappen met bevestigingscodes, MFA en Extended UI gebruiken het geselecteerde account en normale FoxIDs controles. Na een succesvolle wachtwoordreset verwijdert de connector de AD-verplichting tot wachtwoordwijziging.

De gegevens koppelen pwdLastSet aan passwordLastChanged en gebruiken msDS-UserPasswordExpiryTimeComputed om wachtwoordverloop te detecteren. Nul in pwdLastSet vereist wachtwoordwijziging en maakt instelling via e-mail mogelijk, of via SMS als geen e-mailidentificatie is geconfigureerd en een telefoonidentificatie beschikbaar is. De nulwaarde van AD betekent dat bij de volgende aanmelding een wachtwoord moet worden ingesteld of gewijzigd; deze onderscheidt geen ongebruikt account van een account met tijdelijk wachtwoord. De normale bevestigingscodeflow verifieert toegang tot het herstelcontact voordat het wachtwoord wordt ingesteld. Delegeer resetrechten en schakel de bijbehorende herstelmethode in FoxIDs in om dit te gebruiken.

Vindt een wachtwoordbewerking een ontbrekend, uitgeschakeld, verlopen of vergrendeld account, dan retourneert deze operation_rejected met een diagnostische reden. FoxIDs toont een algemene gelokaliseerde fout en laat het opgeslagen account, bestaande sessies en refresh tokens ongewijzigd. Synchronisatie beheert accountstatuswijzigingen en intrekking; ontdekt een refresh-tokenverzoek een uitgeschakeld of verwijderd account, dan wordt datzelfde verzoek geweigerd.

De connector retourneert password_expired alleen vanuit authentication, nadat AD het huidige wachtwoord heeft geverifieerd. Een verlopen huidig wachtwoord kan nog voor een wachtwoordwijziging worden gebruikt. Ongeldige gegevens geven invalid_password bij authenticatie of invalid_current_password bij wachtwoordwijziging. Zie het foutcontract van de endpoints voor ondersteunde fouten en browsergedrag.

Er is geen achtergrondproces. Een AD-wijziging wordt bij de volgende synchronisatie overgenomen en connectorfouten stoppen de flow. Zie Directory Connector voor de zoeklimiet per sequentie en het volledige API-contract.

Endpoints

De component stelt beschikbaar:

  • GET /health
  • POST /synchronise-user
  • POST /authentication
  • POST /change-password
  • POST /set-password

Het /health endpoint is niet geauthenticeerd en retourneert alleen minimale status. Het controleert vereiste configuratie, AD-bind, toegang tot user search-base en optionele toegang tot group search-base. Het test geen gedelegeerde rechten voor set-password / password reset. Gedetailleerde fouten en stack traces worden op de server gelogd en niet door het endpoint geretourneerd.

Voorbeeldrespons:

{
  "status": "ok",
  "adBind": "ok",
  "userSearch": "ok",
  "groupSearch": "not_configured"
}

De response bevat alleen status, adBind, userSearch en groupSearch. status is alleen ok wanneer vereiste configuratie geldig is, AD-bind slaagt, toegang tot user search-base slaagt en toegang tot group search-base niet is mislukt. groupSearch is not_configured wanneer geen group search base is geconfigureerd. Als een controle niet kan worden uitgevoerd omdat een eerdere controle is mislukt of configuratie ontbreekt, wordt het veld geretourneerd als unknown.

Vereisten

  • Windows Server met IIS.
  • ASP.NET Core Hosting Bundle voor .NET 10.
  • Netwerktoegang vanaf de IIS-server naar de geconfigureerde domeincontroller.
  • LDAPS of een ander veilig kanaal voor wachtwoordoperaties.
  • Eén AD-domein per connector-deployment.
  • Een domeinserviceaccount als geconfigureerde credentials worden gebruikt.
  • Gedelegeerde AD-rechten voor password reset als set-password ondersteund moet worden.

Een domein-joined IIS-server waarvan de application pool draait als domeinserviceaccount is de aanbevolen configuratie. Geconfigureerde bind-credentials worden ook ondersteund via appsettings.json of omgevingsvariabelen.

Authenticatie

Configureer een sterke API-sleutel in appsettings.json.

FoxIDs verstuurt authenticatie via HTTP Basic met API-ID directory_connector en het geconfigureerde geheim.

Gebruik de header X-FoxIDs-Api-Key: <api-key> alleen als een reverse proxy vóór Directory Connector Basic-authenticatie afhandelt voordat het verzoek de component bereikt en api-key herschrijft.

AD lookup en binding

De component zoekt eerst in AD met de geconfigureerde service-identiteit. Lookup wordt ondersteund op:

  • e-mail
  • telefoon
  • gebruikersnaam
  • directoryUserId wanneer FoxIDs deze al kent

De gebruiker wordt in FoxIDs geïdentificeerd met de AD objectGUID, gecodeerd als base64. De waarde wordt teruggegeven als directoryUserId en blijft stabiel wanneer e-mail, telefoon of gebruikersnaam verandert.

Voor wachtwoordauthenticatie vindt de component de distinguished name van de gebruiker en bindt daarna aan AD als die gebruiker met het opgegeven wachtwoord. Dit voorkomt dubbelzinnige gebruikerslookup en ondersteunt alle geconfigureerde identificatortypen.

Voor het wijzigen van een wachtwoord valideert AD het huidige wachtwoord en het wachtwoordbeleid.

Als FoxIDs wachtwoordbeleid voor Directory Connector is ingeschakeld, valideert FoxIDs wachtwoordlengte, tekencomplexiteit, gebruikersidentificaties en context volgens de geconfigureerde controles. Bij wachtwoordwijzigingen wordt het huidige wachtwoord geverifieerd voordat beleidsinformatie wordt getoond. AD beheert de wachtwoordgeschiedenis en blijft leidend: het kan het wachtwoord met password_not_accepted weigeren, bijvoorbeeld vanwege minimumlengte, complexiteit, geschiedenis, minimumleeftijd, fijnmazig wachtwoordbeleid of een aangepast wachtwoordfilter.

Voor set-password moet de geconfigureerde service-identiteit gedelegeerde reset-password-rechten hebben.

Toegang voor AD-serviceaccount

De connector moet draaien met een dedicated AD-service-identiteit. Maak deze identiteit geen domeinadministrator. Gebruik een normale domeingebruiker of een aangepaste beveiligingsgroep, en delegeer alleen de noodzakelijke rechten op de OU's die de connector gebruikt.

Voor gebruikerslookup en authenticatie moet de connector-identiteit in elke geconfigureerde UserSearchBases OU mogen zoeken en de gebruikersobjecten en attributen kunnen lezen die door de connector worden gebruikt. Een nieuwe dedicated AD-service-identiteit heeft deze leestoegang vaak al standaard, tenzij de AD-ACL's zijn beperkt.

Voor wachtwoordauthenticatie vindt de connector eerst de gebruiker met de service-identiteit en bindt daarna aan AD als de gebruiker met het opgegeven wachtwoord. Dit vereist niet dat de service-identiteit het wachtwoord van de gebruiker kent of reset.

Voor het wijzigen van een wachtwoord, waarbij de gebruiker het huidige wachtwoord opgeeft, gebruikt de connector het AD password change-gedrag en valideert AD het huidige wachtwoord en het wachtwoordbeleid.

Voor set-password / password reset moeten password reset-rechten worden gedelegeerd op de gebruikersobjecten in elke geconfigureerde UserSearchBases OU waar de connector password reset moet ondersteunen. Klik in Active Directory Users and Computers met de rechtermuisknop op de user OU die door de connector wordt gebruikt, selecteer Delegate Control..., selecteer de connector-identiteit en selecteer in de stap Tasks to Delegate Reset user passwords and force password change at next logon.

De connector maakt geen gebruikers aan in Active Directory, dus de connector-identiteit heeft geen rechten nodig om AD-gebruikersobjecten aan te maken.

Delegeer de Reset user passwords and force password change at next logon-rechten aan de connector-identiteit

Delegeer ook eventuele aanvullende wachtwoordgerelateerde rechten die door het domeinbeleid worden vereist, alleen als de omgeving die handelingen gebruikt.

Voor groepsrol-claims heeft de connector-identiteit leestoegang nodig tot de geconfigureerde GroupSearchBases. Deze moet de group OU kunnen weergeven en groepsattributen zoals cn, distinguishedName en member kunnen lezen.

Configuratie

Configuratie gebruikt standaard .NET-configuratie. Waarden kunnen worden ingesteld in appsettings.json, omgevingsvariabelen, IIS-configuratie of een andere .NET-configuratieprovider.

Voorbeeld:

{
  "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 wordt altijd toegewezen vanuit de AD-objectGUID en base64-gecodeerd geretourneerd. Deze is niet configureerbaar.

UserIdentifiers bepaalt welke AD-attributen kunnen worden gebruikt voor lookup via e-mail, telefoon en gebruikersnaam en als top-level gebruikersidentificaties worden geretourneerd. Minimaal een van Email, Phone of Username moet zijn geconfigureerd en door AD worden geretourneerd voor een geldige connectorrespons. De volledige gebruikersnaam wordt als LDAP-filterwaarde ge-escaped en gebruikt voor de AD-lookup. Verwijder een identifier-mapping als dat veld niet voor lookup of retour op topniveau moet worden gebruikt. Hetzelfde AD-attribuut kan nog steeds als claim in Claims worden geconfigureerd.

Als Phone is gekoppeld aan het AD-attribuut telephoneNumber, moet de waarde van telephoneNumber de landcode bevatten in internationaal formaat, bijvoorbeeld +4511223344.

De geconfigureerde gebruikersidentifierattributen moeten één gebruiker uniek identificeren binnen de geconfigureerde UserSearchBases. Schakel lookup op gebruikersnaam, e-mail of telefoon niet in tenzij de bijbehorende AD-attribuutwaarden uniek zijn voor de gebruikers die door de connector worden gedekt.

Belangrijke instellingen:

  • ApiKey: gedeelde secret waarmee FoxIDs zich bij de connector authenticeert. FoxIDs verzendt dit als HTTP Basic authentication met API ID directory_connector. Gebruik een sterke unieke waarde en sla deze waar mogelijk op als omgevingsvariabele of IIS-instelling.
  • ActiveDirectory:Domain: AD-domeinnaam, bijvoorbeeld example.local.
  • ActiveDirectory:Server: optionele domeincontroller of LDAP-endpoint. Als deze ontbreekt, wordt Domain gebruikt.
  • ActiveDirectory:Port: LDAP-poort. Gebruik 636 voor LDAPS.
  • ActiveDirectory:UseSsl: schakelt LDAPS in. Laat dit ingeschakeld voor wachtwoordoperaties, tenzij een ander beveiligd kanaal gegarandeerd is.
  • ActiveDirectory:Bind:Mode: Integrated gebruikt de IIS application pool-identiteit of procesidentiteit. ConfiguredCredentials gebruikt de geconfigureerde Username en Password.
  • ActiveDirectory:Bind:Username en ActiveDirectory:Bind:Password: credentials worden alleen gebruikt wanneer Mode ConfiguredCredentials is. Geef voor het wachtwoord de voorkeur aan omgevingsvariabelen of IIS-configuratie.
  • ActiveDirectory:UserSearchBases: een of meer distinguished names waarin gebruikers worden gezocht, bijvoorbeeld OU=Users,DC=example,DC=local.
  • ActiveDirectory:GroupSearchBases: een of meer distinguished names waarin geconfigureerde rolgroepen worden gezocht.
  • ActiveDirectory:UserIdentifiers: optionele AD-velden voor lookup en top-level gebruikersidentificaties: Email, Phone en Username. Configureer er minstens een.
  • ActiveDirectory:Claims: gebruikersvelden die als claims worden geretourneerd, bijvoorbeeld name, given_name, family_name of email.
  • ActiveDirectory:GroupClaims: AD-groepslidmaatschappen die als claims worden geretourneerd, meestal role-claims. Zie Groepsclaims voor configuratiedetails.

Groepsclaims

Groepsclaims zijn standaard uitgeschakeld. Om ze in te schakelen, voegt u een of meer items toe aan ActiveDirectory:GroupClaims.

Elke GroupClaims-vermelding definieert het claimtype dat moet worden geretourneerd en welke AD-groepslidmaatschappen dat claim moeten opleveren. Claim is verplicht en is meestal role.

Er zijn drie veelvoorkomende configuraties:

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

Als noch GroupDistinguishedName noch GroupName is geconfigureerd, doorzoekt de connector de geconfigureerde GroupSearchBases en retourneert één claim voor elke overeenkomende groep waarvan de gebruiker lid is. In deze modus mag u Value niet configureren; de claimwaarde moet afkomstig zijn van ValueAttribute. Met de standaard-ValueAttribute cn retourneert een groep met de naam admin_access:

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

Gebruik GroupDistinguishedName wanneer u de exacte DN van de AD-groep kent. Dit voorkomt zoeken op naam en is de meest precieze optie.

Gebruik GroupName wanneer de connector één groep moet vinden op basis van de cn-waarde in GroupSearchBases. De zoekopdracht moet precies één groep vinden. Als meerdere groepen met dezelfde cn in de geconfigureerde zoekbasissen voor groepen bestaan, mislukt het verzoek omdat de groepsmapping dubbelzinnig is.

Gebruik Value alleen wanneer GroupDistinguishedName of GroupName is geconfigureerd en de geretourneerde claim een vaste waarde moet hebben die onafhankelijk is van de naam van de AD-groep. Een groep met de DN CN=Employees,OU=Groups,DC=example,DC=local kan bijvoorbeeld de role-waarde employees retourneren.

Als Value niet is ingesteld, leest de connector de geconfigureerde ValueAttribute uit de gevonden AD-groep. De standaard-ValueAttribute is cn, waarmee de naam van de AD-groep als claimwaarde wordt geretourneerd. Configureer alleen een ander groepsattribuut als dat attribuut op het groepsobject bestaat en de waarde bevat die naar FoxIDs moet worden verzonden.

IncludeNestedGroups bepaalt hoe lidmaatschap wordt gecontroleerd:

  • true gebruikt de recursieve AD-matchingregel, zodat de claim wordt geretourneerd als de gebruiker direct lid is of via geneste groepen lid is.
  • false controleert alleen direct lidmaatschap van de gevonden groep.

IIS-installatie

De component wordt gedeployed met Xcopy. Er is geen database en geen installer. Updaten of terugdraaien gebeurt door de bestanden in de map van de IIS-website te vervangen terwijl de omgevingsspecifieke configuratie behouden blijft.

  1. Installeer ASP.NET Core Hosting Bundle voor .NET 10 (directe download) op de Windows-server.
  2. Maak een map, bijvoorbeeld C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.
  3. Pak de release-zip uit in de map.
  4. Configureer appsettings.json of omgevingsvariabelen.
  5. Maak een IIS application pool.
  6. Stel de application pool-identiteit in op een domeinserviceaccount, of configureer bind-credentials in appsettings.json.
  7. Maak een IIS-site of IIS-application die naar de map wijst.
  8. Bind de site aan HTTPS.
  9. Maak de logmap C:\inetpub\logs\LogFiles\foxids-ad en geef de application pool-identiteit schrijftoegang. Als de IIS-application pool bijvoorbeeld FoxIDs.DirectoryConnector.AD heet, geef dan schrijftoegang aan IIS AppPool\FoxIDs.DirectoryConnector.AD.
  10. Controleer GET /health.

Gebruik als FoxIDs API URL de base URL van de connector, bijvoorbeeld:

https://connector.example.com

FoxIDs voegt synchronise-user, authentication, change-password en set-password toe aan deze basis-URL.

TLS-certificaat

FoxIDs roept de connector aan via HTTPS, dus de IIS-site moet een vertrouwd TLS-certificaat hebben. U kunt uw eigen certificaat gebruiken of optioneel een gratis Let's Encrypt-certificaat maken met win-acme.

Met win-acme downloadt u de nieuwste release win-acme.v2.x.x.x64.pluggable.zip, pakt u deze uit naar een permanente map, voert u wacs.exe uit vanuit een verhoogde Command Prompt en selecteert u de IIS-site die Directory Connector host. Win-acme voegt de HTTPS-binding toe en registreert automatische certificaatvernieuwing in Windows Task Scheduler.

Zie de volledige flow in de FoxIDs Windows / IIS HTTP and HTTPS guide.

FoxIDs-omgevingsconfiguratie

Wanneer de connector is geïnstalleerd en bereikbaar is via HTTPS, schakelt u deze in de FoxIDs-omgeving in:

  1. Open FoxIDs Control Client.
  2. Selecteer de tenant en omgeving die de connector moeten gebruiken.
  3. Ga naar Settings > Environment.
  4. Zoek Directory connector settings.
  5. Schakel directory connector in.
  6. Voer de API URL van de connector in, bijvoorbeeld https://connector.example.com.
  7. Voer dezelfde secret in als de ApiKey van de connector.
  8. Kies of FoxIDs een lokale wachtwoordkopie moet opslaan en of het FoxIDs-wachtwoordbeleid moet worden toegepast vóór de connector-aanroep.

Wanneer FoxIDs wachtwoordbeleid is ingeschakeld, valideert FoxIDs wachtwoordlengte, tekencomplexiteit, gebruikersidentificaties en context volgens de geconfigureerde controles. Bij wachtwoordwijzigingen wordt het huidige wachtwoord geverifieerd voordat beleidsinformatie wordt getoond. AD beheert de wachtwoordgeschiedenis en blijft leidend: het kan een wachtwoord met password_not_accepted weigeren vanwege minimumlengte, complexiteit, geschiedenis, minimumleeftijd, fijnmazig wachtwoordbeleid of een aangepast wachtwoordfilter.

FoxIDs Directory Connector-instellingen voor Active Directory

De API URL in FoxIDs moet naar de base URL van de connector wijzen. FoxIDs voegt de endpointnamen toe wanneer de connector wordt aangeroepen.

Standaard is in Login authentication method alleen aanmelden met e-mailadres ingeschakeld. Als gebruikers zich moeten kunnen aanmelden met gebruikersnaam of telefoonnummer, schakel dan de bijbehorende gebruikersidentificatoren in Login authentication method in. Gebruikersidentificatoren die door AD worden geretourneerd, kunnen alleen voor aanmelden worden gebruikt wanneer de bijbehorende identificator in Login authentication method is ingeschakeld.

Create user moet op de Login-authenticatiemethode worden uitgeschakeld bij Directory Connector voor AD. Deze connector ondersteunt geen gebruikersaanmaak; maak gebruikers in Active Directory aan en laat FoxIDs de interne gebruiker automatisch aanmaken bij de eerste identificatiezoekopdracht op aanvraag. Bij POST /create-user retourneert de connector create_user_not_supported.

In het onderstaande voorbeeld zijn zowel gebruikersnaam als e-mail ingeschakeld en is gebruiker aanmaken uitgeschakeld.

FoxIDs Login authentication method-gebruikersidentificatoren voor Directory Connector

Patching en updates

  1. Download de nieuwe release FoxIDs.DirectoryConnector.ActiveDirectory-x.x.x-win-x64.zip en lees de release notes.
  2. Pak de zip uit naar een tijdelijke map en kopieer de huidige appsettings*.json bestanden mee, of bewaar secrets in IIS-omgevingsvariabelen.
  3. Stop de IIS-site of application pool.
  4. Hernoem of kopieer de huidige map naar een back-upmap, bijvoorbeeld C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.2026-04-29.bak.
  5. Kopieer de nieuwe bestanden met Xcopy naar C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory en controleer de NTFS-rechten voor de application pool-identiteit.
  6. Start de application pool en controleer GET /health, en test daarna een Directory Connector-aanmelding of een wachtwoordbewerking.
  7. Als een rollback nodig is, stop dan de application pool, herstel de back-upmap naar het live-pad en start de application pool opnieuw.

De standaard-web.config schrijft ASP.NET Core-stdout-logs naar C:\inetpub\logs\LogFiles\foxids-directory-connector-ad. Laat stdout-logging ingeschakeld totdat de connector is geverifieerd en overweeg daarna om deze uit te schakelen of de logs door te sturen naar het normale logsysteem van de omgeving na productievalidatie.