Directory Connector

Directory Connector lader FoxIDs bruge et eksternt katalog som den autoritative kilde til interne brugeres adgangskoder og udvalgte brugerdata.

Brugerne findes stadig som interne brugere i FoxIDs-miljøet. Under adgangskodeautentificering og adgangskodens livscyklusoperationer kalder FoxIDs Directory Connector API'et i stedet for kun at validere adgangskoden mod den interne FoxIDs-bruger.

Fordi FoxIDs bevarer en intern brugerpost, kan FoxIDs' multi-factor authentication (MFA)-håndtering tilføjes til brugere fra det eksterne repository. Connectoren kan returnere MFA-relaterede brugerindstillinger, såsom requireMultiFactor og deaktiverede two-factor-metoder, og FoxIDs anvender indstillingerne på den interne bruger, mens det eksterne repository fortsat er autoritativt for adgangskoder og udvalgte brugerdata.

For Active Directory inkluderer FoxIDs en IIS-deployerbar Directory Connector til Active Directory-komponent.

Brug Directory Connector når:

  • Du vil have, at brugere logger ind med den normale login autentificeringsmetode.
  • Du vil aktivere brugere fra et eksisterende katalog til OpenID Connect- og SAML 2.0-applikationer gennem FoxIDs.
  • Dit eksterne katalog er autoritativt for adgangskodevalidering og ændring af adgangskoder.
  • Du vil have, at FoxIDs bevarer en intern brugerpost med identifikatorer, egenskaber, claims, multi-factor authentication (MFA)-indstillinger, adgangstildelinger og eventuelt en lokal kopi af adgangskoden.
  • Du vil have en mulighed for senere at skifte til interne brugere og adgangskodevalidering i FoxIDs uden at tvinge alle brugere gennem en nulstilling af adgangskoden.

Der er én Directory Connector pr. miljø. Når den er aktiveret, gælder den på miljøniveau.

Sådan fungerer det

Når en bruger logger ind med brugernavn og adgangskode, kalder FoxIDs Directory Connector API'et.

Ved vellykket validering opretter eller opdaterer FoxIDs den interne bruger i miljøet baseret på API-svaret. Svaret skal indeholde en stabil directoryUserId, som gemmes på den interne bruger og bruges til at binde FoxIDs-brugeren til brugeren i det eksterne katalog.

directoryUserId er ikke en brugeridentifikator, som slutbrugeren kender. Det er et separat stabilt eksternt katalog-ID. Brug ikke e-mail, telefon eller brugernavn som directoryUserId, fordi de værdier kan ændre sig. Værdien skal være stabil og entydig i det eksterne katalog.

Hvis FoxIDs allerede kender den interne brugers directoryUserId, sendes den i Directory Connector-anmodningen sammen med præcis én af brugerens e-mail, telefon eller brugernavn. Det gør det muligt for det eksterne katalog at identificere brugeren, selv hvis en identifikator er ændret.

Hvis Directory Connector API'et validerer brugeren med succes, opdaterer FoxIDs den interne bruger med identifikatorer, udvalgte egenskaber og claims, der returneres af API'et.

Hvis connectoren rapporterer, at brugeren er deaktiveret eller slettet, vil FoxIDs deaktivere eller slette den interne bruger i miljøet.

Lokal kopi af adgangskoden

Det eksterne katalog er autoritativt, mens Directory Connector er aktiveret. FoxIDs falder ikke tilbage til den lokale adgangskodehash, hvis Directory Connector API'et midlertidigt ikke er tilgængeligt.

Som standard gemmer FoxIDs en lokal kopi af adgangskoden på den interne bruger efter en vellykket validering af connector-adgangskoden eller en adgangskodelivscyklusoperation. Dette kan deaktiveres i miljøindstillingerne.

Den lokale kopi af adgangskoden bruges ikke, mens Directory Connector er aktiveret. Den findes for at understøtte et senere skift til interne brugere og adgangskodevalidering i FoxIDs uden at tvinge alle brugere gennem en nulstilling af adgangskoden.

Adgangskodens livscyklus

Adgangskodens livscyklusoperationer delegeres til Directory Connector API'et:

  • Adgangskodeautentificering kalder authentication endpointet.
  • Login create-user flow calls the create-user endpoint.
  • Ændring af brugerens adgangskode kalder change-password endpointet.
  • Set-password- og reset-password-flows kalder set-password endpointet.

FoxIDs kalder normalt kun endpointene for adgangskodens livscyklus, når den interne bruger er kendt og har en directoryUserId. Undtagelsen er change-password under første login, når det eksterne katalog har returneret password_expired, før FoxIDs har oprettet den interne bruger. I så fald sender FoxIDs login-identifikatoren og den aktuelle adgangskode uden directoryUserId; efter et vellykket adgangskodeskift bruger FoxIDs success-responsen til at oprette den interne bruger og gemme det returnerede directoryUserId.

FoxIDs opdaterer ikke sin interne adgangskodehistorik, når Directory Connector bruges, fordi FoxIDs ikke nødvendigvis kender alle adgangskodeændringer i det eksterne katalog.

Adgangskodepolitik og fejlmeddelelser

Det eksterne katalog håndhæver adgangskodepolitikken. FoxIDs bruger miljøets adgangskodepolitik, når det viser fejlmeddelelser om adgangskodepolitik, der returneres fra connectoren.

Konfigurer miljøets adgangskodepolitik, så den matcher adgangskodepolitikken i det eksterne katalog. Hvis de ikke matcher, kan brugerne se vejledning om adgangskoder, som ikke afspejler de faktiske krav i det eksterne katalog.

Hvis det eksterne katalog for eksempel afviser en adgangskode, fordi den er for kort, bruger FoxIDs miljøets minimumslængde for adgangskoden, når fejlmeddelelsen gengives.

Implementer API

Du implementerer et Directory Connector API og konfigurerer FoxIDs med dets base-URL og hemmelighed.

The API has a base URL and four endpoints:

  • authentication validerer brugerens nuværende adgangskode.
  • create-user creates a new user in the external directory and returns the created user.
  • change-password validerer den nuværende adgangskode og ændrer den til en ny adgangskode.
  • set-password sætter en ny adgangskode uden at validere den nuværende adgangskode.

Hvis base-URL'en er https://somewhere.org/directory, er endpointene:

  • 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 kalder dit API fra IP 57.128.60.142. IP(s) kan ændre sig eller blive udvidet.

Sikkerhed

Anmodninger beskyttes med HTTP Basic authentication:

  • Brugernavn: directory_connector
  • Adgangskode: den konfigurerede API-hemmelighed

Kaldet er HTTP POST med en JSON-body.

FoxIDs sender det valgte sprog i request-headeren Accept-Language, for eksempel Accept-Language: da-DK. I et loginforløb følger dette det sprog, der er valgt via ui_locales eller browseren, med engelsk som fallback i FoxIDs. API’et kan bruge denne header til at oversætte brugerrettede beskeder og skal selv vælge et fallback-sprog, hvis det ønskede sprog ikke understøttes. Denne header sendes til alle fire endpoints.

Authentication-anmodning

authentication endpointet modtager brugerens adgangskode og præcis én brugeridentifikator. FoxIDs sender directoryUserId, hvis den interne bruger findes, og værdien er kendt.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "password": "testpass1"
}

Felter:

  • directoryUserId er valgfri. FoxIDs sender den, når den interne bruger findes, og værdien er kendt.
  • Præcis én af email, phone eller username sendes.
  • password er påkrævet.

FoxIDs vælger identifikatoren ud fra brugerens logininput og de aktiverede identifikatorindstillinger. Hvis kun brugernavn for eksempel er aktiveret, og brugeren indtaster user1@somewhere.org, sender FoxIDs den som username. FoxIDs fjerner omgivende blanktegn, før brugernavnet sendes til connectoren.

Create-user request

Endpointet create-user modtager præcis én brugeridentifikator, en påkrævet adgangskode, valgte create-user-egenskaber og claims indsamlet under FoxIDs create-user-flowet.

{
  "email": "user1@somewhere.org",
  "password": "testpass1",
  "confirmAccount": true,
  "requireMultiFactor": false,
  "claims": [
    { "type": "given_name", "value": "User" },
    { "type": "family_name", "value": "One" }
  ]
}

Felter:

  • Der sendes præcis én af email, phone eller username.
  • password er påkrævet. Opret bruger uden adgangskode understøttes ikke med Directory Connector, fordi Directory Connector API'et autentificerer brugere med adgangskode.
  • confirmAccount og requireMultiFactor er de ønskede indstillinger for brugeroprettelse i FoxIDs.
  • claims indeholder de claims, der ikke er identifiers, og som indsamles under brugeroprettelsen i FoxIDs.

Ved succes returneres et almindeligt successvar. FoxIDs gemmer den returnerede directoryUserId på den interne bruger, der oprettes, efter at brugeren er oprettet i det eksterne katalog.

Change-password-anmodning

change-password endpointet modtager præcis én brugeridentifikator, aktuel adgangskode og ny adgangskode. FoxIDs sender directoryUserId, når den interne bruger findes, og værdien er kendt.

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

Felter:

  • directoryUserId er valgfri. FoxIDs sender den, når den interne bruger findes, og værdien er kendt. Den kan udelades under første login, hvis det eksterne katalog kræver adgangskodeskift, før FoxIDs har oprettet den interne bruger.
  • Præcis én af email, phone eller username sendes.
  • currentPassword og newPassword er påkrævede.

Set-password-anmodning

set-password endpointet modtager brugerens stabile katalogbinding, præcis én brugeridentifikator og ny adgangskode.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "password": "newpass1"
}

Felter:

  • directoryUserId sendes og bør bruges som den stabile katalogbinding.
  • Præcis én af email, phone eller username sendes. FoxIDs vælger den første tilgængelige interne brugeridentifikator i denne rækkefølge: e-mail, telefon, brugernavn.
  • password er påkrævet.

Svartilfælde ved succes

Ved succes skal API'et returnere HTTP-statuskode 200 og et brugersvar.

{
  "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 bruger svaret til at oprette eller opdatere den interne bruger i miljøet.

Felter:

  • directoryUserId er påkrævet. Den skal være stabil og entydig i det eksterne katalog og gemmes på den interne FoxIDs-bruger.
  • email, phone og username er hver især valgfrie, men mindst én skal være til stede. FoxIDs gemmer de returnerede værdier som den interne brugers identifikatorer. Returnerede brugeridentifikatorværdier skal entydigt identificere én bruger i det eksterne katalog, som connectoren bruger.
  • phone skal indeholde landekoden i internationalt format, fx +4511223344.
  • confirmAccount styrer, om FoxIDs skal køre et bekræftelsesflow for at bekræfte den interne bruger.
  • emailVerified styrer, om den interne brugers e-mail markeres som verificeret.
  • phoneVerified styrer, om den interne brugers telefonnummer markeres som verificeret.
  • disableTwoFactorApp deaktiverer to-faktorautentificering med authenticator-app for den interne bruger.
  • disableTwoFactorSms deaktiverer SMS-to-faktorautentificering for den interne bruger.
  • disableTwoFactorEmail deaktiverer e-mail-to-faktorautentificering for den interne bruger.
  • requireMultiFactor styrer, om den interne bruger skal bruge multifaktorautentificering.
  • claims er valgfri. FoxIDs gemmer de returnerede claims på den interne bruger.

FoxIDs ignorerer claims, hvor type eller value mangler, er null, er tom eller kun indeholder blanktegn. Når trace-logning af meddelelser er aktiveret, viser svarets trace de modtagne claims, før de filtreres. Lange trace-meddelelser afkortes.

Fejlsvar

Hvis Basic authentication afvises, returneres HTTP-statuskode 401 og invalid_api_id_secret.

{
  "error": "invalid_api_id_secret",
  "errorMessage": "Invalid API ID or secret."
}

Hvis brugeren ikke findes ved kald til authentication endpointet uden et directoryUserId, returneres HTTP-statuskode 400, 401 eller 403 og user_not_exists.

{
  "error": "user_not_exists",
  "errorMessage": "User not found."
}

Hvis adgangskoden afvises af authentication endpointet, returneres HTTP-statuskode 400, 401 eller 403 og invalid_password.

{
  "error": "invalid_password",
  "errorMessage": "Invalid password."
}

Hvis brugeridentifier og adgangskode er gyldige, men login afvises af en anden årsag, skal authentication returnere HTTP-statuskode 400, 401 eller 403 og login_rejected. Det understøttes både med og uden directoryUserId. Den valgfrie uiErrorMessage vises som almindelig tekst på loginformularen. API’et leverer den oversatte besked ud fra Accept-Language.

{
  "error": "login_rejected",
  "errorMessage": "Credentials verified; login rejected by directory policy.",
  "uiErrorMessage": "You cannot log in here. Contact support."
}

Hvis uiErrorMessage udelades, er null, tom eller kun indeholder blanktegn, viser FoxIDs samme oversatte generelle loginbesked som ved invalid_password, user_not_exists, user_disabled og user_deleted. Et afvist login tæller med i den eksisterende beskyttelse mod gentagne fejlede loginforsøg. Det opretter, opdaterer, deaktiverer eller sletter ikke den interne bruger.

Hvis den nuværende adgangskode afvises af change-password endpointet, returneres HTTP-statuskode 400, 401 eller 403 og invalid_current_password.

{
  "error": "invalid_current_password",
  "errorMessage": "Invalid current password."
}

Feltet errorMessage er diagnostisk tekst til loggen i FoxIDs og vises ikke til slutbrugeren. Angiv årsagen til fejlen, men medtag aldrig adgangskoder, API-hemmeligheder eller private nøgler.

FoxIDs viser kun en returneret uiErrorMessage ved login_rejected. For andre understøttede fejlkoder vælger FoxIDs den brugerrettede besked fra sine egne oversatte tekstressourcer. Diagnostisk tekst i errorMessage bruges aldrig som fallback til en brugerrettet besked.

Understøttede fejlkoder pr. endpoint:

Fejlkode authentication create-user change-password set-password Betydning
invalid_api_id_secret Ja Ja Ja Ja API-brugernavnet eller hemmeligheden til HTTP Basic authentication er ugyldig.
user_exists Nej Ja Nej Nej Der findes allerede en bruger med den angivne identifier i det eksterne katalog.
user_not_exists Ja, uden directoryUserId Nej Ja, uden directoryUserId Nej Ingen bruger i det eksterne katalog matcher de angivne brugeridentifiers.
invalid_password Ja Nej Nej Nej Kataloget afviste adgangskoden i en autentificeringsanmodning.
login_rejected Ja Nej Nej Nej Login blev afvist efter verificering af brugeridentifier og adgangskode. En valgfri uiErrorMessage vises på loginformularen.
invalid_current_password Nej Nej Ja Nej Kataloget afviste den nuværende adgangskode i en anmodning om ændring af adgangskode.
create_user_not_supported Nej Ja Nej Nej Connectoren understøtter ikke oprettelse af brugere i det eksterne katalog.
user_disabled Ja Nej Ja Ja Brugeren findes i kataloget, men er deaktiveret. FoxIDs deaktiverer den interne bruger.
user_deleted Ja, med directoryUserId Nej Ja, med directoryUserId Ja, med directoryUserId Brugeren i det eksterne katalog, der er knyttet via directoryUserId, findes ikke længere eller er slettet. FoxIDs sletter den interne bruger.
password_not_accepted Ja Ja Ja Ja Adgangskoden, der valideres, bruges ved brugeroprettelse, ændres eller sættes, blev afvist af en adgangskoderegel i kataloget, som ikke svarer til en mere specifik kode.
password_min_length Ja Ja Ja Ja Adgangskoden, der valideres, bruges ved brugeroprettelse, ændres eller sættes, er kortere end katalogets minimumslængde for adgangskoder.
password_max_length Ja Ja Ja Ja Adgangskoden, der valideres, bruges ved brugeroprettelse, ændres eller sættes, er længere end katalogets maksimumslængde for adgangskoder.
password_banned_characters Ja Ja Ja Ja Adgangskoden, der valideres, bruges ved brugeroprettelse, ændres eller sættes, indeholder et eller flere tegn eller ord, som kataloget afviser.
password_complexity Ja Ja Ja Ja Ældre fejl om tegnkompleksitet, som FoxIDs fortolker som password_character_variation. Brug en af de to specifikke tegnfejlkoder til nye integrationer.
password_character_repeat Ja Ja Ja Ja Adgangskoden, der valideres, bruges ved brugeroprettelse, ændres eller sættes, indeholder for mange gentagelser af tegn.
password_character_variation Ja Ja Ja Ja Adgangskoden, der valideres, bruges ved brugeroprettelse, ændres eller sættes, indeholder ikke tilstrækkelig variation i tegn.
password_email_text_complexity Ja Ja Ja Ja Adgangskoden, der valideres, bruges ved brugeroprettelse, ændres eller sættes, indeholder brugerens e-mail eller en del af den.
password_phone_text_complexity Ja Ja Ja Ja Adgangskoden, der valideres, bruges ved brugeroprettelse, ændres eller sættes, indeholder brugerens telefonnummer eller en del af det.
password_username_text_complexity Ja Ja Ja Ja Adgangskoden, der valideres, bruges ved brugeroprettelse, ændres eller sættes, indeholder brugerens brugernavn eller en del af det.
password_url_text_complexity Ja Ja Ja Ja Adgangskoden, der valideres, bruges ved brugeroprettelse, ændres eller sættes, indeholder tekst, der er relateret til URL'en til FoxIDs.
password_risk Ja Ja Ja Ja Adgangskoden, der valideres, bruges ved brugeroprettelse, ændres eller sættes, er kendt for at være risikabel, kompromitteret eller på anden måde usikker.
password_history Ja Ja Ja Ja Adgangskoden, der valideres, bruges ved brugeroprettelse, ændres eller sættes, blev afvist, fordi den har været brugt før.
password_expired Ja Ja Ja Ja Adgangskoden, der valideres, bruges ved brugeroprettelse, ændres eller sættes, er udløbet og skal ændres, før autentificeringen kan fortsætte.
new_password_equals_current Nej Nej Ja Nej Den nye adgangskode er den samme som den nuværende. set-password kan ikke returnere denne fejl, fordi endpointet ikke modtager den nuværende adgangskode.

Ved fejl om adgangskodepolitik bruger FoxIDs miljøets adgangskodepolitik til at vise den brugerrettede fejlmeddelelse. Se Adgangskodepolitik og fejlmeddelelser.

Returnér kun en fejlkode, som understøttes af endpointet og det medsendte directoryUserId, som angivet ovenfor. En ikke-understøttet kode, et ugyldigt formateret svar eller en uventet HTTP-status er en integrationsfejl og fører til den generelle fejlside. Ved en teknisk fejl i connectoren returneres HTTP-statuskode 500. Se Fejlsøgning af browserfejl for at finde de diagnostiske oplysninger ved hjælp af identifierne på fejlsiden.

Autentificeringsfejl og beskyttelse af brugeroplysninger

En ikke-autentificeret afsender må ikke kunne afgøre, om et brugernavn eller en e-mailadresse findes, ud fra en loginfejl. Ved autentificering med adgangskode håndterer FoxIDs de understøttede fejl således:

Connectorfejl Resultat for brugeren
invalid_password, user_not_exists, user_disabled eller user_deleted Den samme generelle loginbesked, f.eks. Forkert e-mail eller kodeord., oversat til det aktive sprog og tilpasset de aktiverede loginidentifiers.
login_rejected Den angivne uiErrorMessage, eller samme generelle loginbesked, hvis den mangler eller er blank, på samme sted på loginformularen.
password_not_accepted Siden til ændring af adgangskode med generel vejledning om adgangskodepolitik.
password_expired eller en anden specifik fejl om adgangskodepolitik Siden til ændring af adgangskode med den tilsvarende oversatte vejledning om adgangskodepolitik.

Connectoren skal kontrollere den angivne nuværende adgangskode, før den returnerer en fejl om adgangskodepolitik fra authentication. Ellers kan en anden side eller besked give en angriber mulighed for at finde brugere og bekræfte deres identifiers ved at gætte brugernavne eller e-mailadresser. Ved change-password skal den nuværende adgangskode kontrolleres, før der returneres kontospecifik vejledning om den nye adgangskode. Generelle formatkontroller må ikke afsløre, om en konto findes.

Hvis en bruger af en eller anden årsag ikke må logge ind via dette loginforløb, skal den angivne brugeridentifier og adgangskode først valideres. Returnér først en afvisning baseret på denne begrænsning, når begge er verificeret, så begrænsningen ikke afslører, om en gættet identifier tilhører en reel bruger. Returnér login_rejected fra authentication, angiv den diagnostiske årsag i errorMessage, og tilføj eventuelt sikker vejledning til brugeren i uiErrorMessage. Hvis loginoplysningerne ikke kan verificeres, returneres den almindelige autentificeringsfejl uden at afsløre begrænsningen.

FoxIDs er afhængig af, at connectoren verificerer loginoplysningerne, før den returnerer login_rejected; et vellykket kontoopslag eller kendskab til directoryUserId er ikke tilstrækkeligt. Før loginoplysningerne er verificeret, skal eventuel vejledning eller knapper til alternative loginmetoder vises uafhængigt af, om den angivne identifier matcher en konto.

Brug kun user_disabled og user_deleted til at rapportere den tilsvarende kontotilstand i kataloget. De deaktiverer eller sletter også den interne bruger og tilbagekalder brugerens adgang; de er ikke generelle koder til afvisning af login.

Håndtér fejl ensartet for kendte og ukendte identifiers, herunder observerbare svartider og beskyttelse mod gentagne forsøg. En generel besked alene forhindrer ikke opdagelse af brugere, hvis en anden omdirigering, status eller svartid afslører resultatet. Følg OWASP's vejledning om autentificeringsfejl, når connectoren implementeres.

API-eksempel

Eksemplet DirectoryConnectorApiSample viser, hvordan du implementerer Directory Connector API'et i ASP.NET Core.

Eksemplet indeholder:

  • authentication, create-user, change-password og set-password endpoints.
  • HTTP Basic authentication med API-brugernavnet directory_connector.
  • Et lille in-memory-katalog med demo-brugere og stabile directoryUserId-værdier.
  • Eksempler på fejl i adgangskodepolitikken såsom password_min_length, password_banned_characters og new_password_equals_current.
  • Et eksempel på en deaktiveret bruger, der returnerer user_disabled.

Postman-samlingen directory-connector-api.postman_collection.json kan bruges til at kalde og teste eksempel-API'et med Postman.

Active Directory-komponent

FoxIDs indeholder en Directory Connector til Active Directory-komponent, der kan deployes til IIS. Komponenten implementerer Directory Connector API'et for ét AD/LDAP-domæne og kan validere adgangskoder, ændre adgangskoder, sætte adgangskoder, returnere konfigurerede AD-attributter som claims og returnere konfigurerede indlejrede AD-gruppemedlemskaber som claims.

Konfiguration

Konfigurer Directory Connector i miljøindstillingerne i FoxIDs Control Client.

  1. Vælg fanen Settings.
  2. Vælg fanen Environment.
  3. Find sektionen Directory Connector.
  4. Aktiver Directory Connector.
  5. Tilføj basis-API-URL'en uden endpoint-mappen i API URL.
  6. Tilføj API secret.
  7. Beslut, om en lokal kopi af adgangskoden skal gemmes.
  8. Konfigurer miljøets adgangskodepolitik, så den matcher adgangskodepolitikken i det eksterne katalog.
  9. Klik Update.

Directory Connector-indstillinger