Directory Connector

Met Directory Connector kan FoxIDs een externe directory gebruiken als gezaghebbende bron voor wachtwoorden van interne gebruikers en geselecteerde gebruikersgegevens.

De gebruikers bestaan nog steeds als interne gebruikers in de FoxIDs-omgeving. Tijdens wachtwoordauthenticatie en bewerkingen in de wachtwoordlevenscyclus roept FoxIDs de Directory Connector API aan in plaats van het wachtwoord alleen te valideren tegen de interne FoxIDs-gebruiker.

Gebruik Directory Connector wanneer:

  • gebruikers zich moeten aanmelden met de normale login-authenticatiemethode.
  • uw externe directory gezaghebbend is voor wachtwoordvalidatie en wachtwoordwijzigingen.
  • u wilt dat FoxIDs een intern gebruikersrecord bewaart met identifiers, eigenschappen, claims, MFA-instellingen, toegangstoewijzingen en optioneel een lokale kopie van het wachtwoord.
  • u later wilt kunnen overstappen naar interne gebruikers en wachtwoordvalidatie in FoxIDs zonder alle gebruikers door een wachtwoordreset te dwingen.

Er is één Directory Connector per omgeving. Wanneer deze is ingeschakeld, geldt deze op omgevingsniveau.

Hoe het werkt

Wanneer een gebruiker zich aanmeldt met gebruikersnaam en wachtwoord, roept FoxIDs de Directory Connector API aan.

Bij succesvolle validatie maakt FoxIDs de interne gebruiker in de omgeving aan of werkt deze bij op basis van de API-respons. De respons moet een stabiele directoryUserId bevatten, die op de interne gebruiker wordt opgeslagen en wordt gebruikt om de FoxIDs-gebruiker te koppelen aan de gebruiker in de externe directory.

De directoryUserId is geen gebruikersidentifier die bij de eindgebruiker bekend is. Het is een aparte stabiele externe directory-ID. Gebruik e-mail, telefoon of gebruikersnaam niet als directoryUserId, omdat deze waarden kunnen veranderen. De waarde moet stabiel en uniek zijn in de externe directory.

Als FoxIDs de directoryUserId van de interne gebruiker al kent, wordt deze in de Directory Connector-aanvraag meegestuurd samen met precies één van de gebruikersidentifiers: e-mail, telefoon of gebruikersnaam. Hierdoor kan de externe directory de gebruiker identificeren, zelfs als een identifier is gewijzigd.

Als de Directory Connector API de gebruiker succesvol valideert, werkt FoxIDs de interne gebruiker bij met de identifiers, geselecteerde eigenschappen en claims die door de API zijn geretourneerd.

Als de connector meldt dat de gebruiker is uitgeschakeld of verwijderd, zal FoxIDs de interne gebruiker in de omgeving uitschakelen of verwijderen.

Lokale wachtwoordkopie

De externe directory is gezaghebbend zolang Directory Connector is ingeschakeld. FoxIDs valt niet terug op de lokale wachtwoordhash als de Directory Connector API tijdelijk niet beschikbaar is.

Standaard slaat FoxIDs een lokale kopie van het wachtwoord op bij de interne gebruiker na een succesvolle wachtwoordvalidatie via de connector of na een bewerking in de wachtwoordlevenscyclus. Dit kan worden uitgeschakeld in de omgevingsinstellingen.

De lokale wachtwoordkopie wordt niet gebruikt zolang Directory Connector is ingeschakeld. Deze bestaat om later een overstap naar interne gebruikers en wachtwoordvalidatie in FoxIDs mogelijk te maken zonder alle gebruikers te dwingen hun wachtwoord te resetten.

Wachtwoordlevenscyclus

Bewerkingen in de wachtwoordlevenscyclus worden gedelegeerd aan de Directory Connector API:

  • Wachtwoordauthenticatie roept het authentication-endpoint aan.
  • Het wijzigen van het gebruikerswachtwoord roept het change-password-endpoint aan.
  • De stromen voor wachtwoord instellen en wachtwoord resetten roepen het set-password-endpoint aan.

FoxIDs roept alleen endpoints voor de wachtwoordlevenscyclus aan wanneer de interne gebruiker bekend is en een directoryUserId heeft. Dit voorkomt dat FoxIDs de externe directory aanroept zonder de stabiele koppeling met de externe gebruiker.

FoxIDs werkt zijn interne wachtwoordgeschiedenis niet bij wanneer Directory Connector wordt gebruikt, omdat FoxIDs niet noodzakelijk alle wachtwoordwijzigingen in de externe directory kent.

Wachtwoordbeleid en foutmeldingen

De externe directory handhaaft het wachtwoordbeleid. FoxIDs gebruikt het wachtwoordbeleid van de omgeving wanneer het foutmeldingen over wachtwoordbeleid weergeeft die door de connector zijn geretourneerd.

Configureer het wachtwoordbeleid van de omgeving zodat dit overeenkomt met het wachtwoordbeleid van de externe directory. Als ze niet overeenkomen, kunnen gebruikers wachtwoordhints zien die niet overeenkomen met de werkelijke vereisten van de externe directory.

Als de externe directory bijvoorbeeld een wachtwoord afwijst omdat het te kort is, gebruikt FoxIDs de minimale wachtwoordlengte van de omgeving bij het weergeven van de foutmelding.

API implementeren

U implementeert een Directory Connector API en configureert FoxIDs met de basis-URL en het secret.

De API heeft een basis-URL en drie endpoints:

  • authentication valideert het huidige wachtwoord van een gebruiker.
  • change-password valideert het huidige wachtwoord en wijzigt het naar een nieuw wachtwoord.
  • set-password stelt een nieuw wachtwoord in zonder het huidige wachtwoord te valideren.

Als de basis-URL https://somewhere.org/directory is, zijn de endpoints:

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

FoxIDs Cloud roept uw API aan vanaf IP 57.128.60.142.
IP-adressen kunnen wijzigen of worden uitgebreid.

Beveiliging

Aanvragen worden beveiligd met HTTP Basic authentication:

  • Gebruikersnaam: directory_connector
  • Wachtwoord: het geconfigureerde API-secret

De call is een HTTP POST met een JSON-body.

Authentication-aanvraag

Het authentication-endpoint ontvangt het wachtwoord van de gebruiker en precies één gebruikersidentifier. FoxIDs verzendt directoryUserId als de interne gebruiker bestaat en de waarde bekend is.

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

Velden:

  • directoryUserId is optioneel. FoxIDs verzendt deze wanneer de interne gebruiker bestaat en de waarde bekend is.
  • Precies één van email, phone of username wordt verzonden.
  • password is verplicht.

FoxIDs selecteert de identifier op basis van de login-invoer van de gebruiker en de ingeschakelde identifierinstellingen. Als bijvoorbeeld alleen gebruikersnaam is ingeschakeld en de gebruiker user1@somewhere.org invoert, verzendt FoxIDs die waarde als username.

Change-password-aanvraag

Het change-password-endpoint ontvangt de stabiele directorykoppeling van de gebruiker, precies één gebruikersidentifier, het huidige wachtwoord en het nieuwe wachtwoord.

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

Velden:

  • directoryUserId wordt verzonden en moet worden gebruikt als de stabiele directorykoppeling.
  • Precies één van email, phone of username wordt verzonden.
  • currentPassword en newPassword zijn verplicht.

Set-password-aanvraag

Het set-password-endpoint ontvangt de stabiele directorykoppeling van de gebruiker, precies één gebruikersidentifier en een nieuw wachtwoord.

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

Velden:

  • directoryUserId wordt verzonden en moet worden gebruikt als de stabiele directorykoppeling.
  • Precies één van email, phone of username wordt verzonden. FoxIDs selecteert de eerste beschikbare interne gebruikersidentifier in deze volgorde: e-mail, telefoon, gebruikersnaam.
  • password is verplicht.

Succesrespons

Bij succes moet de API HTTP-statuscode 200 en een gebruikersrespons retourneren.

{
  "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 gebruikt de respons om de interne gebruiker in de omgeving aan te maken of bij te werken.

Velden:

  • directoryUserId is verplicht. Deze moet stabiel en uniek zijn in de externe directory en wordt opgeslagen op de interne FoxIDs-gebruiker.
  • email, phone en username zijn elk afzonderlijk optioneel, maar minstens één moet aanwezig zijn. FoxIDs slaat de geretourneerde waarden op als identifiers van de interne gebruiker.
  • confirmAccount bepaalt of FoxIDs een bevestigingsstroom moet uitvoeren om de interne gebruiker te bevestigen.
  • emailVerified bepaalt of de e-mail van de interne gebruiker als geverifieerd wordt gemarkeerd.
  • phoneVerified bepaalt of het telefoonnummer van de interne gebruiker als geverifieerd wordt gemarkeerd.
  • disableAccount bepaalt of de interne gebruiker na synchronisatie in FoxIDs wordt uitgeschakeld.
  • disableTwoFactorApp schakelt twee-factor-authenticatie met een authenticator-app uit voor de interne gebruiker.
  • disableTwoFactorSms schakelt sms-twee-factor-authenticatie uit voor de interne gebruiker.
  • disableTwoFactorEmail schakelt e-mail-twee-factor-authenticatie uit voor de interne gebruiker.
  • requireMultiFactor bepaalt of de interne gebruiker multi-factor-authenticatie moet gebruiken.
  • claims is optioneel. FoxIDs slaat de geretourneerde claims op bij de interne gebruiker.

Foutrespons

Als Basic authentication wordt afgewezen, retourneer dan HTTP-statuscode 401 en invalid_api_id_secret.

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

Als de combinatie van gebruikersnaam en wachtwoord wordt afgewezen door het authentication-endpoint, retourneer dan HTTP-statuscode 400, 401 of 403 en invalid_username_password.

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

Als het huidige wachtwoord wordt afgewezen door het change-password-endpoint, retourneer dan HTTP-statuscode 400, 401 of 403 en invalid_current_password.

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

Het veld errorMessage wordt door FoxIDs gelogd en niet aan de eindgebruiker getoond.

Ondersteunde foutcodes:

  • invalid_username_password - De combinatie van gebruikersidentifier en wachtwoord is afgewezen door de directory.
  • invalid_current_password - Het huidige wachtwoord in een change-password-aanvraag is afgewezen door de directory.
  • user_disabled - De gebruiker bestaat in de directory, maar is uitgeschakeld. FoxIDs zal de interne gebruiker uitschakelen.
  • user_deleted - De gebruiker bestaat niet meer of is verwijderd uit de directory. FoxIDs zal de interne gebruiker verwijderen.
  • password_not_accepted - Het nieuwe wachtwoord is afgewezen door een wachtwoordregel van de directory die niet aan een specifiekere code kan worden gekoppeld.
  • password_min_length - Het nieuwe wachtwoord is korter dan de minimale wachtwoordlengte in de directory.
  • password_max_length - Het nieuwe wachtwoord is langer dan de maximale wachtwoordlengte in de directory.
  • password_banned_characters - Het nieuwe wachtwoord bevat een of meer tekens of woorden die door de directory worden afgewezen.
  • password_complexity - Het nieuwe wachtwoord voldoet niet aan de complexiteitseisen van de directory.
  • password_email_text_complexity - Het nieuwe wachtwoord bevat het e-mailadres van de gebruiker of een deel daarvan.
  • password_phone_text_complexity - Het nieuwe wachtwoord bevat het telefoonnummer van de gebruiker of een deel daarvan.
  • password_username_text_complexity - Het nieuwe wachtwoord bevat de gebruikersnaam van de gebruiker of een deel daarvan.
  • password_url_text_complexity - Het nieuwe wachtwoord bevat tekst die verband houdt met de FoxIDs-URL.
  • password_risk - Het nieuwe wachtwoord staat bekend als risicovol, gecompromitteerd of anderszins onveilig.
  • password_history - Het nieuwe wachtwoord is afgewezen omdat het eerder al is gebruikt.
  • password_expired - Het huidige wachtwoord is verlopen en moet worden gewijzigd voordat authenticatie kan doorgaan.
  • new_password_equals_current - Het nieuwe wachtwoord is hetzelfde als het huidige wachtwoord.

Bij fouten in het wachtwoordbeleid gebruikt FoxIDs het wachtwoordbeleid van de omgeving om de gebruikersgerichte foutmelding weer te geven. Zie Wachtwoordbeleid en foutmeldingen.

Als er andere fouten optreden, retourneer dan HTTP-statuscode 500 of een andere passende foutcode. Voeg een technische errorMessage toe wanneer dit nuttig is voor diagnose.

API-voorbeeld

Het voorbeeld DirectoryConnectorApiSample laat zien hoe u de Directory Connector API implementeert in ASP.NET Core.

Het voorbeeld bevat:

  • de endpoints authentication, change-password en set-password.
  • HTTP Basic authentication met de API-gebruikersnaam directory_connector.
  • een kleine in-memory-directory met demo-gebruikers en stabiele directoryUserId-waarden.
  • voorbeelden van fouten in wachtwoordbeleid zoals password_min_length, password_banned_characters en new_password_equals_current.
  • een voorbeeld van een uitgeschakelde gebruiker die user_disabled retourneert.

De Postman-collectie directory-connector-api.postman_collection.json kan worden gebruikt om de voorbeeld-API aan te roepen en te testen met Postman.

Active Directory-component

FoxIDs bevat een Active Directory Directory Connector-component die naar IIS kan worden gedeployed. De component implementeert de Directory Connector API voor één AD/LDAP-domein en kan wachtwoorden valideren, wachtwoorden wijzigen, wachtwoorden instellen, geconfigureerde AD-attributen als claims retourneren en geconfigureerde geneste AD-groepslidmaatschappen als claims retourneren.

Configureren

Configureer Directory Connector in de omgevingsinstellingen in FoxIDs Control Client.

  1. Selecteer het tabblad Settings.
  2. Selecteer het tabblad Environment.
  3. Zoek de sectie Directory Connector.
  4. Schakel Directory Connector in.
  5. Voeg de basis-API-URL zonder de endpointmap toe in API URL.
  6. Voeg het API secret toe.
  7. Bepaal of er een lokale wachtwoordkopie moet worden opgeslagen.
  8. Configureer het wachtwoordbeleid van de omgeving zodat dit overeenkomt met het wachtwoordbeleid van de externe directory.
  9. Klik op Update.

Instellingen voor Directory Connector

Uw privacy

Uw privacy

We gebruiken cookies om uw ervaring op onze websites te verbeteren. Klik op de knop 'Alle cookies accepteren' om akkoord te gaan met het gebruik van cookies. Om niet-noodzakelijke cookies te weigeren, klikt u op 'Alleen noodzakelijke cookies'.

Bezoek onze privacyverklaring voor meer informatie