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

FoxIDs synkroniserer efter behov, når en bruger angiver en identifikator i et login- eller gendannelsesforløb. FoxIDs kalder synchronise-user, før kontoen kontrolleres, opretter om nødvendigt en FoxIDs bruger og opdaterer identifikatorer, egenskaber og claims, som kataloget ejer.

Synkronisering indgår, når Directory Connector aktiveres. FoxIDs synkroniserer ved starten af login, gendannelse og kontokontrol ved genbrug af en session samt ved brug af et refresh token til en katalogbundet konto. Fortsættelser med bekræftelseskoder, MFA og Extended UI bruger den valgte konto og de normale FoxIDs kontroller. Hvis synkroniseringen fejler, stoppes forløbet.

Svaret skal indeholde et stabilt, entydigt directoryUserId. Brug katalogets permanente konto-ID frem for e-mail, telefonnummer eller brugernavn. FoxIDs bruger bindingen til at finde samme konto, efter at identifikatorer ændres. Registrerede autentificeringsapps og adgangstildelinger i FoxIDs bevares.

Når brugeren indtaster en identifikator, sender FoxIDs kun denne e-mail, dette telefonnummer eller dette brugernavn. Ved sessionsgenbrug og anmodninger med refresh tokens indlæser FoxIDs den tilknyttede bruger og synkroniserer med det katalog-ID, der er gemt på brugeren. Adgangskodeoperationer bruger også katalog-ID'et på den indlæste bruger. Det gemmes ikke separat i loginsekvensen.

Connectoren returnerer alle aktuelle brugerdata. FoxIDs erstatter katalogets identifikatorer, egenskaber og claims, herunder deaktiveringsstatus, krav om adgangskodeskift og indstillinger for første adgangskodeopsætning. De samme konto-, gendannelses- og MFA-kontroller som for interne brugere anvendes. Interne brugere uden katalogbinding synkroniseres ikke og tilknyttes ikke automatisk.

Et synkroniseringssvar med disableAccount: true deaktiverer brugeren i FoxIDs og tilbagekalder aktive sessioner og refresh-token grants. Returnerer connectoren fejlkoden user_deleted ved synkronisering med brugerens katalog-ID, sletter FoxIDs den interne bruger og tilbagekalder aktive sessioner og refresh tokens. Finder et opslag alene på en identifikator ingen konto, kontrollerer FoxIDs en eventuel eksisterende katalogbinding, før forløbet fortsætter, så forældede lokale kontodata ikke giver adgang til login eller gendannelse. Fejlkoden user_not_exists sletter ikke i sig selv en konto.

Anmodninger med refresh tokens kontrollerer både den oprindelige konto og en lokal konto, som brugeren impersonerer, hvis de er katalogbundne. Finder synkroniseringen en deaktiveret eller slettet konto, tilbagekalder FoxIDs aktive sessioner og refresh-token grants og afviser den aktuelle tokenfornyelse. Den almindelige kontrol af aktive sessioner validerer sessionstilstanden i FoxIDs; den kontakter ikke selv kataloget. En applikation, der validerer et udstedt access token lokalt, følger tokenets udløb frem for tilbagekaldelsen af sessionen i FoxIDs.

Ændringer bliver tilgængelige ved næste kontokontrol efter behov. Der er ingen baggrundssynkronisering.

Directory Connector kan bruges som en permanent integration, hvor brugere og adgangskoder administreres i det eksterne katalog, eller til gradvist at flytte brugere til FoxIDs. Ved flytning holdes connectoren aktiveret, mens brugerne oprettes. Aktivér lokal kopi af adgangskoden for at gemme adgangskoder efter vellykket autentificering, ændring eller nulstilling gennem FoxIDs.

Når flytningen er fuldført, deaktiveres Directory Connector, og brugere og adgangskoder administreres direkte i FoxIDs. Opret først eventuelle brugere, der endnu ikke er oprettet, og sørg for adgangskodeopsætning eller gendannelse for brugere uden en aktuel lokal adgangskodekopi. Kopien afspejler den seneste vellykkede adgangskodeautentificering, ændring eller nulstilling gennem FoxIDs; senere ændringer foretaget alene i det eksterne katalog er ikke med.

Beskyttelse af opslag

Når en bruger indtaster e-mail, telefonnummer eller brugernavn i brugerfladen til login eller gendannelse, tæller katalogopslaget med i en fælles grænse for alle indtastede identifikatorer i den aktuelle loginsekvens. Grænsen bruger miljøets indstillinger for Failed login attempt limit, tællerens levetid og observationsperioden. Både vellykkede opslag og fejlede connectorkald tæller med; vellykket adgangskodeautentificering nulstiller ikke tælleren. Når grænsen nås, skal observationsperioden afventes, eller en ny loginsekvens startes. Synkronisering ved sessionsgenbrug og refresh-token-anmodninger bruger ikke denne tæller. Beskyttelsen af adgangskoder og bekræftelseskoder bruger fortsat sine eksisterende separate tællere.

Loginidentifikatorer og katalogbinding

Brugere kan logge ind med deres aktuelle e-mail, telefonnummer eller brugernavn afhængigt af de identifikatortyper, der er aktiveret på login autentificeringsmetoden. Før adgangskodeautentificering skal den indtastede identifikator matche en aktuel identifikator fra connectoren. FoxIDs fjerner omgivende blanktegn. Sammenligning af e-mail og brugernavn skelner ikke mellem store og små bogstaver. Telefonnumre bruger det krævede internationale format.

Login efter ændring af identifikatorer

Når brugere indtaster en identifikator, synkroniserer FoxIDs deres e-mail, telefonnummer og brugernavn fra kataloget. Det stabile katalog-ID knytter dem til samme FoxIDs konto, selv hvis én eller alle identifikatorer ændres. Registrerede autentificeringsapps og adgangstildelinger bevares, og eksisterende adgangsbegrænsninger og MFA-krav gælder fortsat.

Situation Hvad sker der under synkronisering?
Brugeren logger ind med et uændret brugernavn, mens e-mail eller telefonnummer er ændret i kataloget. FoxIDs opdaterer samme konto med de aktuelle identifikatorer fra connectoren.
Brugeren logger ind med en ny identifikator, som FoxIDs endnu ikke kender. Returnerer kataloget den nye identifikator og samme stabile katalog-ID, fortsætter brugeren med sin eksisterende FoxIDs konto. Det gælder også, når alle identifikatorer er ændret.
Brugeren logger ind med en gammel identifikator, som connectoren ikke længere returnerer. Login afvises med den normale loginfejl, selv hvis brugeren stadig kender adgangskoden. Brugeren skal bruge en aktuel identifikator af en aktiveret type.
Connectoren stopper med at returnere e-mail, telefonnummer eller brugernavn. Identifikatoren fjernes fra FoxIDs kontoen under synkroniseringen. Connectoren skal returnere mindst én aktuel identifikator.

En bruger, hvis e-mail ændres fra old@example.org til new@example.org, kan eksempelvis logge ind med new@example.org, før FoxIDs kender adressen. Connectoren skal returnere new@example.org og brugerens uændrede katalog-ID. Brugeren beholder samme konto og registrerede autentificeringsapps. Alternativt kan brugeren logge ind med et uændret brugernavn, hvis login med brugernavn er aktiveret.

Connectoren skal returnere alle aktuelle identifikatorer, som FoxIDs skal bevare. Udeladte eller tomme værdier behandles som fjernede identifikatorer, og tidligere værdier bevares ikke som login-aliasser. Kun identifikatortyper, der er aktiveret på login autentificeringsmetoden, kan bruges til login.

Kontokonflikter

Hver katalogbruger skal have et stabilt, entydigt katalog-ID, og brugerens identifikatorer må ikke tilhøre en anden FoxIDs konto. FoxIDs slår først den indtastede identifikator op i kataloget og bruger derefter det returnerede katalog-ID til at finde eller oprette den lokale konto. Hvis gemning af identifikatorerne konflikter med en anden konto, stoppes forløbet. En administrator skal rette konflikten i kataloget eller kontokonfigurationen i FoxIDs; konti sammenlægges eller omfordeles ikke automatisk.

En eksisterende intern bruger uden katalogbinding kan ikke logge ind gennem Directory Connector. Aktivering af connectoren knytter ikke automatisk en eksisterende konto til en katalogbruger, blot fordi e-mail, telefonnummer eller brugernavn matcher.

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

Brugeroprettelse og handlinger i adgangskodens livscyklus delegeres til Directory Connector API’et:

  • Adgangskodeautentificering kalder authentication endpointet.
  • Brugeroprettelse under login kalder endpointet create-user.
  • Ændring af brugerens adgangskode kalder change-password endpointet.
  • Set-password- og reset-password-flows kalder set-password endpointet.

Adgangskodeendpoints modtager det stabile directoryUserId fra den indlæste bruger. Kataloget kontrollerer aktuel kontotilstand og legitimationsoplysninger under operationen. Autentificering, ændring og nulstilling af adgangskoder returnerer succes eller en fejl. Brugeroprettelse returnerer den oprettede kontos katalog-ID, som FoxIDs bruger til en separat synkronisering.

Adgangskodeoperationer bruger katalog-ID'et gemt på den indlæste FoxIDs bruger. Connectoren kontrollerer kontotilstanden og de legitimationsoplysninger eller den nulstillingsautorisation, operationen kræver, udfører handlingen og returnerer succes eller en fejl. Brugeridentifikatorer, attributter og claims returneres kun af synkronisering.

Efter vellykket ændring eller nulstilling af adgangskoden gemmer FoxIDs det aktuelle tidspunkt for adgangskodeændringen og fjerner krav om at ændre eller sætte en adgangskode. En lokal adgangskodekopi gemmes også, hvis det er konfigureret. Den aktive sekvens fortsætter derefter med normal konto-, gendannelses- og MFA-håndtering i FoxIDs.

Hvis en handling fejler, eller FoxIDs ikke kan gemme de kendte adgangskodeændringer, stoppes forløbet. En adgangskodeændring, der allerede er accepteret af kataloget, rulles ikke tilbage, og FoxIDs gentager ikke automatisk handlingen efter timeout eller et fejlet svar. Næste synkronisering opdaterer den lokale konto.

Når Enable password policy er aktiveret, verificerer FoxIDs den aktuelle adgangskode i kataloget, før kontrollen af en ny adgangskode udføres. Det kan kræve et ekstra autentificeringskald før change-password.

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

Opsætning og gendannelse af adgangskoder

Ved første login kan en katalogbruger sætte en adgangskode med en bekræftelseskode via e-mail eller SMS, enten fordi adgangskoden er glemt, eller fordi brugeren skal vælge en ny.

For at bruge Forgot your password? indtastes en aktuel katalogidentifikator af en type, som login autentificeringsmetoden tillader. FoxIDs synkroniserer og opretter kontoen, før bekræftelseskoden sendes. Gendannelse via e-mail eller SMS skal være aktiveret, og brugeren skal have adgang til den aktuelle gendannelseskontakt, som kataloget returnerer.

Når brugeren har bekræftet koden og indsendt en ny adgangskode, kalder FoxIDs set-password med det stabile katalog-ID. Returnér setPasswordEmail eller setPasswordSms og den tilhørende kontaktidentifikator for at kræve adgangskodeopsætning gennem dette forløb. FoxIDs bruger sit normale forløb til adgangskodeopsætning.

Bekræftelseskoder er bundet til den konto, de blev udstedt til. Katalogadministrerede konti bruger samme kodeverifikation som andre interne brugere. FoxIDs bevarer den normale fejlhåndtering ved gendannelse uden at vise diagnostik fra connectoren.

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.

API'et har en basis-URL og fem endpoints:

  • synchronise-user slår en bruger op og returnerer aktuel kontotilstand, identifikatorer og claims.
  • authentication validerer brugerens nuværende adgangskode.
  • create-user opretter en bruger i det eksterne katalog og returnerer brugerens permanente katalog-ID.
  • 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/synchronise-user
  • 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, eksempelvis Accept-Language: da-DK. Under login følger det sproget valgt med ui_locales eller i browseren, med engelsk som standard i FoxIDs. API'et kan bruge headeren til at oversætte brugerbeskeder og skal vælge sit eget standardsprog, hvis det ønskede sprog ikke understøttes. Headeren sendes til alle fem endpoints.

Synkroniseringsanmodning

Endpointet synchronise-user modtager enten en brugeridentifikator eller et kendt katalog-ID. Første opslag under login eller gendannelse bruger den indtastede identifikator. FoxIDs bruger det gemte directoryUserId ved kontrol af eksisterende sessioner og refresh-token-anmodninger samt det returnerede katalog-ID efter create-user.

Et indledende opslag med e-mail:

{
  "email": "user1@somewhere.org"
}

En efterfølgende kontokontrol:

{
  "directoryUserId": "a1b2c3d4"
}

Brug directoryUserId som autoritativ opslagsnøgle, når det er angivet. Ellers slås præcis én af email, phone eller username op. Returnér HTTP 200 med alle aktuelle brugerdata, også for deaktiverede konti. Returnér fejlkoden user_deleted, når det kendte ID ikke findes, og user_not_exists, når et opslag alene på en identifikator ikke finder en konto. Acceptér aldrig en angivet identifikator som bevis på ejerskab af kontoen.

FoxIDs vælger anmodningens identifikator ud fra de aktiverede loginidentifikatorer. Hvis kun brugernavn er aktiveret, sendes input i e-mailformat som username. Omgivende blanktegn fjernes. Inputtet skal matche en aktuel identifikator af en aktiveret type i svaret; det valgte request-felt begrænser ikke, hvilket svarfelt der kan matche.

Se Fejlsvar for fejl.

Svar ved succes

Endpointet synchronise-user returnerer HTTP 200 med alle aktuelle brugerdata. Hvis anmodningen indeholder et katalog-ID, skal svaret indeholde samme ID. FoxIDs kontrollerer dette, før data gemmes. HTTP 204 eller ufuldstændige brugerdata afvises.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "phone": "+4511223344",
  "username": "user1",
  "confirmAccount": true,
  "disableAccount": false,
  "changePassword": false,
  "setPasswordEmail": false,
  "setPasswordSms": false,
  "disableSetPasswordEmail": false,
  "disableSetPasswordSms": false,
  "passwordLastChanged": 1760000000,
  "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.
  • disableAccount styrer kontoens direkte deaktiveringsstatus. Overgang til deaktiveret tilbagekalder brugerens sessioner og refresh-token grants i FoxIDs.
  • changePassword kræver adgangskodeskift efter vellykket verifikation af legitimationsoplysningerne.
  • setPasswordEmail og setPasswordSms kræver adgangskodeopsætning gennem det tilsvarende bekræftelseskodeforløb. Kontaktidentifikatoren skal være angivet, og gendannelsesmetoden skal være aktiveret.
  • disableSetPasswordEmail og disableSetPasswordSms deaktiverer de tilsvarende gendannelsesmetoder.
  • passwordLastChanged er et valgfrit, ikke-negativt Unix-tidsstempel i sekunder. Når synkronisering angiver det, opdateres adgangskodealderen i FoxIDs. Udelades det, bevares et eksisterende tidsstempel. En vellykket ændring eller nulstilling gemmer det aktuelle tidspunkt i FoxIDs; en senere synkronisering kan angive katalogets autoritative tidspunkt.
  • 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.

Claims understøtter en valgfri valueType: String, Boolean, Number, JsonObject eller JsonArray. Feltet value forbliver tekst; udelad valueType for String. FoxIDs bevarer den valgte type og logger en warning, før en ugyldig værdi falder tilbage til tekst. Se claimværdiers typer for eksempler og talgrænser. Den samme repræsentation bruges til claims, der sendes i requests om brugeroprettelse og returneres i synkroniseringssvar.

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.

Beskyttede claims, eksempelvis sid og auth_time, fjernes også fra synkroniseringssvar.

Authentication-anmodning

Endpointet authentication modtager det påkrævede stabile katalog-ID og den aktuelle adgangskode.

{
  "directoryUserId": "a1b2c3d4",
  "password": "testpass1"
}

Kontrollér den aktuelle kontotilstand i kataloget og adgangskoden, før succes returneres. Verificér adgangskoden, før der returneres kontospecifik vejledning om adgangskodepolitik.

Se Fejlsvar for fejl.

Svar ved succes

Returnér HTTP 204 uden svarindhold ved succes.

Anmodning om brugeroprettelse

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:

  • Præcis én af email, phone eller username sendes.
  • 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.

Se Fejlsvar for fejl.

Svar ved succes

Returnér HTTP 200 med den oprettede kontos permanente katalog-ID ved succes:

{
  "directoryUserId": "a1b2c3d4"
}

FoxIDs kalder derefter synchronise-user med dette ID for at hente hele kontoen og oprette den interne FoxIDs bruger.

Change-password-anmodning

Endpointet change-password modtager det påkrævede katalog-ID, den aktuelle og den nye adgangskode. Verificér den aktuelle adgangskode, før kontospecifik vejledning om politik returneres.

{
  "directoryUserId": "a1b2c3d4",
  "currentPassword": "oldpass1",
  "newPassword": "newpass1"
}

Se Fejlsvar for fejl.

Svar ved succes

Returnér HTTP 204 uden svarindhold ved succes. Adgangskodeændringen skal opfylde katalogets krav om adgangskodeændring.

Set-password-anmodning

Endpointet set-password modtager det påkrævede katalog-ID og den nye adgangskode. FoxIDs kalder det efter autorisation af nulstilling eller opsætning, herunder kodeverifikation i gendannelsesforløb. Connectoren skal kontrollere den aktuelle kontotilstand igen, før adgangskoden ændres.

{
  "directoryUserId": "a1b2c3d4",
  "password": "newpass1"
}

Se Fejlsvar for fejl.

Svar ved succes

Returnér HTTP 204 uden svarindhold ved succes. Nulstilling eller opsætning skal opfylde katalogets adgangskodekrav.

Fejlsvar

Alle endpoints bruger samme JSON-fejlformat. Returnér en fejlkode, som endpointet understøtter, i feltet error og diagnostiske detaljer i errorMessage. Eksempelvis en afvist adgangskode fra authentication:

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

Brug disse HTTP-statuskoder:

  • 401 med fejlkoden invalid_api_id_secret, når HTTP Basic-autentificering afvises.
  • 400, 401 eller 403 for andre understøttede fejlkoder i endpointtabellen nedenfor.
  • 500 ved tekniske fejl i connectoren.

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.

Kun endpointet authentication kan returnere fejlkoden login_rejected, efter brugerens identifikator og adgangskode er verificeret. Det kan indeholde en valgfri uiErrorMessage, som FoxIDs viser som almindelig tekst på loginformularen. API'et leverer beskeden på sproget valgt via 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 fejlkoderne invalid_password og operation_rejected. For andre understøttede fejlkoder ignorerer FoxIDs uiErrorMessage og vælger brugerbeskeden fra sine egne oversatte tekster. Diagnostisk tekst fra errorMessage bruges aldrig som reserve for en brugerbesked. Se Autentificeringsfejl og beskyttelse af brugeroplysninger for krav til verifikation.

Fejl fra authentication, change-password og set-password returnerer ikke brugerdata, ændrer ikke den interne konto og tilbagekalder ikke eksisterende sessioner og refresh tokens. Synkronisering anvender katalogets kontoændringer. Afviste autentificerings- og adgangskodeskiftforsøg tæller fortsat med i den eksisterende grænse for mislykkede loginforsøg.

Understøttede fejlkoder pr. endpoint:

Fejlkode synchronise-user authentication create-user change-password set-password Betydning
invalid_api_id_secret Ja Ja Ja Ja Ja API-brugernavnet eller hemmeligheden til HTTP Basic authentication er ugyldig.
user_exists Nej Nej Ja Nej Nej Der findes allerede en bruger med den angivne identifier i det eksterne katalog.
user_not_exists Uden katalog-ID Nej Nej Nej Nej Ingen katalogbruger matchede opslaget alene på en identifikator.
invalid_password Nej Ja Nej Nej Nej Kataloget afviste adgangskoden i en autentificeringsanmodning.
login_rejected Nej Ja Nej Nej Nej Login blev afvist efter verificering af brugeridentifier og adgangskode. En valgfri uiErrorMessage vises på loginformularen.
invalid_current_password Nej Nej Nej Ja Nej Kataloget afviste den nuværende adgangskode i en anmodning om ændring af adgangskode.
create_user_not_supported Nej Nej Ja Nej Nej Connectoren understøtter ikke oprettelse af brugere i det eksterne katalog.
operation_rejected Nej Ja Nej Ja Ja Handlingen kan ikke gennemføres, eksempelvis fordi kontoen ikke er tilgængelig. FoxIDs logger errorMessage, ignorerer uiErrorMessage og viser en generel oversat fejl uden at ændre kontotilstanden.
user_deleted Med katalog-ID Nej Nej Nej Nej Et kendt katalog-ID findes ikke længere. FoxIDs tilbagekalder adgang og sletter brugeren under synkroniseringen.
password_not_accepted Nej 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 Nej 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 Nej 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 Nej 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 Nej 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 Nej Ja Ja Ja Ja Adgangskoden, der valideres, bruges ved brugeroprettelse, ændres eller sættes, indeholder for mange gentagelser af tegn.
password_character_variation Nej 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 Nej 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 Nej 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 Nej 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 Nej 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 Nej 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 Nej Nej Nej Ja Ja Den nye adgangskode blev afvist, fordi den har været brugt før.
password_expired Nej Ja Nej Nej Nej Den angivne adgangskode er verificeret, men udløbet; brugeren skal ændre den, før autentificeringen kan fortsætte.
new_password_equals_current Nej 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.

Når FoxIDs skal kontrollere sin egen adgangskodepolitik før et adgangskodeskift, kaldes først authentication for at verificere den aktuelle adgangskode. Returnerer connectoren fejlkoden password_expired fra denne autentificering, kan ændringen fortsætte. Endpointet change-password skal selv acceptere en verificeret, udløbet aktuel adgangskode og kun returnere fejl, som ændringsoperationen understøtter.

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 angivne directoryUserId, som beskrevet ovenfor. En ikke-understøttet kode, et ugyldigt svar eller en uventet HTTP-status er en integrationsfejl og fører til den generelle fejlside. Se Fejlfinding af browserfejl for at finde diagnostik med identifikatorerne fra 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, operation_rejected eller en utilgængelig konto konstateret under synkronisering 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 grund ikke må logge ind gennem dette loginforløb, skal den angivne brugeridentifikator og adgangskode først valideres. Returnér først en afvisning baseret på begrænsningen, når begge er verificeret, så begrænsningen ikke afslører, om en gættet identifikator tilhører en virkelig bruger. Returnér fejlkoden login_rejected fra authentication, angiv den diagnostiske årsag i errorMessage, og tilføj eventuelt sikker brugervejledning i uiErrorMessage. Kan legitimationsoplysningerne ikke verificeres, returneres den normale autentificeringsfejl uden at afsløre begrænsningen.

FoxIDs stoler på, at connectoren verificerer legitimationsoplysningerne, før fejlkoden login_rejected returneres; et vellykket kontoopslag eller kendskab til directoryUserId er ikke nok. Før verifikation skal eventuelle instruktioner eller knapper til alternative loginmetoder vises uafhængigt af, om den indsendte identifikator matcher en konto.

Kun synchronise-user rapporterer kontotilstand: Returnér alle brugerdata med disableAccount: true for en deaktiveret konto eller fejlkoden user_deleted, når et kendt katalog-ID ikke længere findes. Adgangskodeendpoints returnerer fejlkoden operation_rejected, hvis kontoen ikke er tilgængelig. I modsætning til login_rejected kræver denne fejl ikke en verificeret adgangskode, fordi den aldrig giver browseren kontospecifik vejledning.

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.

Implementeringer og testklienter skal følge endpointkontrakterne ovenfor: HTTP 200 med alle aktuelle brugerdata for synchronise-user, HTTP 200 med det oprettede katalog-ID for create-user og HTTP 204 uden indhold for vellykkede adgangskodeoperationer.

Active Directory-komponent

FoxIDs inkluderer en Directory Connector til Active Directory, som kan installeres på IIS. Komponenten implementerer Directory Connector API'et for ét AD/LDAP-domæne og kan synkronisere konti, validere, ændre og sætte adgangskoder samt returnere konfigurerede AD-attributter og indlejrede AD-gruppemedlemskaber som claims.

Konfiguration

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

  1. Vælg fanen Indstillinger.
  2. Vælg fanen Miljø.
  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