Directory Connector

Directory Connector ermöglicht es FoxIDs, ein externes Verzeichnis als autoritative Quelle für die Kennwörter interner Benutzer und ausgewählte Benutzerdaten zu verwenden.

Die Benutzer existieren weiterhin als interne Benutzer in der FoxIDs-Umgebung. Während der Kennwortauthentifizierung und bei Vorgängen im Kennwortlebenszyklus ruft FoxIDs die Directory Connector API auf, anstatt das Kennwort nur gegen den internen FoxIDs-Benutzer zu validieren.

Da FoxIDs einen internen Benutzerdatensatz beibehält, kann FoxIDs-Multi-Faktor-Authentifizierung (MFA) für Benutzer aus dem externen Repository ergänzt werden. Der Connector kann MFA-bezogene Benutzereinstellungen zurückgeben, z. B. requireMultiFactor und deaktivierte Zwei-Faktor-Methoden, und FoxIDs wendet diese Einstellungen auf den internen Benutzer an, während das externe Repository für Kennwörter und ausgewählte Benutzerdaten autoritativ bleibt.

Für Active Directory enthält FoxIDs eine in IIS bereitstellbare Directory Connector für Active Directory-Komponente.

Verwenden Sie Directory Connector, wenn:

  • sich Benutzer mit der normalen login-Authentifizierungsmethode anmelden sollen.
  • Sie Benutzer aus einem vorhandenen Verzeichnis für OpenID Connect- und SAML 2.0-Anwendungen über FoxIDs aktivieren möchten.
  • Ihr externes Verzeichnis für die Kennwortvalidierung und Kennwortänderungen autoritativ ist.
  • FoxIDs einen internen Benutzerdatensatz mit Kennungen, Eigenschaften, Claims, Multi-Faktor-Authentifizierung (MFA)-Einstellungen, Zugriffszuweisungen und optional einer lokalen Kennwortkopie beibehalten soll.
  • Sie später auf interne Benutzer und Kennwortvalidierung in FoxIDs umstellen möchten, ohne alle Benutzer zu einem Kennwort-Reset zu zwingen.

Es gibt einen Directory Connector pro Umgebung. Wenn er aktiviert ist, gilt er auf Umgebungsebene.

So funktioniert es

Wenn sich ein Benutzer mit Benutzername und Kennwort anmeldet, ruft FoxIDs die Directory Connector API auf.

Bei erfolgreicher Validierung erstellt oder aktualisiert FoxIDs den internen Benutzer in der Umgebung auf Grundlage der API-Antwort. Die Antwort muss eine stabile directoryUserId enthalten, die auf dem internen Benutzer gespeichert wird und zur Bindung des FoxIDs-Benutzers an den Benutzer im externen Verzeichnis dient.

Die directoryUserId ist keine Benutzerkennung, die dem Endbenutzer bekannt ist. Es handelt sich um eine separate stabile externe Verzeichnis-ID. Verwenden Sie E-Mail, Telefonnummer oder Benutzername nicht als directoryUserId, da sich diese Werte ändern können. Der Wert muss im externen Verzeichnis stabil und eindeutig sein.

Wenn FoxIDs die directoryUserId des internen Benutzers bereits kennt, wird sie zusammen mit genau einer der Kennungen E-Mail, Telefonnummer oder Benutzername des Benutzers in der Directory Connector-Anfrage gesendet. Dadurch kann das externe Verzeichnis den Benutzer auch dann identifizieren, wenn sich eine Kennung geändert hat.

Wenn die Directory Connector API den Benutzer erfolgreich validiert, aktualisiert FoxIDs den internen Benutzer mit den von der API zurückgegebenen Kennungen, ausgewählten Eigenschaften und Claims.

Wenn der Connector meldet, dass der Benutzer deaktiviert oder gelöscht ist, deaktiviert oder löscht FoxIDs den internen Benutzer in der Umgebung.

Lokale Kennwortkopie

Das externe Verzeichnis ist autoritativ, solange Directory Connector aktiviert ist. FoxIDs greift nicht auf den lokalen Kennworthash zurück, wenn die Directory Connector API vorübergehend nicht verfügbar ist.

Standardmäßig speichert FoxIDs nach einer erfolgreichen Kennwortvalidierung oder einem Kennwortlebenszyklusvorgang über den Connector eine lokale Kennwortkopie auf dem internen Benutzer. Dies kann in den Umgebungseinstellungen deaktiviert werden.

Die lokale Kennwortkopie wird nicht verwendet, solange Directory Connector aktiviert ist. Sie dient dazu, später auf interne Benutzer und Kennwortvalidierung in FoxIDs umzustellen, ohne alle Benutzer zu einem Kennwort-Reset zu zwingen.

Kennwortlebenszyklus

Vorgänge des Kennwortlebenszyklus werden an die Directory Connector API delegiert:

  • Die Kennwortauthentifizierung ruft den Endpunkt authentication auf.
  • Login create-user flow calls the create-user endpoint.
  • Das Ändern des Benutzerkennworts ruft den Endpunkt change-password auf.
  • Set-password- und Reset-password-Abläufe rufen den Endpunkt set-password auf.

The API has a base URL and four endpoints:

FoxIDs aktualisiert seinen internen Kennwortverlauf nicht, wenn Directory Connector verwendet wird, da FoxIDs nicht unbedingt alle Kennwortänderungen im externen Verzeichnis kennt.

Kennwortrichtlinie und Fehlermeldungen

Das externe Verzeichnis erzwingt die Kennwortrichtlinie. FoxIDs verwendet die Kennwortrichtlinie der Umgebung, wenn Kennwortrichtlinien-Fehlermeldungen angezeigt werden, die vom Connector zurückgegeben wurden.

Konfigurieren Sie die Kennwortrichtlinie der Umgebung so, dass sie der Kennwortrichtlinie des externen Verzeichnisses entspricht. Wenn sie nicht übereinstimmen, können Benutzer Kennworthinweise sehen, die nicht den tatsächlichen Anforderungen des externen Verzeichnisses entsprechen.

Wenn das externe Verzeichnis beispielsweise ein Kennwort zurückweist, weil es zu kurz ist, verwendet FoxIDs beim Anzeigen der Fehlermeldung die Mindestlänge des Kennworts aus der Umgebung.

API implementieren

Sie implementieren eine Directory Connector API und konfigurieren FoxIDs mit deren Basis-URL und Secret.

The API has a base URL and four endpoints:

  • authentication validiert das aktuelle Kennwort eines Benutzers.
  • create-user creates a new user in the external directory and returns the created user.
  • change-password validiert das aktuelle Kennwort und ändert es in ein neues Kennwort.
  • set-password setzt ein neues Kennwort, ohne das aktuelle Kennwort zu validieren.

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 ruft Ihre API von IP 57.128.60.142 auf.
IP(s) können sich ändern oder erweitert werden.

Sicherheit

Anfragen werden mit HTTP Basic authentication abgesichert:

  • Benutzername: directory_connector
  • Kennwort: das konfigurierte API-Secret

Der Aufruf erfolgt per HTTP POST mit einem JSON-Body.

Authentifizierungsanfrage

Der Endpunkt authentication empfängt das Kennwort des Benutzers und genau eine Benutzerkennung. FoxIDs sendet directoryUserId, wenn der interne Benutzer existiert und der Wert bekannt ist.

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

Felder:

  • directoryUserId ist optional. FoxIDs sendet sie, wenn der interne Benutzer existiert und der Wert bekannt ist.
  • Genau eine von email, phone oder username wird gesendet.
  • password ist erforderlich.

FoxIDs wählt die Kennung aus der Login-Eingabe des Benutzers und den aktivierten Kennungseinstellungen. Wenn zum Beispiel nur der Benutzername aktiviert ist und der Benutzer user1@somewhere.org eingibt, sendet FoxIDs diesen Wert als username.

Create-user request

Der Endpunkt create-user erhält genau eine Benutzerkennung, ein erforderliches Kennwort, ausgewählte create-user-Eigenschaften und Claims, die während des FoxIDs create-user-Ablaufs erfasst wurden.

{
  "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 ist erforderlich. Benutzer erstellen ohne Kennwort wird mit Directory Connector nicht unterstützt, da die Directory Connector API Benutzer mit einem Kennwort authentifiziert.
  • 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-Anfrage

Der Endpunkt change-password empfängt genau eine Benutzerkennung, das aktuelle Kennwort und das neue Kennwort. FoxIDs sendet directoryUserId, wenn der interne Benutzer existiert und der Wert bekannt ist.

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

Felder:

  • directoryUserId ist optional. FoxIDs sendet sie, wenn der interne Benutzer existiert und der Wert bekannt ist. Sie kann beim ersten Login weggelassen werden, wenn das externe Verzeichnis eine Kennwortänderung verlangt, bevor FoxIDs den internen Benutzer erstellt hat.
  • Genau eine von email, phone oder username wird gesendet.
  • currentPassword und newPassword sind erforderlich.

Set-password-Anfrage

Der Endpunkt set-password empfängt die stabile Verzeichnisbindung des Benutzers, genau eine Benutzerkennung und ein neues Kennwort.

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

Felder:

  • directoryUserId wird gesendet und sollte als stabile Verzeichnisbindung verwendet werden.
  • Genau eine von email, phone oder username wird gesendet. FoxIDs wählt die erste verfügbare interne Benutzerkennung in dieser Reihenfolge: E-Mail, Telefonnummer, Benutzername.
  • password ist erforderlich.

Erfolgsantwort

Bei Erfolg muss die API den HTTP-Statuscode 200 und eine Benutzerantwort zurückgeben.

{
  "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 verwendet die Antwort, um den internen Benutzer in der Umgebung zu erstellen oder zu aktualisieren.

Felder:

  • directoryUserId ist erforderlich. Sie muss im externen Verzeichnis stabil und eindeutig sein und wird auf dem internen FoxIDs-Benutzer gespeichert.
  • email, phone und username sind einzeln optional, aber mindestens eines muss vorhanden sein. FoxIDs speichert die zurückgegebenen Werte als Kennungen des internen Benutzers. Zurückgegebene Benutzerkennungswerte müssen genau einen Benutzer im externen Verzeichnis identifizieren, das der Connector verwendet.
  • phone muss die Landesvorwahl im internationalen Format enthalten, z. B. +4511223344.
  • confirmAccount steuert, ob FoxIDs einen Bestätigungsablauf für den internen Benutzer ausführen soll.
  • emailVerified steuert, ob die E-Mail des internen Benutzers als verifiziert markiert wird.
  • phoneVerified steuert, ob die Telefonnummer des internen Benutzers als verifiziert markiert wird.
  • disableTwoFactorApp deaktiviert die Zwei-Faktor-Authentifizierung per Authenticator-App für den internen Benutzer.
  • disableTwoFactorSms deaktiviert die SMS-Zwei-Faktor-Authentifizierung für den internen Benutzer.
  • disableTwoFactorEmail deaktiviert die E-Mail-Zwei-Faktor-Authentifizierung für den internen Benutzer.
  • requireMultiFactor steuert, ob der interne Benutzer Multi-Faktor-Authentifizierung verwenden muss.
  • claims ist optional. FoxIDs speichert die zurückgegebenen Claims auf dem internen Benutzer.

Fehlerantwort

Wenn die Basic Authentication abgelehnt wird, geben Sie den HTTP-Statuscode 401 und invalid_api_id_secret zurück.

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

Wenn der Benutzer beim Aufruf des Endpunkts authentication nicht existiert, geben Sie den HTTP-Statuscode 400, 401 oder 403 und user_not_exists zurück.

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

Wenn das Kennwort vom Endpunkt authentication abgelehnt wird, geben Sie den HTTP-Statuscode 400, 401 oder 403 und invalid_password zurück.

{
  "error": "invalid_password",
  "errorMessage": "Invalid password."
}

Wenn das aktuelle Kennwort vom Endpunkt change-password abgelehnt wird, geben Sie den HTTP-Statuscode 400, 401 oder 403 und invalid_current_password zurück.

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

Das Feld errorMessage wird von FoxIDs protokolliert und dem Endbenutzer nicht angezeigt.

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.

Bei Kennwortrichtlinienfehlern verwendet FoxIDs die Kennwortrichtlinie der Umgebung, um die benutzerseitige Fehlermeldung anzuzeigen. Siehe Kennwortrichtlinie und Fehlermeldungen.

Wenn andere Fehler auftreten, geben Sie den HTTP-Statuscode 500 oder einen anderen geeigneten Fehlercode zurück. Fügen Sie bei Bedarf eine technische errorMessage zur Diagnose hinzu.

API-Beispiel

Das Beispiel DirectoryConnectorApiSample zeigt, wie die Directory Connector API in ASP.NET Core implementiert wird.

Das Beispiel enthält: The API has a base URL and four endpoints:

  • HTTP Basic Authentication mit dem API-Benutzernamen directory_connector.
  • ein kleines In-Memory-Verzeichnis mit Demo-Benutzern und stabilen directoryUserId-Werten.
  • Beispiele für Kennwortrichtlinienfehler wie password_min_length, password_banned_characters und new_password_equals_current.
  • ein Beispiel für einen deaktivierten Benutzer, das user_disabled zurückgibt.

Die Postman-Collection directory-connector-api.postman_collection.json kann verwendet werden, um die Beispiel-API mit Postman aufzurufen und zu testen.

Active Directory-Komponente

FoxIDs enthält eine Directory Connector für Active Directory-Komponente, die in IIS bereitgestellt werden kann. Die Komponente implementiert die Directory Connector API für eine AD/LDAP-Domäne und kann Kennwörter validieren, Kennwörter ändern, Kennwörter setzen, konfigurierte AD-Attribute als Claims zurückgeben und konfigurierte verschachtelte AD-Gruppenmitgliedschaften als Claims zurückgeben.

Konfiguration

Konfigurieren Sie Directory Connector in den Umgebungseinstellungen im FoxIDs Control Client.

  1. Wählen Sie die Registerkarte Settings.
  2. Wählen Sie die Registerkarte Environment.
  3. Suchen Sie den Abschnitt Directory Connector.
  4. Aktivieren Sie Directory Connector.
  5. Fügen Sie die Basis-API-URL ohne den Endpunktordner in API URL hinzu.
  6. Fügen Sie das API secret hinzu.
  7. Entscheiden Sie, ob eine lokale Kennwortkopie gespeichert werden soll.
  8. Konfigurieren Sie die Kennwortrichtlinie der Umgebung so, dass sie der Kennwortrichtlinie des externen Verzeichnisses entspricht.
  9. Klicken Sie auf Update.

Directory Connector Einstellungen

Ihre Privatsphäre

Ihre Privatsphäre

Wir verwenden Cookies, um Ihre Erfahrung auf unseren Websites zu verbessern. Klicken Sie auf 'Alle Cookies akzeptieren', um der Verwendung von Cookies zuzustimmen. Um nicht notwendige Cookies abzulehnen, klicken Sie auf 'Nur notwendige Cookies'.

Weitere Informationen finden Sie in unserer Datenschutzerklärung