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.

Omdat FoxIDs een intern gebruikersrecord bewaart, kan FoxIDs multi-factor-authenticatie (MFA)-afhandeling worden toegevoegd aan gebruikers uit de externe repository. De connector kan MFA-gerelateerde gebruikersinstellingen retourneren, zoals requireMultiFactor en uitgeschakelde two-factor-methoden, en FoxIDs past deze instellingen toe op de interne gebruiker terwijl de externe repository gezaghebbend blijft voor wachtwoorden en geselecteerde gebruikersgegevens.

Voor Active Directory bevat FoxIDs een op IIS deploybare Directory Connector voor Active Directory-component.

Gebruik Directory Connector wanneer:

  • gebruikers zich moeten aanmelden met de normale login-authenticatiemethode.
  • u gebruikers uit een bestaande directory wilt inschakelen voor OpenID Connect- en SAML 2.0-applicaties via FoxIDs.
  • uw externe directory gezaghebbend is voor wachtwoordvalidatie en wachtwoordwijzigingen.
  • u wilt dat FoxIDs een intern gebruikersrecord bewaart met identifiers, eigenschappen, claims, multi-factor-authenticatie (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.
  • Login create-user flow calls the create-user endpoint.
  • 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 normaal alleen endpoints voor de wachtwoordlevenscyclus aan wanneer de interne gebruiker bekend is en een directoryUserId heeft. De uitzondering is change-password tijdens de eerste aanmelding, wanneer de externe directory password_expired heeft teruggegeven voordat FoxIDs de interne gebruiker heeft aangemaakt. In dat geval verzendt FoxIDs de login-identifier en het huidige wachtwoord zonder directoryUserId; na een geslaagde wachtwoordwijziging gebruikt FoxIDs de succesvolle respons om de interne gebruiker aan te maken en de geretourneerde directoryUserId op te slaan.

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.

The API has a base URL and four endpoints:

  • authentication valideert het huidige wachtwoord van een gebruiker.
  • create-user creates a new user in the external directory and returns the created user.
  • 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/create-user
  • 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.

Create-user request

Het endpoint create-user ontvangt precies één gebruikersidentifier, een verplicht wachtwoord, geselecteerde create-user-eigenschappen en claims die tijdens de FoxIDs create-user-flow zijn verzameld.

{
  "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 is verplicht. Gebruiker aanmaken zonder wachtwoord wordt niet ondersteund met Directory Connector, omdat de Directory Connector API gebruikers met een wachtwoord authenticeert.
  • 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-aanvraag

Het change-password-endpoint ontvangt precies één gebruikersidentifier, het huidige wachtwoord en het nieuwe wachtwoord. FoxIDs verzendt directoryUserId wanneer de interne gebruiker bestaat en de waarde bekend is.

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

Velden:

  • directoryUserId is optioneel. FoxIDs verzendt deze wanneer de interne gebruiker bestaat en de waarde bekend is. Deze kan worden weggelaten tijdens de eerste aanmelding als de externe directory een wachtwoordwijziging vereist voordat FoxIDs de interne gebruiker heeft aangemaakt.
  • 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,
  "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. Geretourneerde gebruikersidentifierwaarden moeten één gebruiker uniek identificeren in de externe directory die door de connector wordt gebruikt.
  • phone moet de landcode bevatten in internationaal formaat, bijvoorbeeld +4511223344.
  • 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.
  • 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 gebruiker niet bestaat bij het aanroepen van het authentication-endpoint, retourneer dan HTTP-statuscode 400, 401 of 403 en user_not_exists.

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

Als het wachtwoord wordt afgewezen door het authentication-endpoint, retourneer dan HTTP-statuscode 400, 401 of 403 en invalid_password.

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

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.

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