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.

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.

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

Fields:

  • Exactly one of email, phone, or username is sent.
  • 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 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-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.

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

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 fejl om adgangskodepolitik bruger FoxIDs miljøets adgangskodepolitik til at vise den brugerrettede fejlmeddelelse. Se Adgangskodepolitik og fejlmeddelelser.

Hvis der opstår andre fejl, returneres HTTP-statuskode 500 eller en anden passende fejlkode. Inkluder en teknisk errorMessage, når det er nyttigt til diagnosticering.

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

Dit privatliv

Dit privatliv

Vi bruger cookies til at gøre din oplevelse på vores websites bedre. Klik på 'Acceptér alle cookies' for at acceptere brugen af cookies. For at fravælge ikke-nødvendige cookies, klik på 'Kun nødvendige cookies'.

Besøg vores privatlivspolitik for mere