Directory Connector for Active Directory

Directory Connector for Active Directory er en FoxIDs-komponent som implementerer Directory Connector-API-et for ett AD/LDAP-domene.

Bruk den når eksisterende Active Directory-brukere skal logge inn i OpenID Connect- og SAML 2.0-applikasjoner gjennom FoxIDs, mens AD fortsatt er den autoritative katalogen for passordvalidering, passordendringer, utvalgte brukerattributter og gruppebaserte claims.

AD er fortsatt autoritativ for passordet, men FoxIDs oppretter og oppdaterer fortsatt en intern FoxIDs-bruker som er knyttet til AD-kontoen. Dette gjør det mulig å legge til FoxIDs' multi-factor authentication (MFA)-håndtering for AD-brukere, inkludert MFA-krav og tillatte second-factor-metoder, mens brukerne fortsatt autentiserer passordet sitt mot AD.

Installer komponenten i kundens Windows-miljø der den kan nå domenekontrollerne. FoxIDs kaller komponenten over HTTPS, og komponenten validerer brukere, endrer passord, setter passord og returnerer brukeregenskaper og claims fra Active Directory.

Arkitektur og deployment for Directory Connector for Active Directory

Connectoren installeres og konfigureres på Windows/IIS-serveren nær Active Directory. I FoxIDs aktiveres den deretter på miljøet under Settings > Environment > Directory connector settings, der connectorens API URL og secret konfigureres.

Komponenten utgis som en Windows-zip sammen med FoxIDs-utgivelser:

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

Synkronisering ved behov

Synkronisering er obligatorisk når Directory Connector er aktivert. Ved starten av innlogging, gjenoppretting og kontokontroll av eksisterende økter, samt ved bruk av refresh tokens for katalogbundne kontoer, henter FoxIDs gjeldende identifikatorer, attributter og gruppeclaims. FoxIDs kontoen kan opprettes før første vellykkede innlogging, slik at flyter for glemt passord og første passordoppsett kan bruke gjeldende gjenopprettingskontakt i AD.

Connectoren bruker objectGUID som stabil katalog-ID. Synkronisering rapporterer deaktiverte eller utløpte kontoer og en slettet konto når kjent ID ikke finnes. Passordoperasjoner bruker katalog-ID og returnerer HTTP 204 uten innhold. Connectoren kontrollerer kontotilstand og utfører operasjonen. Synkronisering returnerer alle brukerattributter, passordtilstand og konfigurerte gruppeclaims. Fortsettelser med bekreftelseskoder, MFA og Extended UI bruker valgt konto og vanlige FoxIDs kontroller. Etter vellykket tilbakestilling fjerner connectoren ADs krav om passordendring.

Brukerdataene mapper pwdLastSet til passwordLastChanged og bruker msDS-UserPasswordExpiryTimeComputed til å oppdage passordutløp. Null i pwdLastSet krever passordendring og aktiverer oppsett via e-post, eller SMS hvis ingen e-postidentifikator er konfigurert og en telefonidentifikator finnes. ADs nullverdi betyr at passord må angis eller endres ved neste innlogging; den skiller ikke en ubrukt konto fra en konto med midlertidig passord. Vanlig bekreftelseskodeflyt verifiserer kontroll over gjenopprettingskontakten før passordet angis. Deleger tilbakestillingsrettigheter og aktiver tilhørende gjenopprettingsmetode i FoxIDs for å bruke den.

Finner en passordoperasjon en manglende, deaktivert, utløpt eller låst konto, returneres operation_rejected med diagnostisk årsak. FoxIDs viser generell oversatt feil og lar lagret konto, eksisterende økter og refresh tokens være uendret. Synkronisering eier oppdateringer av kontotilstand og tilbakekalling; oppdager en refresh-token-forespørsel deaktivert eller slettet konto, avvises samme forespørsel.

Connectoren returnerer password_expired bare fra authentication, etter at AD har verifisert gjeldende passord. Et utløpt gjeldende passord kan fortsatt brukes til passordendring. Ugyldige påloggingsopplysninger gir invalid_password ved autentisering eller invalid_current_password ved passordendring. Se endepunktenes feilkontrakt for støttede feil og nettleseratferd.

Det finnes ingen bakgrunnsprosess. Endringer i AD gjenspeiles ved neste synkronisering, og connectorfeil stopper flyten. Se Directory Connector for sekvensens oppslagsgrense og hele API-kontrakten.

Endpoints

Komponenten eksponerer:

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

/health endpointet er ikke autentisert og returnerer bare minimal status. Det kontrollerer nødvendig konfigurasjon, AD-bind, tilgang til user search-base og valgfri tilgang til group search-base. Det tester ikke delegerte rettigheter for set-password / password reset. Detaljerte feil og stack traces logges på serveren og returneres ikke av endepunktet.

Eksempel på svar:

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

Svaret inneholder bare status, adBind, userSearch og groupSearch. status er ok bare når nødvendig konfigurasjon er gyldig, AD-bind lykkes, tilgang til user search-base lykkes, og group search-base tilgang ikke har feilet. groupSearch er not_configured når ingen group search base er konfigurert. Hvis en sjekk ikke kan utføres fordi en tidligere sjekk har feilet eller konfigurasjon mangler, returneres feltet som unknown.

Krav

  • Windows Server med IIS.
  • ASP.NET Core Hosting Bundle for .NET 10.
  • Nettverkstilgang fra IIS-serveren til den konfigurerte domenekontrolleren.
  • LDAPS eller en annen sikker kanal for passordoperasjoner.
  • Ett AD-domene per connector-deployment.
  • En domeneservicekonto hvis konfigurerte credentials brukes.
  • Delegert AD password reset-rettighet hvis set-password skal støttes.

En domenejoinet IIS-server som kjører application pool som en domeneservicekonto, er anbefalt oppsett. Konfigurerte bind-credentials støttes også via appsettings.json eller miljøvariabler.

Autentisering

Konfigurer en sterk API-nøkkel i appsettings.json.

FoxIDs sender autentisering med HTTP Basic, API ID directory_connector og den konfigurerte hemmeligheten.

Bruk bare hodet X-FoxIDs-Api-Key: <api-key> hvis en reverse proxy foran Directory Connector håndterer Basic-autentisering før forespørselen når komponenten og omskriver api-key.

AD-oppslag og binding

Komponenten søker først i AD med den konfigurerte serviceidentiteten. Den støtter oppslag etter:

  • e-post
  • telefon
  • brukernavn
  • directoryUserId når FoxIDs allerede kjenner det

Brukeren identifiseres i FoxIDs med AD objectGUID kodet som base64. Verdien returneres som directoryUserId og er stabil selv om e-post, telefon eller brukernavn endres.

Ved passordautentisering finner komponenten brukerens distinguished name og binder deretter til AD som den brukeren med det innsendte passordet. Dette unngår tvetydige brukeroppslag og støtter alle konfigurerte identifikatortyper.

Ved passordendring validerer AD det nåværende passordet og passordpolicyen.

Hvis FoxIDs passordpolicy er aktivert for Directory Connector, validerer FoxIDs passordlengde, tegnkompleksitet, brukeridentifikatorer og kontekst etter konfigurerte kontroller. Ved passordendring verifiseres gjeldende passord før policyveiledning vises. AD vedlikeholder passordhistorikken og er fortsatt autoritativt: Passordet kan avvises med password_not_accepted, eksempelvis på grunn av minimumslengde, kompleksitet, historikk, minimumsalder, detaljert passordpolicy eller et tilpasset passordfilter.

For set-password må den konfigurerte serviceidentiteten ha delegerte reset-password-rettigheter.

Tilgang for AD-servicekonto

Connectoren bør kjøre med en dedikert AD-serviceidentitet. Ikke gjør identiteten til domeneadministrator. Bruk en vanlig domenebruker eller en egendefinert sikkerhetsgruppe, og deleger bare nødvendige rettigheter på OU-ene connectoren bruker.

For brukeroppslag og autentisering må connector-identiteten ha tillatelse til å søke i hver konfigurerte UserSearchBases OU og lese brukerobjektene og attributtene som brukes av connectoren. En ny dedikert AD-serviceidentitet har ofte allerede denne lesetilgangen som standard, med mindre AD-ACL-ene er strammet inn.

Ved passordautentisering finner connectoren først brukeren med serviceidentiteten og binder deretter til AD som brukeren med det innsendte passordet. Dette krever ikke at serviceidentiteten kjenner eller tilbakestiller brukerens passord.

Ved passordendring, når brukeren oppgir det nåværende passordet, bruker connectoren AD sin password change-adferd, og AD validerer det nåværende passordet og passordpolicyen.

For set-password / password reset skal password reset-rettigheter delegeres på brukerobjektene i hver konfigurerte UserSearchBases OU der connectoren skal støtte password reset. I Active Directory Users and Computers høyreklikker du på user OU-en som connectoren bruker, velger Delegate Control..., velger connector-identiteten og på trinnet Tasks to Delegate velger du Reset user passwords and force password change at next logon.

Connectoren oppretter ikke brukere i Active Directory, så connector-identiteten trenger ikke rettigheter til å opprette AD-brukerobjekter.

Deleger Reset user passwords and force password change at next logon-rettigheten til connector-identiteten

Deleger også eventuelle ekstra passordrelaterte rettigheter som domenepolicyen krever, bare hvis miljøet bruker de handlingene.

For grupperolle-claims må connector-identiteten ha lesetilgang til de konfigurerte GroupSearchBases. Den må kunne liste group OU-en og lese gruppeattributter som cn, distinguishedName og member.

Konfigurasjon

Konfigurasjon bruker standard .NET-konfigurasjon. Verdier kan settes i appsettings.json, miljøvariabler, IIS-konfigurasjon eller en annen .NET-konfigurasjonsprovider.

Eksempel:

{
  "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 mappes alltid fra AD objectGUID og returneres base64-kodet. Den er ikke konfigurerbar.

UserIdentifiers styrer hvilke AD-attributter som kan brukes til oppslag via e-post, telefon og brukernavn og returneres som brukeridentifikatorer på toppnivå. Minst én av Email, Phone eller Username må være konfigurert og returnert fra AD for et gyldig connector-svar. Hele brukernavnet escapes som en LDAP-filterverdi og brukes til AD-oppslaget. Fjern en identifier-mapping hvis feltet ikke skal brukes til oppslag eller returneres på toppnivå. Den samme AD-attributten kan fortsatt konfigureres som et claim i Claims.

Hvis Phone mappes til AD telephoneNumber, må verdien i telephoneNumber inneholde landskode i internasjonalt format, for eksempel +4511223344.

De konfigurerte brukeridentifikatorattributtene må entydig identifisere én bruker innenfor de konfigurerte UserSearchBases. Ikke aktiver oppslag på brukernavn, e-post eller telefon med mindre de tilsvarende AD-attributtverdiene er unike for brukerne connectoren dekker.

Viktige innstillinger:

  • ApiKey: Delt secret som FoxIDs bruker til å autentisere mot connectoren. FoxIDs sender dette som HTTP Basic authentication med API ID directory_connector. Bruk en sterk unik verdi og lagre den som en miljøvariabel eller IIS-innstilling der det er mulig.
  • ActiveDirectory:Domain: AD-domenenavnet, for eksempel example.local.
  • ActiveDirectory:Server: Valgfri domenekontroller eller LDAP-endpoint. Hvis den utelates, brukes Domain.
  • ActiveDirectory:Port: LDAP-port. Bruk 636 for LDAPS.
  • ActiveDirectory:UseSsl: Aktiverer LDAPS. Hold dette aktivert for passordoperasjoner med mindre en annen sikker kanal er garantert.
  • ActiveDirectory:Bind:Mode: Integrated bruker IIS application pool-identiteten eller prosessidentiteten. ConfiguredCredentials bruker konfigurert Username og Password.
  • ActiveDirectory:Bind:Username og ActiveDirectory:Bind:Password: Credentials brukes bare når Mode er ConfiguredCredentials. Foretrekk miljøvariabler eller IIS-konfigurasjon for passordet.
  • ActiveDirectory:UserSearchBases: Ett eller flere distinguished names der brukere søkes, for eksempel OU=Users,DC=example,DC=local.
  • ActiveDirectory:GroupSearchBases: Ett eller flere distinguished names der konfigurerte rollegrupper søkes.
  • ActiveDirectory:UserIdentifiers: Valgfrie AD-felt for oppslag og toppnivå brukeridentifikatorer: Email, Phone og Username. Konfigurer minst ett.
  • ActiveDirectory:Claims: Brukerfelt som returneres som claims, for eksempel name, given_name, family_name eller email.
  • ActiveDirectory:GroupClaims: AD-gruppemedlemskap som returneres som claims, typisk role-claims. Se Gruppeclaims for konfigurasjonsdetaljer.

Gruppeclaims

Gruppeclaims er deaktivert som standard. For å aktivere dem legger du til én eller flere oppføringer i ActiveDirectory:GroupClaims.

Hver GroupClaims oppføring definerer claim-typen som skal returneres og hvilke AD-gruppemedlemskap som skal produsere det claimet. Claim er påkrevd og er typisk role.

Det finnes tre vanlige konfigurasjoner:

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

Hvis verken GroupDistinguishedName eller GroupName er konfigurert, søker connectoren i de konfigurerte GroupSearchBases og returnerer ett claim for hver matchende gruppe som brukeren er medlem av. I denne modusen skal du ikke konfigurere Value; claim-verdien må komme fra ValueAttribute. Med standard ValueAttribute satt til cn returnerer en gruppe med navnet admin_access:

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

Bruk GroupDistinguishedName når du kjenner den eksakte DN-en til AD-gruppen. Dette unngår søk etter navn og er det mest presise alternativet.

Bruk GroupName når connectoren skal finne én gruppe ut fra cn-verdien i GroupSearchBases. Søket må finne nøyaktig én gruppe. Hvis flere grupper med samme cn finnes i de konfigurerte søkebasene for grupper, mislykkes forespørselen fordi gruppetilordningen er tvetydig.

Bruk Value bare når GroupDistinguishedName eller GroupName er konfigurert og det returnerte claimet skal ha en fast verdi som er uavhengig av AD-gruppens navn. For eksempel kan en gruppe med DN CN=Employees,OU=Groups,DC=example,DC=local returnere role-verdien employees.

Hvis Value ikke er satt, leser connectoren det konfigurerte ValueAttribute fra den matchede AD-gruppen. Standard ValueAttribute er cn, som returnerer AD-gruppens navn som claim-verdi. Konfigurer bare et annet gruppeattributt hvis det attributtet finnes på gruppeobjektet og inneholder verdien som skal sendes til FoxIDs.

IncludeNestedGroups styrer hvordan medlemskap kontrolleres:

  • true bruker AD sin rekursive matchingsregel, slik at claimet returneres hvis brukeren er direkte medlem eller er medlem gjennom nestede grupper.
  • false kontrollerer bare direkte medlemskap i den matchede gruppen.

IIS-installasjon

Komponenten deployes med Xcopy. Den har ingen database og ingen installer. Oppdatering eller rollback utføres ved å erstatte filene i IIS-nettstedets mappe mens den miljøspesifikke konfigurasjonen beholdes.

  1. Installer ASP.NET Core Hosting Bundle for .NET 10 (direkte nedlasting) på Windows-serveren.
  2. Opprett en mappe, for eksempel C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.
  3. Pakk ut release-zippen i mappen.
  4. Konfigurer appsettings.json eller miljøvariabler.
  5. Opprett en IIS application pool.
  6. Sett application pool-identiteten til en domeneservicekonto, eller konfigurer bind-credentials i appsettings.json.
  7. Opprett et IIS-site eller en IIS-application som peker til mappen.
  8. Bind nettstedet til HTTPS.
  9. Opprett loggmappen C:\inetpub\logs\LogFiles\foxids-ad, og gi application pool-identiteten skrivetilgang. Hvis IIS-application poolen for eksempel heter FoxIDs.DirectoryConnector.AD, gir du skrivetilgang til IIS AppPool\FoxIDs.DirectoryConnector.AD.
  10. Verifiser GET /health.

For en FoxIDs API URL bruker du connectorens base URL, for eksempel:

https://connector.example.com

FoxIDs legger til synchronise-user, authentication, change-password og set-password i denne basis-URL-en.

TLS-sertifikat

FoxIDs kaller connectoren over HTTPS, så IIS-nettstedet bør ha et betrodd TLS-sertifikat. Du kan bruke ditt eget sertifikat eller valgfritt opprette et gratis Let's Encrypt-sertifikat med win-acme.

Med win-acme laster du ned den nyeste releasen win-acme.v2.x.x.x64.pluggable.zip, pakker den ut til en permanent mappe, kjører wacs.exe fra en forhøyet Command Prompt og velger IIS-nettstedet som hoster Directory Connector. Win-acme legger til HTTPS-bindingen og registrerer automatisk sertifikatfornyelse i Windows Task Scheduler.

Se hele win-acme-flyten i FoxIDs Windows / IIS HTTP and HTTPS guide.

FoxIDs-miljøkonfigurasjon

Når connectoren er installert og tilgjengelig over HTTPS, aktiveres den i FoxIDs-miljøet:

  1. Åpne FoxIDs Control Client.
  2. Velg den tenanten og det miljøet som skal bruke connectoren.
  3. Gå til Settings > Environment.
  4. Finn Directory connector settings.
  5. Aktiver directory connector.
  6. Angi connectorens API URL, for eksempel https://connector.example.com.
  7. Angi samme secret som connectorens ApiKey.
  8. Velg om FoxIDs skal lagre en lokal passordkopi og om FoxIDs passordpolicy skal brukes før connector-kallet.

Når FoxIDs passordpolicy er aktivert, validerer FoxIDs passordlengde, tegnkompleksitet, brukeridentifikatorer og kontekst etter konfigurerte kontroller. Ved passordendring verifiseres gjeldende passord før policyveiledning vises. AD vedlikeholder passordhistorikken og er fortsatt autoritativt: Et passord kan avvises med password_not_accepted på grunn av minimumslengde, kompleksitet, historikk, minimumsalder, detaljert passordpolicy eller et tilpasset passordfilter.

FoxIDs Directory Connector-innstillinger for Active Directory

API URL-en i FoxIDs må peke på connectorens base URL. FoxIDs legger til endepunktsnavnene når den kaller connectoren.

Som standard er bare innlogging med e-postadresse aktivert i Login authentication method. Hvis brukerne skal kunne logge inn med brukernavn eller telefonnummer, aktiverer du de tilsvarende brukeridentifikatorene i Login authentication method. Brukeridentifikatorer som returneres fra AD, kan bare brukes til innlogging når den tilsvarende identifikatoren er aktivert i Login authentication method.

Create user bør deaktiveres på Login autentiseringsmetoden ved bruk av Directory Connector for AD. Connectoren støtter ikke brukeroppretting; opprett brukere i Active Directory og la FoxIDs opprette den interne brukeren automatisk ved første identifikatoroppslag ved behov. Hvis FoxIDs kaller POST /create-user, returnerer connectoren create_user_not_supported.

Eksemplet nedenfor har både brukernavn og e-post aktivert og opprett bruker slått av.

FoxIDs Login authentication method-brukeridentifikatorer for Directory Connector

Patching og oppdateringer

  1. Last ned den nye releasen FoxIDs.DirectoryConnector.ActiveDirectory-x.x.x-win-x64.zip og les release notes.
  2. Pakk ut zip-filen til en midlertidig mappe og kopier over de nåværende appsettings*.json filene, eller behold secrets i IIS-miljøvariabler.
  3. Stopp IIS-nettstedet eller application poolen.
  4. Gi nytt navn til eller kopier den nåværende mappen til en backupmappe, for eksempel C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory.2026-04-29.bak.
  5. Xcopy de nye filene til C:\inetpub\FoxIDs.DirectoryConnector.ActiveDirectory og verifiser NTFS-rettigheter for application pool-identiteten.
  6. Start application poolen og verifiser GET /health, og test deretter en Directory Connector-innlogging eller en passordoperasjon.
  7. Hvis rollback er nødvendig, stopper du application poolen, gjenoppretter backupmappen til live-stien og starter application poolen på nytt.

Standard-web.config skriver ASP.NET Core stdout-logger til C:\inetpub\logs\LogFiles\foxids-directory-connector-ad. Hold stdout-logging aktivert til connectoren er verifisert, og vurder deretter å deaktivere den eller videresende loggene til miljøets normale loggsystem etter validering i produksjon.