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

FoxIDs synchronisiert bei Bedarf, sobald ein Benutzer in einem Anmelde- oder Wiederherstellungsablauf eine Kennung eingibt. Vor der Kontoprüfung ruft FoxIDs synchronise-user auf, legt bei Bedarf einen FoxIDs Benutzer an und aktualisiert die vom Verzeichnis verwalteten Kennungen, Eigenschaften und Claims.

Die Synchronisierung gehört zur Aktivierung von Directory Connector. FoxIDs synchronisiert zu Beginn von Anmeldung, Wiederherstellung und Kontoprüfungen bestehender Sitzungen sowie bei Verwendung eines Refresh Tokens für ein verzeichnisgebundenes Konto. Fortsetzungen mit Bestätigungscodes, MFA und Extended UI verwenden das ausgewählte Konto und die normalen FoxIDs Prüfungen. Eine fehlgeschlagene Synchronisierung beendet den Ablauf.

Die Antwort muss eine stabile, eindeutige directoryUserId enthalten. Verwenden Sie die permanente Konto-ID des Verzeichnisses statt E-Mail, Telefonnummer oder Benutzername. Mit dieser Bindung findet FoxIDs nach Kennungsänderungen dasselbe Konto. Registrierte Authenticator-Apps und FoxIDs Zugriffszuweisungen bleiben erhalten.

Bei Eingabe einer Kennung sendet FoxIDs ausschließlich diese E-Mail-Adresse, Telefonnummer oder diesen Benutzernamen. Bei Sitzungswiederverwendung und Refresh-Token-Anfragen lädt FoxIDs den zugehörigen Benutzer und synchronisiert anhand der dort gespeicherten Verzeichnis-ID. Auch Passwortoperationen verwenden die Verzeichnis-ID des geladenen Benutzers. Sie wird nicht zusätzlich in der Anmeldesequenz gespeichert.

Der Connector liefert den vollständigen aktuellen Benutzerdatensatz. FoxIDs ersetzt die vom Verzeichnis verwalteten Kennungen, Eigenschaften und Claims, einschließlich Kontodeaktivierung, Passwortwechselpflicht und Einstellungen zur erstmaligen Passwortvergabe. Es gelten dieselben Konto-, Wiederherstellungs- und MFA-Prüfungen wie für interne Benutzer. Ungebundene interne Benutzer werden weder synchronisiert noch automatisch verknüpft.

Eine Synchronisierungsantwort mit disableAccount: true deaktiviert den FoxIDs Benutzer und widerruft seine aktiven Sitzungen und Refresh-Token-Grants. Liefert der Connector bei der Synchronisierung anhand der Verzeichnis-ID den Fehlercode user_deleted, löscht FoxIDs den internen Benutzer und widerruft aktive Sitzungen und Refresh Tokens. Findet eine reine Kennungssuche kein Konto, prüft FoxIDs vor dem Fortfahren eine vorhandene Verzeichnisbindung, damit veraltete lokale Kontodaten keine Anmeldung oder Wiederherstellung ermöglichen. Der Fehlercode user_not_exists allein löscht kein Konto.

Refresh-Token-Anfragen prüfen sowohl das ursprüngliche Konto als auch ein im Rahmen einer Impersonation verwendetes lokales Konto, sofern sie verzeichnisgebunden sind. Erkennt die Synchronisierung ein deaktiviertes oder gelöschtes Konto, widerruft FoxIDs aktive Sitzungen und Refresh-Token-Grants und lehnt die aktuelle Token-Erneuerung ab. Die normale Prüfung aktiver Sitzungen validiert den FoxIDs Sitzungszustand; sie kontaktiert das Verzeichnis nicht selbst. Eine Anwendung, die ausgestellte Access Tokens lokal validiert, berücksichtigt deren Ablauf statt des Sitzungswiderrufs in FoxIDs.

Änderungen werden bei der nächsten bedarfsgesteuerten Kontoprüfung wirksam. Es gibt keine Hintergrundsynchronisierung.

Directory Connector eignet sich als dauerhafte Integration mit Benutzer- und Passwortverwaltung im externen Verzeichnis oder für eine schrittweise Migration zu FoxIDs. Lassen Sie den Connector während der Bereitstellung der Benutzer aktiviert und aktivieren Sie die lokale Passwortkopie, um Passwörter nach erfolgreicher Authentifizierung, Änderung oder Zurücksetzung über FoxIDs zu speichern.

Deaktivieren Sie nach abgeschlossener Migration Directory Connector und verwalten Sie Benutzer und Passwörter direkt in FoxIDs. Legen Sie vorher noch nicht bereitgestellte Benutzer an und ermöglichen Sie Benutzern ohne aktuelle lokale Passwortkopie die Passwortvergabe oder Wiederherstellung. Die Kopie entspricht der letzten erfolgreichen Passwortauthentifizierung, Änderung oder Zurücksetzung über FoxIDs; spätere Änderungen ausschließlich im externen Verzeichnis sind nicht enthalten.

Schutz vor übermäßigen Abfragen

Gibt ein Benutzer in der Anmelde- oder Wiederherstellungsoberfläche eine E-Mail-Adresse, Telefonnummer oder einen Benutzernamen ein, zählt die Verzeichnisabfrage gegen ein gemeinsames Limit aller eingegebenen Kennungen der aktuellen Anmeldesequenz. Dafür gelten die Umgebungseinstellungen Failed login attempt limit, Zählerlebensdauer und Beobachtungszeitraum. Erfolgreiche Abfragen und fehlgeschlagene Connector-Aufrufe zählen gleichermaßen; erfolgreiche Passwortauthentifizierung setzt den Zähler nicht zurück. Bei Erreichen des Limits muss der Beobachtungszeitraum abgewartet oder eine neue Anmeldesequenz gestartet werden. Synchronisierung bei Sitzungswiederverwendung und Refresh-Token-Anfragen verwendet diesen Zähler nicht. Passwort- und Bestätigungscode-Schutz verwenden weiterhin ihre bestehenden getrennten Zähler.

Anmeldekennungen und Verzeichnisbindung

Benutzer können sich mit ihrer aktuellen E-Mail-Adresse, Telefonnummer oder ihrem Benutzernamen anmelden, entsprechend den auf der Anmeldemethode aktivierten Kennungstypen. Vor der Passwortauthentifizierung muss die Eingabe einer aktuellen Kennung aus der Connector-Antwort entsprechen. FoxIDs entfernt umgebende Leerzeichen. E-Mail-Adressen und Benutzernamen werden ohne Beachtung der Groß-/Kleinschreibung verglichen. Telefonnummern verwenden das erforderliche internationale Format.

Anmeldung nach Kennungsänderungen

Bei Eingabe einer Kennung synchronisiert FoxIDs E-Mail-Adresse, Telefonnummer und Benutzername aus dem Verzeichnis. Die stabile Verzeichnis-ID verbindet den Benutzer auch nach Änderung einer oder aller Kennungen mit demselben FoxIDs Konto. Registrierte Authenticator-Apps und Zugriffszuweisungen bleiben erhalten; bestehende Zugriffsbeschränkungen und MFA-Anforderungen gelten weiterhin.

Situation Verhalten bei der Synchronisierung
Der Benutzer meldet sich mit unverändertem Benutzernamen an, während E-Mail-Adresse oder Telefonnummer im Verzeichnis geändert wurden. FoxIDs aktualisiert dasselbe Konto mit den aktuellen Kennungen aus der Connector-Antwort.
Der Benutzer meldet sich mit einer neuen, FoxIDs noch unbekannten Kennung an. Liefert das Verzeichnis die neue Kennung und dieselbe stabile Verzeichnis-ID, verwendet der Benutzer sein bestehendes FoxIDs Konto weiter. Dies gilt auch bei Änderung aller Kennungen.
Der Benutzer meldet sich mit einer alten Kennung an, die der Connector nicht mehr zurückgibt. Die Anmeldung wird mit dem normalen Anmeldefehler abgelehnt, auch wenn das Passwort noch bekannt ist. Der Benutzer muss eine aktuelle Kennung eines aktivierten Typs verwenden.
Der Connector liefert eine E-Mail-Adresse, Telefonnummer oder einen Benutzernamen nicht mehr. Diese Kennung wird bei der Synchronisierung vom FoxIDs Konto entfernt. Der Connector muss mindestens eine aktuelle Kennung liefern.

Ändert sich beispielsweise die E-Mail-Adresse von old@example.org zu new@example.org, kann der Benutzer sich mit new@example.org anmelden, bevor FoxIDs die Adresse kennt. Der Connector muss new@example.org und die unveränderte Verzeichnis-ID zurückgeben. Konto und registrierte Authenticator-Apps bleiben erhalten. Alternativ ist die Anmeldung mit einem unveränderten Benutzernamen möglich, sofern diese aktiviert ist.

Der Connector muss alle aktuellen Kennungen zurückgeben, die FoxIDs behalten soll. Fehlende oder leere Werte gelten als entfernte Kennungen; frühere Werte werden nicht als Anmeldealias beibehalten. Nur auf der Anmeldemethode aktivierte Kennungstypen können zur Anmeldung verwendet werden.

Kontokonflikte

Jeder Verzeichnisbenutzer benötigt eine stabile, eindeutige Verzeichnis-ID; seine Kennungen dürfen keinem anderen FoxIDs Konto gehören. FoxIDs sucht zunächst die eingegebene Kennung im Verzeichnis und findet oder erstellt dann anhand der gelieferten Verzeichnis-ID das lokale Konto. Führt das Speichern der Kennungen zu einem Konflikt mit einem anderen Konto, endet der Ablauf. Ein Administrator muss die Verzeichnis- oder FoxIDs Kontokonfiguration korrigieren; Konten werden nicht automatisch zusammengeführt oder neu zugeordnet.

Ein bestehender interner Benutzer ohne Verzeichnisbindung kann sich nicht über Directory Connector anmelden. Dessen Aktivierung verknüpft ein bestehendes Konto nicht allein aufgrund übereinstimmender E-Mail-Adresse, Telefonnummer oder Benutzername automatisch mit einem Verzeichnisbenutzer.

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

Die Benutzererstellung und Vorgänge im Kennwortlebenszyklus werden an die Directory Connector API delegiert:

  • Die Kennwortauthentifizierung ruft den Endpunkt authentication auf.
  • Die Benutzererstellung im Anmeldeablauf ruft den Endpunkt create-user auf.
  • Das Ändern des Benutzerkennworts ruft den Endpunkt change-password auf.
  • Set-password- und Reset-password-Abläufe rufen den Endpunkt set-password auf.

Passwortendpunkte erhalten die stabile directoryUserId des geladenen Benutzers. Das Verzeichnis prüft während der Operation Kontozustand und Anmeldedaten. Authentifizierung, Passwortänderung und Zurücksetzung liefern Erfolg oder einen Fehler. Die Benutzererstellung liefert die Verzeichnis-ID des erstellten Kontos für eine separate Synchronisierung durch FoxIDs.

Passwortoperationen verwenden die gespeicherte Verzeichnis-ID des geladenen FoxIDs Benutzers. Der Connector prüft den Kontozustand und die erforderlichen Anmeldedaten oder Zurücksetzungsberechtigung, führt die Operation aus und meldet Erfolg oder Fehler. Benutzerkennungen, Attribute und Claims werden nur durch Synchronisierung zurückgegeben.

Nach erfolgreicher Passwortänderung oder Zurücksetzung speichert FoxIDs den aktuellen Änderungszeitpunkt und entfernt Anforderungen zur Passwortänderung oder -vergabe. Wenn konfiguriert, wird auch eine lokale Passwortkopie gespeichert. Die aktive Sequenz setzt anschließend die normale Konto-, Wiederherstellungs- und MFA-Verarbeitung in FoxIDs fort.

Scheitert eine Aktion oder kann FoxIDs die bekannten Passwortänderungen nicht speichern, endet der Ablauf. Eine vom Verzeichnis bereits akzeptierte Passwortänderung wird nicht rückgängig gemacht. FoxIDs wiederholt die Aktion nach Zeitüberschreitung oder fehlgeschlagener Antwort nicht automatisch. Die nächste Synchronisierung aktualisiert das lokale Konto.

Wenn Enable password policy aktiviert ist, verifiziert FoxIDs das aktuelle Verzeichnispasswort vor den Prüfungen des neuen Passworts. Dies kann einen zusätzlichen Authentifizierungsaufruf vor change-password erfordern.

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

Passwortvergabe und Wiederherstellung

Bei der ersten Anmeldung kann ein Verzeichnisbenutzer mit einem Bestätigungscode per E-Mail oder SMS ein Passwort festlegen, weil er sein Passwort vergessen hat oder ein neues wählen muss.

Für Forgot your password? geben Benutzer eine aktuelle Verzeichniskennung eines auf der Anmeldemethode aktivierten Typs ein. FoxIDs synchronisiert und erstellt das Konto vor dem Versand des Bestätigungscodes. Wiederherstellung per E-Mail oder SMS muss aktiviert sein, und der Benutzer benötigt Zugriff auf den aktuellen Wiederherstellungskontakt aus dem Verzeichnis.

Nach Codeverifizierung und Eingabe eines neuen Passworts ruft FoxIDs set-password mit der stabilen Verzeichnis-ID auf. Geben Sie setPasswordEmail oder setPasswordSms und die entsprechende Kontaktkennung zurück, um die Passwortvergabe über diesen Ablauf zu verlangen. FoxIDs verwendet seinen normalen Passwortvergabeablauf.

Bestätigungscodes sind an das Konto gebunden, für das sie ausgestellt wurden. Über einen Verzeichnisconnector verwaltete Konten verwenden dieselbe Codeprüfung wie andere interne Benutzer. Die normale Fehlerbehandlung bei der Wiederherstellung bleibt erhalten, ohne Connector-Diagnostik offenzulegen.

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 hat eine Basis-URL und fünf Endpunkte:

  • synchronise-user sucht einen Benutzer und liefert dessen aktuellen Kontozustand, Kennungen und Claims.
  • authentication validiert das aktuelle Kennwort eines Benutzers.
  • create-user erstellt einen Benutzer im externen Verzeichnis und liefert dessen permanente Verzeichnis-ID.
  • 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/synchronise-user
  • 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.

FoxIDs sendet die gewählte Sprache im Anfrageheader Accept-Language, beispielsweise Accept-Language: da-DK. Im Anmeldeablauf folgt dies der Auswahl durch ui_locales oder den Browser; Englisch ist die Rückfallsprache von FoxIDs. Die API kann den Header zur Lokalisierung von Benutzermeldungen verwenden und muss bei nicht unterstützter Sprache eine eigene Rückfallsprache wählen. Der Header wird an alle fünf Endpunkte gesendet.

Synchronisierungsanfrage

Der Endpunkt synchronise-user erhält entweder eine Benutzerkennung oder eine bekannte Verzeichnis-ID. Die erste Abfrage bei Anmeldung oder Wiederherstellung verwendet die eingegebene Kennung. FoxIDs verwendet die gespeicherte directoryUserId für Prüfungen bestehender Sitzungen und Refresh-Token-Anfragen sowie die zurückgegebene Verzeichnis-ID nach create-user.

Eine erste Abfrage mit E-Mail-Adresse:

{
  "email": "user1@somewhere.org"
}

Eine spätere Kontoprüfung:

{
  "directoryUserId": "a1b2c3d4"
}

Verwenden Sie eine vorhandene directoryUserId als maßgeblichen Suchschlüssel. Andernfalls suchen Sie genau eine Kennung aus email, phone oder username. Geben Sie HTTP 200 mit dem vollständigen Benutzerdatensatz zurück, auch für deaktivierte Konten. Verwenden Sie den Fehlercode user_deleted, wenn die bekannte ID fehlt, und user_not_exists, wenn eine reine Kennungssuche kein Konto findet. Eine übermittelte Kennung ist niemals ein Nachweis der Kontoinhaberschaft.

FoxIDs wählt die Anfragekennung anhand der aktivierten Anmeldekennungen. Ist nur Benutzername aktiviert, wird eine Eingabe im E-Mail-Format als username gesendet. Umgebende Leerzeichen werden entfernt. Die Eingabe muss einer aktuellen Antwortkennung eines aktivierten Typs entsprechen; das angenommene Anfragefeld schränkt mögliche Übereinstimmungen mit Antwortfeldern nicht ein.

Zu Fehlern siehe Fehlerantwort.

Erfolgreiche Antwort

Der Endpunkt synchronise-user liefert HTTP 200 mit einem vollständigen aktuellen Benutzerdatensatz. Enthält die Anfrage eine Verzeichnis-ID, muss die Antwort dieselbe ID enthalten. FoxIDs prüft dies vor dem Speichern. HTTP 204 oder ein unvollständiger Datensatz werden abgelehnt.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "phone": "+4511223344",
  "username": "user1",
  "confirmAccount": true,
  "disableAccount": false,
  "changePassword": false,
  "setPasswordEmail": false,
  "setPasswordSms": false,
  "disableSetPasswordEmail": false,
  "disableSetPasswordSms": false,
  "passwordLastChanged": 1760000000,
  "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.
  • disableAccount steuert die direkte Kontodeaktivierung. Ein Wechsel zu deaktiviert widerruft FoxIDs Sitzungen und Refresh-Token-Grants des Benutzers.
  • changePassword verlangt nach erfolgreicher Verifizierung der Anmeldedaten einen Passwortwechsel.
  • setPasswordEmail und setPasswordSms verlangen eine Passwortvergabe über den jeweiligen Bestätigungscode-Ablauf. Kontaktkennung und aktivierte Wiederherstellungsmethode sind erforderlich.
  • disableSetPasswordEmail und disableSetPasswordSms deaktivieren die entsprechenden Wiederherstellungsmethoden.
  • passwordLastChanged ist ein optionaler, nicht negativer Unix-Zeitstempel in Sekunden. Bei Angabe durch die Synchronisierung aktualisiert er das Passwortalter in FoxIDs. Ohne Angabe bleibt ein vorhandener Zeitstempel erhalten. Eine erfolgreiche Passwortänderung oder Zurücksetzung speichert die aktuelle Zeit in FoxIDs; eine spätere Synchronisierung kann den maßgeblichen Verzeichniszeitstempel liefern.
  • 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.

FoxIDs ignoriert Claims, deren type oder value fehlt, null oder leer ist oder nur aus Leerraum besteht. Bei aktiviertem Meldungs-Trace enthält der Antwort-Trace die empfangenen Claims vor der Filterung. Lange Trace-Meldungen werden gekürzt.

Geschützte Claims, etwa sid und auth_time, werden ebenfalls aus Synchronisierungsantworten entfernt.

Authentifizierungsanfrage

Der Endpunkt authentication erhält die erforderliche stabile Verzeichnis-ID und das aktuelle Passwort.

{
  "directoryUserId": "a1b2c3d4",
  "password": "testpass1"
}

Prüfen Sie den aktuellen Verzeichniskontozustand und das Passwort, bevor Sie Erfolg melden. Verifizieren Sie das Passwort vor kontospezifischen Hinweisen zur Passwortrichtlinie.

Zu Fehlern siehe Fehlerantwort.

Erfolgreiche Antwort

Bei Erfolg geben Sie HTTP 204 ohne Antwortinhalt zurück.

Anfrage zur Benutzererstellung

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" }
  ]
}

Felder:

  • Genau eine von email, phone oder username wird gesendet.
  • 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 und requireMultiFactor sind die angeforderten Einstellungen für die Benutzererstellung in FoxIDs.
  • claims enthält die bei der Benutzererstellung in FoxIDs erfassten Claims, die keine Benutzerkennungen sind.

Zu Fehlern siehe Fehlerantwort.

Erfolgreiche Antwort

Bei Erfolg geben Sie HTTP 200 mit der permanenten Verzeichnis-ID des erstellten Kontos zurück:

{
  "directoryUserId": "a1b2c3d4"
}

FoxIDs ruft anschließend synchronise-user mit dieser ID auf, um das vollständige Konto abzurufen und den internen FoxIDs Benutzer anzulegen.

Change-password-Anfrage

Der Endpunkt change-password erhält die erforderliche Verzeichnis-ID, das aktuelle und das neue Passwort. Verifizieren Sie das aktuelle Passwort vor kontospezifischen Richtlinienhinweisen.

{
  "directoryUserId": "a1b2c3d4",
  "currentPassword": "oldpass1",
  "newPassword": "newpass1"
}

Zu Fehlern siehe Fehlerantwort.

Erfolgreiche Antwort

Bei Erfolg geben Sie HTTP 204 ohne Antwortinhalt zurück. Die Passwortänderung muss die Passwortanforderung im Verzeichnis erfüllen.

Set-password-Anfrage

Der Endpunkt set-password erhält die erforderliche Verzeichnis-ID und das neue Passwort. FoxIDs ruft ihn nach Autorisierung der Zurücksetzung oder Vergabe auf, einschließlich Codeprüfung bei Wiederherstellung. Der Connector muss den aktuellen Kontozustand vor der Änderung erneut prüfen.

{
  "directoryUserId": "a1b2c3d4",
  "password": "newpass1"
}

Zu Fehlern siehe Fehlerantwort.

Erfolgreiche Antwort

Bei Erfolg geben Sie HTTP 204 ohne Antwortinhalt zurück. Die Zurücksetzung oder Vergabe muss die Passwortanforderung im Verzeichnis erfüllen.

Fehlerantwort

Alle Endpunkte verwenden dasselbe JSON-Fehlerformat. Geben Sie einen vom Endpunkt unterstützten Fehlercode in error und Diagnosedetails in errorMessage zurück. Beispiel für ein von authentication abgelehntes Passwort:

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

Verwenden Sie folgende HTTP-Statuscodes:

  • 401 mit dem Fehlercode invalid_api_id_secret bei abgelehnter HTTP Basic-Authentifizierung.
  • 400, 401 oder 403 für andere unterstützte Fehlercodes der folgenden Endpunkttabelle.
  • 500 für einen technischen Connector-Fehler.

Das Feld errorMessage enthält Diagnosetext für die Protokolle von FoxIDs und wird dem Endbenutzer nicht angezeigt. Geben Sie den Grund für den Fehler an, aber niemals Kennwörter, API-Geheimnisse oder private Schlüssel.

Nur der Endpunkt authentication darf den Fehlercode login_rejected nach Verifizierung von Benutzerkennung und Passwort liefern. Optional kann er uiErrorMessage enthalten, das FoxIDs als Klartext im Anmeldeformular anzeigt. Die API liefert die Meldung in der über Accept-Language gewählten Sprache:

{
  "error": "login_rejected",
  "errorMessage": "Credentials verified; login rejected by directory policy.",
  "uiErrorMessage": "You cannot log in here. Contact support."
}

Fehlt uiErrorMessage, ist es null, leer oder besteht nur aus Leerzeichen, zeigt FoxIDs dieselbe lokalisierte allgemeine Anmeldemeldung wie bei invalid_password und operation_rejected. Bei anderen unterstützten Fehlercodes ignoriert FoxIDs uiErrorMessage und wählt die Meldung aus seinen eigenen lokalisierten Texten. Diagnostischer errorMessage-Text wird niemals als Ersatz für eine Benutzermeldung verwendet. Verifizierungsanforderungen stehen unter Authentifizierungsfehler und Datenschutz.

Fehler aus authentication, change-password und set-password liefern keine Benutzerdaten, ändern kein internes Konto und widerrufen keine bestehenden Sitzungen oder Refresh Tokens. Verzeichniskontoänderungen erfolgen durch Synchronisierung. Abgelehnte Authentifizierungs- und Passwortänderungsversuche zählen weiterhin gegen das bestehende Limit fehlgeschlagener Anmeldungen.

Unterstützte Fehlercodes nach Endpunkt:

Fehlercode synchronise-user authentication create-user change-password set-password Bedeutung
invalid_api_id_secret Ja Ja Ja Ja Ja Der API-Benutzername oder das Geheimnis für HTTP Basic authentication ist ungültig.
user_exists Nein Nein Ja Nein Nein Ein Benutzer mit der angegebenen Kennung existiert bereits im externen Verzeichnis.
user_not_exists Ohne Verzeichnis-ID Nein Nein Nein Nein Die reine Kennungssuche fand keinen passenden Verzeichnisbenutzer.
invalid_password Nein Ja Nein Nein Nein Das Verzeichnis hat das Kennwort in einer Authentifizierungsanfrage abgelehnt.
login_rejected Nein Ja Nein Nein Nein Die Anmeldung wurde nach Prüfung der Benutzerkennung und des Kennworts abgelehnt. Eine optionale uiErrorMessage wird im Anmeldeformular angezeigt.
invalid_current_password Nein Nein Nein Ja Nein Das Verzeichnis hat das aktuelle Kennwort in einer Anfrage zur Kennwortänderung abgelehnt.
create_user_not_supported Nein Nein Ja Nein Nein Der Connector unterstützt das Erstellen von Benutzern im externen Verzeichnis nicht.
operation_rejected Nein Ja Nein Ja Ja Die Operation kann nicht abgeschlossen werden, etwa weil das Konto nicht verfügbar ist. FoxIDs protokolliert errorMessage, ignoriert uiErrorMessage und zeigt einen allgemeinen lokalisierten Fehler ohne Änderung des Kontozustands.
user_deleted Mit Verzeichnis-ID Nein Nein Nein Nein Eine bekannte Verzeichnis-ID existiert nicht mehr. FoxIDs widerruft den Zugriff und löscht den Benutzer bei der Synchronisierung.
password_not_accepted Nein Ja Ja Ja Ja Das Kennwort, das zur Authentifizierung oder Benutzererstellung verwendet, geändert oder gesetzt wird, wurde durch eine Kennwortregel des Verzeichnisses abgelehnt, der kein spezifischerer Code entspricht.
password_min_length Nein Ja Ja Ja Ja Das Kennwort, das zur Authentifizierung oder Benutzererstellung verwendet, geändert oder gesetzt wird, ist kürzer als die im Verzeichnis festgelegte Mindestlänge für Kennwörter.
password_max_length Nein Ja Ja Ja Ja Das Kennwort, das zur Authentifizierung oder Benutzererstellung verwendet, geändert oder gesetzt wird, ist länger als die im Verzeichnis festgelegte Höchstlänge für Kennwörter.
password_banned_characters Nein Ja Ja Ja Ja Das Kennwort, das zur Authentifizierung oder Benutzererstellung verwendet, geändert oder gesetzt wird, enthält ein oder mehrere Zeichen oder Wörter, die das Verzeichnis ablehnt.
password_complexity Nein Ja Ja Ja Ja Älterer Fehler zur Zeichenkomplexität, den FoxIDs als password_character_variation interpretiert. Verwenden Sie für neue Integrationen einen der beiden spezifischen Zeichenfehlercodes.
password_character_repeat Nein Ja Ja Ja Ja Das Kennwort, das zur Authentifizierung oder Benutzererstellung verwendet, geändert oder gesetzt wird, enthält zu viele Zeichenwiederholungen.
password_character_variation Nein Ja Ja Ja Ja Das Kennwort, das zur Authentifizierung oder Benutzererstellung verwendet, geändert oder gesetzt wird, enthält nicht genügend unterschiedliche Zeichen.
password_email_text_complexity Nein Ja Ja Ja Ja Das Kennwort, das zur Authentifizierung oder Benutzererstellung verwendet, geändert oder gesetzt wird, enthält die E-Mail-Adresse des Benutzers oder einen Teil davon.
password_phone_text_complexity Nein Ja Ja Ja Ja Das Kennwort, das zur Authentifizierung oder Benutzererstellung verwendet, geändert oder gesetzt wird, enthält die Telefonnummer des Benutzers oder einen Teil davon.
password_username_text_complexity Nein Ja Ja Ja Ja Das Kennwort, das zur Authentifizierung oder Benutzererstellung verwendet, geändert oder gesetzt wird, enthält den Benutzernamen des Benutzers oder einen Teil davon.
password_url_text_complexity Nein Ja Ja Ja Ja Das Kennwort, das zur Authentifizierung oder Benutzererstellung verwendet, geändert oder gesetzt wird, enthält Text mit Bezug zur URL von FoxIDs.
password_risk Nein Ja Ja Ja Ja Das Kennwort, das zur Authentifizierung oder Benutzererstellung verwendet, geändert oder gesetzt wird, ist bekanntermaßen riskant, kompromittiert oder anderweitig unsicher.
password_history Nein Nein Nein Ja Ja Das neue Passwort wurde abgelehnt, weil es bereits verwendet wurde.
password_expired Nein Ja Nein Nein Nein Das übermittelte Passwort wurde verifiziert, ist aber abgelaufen; der Benutzer muss es ändern, bevor die Authentifizierung fortgesetzt werden kann.
new_password_equals_current Nein Nein Nein Ja Nein Das neue Kennwort ist mit dem aktuellen identisch. set-password kann diesen Fehler nicht zurückgeben, da der Endpunkt das aktuelle Kennwort nicht erhält.

Muss FoxIDs vor einem Passwortwechsel seine eigene Richtlinie prüfen, ruft es zunächst authentication zur Verifizierung des aktuellen Passworts auf. Liefert der Connector dabei password_expired, kann der Wechsel fortgesetzt werden. Der Endpunkt change-password muss selbst ein verifiziertes abgelaufenes aktuelles Passwort akzeptieren und nur für die Änderungsoperation unterstützte Fehler liefern.

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

Geben Sie nur Fehlercodes zurück, die laut obiger Tabelle für Endpunkt und angegebene directoryUserId zulässig sind. Ein nicht unterstützter Code, eine fehlerhafte Antwort oder ein unerwarteter HTTP-Status gilt als Integrationsfehler und führt zur allgemeinen Fehlerseite. Unter Browserfehler beheben erfahren Sie, wie Sie Diagnosedetails anhand der Kennungen auf der Fehlerseite finden.

Authentifizierungsfehler und Datenschutz

Ein nicht authentifizierter Aufrufer darf aus einem Anmeldefehler nicht ableiten können, ob ein Benutzername oder eine E-Mail-Adresse existiert. Bei der Kennwortauthentifizierung behandelt FoxIDs die unterstützten Fehler wie folgt:

Connectorfehler Ergebnis für den Benutzer
invalid_password, operation_rejected oder ein bei der Synchronisierung als nicht verfügbar erkanntes Konto Dieselbe allgemeine Anmeldemeldung, beispielsweise Falsche E-Mail oder falsches Passwort., übersetzt in die aktive Sprache und angepasst an die aktivierten Anmeldekennungen.
login_rejected Die übermittelte uiErrorMessage oder, wenn sie fehlt oder leer ist, dieselbe allgemeine Anmeldemeldung an derselben Stelle im Anmeldeformular.
password_not_accepted Die Seite zur Kennwortänderung mit allgemeinen Hinweisen zur Kennwortrichtlinie.
password_expired oder ein anderer spezifischer Kennwortrichtlinienfehler Die Seite zur Kennwortänderung mit den entsprechenden lokalisierten Hinweisen zur Kennwortrichtlinie.

Der Connector muss das übermittelte aktuelle Kennwort prüfen, bevor er einen Kennwortrichtlinienfehler von authentication zurückgibt. Andernfalls kann eine andere Seite oder Meldung einem Angreifer ermöglichen, Benutzer zu entdecken und ihre Kennungen durch Erraten von Benutzernamen oder E-Mail-Adressen zu bestätigen. Prüfen Sie bei change-password das aktuelle Kennwort, bevor Sie kontospezifische Hinweise zum neuen Kennwort zurückgeben. Allgemeine Formatprüfungen dürfen nicht offenlegen, ob ein Konto existiert.

Darf ein Benutzer aus irgendeinem Grund diesen Anmeldeablauf nicht verwenden, prüfen Sie zuerst die übermittelte Benutzerkennung und das Passwort. Lehnen Sie aufgrund dieser Beschränkung erst nach erfolgreicher Verifizierung beider Angaben ab, damit die Beschränkung nicht verrät, ob eine erratene Kennung zu einem echten Benutzer gehört. Liefern Sie login_rejected aus authentication, den diagnostischen Grund in errorMessage und optional sichere Benutzerhinweise in uiErrorMessage. Lassen sich die Anmeldedaten nicht verifizieren, geben Sie den normalen Authentifizierungsfehler zurück, ohne die Beschränkung offenzulegen.

FoxIDs vertraut darauf, dass der Connector die Anmeldedaten vor Rückgabe von login_rejected verifiziert; eine erfolgreiche Kontosuche oder Kenntnis der directoryUserId genügt nicht. Vor der Verifizierung müssen Hinweise oder Schaltflächen für alternative Anmeldemethoden unabhängig davon angezeigt werden, ob die eingegebene Kennung zu einem Konto passt.

Nur synchronise-user meldet den Kontozustand: vollständiger Datensatz mit disableAccount: true für deaktivierte Konten oder Fehlercode user_deleted, wenn eine bekannte Verzeichnis-ID nicht mehr existiert. Passwortendpunkte liefern operation_rejected, falls das Konto nicht verfügbar ist. Anders als login_rejected erfordert dieser Fehler kein verifiziertes Passwort, da er dem Browser keine kontospezifischen Hinweise liefert.

Behandeln Sie Fehler bei bekannten und unbekannten Kennungen einheitlich, einschließlich beobachtbarer Antwortzeiten und des Schutzes vor wiederholten Versuchen. Eine allgemeine Meldung allein verhindert die Entdeckung von Benutzern nicht, wenn eine andere Weiterleitung, ein anderer Status oder eine andere Antwortzeit das Ergebnis offenlegt. Beachten Sie bei der Implementierung des Connectors die Hinweise von OWASP zu Authentifizierungsfehlern.

API-Beispiel

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

Implementierungen und Testclients müssen die obigen Endpunktverträge einhalten: HTTP 200 mit vollständigem Benutzerdatensatz für synchronise-user, HTTP 200 mit erstellter Verzeichnis-ID für create-user und HTTP 204 ohne Inhalt für erfolgreiche Passwortoperationen.

Active Directory-Komponente

FoxIDs enthält eine unter IIS bereitstellbare Komponente Directory Connector für Active Directory. Sie implementiert die Directory Connector API für eine AD/LDAP-Domäne und kann Konten synchronisieren, Passwörter validieren, ändern und setzen sowie konfigurierte AD-Attribute und verschachtelte AD-Gruppenmitgliedschaften als Claims liefern.

Konfiguration

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

  1. Wählen Sie die Registerkarte Einstellungen.
  2. Wählen Sie die Registerkarte Umgebung.
  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