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.

Brug Directory Connector når:

  • Du vil have, at brugere logger ind med den normale login autentificeringsmetode.
  • Dit eksterne katalog er autoritativt for adgangskodevalidering og ændring af adgangskoder.
  • Du vil have, at FoxIDs bevarer en intern brugerpost med identifikatorer, egenskaber, claims, 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.
  • Ændring af brugerens adgangskode kalder change-password endpointet.
  • Set-password- og reset-password-flows kalder set-password endpointet.

FoxIDs kalder kun endpointene for adgangskodens livscyklus, når den interne bruger er kendt og har en directoryUserId. Dette forhindrer FoxIDs i at kalde det eksterne katalog uden den stabile binding til den eksterne bruger.

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.

API'et har en base-URL og tre endpoints:

  • authentication validerer brugerens nuværende adgangskode.
  • 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/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.

Change-password-anmodning

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

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

Felter:

  • directoryUserId sendes og bør bruges som den stabile katalogbinding.
  • 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,
  "disableAccount": false,
  "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.
  • 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.
  • disableAccount styrer, om den interne bruger deaktiveres i FoxIDs efter synkronisering.
  • 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 kombinationen af brugernavn og adgangskode afvises af authentication endpointet, returneres HTTP-statuskode 400, 401 eller 403 og invalid_username_password.

{
  "error": "invalid_username_password",
  "errorMessage": "Invalid username or 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.

Understøttede fejlkoder:

  • invalid_username_password - Kombinationen af brugeridentifikator og adgangskode blev afvist af kataloget.
  • invalid_current_password - Den nuværende adgangskode i en change-password-anmodning blev afvist af kataloget.
  • user_disabled - Brugeren findes i kataloget, men er deaktiveret. FoxIDs vil deaktivere den interne bruger.
  • user_deleted - Brugeren findes ikke længere eller er slettet i kataloget. FoxIDs vil slette den interne bruger.
  • password_not_accepted - Den nye adgangskode blev afvist af en katalogregel for adgangskoder, som ikke matcher en mere specifik kode.
  • password_min_length - Den nye adgangskode er kortere end katalogets minimumslængde for adgangskoder.
  • password_max_length - Den nye adgangskode er længere end katalogets maksimumslængde for adgangskoder.
  • password_banned_characters - Den nye adgangskode indeholder et eller flere tegn eller ord, som kataloget afviser.
  • password_complexity - Den nye adgangskode opfylder ikke katalogets krav til kompleksitet.
  • password_email_text_complexity - Den nye adgangskode indeholder brugerens e-mail eller en del af den.
  • password_phone_text_complexity - Den nye adgangskode indeholder brugerens telefonnummer eller en del af det.
  • password_username_text_complexity - Den nye adgangskode indeholder brugerens brugernavn eller en del af det.
  • password_url_text_complexity - Den nye adgangskode indeholder tekst, der er relateret til FoxIDs-URL'en.
  • password_risk - Den nye adgangskode er kendt som risikabel, kompromitteret eller på anden måde usikker.
  • password_history - Den nye adgangskode blev afvist, fordi den er blevet brugt før.
  • password_expired - Den nuværende adgangskode er udløbet og skal ændres, før autentificeringen kan fortsætte.
  • new_password_equals_current - Den nye adgangskode er den samme som den nuværende adgangskode.

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, 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 Active Directory Directory Connector-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