Directory Connector

Directory Connector gör att FoxIDs kan använda en extern katalog som auktoritativ källa för interna användares lösenord och utvalda användardata.

Användarna finns fortfarande som interna användare i FoxIDs-miljön. Under lösenordsautentisering och operationer i lösenordets livscykel anropar FoxIDs Directory Connector API:et i stället för att bara validera lösenordet mot den interna FoxIDs-användaren.

Använd Directory Connector när:

  • du vill att användare ska logga in med den vanliga login-autentiseringsmetoden.
  • din externa katalog är auktoritativ för lösenordsvalidering och lösenordsändringar.
  • du vill att FoxIDs ska behålla en intern användarpost med identifierare, egenskaper, claims, MFA-inställningar, åtkomsttilldelningar och eventuellt en lokal kopia av lösenordet.
  • du vill ha en väg att senare byta till interna användare och lösenordsvalidering i FoxIDs utan att tvinga alla användare att återställa sina lösenord.

Det finns en Directory Connector per miljö. När den är aktiverad gäller den på miljönivå.

Så fungerar det

När en användare loggar in med användarnamn och lösenord anropar FoxIDs Directory Connector API:et.

Vid lyckad validering skapar eller uppdaterar FoxIDs den interna användaren i miljön baserat på API-svaret. Svaret måste innehålla ett stabilt directoryUserId, som lagras på den interna användaren och används för att knyta FoxIDs-användaren till användaren i den externa katalogen.

directoryUserId är inte en användaridentifierare som slutanvändaren känner till. Det är ett separat stabilt externt katalog-ID. Använd inte e-post, telefon eller användarnamn som directoryUserId, eftersom dessa värden kan ändras. Värdet måste vara stabilt och unikt i den externa katalogen.

Om FoxIDs redan känner till den interna användarens directoryUserId skickas det i Directory Connector-begäran tillsammans med exakt en av användarens identifierare: e-post, telefon eller användarnamn. Detta gör att den externa katalogen kan identifiera användaren även om en identifierare har ändrats.

Om Directory Connector API:et validerar användaren framgångsrikt uppdaterar FoxIDs den interna användaren med identifierare, utvalda egenskaper och claims som returneras från API:et.

Om connectorn rapporterar att användaren är inaktiverad eller borttagen kommer FoxIDs att inaktivera eller ta bort den interna användaren i miljön.

Lokal lösenordskopia

Den externa katalogen är auktoritativ så länge Directory Connector är aktiverad. FoxIDs faller inte tillbaka till den lokala lösenordshashen om Directory Connector API:et tillfälligt inte är tillgängligt.

Som standard sparar FoxIDs en lokal kopia av lösenordet på den interna användaren efter en lyckad lösenordsvalidering eller en operation i lösenordets livscykel via connectorn. Detta kan stängas av i miljöinställningarna.

Den lokala lösenordskopian används inte medan Directory Connector är aktiverad. Den finns för att stödja ett senare byte till interna användare och lösenordsvalidering i FoxIDs utan att tvinga alla användare att återställa sina lösenord.

Lösenordets livscykel

Operationer i lösenordets livscykel delegeras till Directory Connector API:et:

  • Lösenordsautentisering anropar endpointen authentication.
  • Ändring av användarens lösenord anropar endpointen change-password.
  • Flöden för att sätta lösenord och återställa lösenord anropar endpointen set-password.

FoxIDs anropar endast endpointarna för lösenordets livscykel när den interna användaren är känd och har ett directoryUserId. Detta förhindrar att FoxIDs anropar den externa katalogen utan den stabila kopplingen till den externa användaren.

FoxIDs uppdaterar inte sin interna lösenordshistorik när Directory Connector används, eftersom FoxIDs inte nödvändigtvis känner till alla lösenordsändringar i den externa katalogen.

Lösenordspolicy och felmeddelanden

Den externa katalogen upprätthåller lösenordspolicyn. FoxIDs använder miljöns lösenordspolicy när felmeddelanden om lösenordspolicy som returneras från connectorn visas.

Konfigurera miljöns lösenordspolicy så att den matchar lösenordspolicyn i den externa katalogen. Om de inte matchar kan användarna se lösenordshjälp som inte speglar de faktiska kraven i den externa katalogen.

Om den externa katalogen till exempel avvisar ett lösenord eftersom det är för kort använder FoxIDs miljöns minsta lösenordslängd när felmeddelandet visas.

Implementera API

Du implementerar ett Directory Connector API och konfigurerar FoxIDs med dess bas-URL och secret.

API:et har en bas-URL och tre endpointar:

  • authentication validerar en användares nuvarande lösenord.
  • change-password validerar det nuvarande lösenordet och ändrar det till ett nytt lösenord.
  • set-password sätter ett nytt lösenord utan att validera det nuvarande lösenordet.

Om bas-URL:en är https://somewhere.org/directory är endpointarna:

  • https://somewhere.org/directory/authentication
  • https://somewhere.org/directory/change-password
  • https://somewhere.org/directory/set-password

FoxIDs Cloud anropar ditt API från IP 57.128.60.142.
IP-adresser kan ändras eller utökas.

Säkerhet

Begäranden skyddas med HTTP Basic authentication:

  • Användarnamn: directory_connector
  • Lösenord: det konfigurerade API-secretet

Anropet är HTTP POST med en JSON-body.

Authentication-begäran

Endpointen authentication tar emot användarens lösenord och exakt en användaridentifierare. FoxIDs skickar directoryUserId om den interna användaren finns och värdet är känt.

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

Fält:

  • directoryUserId är valfritt. FoxIDs skickar det när den interna användaren finns och värdet är känt.
  • Exakt en av email, phone eller username skickas.
  • password är obligatoriskt.

FoxIDs väljer identifieraren utifrån användarens inloggningsinput och de aktiverade identifierarinställningarna. Om till exempel bara användarnamn är aktiverat och användaren skriver in user1@somewhere.org, skickar FoxIDs det värdet som username.

Change-password-begäran

Endpointen change-password tar emot användarens stabila katalogkoppling, exakt en användaridentifierare, nuvarande lösenord och nytt lösenord.

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

Fält:

  • directoryUserId skickas och bör användas som den stabila katalogkopplingen.
  • Exakt en av email, phone eller username skickas.
  • currentPassword och newPassword är obligatoriska.

Set-password-begäran

Endpointen set-password tar emot användarens stabila katalogkoppling, exakt en användaridentifierare och ett nytt lösenord.

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

Fält:

  • directoryUserId skickas och bör användas som den stabila katalogkopplingen.
  • Exakt en av email, phone eller username skickas. FoxIDs väljer den första tillgängliga interna användaridentifieraren i denna ordning: e-post, telefon, användarnamn.
  • password är obligatoriskt.

Svarsdata vid lyckat resultat

Vid lyckat resultat måste API:et returnera HTTP-statuskod 200 och ett användarsvar.

{
  "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 använder svaret för att skapa eller uppdatera den interna användaren i miljön.

Fält:

  • directoryUserId är obligatoriskt. Det måste vara stabilt och unikt i den externa katalogen och lagras på den interna FoxIDs-användaren.
  • email, phone och username är var för sig valfria, men minst ett måste finnas. FoxIDs sparar de returnerade värdena som identifierare för den interna användaren.
  • confirmAccount styr om FoxIDs ska köra ett bekräftelseflöde för att bekräfta den interna användaren.
  • emailVerified styr om den interna användarens e-post markeras som verifierad.
  • phoneVerified styr om den interna användarens telefonnummer markeras som verifierat.
  • disableAccount styr om den interna användaren inaktiveras i FoxIDs efter synkronisering.
  • disableTwoFactorApp inaktiverar tvåfaktorsautentisering med authenticator-app för den interna användaren.
  • disableTwoFactorSms inaktiverar SMS-baserad tvåfaktorsautentisering för den interna användaren.
  • disableTwoFactorEmail inaktiverar e-postbaserad tvåfaktorsautentisering för den interna användaren.
  • requireMultiFactor styr om den interna användaren måste använda multifaktorautentisering.
  • claims är valfritt. FoxIDs sparar de returnerade claims på den interna användaren.

Felsvar

Om Basic authentication avvisas, returnera HTTP-statuskod 401 och invalid_api_id_secret.

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

Om kombinationen av användarnamn och lösenord avvisas av endpointen authentication, returnera HTTP-statuskod 400, 401 eller 403 och invalid_username_password.

{
  "error": "invalid_username_password",
  "errorMessage": "Invalid username or password."
}

Om det nuvarande lösenordet avvisas av endpointen change-password, returnera HTTP-statuskod 400, 401 eller 403 och invalid_current_password.

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

Fältet errorMessage loggas av FoxIDs och visas inte för slutanvändaren.

Felmeddelandekoder som stöds:

  • invalid_username_password - Kombinationen av användaridentifierare och lösenord avvisades av katalogen.
  • invalid_current_password - Det nuvarande lösenordet i en change-password-begäran avvisades av katalogen.
  • user_disabled - Användaren finns i katalogen men är inaktiverad. FoxIDs kommer att inaktivera den interna användaren.
  • user_deleted - Användaren finns inte längre eller är borttagen i katalogen. FoxIDs kommer att ta bort den interna användaren.
  • password_not_accepted - Det nya lösenordet avvisades av en lösenordsregel i katalogen som inte kan kopplas till en mer specifik kod.
  • password_min_length - Det nya lösenordet är kortare än katalogens minimilängd för lösenord.
  • password_max_length - Det nya lösenordet är längre än katalogens maximala lösenordslängd.
  • password_banned_characters - Det nya lösenordet innehåller ett eller flera tecken eller ord som avvisas av katalogen.
  • password_complexity - Det nya lösenordet uppfyller inte katalogens krav på komplexitet.
  • password_email_text_complexity - Det nya lösenordet innehåller användarens e-post eller en del av den.
  • password_phone_text_complexity - Det nya lösenordet innehåller användarens telefonnummer eller en del av det.
  • password_username_text_complexity - Det nya lösenordet innehåller användarens användarnamn eller en del av det.
  • password_url_text_complexity - Det nya lösenordet innehåller text relaterad till FoxIDs-URL:en.
  • password_risk - Det nya lösenordet är känt som riskfyllt, komprometterat eller på annat sätt osäkert.
  • password_history - Det nya lösenordet avvisades eftersom det har använts tidigare.
  • password_expired - Det nuvarande lösenordet har gått ut och måste ändras innan autentiseringen kan fortsätta.
  • new_password_equals_current - Det nya lösenordet är samma som det nuvarande lösenordet.

Vid fel i lösenordspolicyn använder FoxIDs miljöns lösenordspolicy för att visa det användarvända felmeddelandet. Se Lösenordspolicy och felmeddelanden.

Om andra fel uppstår, returnera HTTP-statuskod 500 eller någon annan lämplig felkod. Inkludera ett tekniskt errorMessage när det är användbart för felsökning.

API-exempel

Exemplet DirectoryConnectorApiSample visar hur du implementerar Directory Connector API:et i ASP.NET Core.

Exemplet innehåller:

  • endpointarna authentication, change-password och set-password.
  • HTTP Basic authentication med API-användarnamnet directory_connector.
  • en liten in-memory-katalog med demoanvändare och stabila directoryUserId-värden.
  • exempel på fel i lösenordspolicyn som password_min_length, password_banned_characters och new_password_equals_current.
  • ett exempel på en inaktiverad användare som returnerar user_disabled.

Postman-samlingen directory-connector-api.postman_collection.json kan användas för att anropa och testa exempel-API:et med Postman.

Active Directory-komponent

FoxIDs innehåller en Active Directory Directory Connector-komponent som kan distribueras till IIS. Komponenten implementerar Directory Connector API:et för en AD/LDAP-domän och kan validera lösenord, ändra lösenord, sätta lösenord, returnera konfigurerade AD-attribut som claims och returnera konfigurerade nästlade AD-gruppmedlemskap som claims.

Konfigurera

Konfigurera Directory Connector i miljöinställningarna i FoxIDs Control Client.

  1. Välj fliken Settings.
  2. Välj fliken Environment.
  3. Leta upp avsnittet Directory Connector.
  4. Aktivera Directory Connector.
  5. Lägg till API:ets bas-URL utan endpointmappen i API URL.
  6. Lägg till API secret.
  7. Bestäm om en lokal kopia av lösenordet ska sparas.
  8. Konfigurera miljöns lösenordspolicy så att den matchar lösenordspolicyn i den externa katalogen.
  9. Klicka på Update.

Inställningar för Directory Connector

Din integritet

Din integritet

Vi använder cookies för att göra din upplevelse av våra webbplatser bättre. Klicka på 'Acceptera alla cookies' för att godkänna användningen av cookies. För att avstå från icke-nödvändiga cookies, klicka på 'Endast nödvändiga cookies'.

Besök vår integritetspolicy för mer