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.

Eftersom FoxIDs behåller en intern användarpost kan FoxIDs hantering av multi-factor authentication (MFA) läggas till för användare från det externa repositoriet. Connectorn kan returnera MFA-relaterade användarinställningar, till exempel requireMultiFactor och inaktiverade two-factor-metoder, och FoxIDs tillämpar inställningarna på den interna användaren medan det externa repositoriet förblir auktoritativt för lösenord och utvalda användardata.

För Active Directory innehåller FoxIDs en IIS-distribuerbar Directory Connector för Active Directory-komponent.

Använd Directory Connector när:

  • du vill att användare ska logga in med den vanliga login-autentiseringsmetoden.
  • du vill aktivera användare från en befintlig katalog för OpenID Connect- och SAML 2.0-applikationer via FoxIDs.
  • 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, multi-factor authentication (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.
  • Login create-user flow calls the create-user endpoint.
  • Ä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.

The API has a base URL and four endpoints:

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.

The API has a base URL and four endpoints:

  • authentication validerar en användares nuvarande lösenord.
  • create-user creates a new user in the external directory and returns the created user.
  • 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.

The API has a base URL and four endpoints:

  • 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 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.

Create-user request

Endpointen create-user tar emot exakt en användaridentifierare, ett obligatoriskt lösenord, valda create-user-egenskaper och claims som samlats in under FoxIDs create-user-flödet.

{
  "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 är obligatoriskt. Skapa användare utan lösenord stöds inte med Directory Connector, eftersom Directory Connector API:t autentiserar användare med lösenord.
  • 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-begäran

Endpointen change-password tar emot exakt en användaridentifierare, nuvarande lösenord och nytt lösenord. FoxIDs skickar directoryUserId när den interna användaren finns och värdet är känt.

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

Fält:

  • directoryUserId är valfritt. FoxIDs skickar det när den interna användaren finns och värdet är känt. Det kan utelämnas vid första inloggningen om den externa katalogen kräver lösenordsändring innan FoxIDs har skapat den interna användaren.
  • 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,
  "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 valfria var för sig, men minst ett måste finnas. FoxIDs sparar de returnerade värdena som identifierare för den interna användaren. Returnerade användaridentifierarvärden måste entydigt identifiera en användare i den externa katalog som connectorn använder.
  • phone måste innehålla landskod i internationellt format, till exempel +4511223344.
  • 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.
  • 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 användaren inte finns vid anrop till endpointen authentication, returnera HTTP-statuskod 400, 401 eller 403 och user_not_exists.

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

Om lösenordet avvisas av endpointen authentication, returnera HTTP-statuskod 400, 401 eller 403 och invalid_password.

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

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.

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: The API has a base URL and four endpoints:

  • 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 Directory Connector för Active Directory-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