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.

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.

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

Fields:

  • Exactly one of email, phone, or username is sent.
  • password er påkrevd. Opprett bruker uten passord støttes ikke med Directory Connector fordi Directory Connector API-et autentiserer brukere med passord.
  • confirmAccount and requireMultiFactor are the requested FoxIDs create-user settings.
  • claims contains the non-identifier claims collected during the FoxIDs create-user flow.

On success, return a normal success response. FoxIDs stores the returned directoryUserId on the internal user created after the external directory user has been created.

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.

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, 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 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 logges av FoxIDs og vises ikke til sluttbrukeren.

Supported error codes by endpoint:

Error code authentication create-user change-password set-password Meaning
invalid_api_id_secret Yes Yes Yes Yes The HTTP Basic API username or secret is invalid.
user_exists No Yes No No A user with the supplied identifier already exists in the external directory.
user_not_exists Yes, without DirectoryUserId No Yes, without DirectoryUserId No No external directory user matched the supplied user identifiers.
invalid_password Yes No No No The password in an authentication request was rejected by the directory.
invalid_current_password No No Yes No The current password in a change-password request was rejected by the directory.
create_user_not_supported No Yes No No The connector does not support creating users in the external directory.
user_disabled Yes No Yes Yes The user exists in the directory but is disabled. FoxIDs will disable the internal user.
user_deleted Yes, with DirectoryUserId No Yes, with DirectoryUserId Yes, with DirectoryUserId The external directory user linked by DirectoryUserId no longer exists or is deleted. FoxIDs will delete the internal user.
password_not_accepted Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set was rejected by a directory password rule that does not map to a more specific code.
password_min_length Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is shorter than the directory password minimum length.
password_max_length Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is longer than the directory password maximum length.
password_banned_characters Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains one or more characters or words rejected by the directory.
password_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set does not satisfy the directory complexity requirements.
password_email_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains the user's email or part of it.
password_phone_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains the user's phone number or part of it.
password_username_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains the user's username or part of it.
password_url_text_complexity Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set contains text related to the FoxIDs URL.
password_risk Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is known to be risky, compromised, or otherwise unsafe.
password_history Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set was rejected because it has been used before.
password_expired Yes Yes Yes Yes The password being authenticated, used for create-user, changed, or set is expired and must be changed before authentication can continue.
new_password_equals_current No No Yes No The new password is the same as the current password. set-password cannot return this error because it does not receive the current password.

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

Hvis andre feil oppstår, returner HTTP-statuskode 500 eller en annen passende feilkode. Inkluder en teknisk errorMessage når det er nyttig for diagnostikk.

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

Ditt personvern

Ditt personvern

Vi bruker cookies for å gjøre opplevelsen av nettstedene våre bedre. Klikk på 'Godta alle cookies' for å samtykke til bruk av cookies. For å reservere deg mot ikke-nødvendige cookies, klikk på 'Kun nødvendige cookies'.

Besøk vår personvernerklæring for mer