Directory Connector

Directory Connector lar FoxIDs bruke et eksternt katalog som autoritativ kilde for interne brukeres passord og utvalgte brukerdata.

Brukerne eksisterer fortsatt som interne brukere i FoxIDs-miljøet. Under passordautentisering og operasjoner i passordets livssyklus kaller FoxIDs Directory Connector API-et i stedet for bare å validere passordet mot den interne FoxIDs-brukeren.

Fordi FoxIDs beholder en intern brukerpost, kan FoxIDs' multi-factor authentication (MFA)-håndtering legges til for brukere fra det eksterne repositoriet. Connectoren kan returnere MFA-relaterte brukerinnstillinger, for eksempel requireMultiFactor og deaktiverte two-factor-metoder, og FoxIDs bruker disse innstillingene på den interne brukeren mens det eksterne repositoriet fortsatt er autoritativt for passord og utvalgte brukerdata.

For Active Directory inkluderer FoxIDs en IIS-distribuerbar Directory Connector for Active Directory-komponent.

Bruk Directory Connector når:

  • du vil at brukere skal logge inn med den vanlige login-autentiseringsmetoden.
  • du vil aktivere brukere fra en eksisterende katalog for OpenID Connect- og SAML 2.0-applikasjoner gjennom FoxIDs.
  • det eksterne kataloget er autoritativt for passordvalidering og passordendringer.
  • du vil at FoxIDs skal beholde en intern brukerpost med identifikatorer, egenskaper, claims, multi-factor authentication (MFA)-innstillinger, tilgangstildelinger og eventuelt en lokal kopi av passordet.
  • du vil ha en vei til senere å bytte til interne brukere og passordvalidering i FoxIDs uten å tvinge alle brukere gjennom en passordtilbakestilling.

Det finnes én Directory Connector per miljø. Når den er aktivert, gjelder den på miljønivå.

Slik fungerer det

Når en bruker logger inn med brukernavn og passord, kaller FoxIDs Directory Connector API-et.

Ved vellykket validering oppretter eller oppdaterer FoxIDs den interne brukeren i miljøet basert på API-responsen. Responsen må inneholde en stabil directoryUserId, som lagres på den interne brukeren og brukes til å binde FoxIDs-brukeren til brukeren i det eksterne kataloget.

directoryUserId er ikke en brukeridentifikator som sluttbrukeren kjenner. Det er en separat stabil ekstern katalog-ID. Ikke bruk e-post, telefon eller brukernavn som directoryUserId, fordi disse verdiene kan endre seg. Verdien må være stabil og unik i det eksterne kataloget.

Hvis FoxIDs allerede kjenner den interne brukerens directoryUserId, sendes den i Directory Connector-forespørselen sammen med nøyaktig én av brukerens identifikatorer: e-post, telefon eller brukernavn. Dette gjør det mulig for det eksterne kataloget å identifisere brukeren selv om en identifikator har endret seg.

Hvis Directory Connector API-et validerer brukeren vellykket, oppdaterer FoxIDs den interne brukeren med identifikatorer, utvalgte egenskaper og claims som returneres fra API-et.

Hvis connectoren rapporterer at brukeren er deaktivert eller slettet, vil FoxIDs deaktivere eller slette den interne brukeren i miljøet.

Lokal passordkopi

Det eksterne kataloget er autoritativt så lenge Directory Connector er aktivert. FoxIDs faller ikke tilbake til den lokale passordhashen hvis Directory Connector API-et er midlertidig utilgjengelig.

Som standard lagrer FoxIDs en lokal kopi av passordet på den interne brukeren etter en vellykket passordvalidering eller operasjon i passordets livssyklus via connectoren. Dette kan deaktiveres i miljøinnstillingene.

Den lokale passordkopien brukes ikke mens Directory Connector er aktivert. Den finnes for å støtte en senere overgang til interne brukere og passordvalidering i FoxIDs uten å tvinge alle brukere til å tilbakestille passordet.

Passordlivssyklus

Operasjoner i passordets livssyklus delegeres til Directory Connector API-et:

  • Passordautentisering kaller endepunktet authentication.
  • Login create-user flow calls the create-user endpoint.
  • Endring av brukerpassord kaller endepunktet change-password.
  • Flyter for å sette passord og tilbakestille passord kaller endepunktet set-password.

FoxIDs kaller normalt bare endepunktene for passordlivssyklus når den interne brukeren er kjent og har en directoryUserId. Unntaket er change-password ved første innlogging, når det eksterne kataloget har returnert password_expired før FoxIDs har opprettet den interne brukeren. I så fall sender FoxIDs innloggingsidentifikatoren og det nåværende passordet uten directoryUserId; etter et vellykket passordbytte bruker FoxIDs suksessresponsen til å opprette den interne brukeren og lagre returnert directoryUserId.

FoxIDs oppdaterer ikke sin interne passordhistorikk når Directory Connector brukes, fordi FoxIDs ikke nødvendigvis kjenner til alle passordendringer i det eksterne kataloget.

Passordpolicy og feilmeldinger

Det eksterne kataloget håndhever passordpolicyen. FoxIDs bruker miljøets passordpolicy når det viser feilmeldinger om passordpolicy som returneres fra connectoren.

Konfigurer miljøets passordpolicy slik at den samsvarer med passordpolicyen i det eksterne kataloget. Hvis de ikke samsvarer, kan brukerne se passordveiledning som ikke gjenspeiler de faktiske kravene i det eksterne kataloget.

Hvis det eksterne kataloget for eksempel avviser et passord fordi det er for kort, bruker FoxIDs miljøets minimumslengde for passord når feilmeldingen vises.

Implementer API

Du implementerer et Directory Connector API og konfigurerer FoxIDs med basis-URL og secret.

The API has a base URL and four endpoints:

  • authentication validerer brukerens nåværende passord.
  • create-user creates a new user in the external directory and returns the created user.
  • change-password validerer det nåværende passordet og endrer det til et nytt passord.
  • set-password setter et nytt passord uten å validere det nåværende passordet.

Hvis basis-URL-en er https://somewhere.org/directory, er endepunktene:

  • 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 kaller API-et ditt fra IP 57.128.60.142. IP(s) kan endres eller utvides.

Sikkerhet

Forespørsler sikres med HTTP Basic authentication:

  • Brukernavn: directory_connector
  • Passord: det konfigurerte API-secretet

Kallet er HTTP POST med en JSON-body.

FoxIDs sender det valgte språket i forespørselens HTTP-header Accept-Language, for eksempel Accept-Language: da-DK. I en påloggingsflyt følger dette språket som er valgt via ui_locales eller nettleseren, med engelsk som reservespråk i FoxIDs. API-et kan bruke denne headeren til å lokalisere meldinger til brukeren og må velge sitt eget reservespråk hvis det forespurte språket ikke støttes. Denne headeren sendes til alle fire endepunktene.

Authentication-forespørsel

Endepunktet authentication mottar brukerens passord og nøyaktig én brukeridentifikator. FoxIDs sender directoryUserId hvis den interne brukeren finnes og verdien er kjent.

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

Felt:

  • directoryUserId er valgfri. FoxIDs sender den når den interne brukeren finnes og verdien er kjent.
  • Nøyaktig én av email, phone eller username sendes.
  • password er påkrevd.

FoxIDs velger identifikatoren fra brukerens innloggingsinput og de aktiverte identifikatorinnstillingene. Hvis for eksempel bare brukernavn er aktivert og brukeren skriver inn user1@somewhere.org, sender FoxIDs den som username. FoxIDs fjerner omgivende blanktegn før brukernavnet sendes til connectoren.

Create-user request

Endepunktet create-user mottar nøyaktig én brukeridentifikator, et påkrevd passord, valgte create-user-egenskaper og claims samlet inn under FoxIDs create-user-flyten.

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

Felter:

  • Nøyaktig én av email, phone eller username sendes.
  • password er påkrevd. Opprett bruker uten passord støttes ikke med Directory Connector fordi Directory Connector API-et autentiserer brukere med passord.
  • confirmAccount og requireMultiFactor er de ønskede innstillingene for brukeropprettelse i FoxIDs.
  • claims inneholder claims som ikke er identifikatorer, og som samles inn når brukeren opprettes i FoxIDs.

Ved vellykket opprettelse returneres et vanlig suksessvar. FoxIDs lagrer den returnerte directoryUserId på den interne brukeren som opprettes etter at brukeren er opprettet i den eksterne katalogen.

Change-password-forespørsel

Endepunktet change-password mottar nøyaktig én brukeridentifikator, nåværende passord og nytt passord. FoxIDs sender directoryUserId når den interne brukeren finnes og verdien er kjent.

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

Felt:

  • directoryUserId er valgfri. FoxIDs sender den når den interne brukeren finnes og verdien er kjent. Den kan utelates ved første innlogging hvis det eksterne kataloget krever passordbytte før FoxIDs har opprettet den interne brukeren.
  • Nøyaktig én av email, phone eller username sendes.
  • currentPassword og newPassword er påkrevd.

Set-password-forespørsel

Endepunktet set-password mottar brukerens stabile katalogbinding, nøyaktig én brukeridentifikator og nytt passord.

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

Felt:

  • directoryUserId sendes og bør brukes som den stabile katalogbindingen.
  • Nøyaktig én av email, phone eller username sendes. FoxIDs velger den første tilgjengelige interne brukeridentifikatoren i denne rekkefølgen: e-post, telefon, brukernavn.
  • password er påkrevd.

Suksessrespons

Ved suksess må API-et returnere HTTP-statuskode 200 og en brukerrespons.

{
  "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 bruker responsen til å opprette eller oppdatere den interne brukeren i miljøet.

Felt:

  • directoryUserId er påkrevd. Den må være stabil og unik i det eksterne kataloget og lagres på den interne FoxIDs-brukeren.
  • email, phone og username er valgfrie hver for seg, men minst én må være til stede. FoxIDs lagrer de returnerte verdiene som den interne brukerens identifikatorer. Returnerte brukeridentifikatorverdier må entydig identifisere én bruker i det eksterne kataloget som connectoren bruker.
  • phone må inneholde landskode i internasjonalt format, for eksempel +4511223344.
  • confirmAccount styrer om FoxIDs skal kjøre en bekreftelsesflyt for å bekrefte den interne brukeren.
  • emailVerified styrer om den interne brukerens e-post merkes som verifisert.
  • phoneVerified styrer om den interne brukerens telefonnummer merkes som verifisert.
  • disableTwoFactorApp deaktiverer to-faktorautentisering med authenticator-app for den interne brukeren.
  • disableTwoFactorSms deaktiverer SMS-basert to-faktorautentisering for den interne brukeren.
  • disableTwoFactorEmail deaktiverer e-postbasert to-faktorautentisering for den interne brukeren.
  • requireMultiFactor styrer om den interne brukeren må bruke multi-faktorautentisering.
  • claims er valgfri. FoxIDs lagrer de returnerte claims på den interne brukeren.

FoxIDs ignorerer claims der type eller value mangler, er null, er tom eller bare inneholder blanktegn. Når trace-logging av meldinger er aktivert, viser svarets trace de mottatte claims før de filtreres. Lange trace-meldinger avkortes.

Feilrespons

Hvis Basic authentication avvises, returner HTTP-statuskode 401 og invalid_api_id_secret.

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

Hvis brukeren ikke finnes ved kall til endepunktet authentication uten en directoryUserId, returner HTTP-statuskode 400, 401 eller 403 og user_not_exists.

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

Hvis passordet avvises av endepunktet authentication, returner HTTP-statuskode 400, 401 eller 403 og invalid_password.

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

Hvis brukeridentifikatoren og passordet er gyldige, men påloggingen avvises av en annen grunn, skal authentication returnere HTTP-statuskode 400, 401 eller 403 og login_rejected. Dette støttes både med og uten directoryUserId. Den valgfrie uiErrorMessage vises som ren tekst i påloggingsskjemaet. API-et leverer den oversatte meldingen basert på Accept-Language.

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

Hvis uiErrorMessage utelates, er null, tom eller bare inneholder blanktegn, viser FoxIDs den samme lokaliserte generelle påloggingsmeldingen som for invalid_password, user_not_exists, user_disabled og user_deleted. En avvist pålogging teller med i den eksisterende beskyttelsen mot gjentatte mislykkede påloggingsforsøk. Den oppretter, oppdaterer, deaktiverer eller sletter ikke den interne brukeren.

Hvis det nåværende passordet avvises av endepunktet change-password, returner HTTP-statuskode 400, 401 eller 403 og invalid_current_password.

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

Feltet errorMessage er diagnostisk tekst for loggene i FoxIDs og vises ikke til sluttbrukeren. Oppgi årsaken til feilen, men ta aldri med passord, API-hemmeligheter eller private nøkler.

FoxIDs viser en returnert uiErrorMessage bare for login_rejected. For andre støttede feilkoder velger FoxIDs meldingen til brukeren fra sine egne lokaliserte tekstressurser. Diagnostisk tekst i errorMessage brukes aldri som reserve for en melding til brukeren.

Støttede feilkoder per endepunkt:

Feilkode authentication create-user change-password set-password Betydning
invalid_api_id_secret Ja Ja Ja Ja API-brukernavnet eller hemmeligheten for HTTP Basic authentication er ugyldig.
user_exists Nei Ja Nei Nei En bruker med den oppgitte identifikatoren finnes allerede i den eksterne katalogen.
user_not_exists Ja, uten directoryUserId Nei Ja, uten directoryUserId Nei Ingen bruker i den eksterne katalogen samsvarte med de oppgitte brukeridentifikatorene.
invalid_password Ja Nei Nei Nei Katalogen avviste passordet i en autentiseringsforespørsel.
login_rejected Ja Nei Nei Nei Påloggingen ble avvist etter at brukeridentifikatoren og passordet ble verifisert. En valgfri uiErrorMessage vises i påloggingsskjemaet.
invalid_current_password Nei Nei Ja Nei Katalogen avviste det gjeldende passordet i en forespørsel om passordendring.
create_user_not_supported Nei Ja Nei Nei Connectoren støtter ikke opprettelse av brukere i den eksterne katalogen.
user_disabled Ja Nei Ja Ja Brukeren finnes i katalogen, men er deaktivert. FoxIDs deaktiverer den interne brukeren.
user_deleted Ja, med directoryUserId Nei Ja, med directoryUserId Ja, med directoryUserId Brukeren i den eksterne katalogen som er koblet via directoryUserId, finnes ikke lenger eller er slettet. FoxIDs sletter den interne brukeren.
password_not_accepted Ja Ja Ja Ja Passordet som valideres, brukes ved brukeropprettelse, endres eller settes, ble avvist av en passordregel i katalogen som ikke tilsvarer en mer spesifikk kode.
password_min_length Ja Ja Ja Ja Passordet som valideres, brukes ved brukeropprettelse, endres eller settes, er kortere enn katalogens minimumslengde for passord.
password_max_length Ja Ja Ja Ja Passordet som valideres, brukes ved brukeropprettelse, endres eller settes, er lengre enn katalogens maksimumslengde for passord.
password_banned_characters Ja Ja Ja Ja Passordet som valideres, brukes ved brukeropprettelse, endres eller settes, inneholder ett eller flere tegn eller ord som katalogen avviser.
password_complexity Ja Ja Ja Ja Eldre feil for tegnkompleksitet som FoxIDs tolker som password_character_variation. Bruk en av de to spesifikke tegnfeilkodene for nye integrasjoner.
password_character_repeat Ja Ja Ja Ja Passordet som valideres, brukes ved brukeropprettelse, endres eller settes, inneholder for mange gjentakelser av tegn.
password_character_variation Ja Ja Ja Ja Passordet som valideres, brukes ved brukeropprettelse, endres eller settes, inneholder ikke tilstrekkelig tegnvariasjon.
password_email_text_complexity Ja Ja Ja Ja Passordet som valideres, brukes ved brukeropprettelse, endres eller settes, inneholder brukerens e-postadresse eller en del av den.
password_phone_text_complexity Ja Ja Ja Ja Passordet som valideres, brukes ved brukeropprettelse, endres eller settes, inneholder brukerens telefonnummer eller en del av det.
password_username_text_complexity Ja Ja Ja Ja Passordet som valideres, brukes ved brukeropprettelse, endres eller settes, inneholder brukerens brukernavn eller en del av det.
password_url_text_complexity Ja Ja Ja Ja Passordet som valideres, brukes ved brukeropprettelse, endres eller settes, inneholder tekst relatert til URL-en til FoxIDs.
password_risk Ja Ja Ja Ja Passordet som valideres, brukes ved brukeropprettelse, endres eller settes, er kjent for å være risikabelt, kompromittert eller på annen måte usikkert.
password_history Ja Ja Ja Ja Passordet som valideres, brukes ved brukeropprettelse, endres eller settes, ble avvist fordi det har vært brukt før.
password_expired Ja Ja Ja Ja Passordet som valideres, brukes ved brukeropprettelse, endres eller settes, er utløpt og må endres før autentiseringen kan fortsette.
new_password_equals_current Nei Nei Ja Nei Det nye passordet er det samme som det gjeldende. set-password kan ikke returnere denne feilen fordi endepunktet ikke mottar det gjeldende passordet.

Ved feil knyttet til passordpolicy bruker FoxIDs miljøets passordpolicy til å vise den brukerrettede feilmeldingen. Se Passordpolicy og feilmeldinger.

Returner bare en feilkode som støttes av endepunktet og den oppgitte directoryUserId, som angitt ovenfor. En kode som ikke støttes, et feilformatert svar eller en uventet HTTP-status er en integrasjonsfeil og fører til den generelle feilsiden. Returner HTTP-statuskode 500 ved en teknisk feil i connectoren. Se Feilsøking av nettleserfeil for å finne diagnostiske opplysninger ved hjelp av identifikatorene på feilsiden.

Autentiseringsfeil og brukernes personvern

En uautentisert klient skal ikke kunne avgjøre om et brukernavn eller en e-postadresse finnes, ut fra en påloggingsfeil. Ved passordautentisering håndterer FoxIDs de støttede feilene slik:

Connectorfeil Resultat for brukeren
invalid_password, user_not_exists, user_disabled eller user_deleted Den samme generelle påloggingsmeldingen, for eksempel Feil e-post eller passord., oversatt til det aktive språket og tilpasset de aktiverte påloggingsidentifikatorene.
login_rejected Den oppgitte uiErrorMessage, eller den samme generelle påloggingsmeldingen hvis den mangler eller er blank, på samme sted i påloggingsskjemaet.
password_not_accepted Siden for passordendring med generell veiledning om passordpolicy.
password_expired eller en annen spesifikk passordpolicyfeil Siden for passordendring med den tilsvarende lokaliserte veiledningen om passordpolicy.

Connectoren må kontrollere det oppgitte gjeldende passordet før den returnerer en passordpolicyfeil fra authentication. Ellers kan en annen side eller melding gjøre det mulig for en angriper å oppdage brukere og bekrefte identifikatorene deres ved å gjette brukernavn eller e-postadresser. For change-password må det gjeldende passordet kontrolleres før kontospesifikk veiledning om det nye passordet returneres. Generelle formatkontroller må ikke avsløre om en konto finnes.

Hvis en bruker av en eller annen grunn ikke får logge på gjennom denne påloggingsflyten, må den oppgitte brukeridentifikatoren og passordet først valideres. Returner en avvisning basert på denne begrensningen først etter at begge er verifisert, slik at begrensningen ikke avslører om en gjettet identifikator tilhører en reell bruker. Returner login_rejected fra authentication, oppgi den diagnostiske årsaken i errorMessage, og legg eventuelt til trygg veiledning til brukeren i uiErrorMessage. Hvis påloggingsopplysningene ikke kan verifiseres, returneres den vanlige autentiseringsfeilen uten å avsløre begrensningen.

FoxIDs er avhengig av at connectoren verifiserer påloggingsopplysningene før den returnerer login_rejected; et vellykket kontooppslag eller kjennskap til directoryUserId er ikke tilstrekkelig. Før påloggingsopplysningene er verifisert, skal eventuelle instruksjoner eller knapper for alternative påloggingsmetoder vises uavhengig av om den oppgitte identifikatoren samsvarer med en konto.

Bruk bare user_disabled og user_deleted for å rapportere den tilsvarende kontotilstanden i katalogen. De deaktiverer eller sletter også den interne brukeren og tilbakekaller brukerens tilgang; de er ikke generelle koder for å avvise pålogging.

Håndter feil konsekvent for kjente og ukjente identifikatorer, inkludert observerbare svartider og beskyttelse mot gjentatte forsøk. En generell melding alene hindrer ikke oppdagelse av brukere hvis en annen omdirigering, status eller svartid avslører resultatet. Følg OWASPs veiledning om autentiseringsfeil når connectoren implementeres.

API-eksempel

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

Eksemplet inkluderer:

  • endepunktene authentication, create-user, change-password og set-password.
  • HTTP Basic authentication med API-brukernavnet directory_connector.
  • et lite in-memory-katalog med demobrukere og stabile directoryUserId-verdier.
  • eksempler på feil i passordpolicy som password_min_length, password_banned_characters og new_password_equals_current.
  • et eksempel på en deaktivert bruker som returnerer user_disabled.

Postman-kolleksjonen directory-connector-api.postman_collection.json kan brukes til å kalle og teste eksempel-API-et med Postman.

Active Directory-komponent

FoxIDs inkluderer en Directory Connector for Active Directory-komponent som kan deployes til IIS. Komponenten implementerer Directory Connector API-et for ett AD/LDAP-domene og kan validere passord, endre passord, sette passord, returnere konfigurerte AD-attributter som claims og returnere konfigurerte nestede AD-gruppemedlemskap som claims.

Konfigurer

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

  1. Velg fanen Settings.
  2. Velg fanen Environment.
  3. Finn seksjonen Directory Connector.
  4. Aktiver Directory Connector.
  5. Legg til basis-API-URL-en uten endepunktmappen i API URL.
  6. Legg til API secret.
  7. Bestem om en lokal kopi av passordet skal lagres.
  8. Konfigurer miljøets passordpolicy slik at den samsvarer med passordpolicyen i det eksterne kataloget.
  9. Klikk Update.

Directory Connector-innstillinger