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.

Verwenden Sie Directory Connector, wenn:

  • sich Benutzer mit der normalen login-Authentifizierungsmethode anmelden sollen.
  • Ihr externes Verzeichnis für die Kennwortvalidierung und Kennwortänderungen autoritativ ist.
  • FoxIDs einen internen Benutzerdatensatz mit Kennungen, Eigenschaften, Claims, 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.
  • Das Ändern des Benutzerkennworts ruft den Endpunkt change-password auf.
  • Set-password- und Reset-password-Abläufe rufen den Endpunkt set-password auf.

FoxIDs ruft Endpunkte des Kennwortlebenszyklus nur auf, wenn der interne Benutzer bekannt ist und eine directoryUserId besitzt. Dadurch wird verhindert, dass FoxIDs das externe Verzeichnis ohne die stabile Bindung an den externen Benutzer aufruft.

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.

Die API verfügt über eine Basis-URL und drei Endpunkte:

  • authentication validiert das aktuelle Kennwort eines Benutzers.
  • 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.

Wenn die Basis-URL https://somewhere.org/directory lautet, sind die Endpunkte:

  • https://somewhere.org/directory/authentication
  • 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.

Change-password-Anfrage

Der Endpunkt change-password empfängt die stabile Verzeichnisbindung des Benutzers, genau eine Benutzerkennung, das aktuelle Kennwort und das neue Kennwort.

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

Felder:

  • directoryUserId wird gesendet und sollte als stabile Verzeichnisbindung verwendet werden.
  • 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,
  "disableAccount": false,
  "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 jeweils optional, aber mindestens einer dieser Werte muss vorhanden sein. FoxIDs speichert die zurückgegebenen Werte als Kennungen des internen Benutzers.
  • 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.
  • disableAccount steuert, ob der interne Benutzer nach der Synchronisierung in FoxIDs deaktiviert 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 die Kombination aus Benutzername und Kennwort vom Endpunkt authentication abgelehnt wird, geben Sie den HTTP-Statuscode 400, 401 oder 403 und invalid_username_password zurück.

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

Unterstützte Fehlercodes:

  • invalid_username_password - Die Kombination aus Benutzerkennung und Kennwort wurde vom Verzeichnis zurückgewiesen.
  • invalid_current_password - Das aktuelle Kennwort in einer Change-password-Anfrage wurde vom Verzeichnis zurückgewiesen.
  • user_disabled - Der Benutzer existiert im Verzeichnis, ist aber deaktiviert. FoxIDs deaktiviert den internen Benutzer.
  • user_deleted - Der Benutzer existiert nicht mehr oder ist im Verzeichnis gelöscht. FoxIDs löscht den internen Benutzer.
  • password_not_accepted - Das neue Kennwort wurde durch eine Kennwortregel des Verzeichnisses abgelehnt, die keinem spezifischeren Code zugeordnet werden kann.
  • password_min_length - Das neue Kennwort ist kürzer als die Mindestlänge des Kennworts im Verzeichnis.
  • password_max_length - Das neue Kennwort ist länger als die maximale Kennwortlänge des Verzeichnisses.
  • password_banned_characters - Das neue Kennwort enthält ein oder mehrere Zeichen oder Wörter, die vom Verzeichnis abgelehnt werden.
  • password_complexity - Das neue Kennwort erfüllt nicht die Komplexitätsanforderungen des Verzeichnisses.
  • password_email_text_complexity - Das neue Kennwort enthält die E-Mail des Benutzers oder einen Teil davon.
  • password_phone_text_complexity - Das neue Kennwort enthält die Telefonnummer des Benutzers oder einen Teil davon.
  • password_username_text_complexity - Das neue Kennwort enthält den Benutzernamen des Benutzers oder einen Teil davon.
  • password_url_text_complexity - Das neue Kennwort enthält Text mit Bezug auf die FoxIDs-URL.
  • password_risk - Das neue Kennwort ist als riskant, kompromittiert oder anderweitig unsicher bekannt.
  • password_history - Das neue Kennwort wurde abgelehnt, weil es bereits zuvor verwendet wurde.
  • password_expired - Das aktuelle Kennwort ist abgelaufen und muss geändert werden, bevor die Authentifizierung fortgesetzt werden kann.
  • new_password_equals_current - Das neue Kennwort ist identisch mit dem aktuellen Kennwort.

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:

  • die Endpunkte authentication, change-password und set-password.
  • 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 Active Directory Directory Connector-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