External Password API

Verwenden Sie eine externe Passwort-API, wenn Sie FoxIDs benötigen, um (a) die Passwortvalidierung an einen bestehenden Passwortspeicher oder eine Policy-Engine zu delegieren, (b) ein externes System über in FoxIDs vorgenommene Passwortänderungen zu benachrichtigen oder (c) beide Szenarien abzudecken.

Sie implementieren die externe Passwort-API und konfigurieren FoxIDs so, dass diese aufgerufen wird.

Validierungs-API: validiert ein Passwort (z. B. bei der Anmeldung oder vor der Bestätigung einer Passwortänderung) und kann Sie optional im selben Aufruf über eine Passwortänderung benachrichtigen.
Benachrichtigungs-API: Benachrichtigt über eine Passwortänderung, nachdem das Passwort alle Richtlinienprüfungen bestanden hat. Sie wird nur bei Ereignissen mit neuem Passwort (Status 200) aufgerufen.

Wenn die integrierte Passwortrichtlinie das Passwort ablehnt, wird die externe Passwort-API nicht aufgerufen. Die Benachrichtigungsmethode der externen Passwort-API wird nur aufgerufen, wenn das Passwort alle konfigurierten Richtlinienprüfungen bestanden hat und nur dann, wenn der Passwortstatus 200 (neues Passwort) lautet.

Wenn Sie sowohl eine Validierung als auch eine Änderungsbenachrichtigung benötigen und beides von demselben System abgewickelt werden kann, implementieren Sie nur die Validierungs-API. Wenn Sie eine Validierungsanfrage erhalten, bei der das Passwort akzeptiert wird, führen Sie Ihre Benachrichtigungslogik intern aus. Implementieren Sie beide Endpunkte nur bei Bedarf, z. B. wenn Sie zwei verschiedene Backend-Systeme ansprechen müssen.

Die externe Passwort-API kann für interne Benutzer als Passwortprüfung konfiguriert werden.

API implementieren

Sie müssen eine einfache API implementieren, die FoxIDs für Validation / Notification Requests aufruft (siehe sample).

Die API hat eine Base URL; die Funktionalität ist in Ordner gruppiert: den Ordner validation (Passwort validieren) und den Ordner notification (Passwortänderungen melden).

Wenn die Base URL https://somewhere.org/mystore ist,

der Validation Endpoint ist: https://somewhere.org/mystore/validation
und der Notification Endpoint ist: https://somewhere.org/mystore/notification.

FoxIDs Cloud ruft Ihre API von IP 57.128.60.142 auf. IP(s) können sich ändern oder erweitert werden.

Request und Response sind für Validation und Notification identisch. Die Validation Methode hat einen zusätzlichen Fehlerfall, wenn das Passwort nicht akzeptiert wird.

Request

Gesichert mit HTTP Basic authentication: Benutzername external_password, Passwort ist das konfigurierte Secret.

Der Aufruf erfolgt via HTTP POST mit einem JSON Body.

Felder:

email / phone / username (optional - mindestens eines muss vorhanden sein)
password (required)
state (required) - siehe password state

Dies ist ein Request JSON Body nur mit der E-Mail als User Identifier (Validierung eines bestehenden Passworts beim Login):

{
  "email": "user1@somewhere.org",
  "password": "testpass1",
  "state": 100
}

Dies ist ein Request JSON Body mit allen drei User Identifiers (Validierung eines neuen Passworts, das gesetzt oder geändert wird):

{
  "email": "user1@somewhere.org",
  "phone": "+4011223344",
  "username": "user1",
  "password": "testpass1",
  "state": 200
}

Die User Identifiers sind optional, aber mindestens einer muss vorhanden sein. Passwort und State sind erforderlich.

Password state

Der Password State ermöglicht es, je nach Kontext unterschiedliche Logik anzuwenden.

Werte:

100 ist current password, das gesendet wird, wenn ein Benutzer beim Login ein bestehendes Passwort eingibt.
200 ist new password, das gesendet wird, wenn ein Benutzer ein neues Passwort setzt oder ändert (user creation, password change oder reset).

Response

Success Bei Erfolg sollte die API den HTTP Status Code 200 zurückgeben.

Error Die API muss den HTTP Status Code 401 (Unauthorized) und einen error (erforderlich) zurückgeben, wenn die Basic Authentication abgelehnt wird. Optional fügen Sie eine Fehlerbeschreibung in ErrorMessage hinzu.

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

Error - nur für die Validation Methode Die API muss den HTTP Status Code 400 oder 403 und einen error (erforderlich) zurückgeben, wenn das Passwort (unter Berücksichtigung des State) nicht akzeptiert wird. Optional fügen Sie eine Fehlerbeschreibung in ErrorMessage hinzu.

{
  "error": "password_not_accepted",
  "ErrorMessage": "Password not accepted."
}

Wenn andere Fehler auftreten, sollte die API den HTTP Status Code 500 oder einen anderen geeigneten Fehlercode zurückgeben. Es wird empfohlen, eine technische Fehlermeldung in ErrorMessage für die Diagnose hinzuzufügen (sie wird nur geloggt; nie dem Endbenutzer angezeigt).

API Sample

Das Sample ExternalPasswordApiSample zeigt, wie die API in ASP.NET Core implementiert wird.

Verwenden Sie die Postman Collection external-password-api.postman_collection.json, um Ihre API mit Postman aufzurufen und zu testen.

Configure

Die External Password API wird in den Environment Settings im FoxIDs Control Client konfiguriert.

Wählen Sie den Tab Settings
Und anschließend den Tab Environment
Finden Sie den Bereich External password API
Wählen Sie Validate on password change, um eine externe Password Policy zu erzwingen, bevor ein neues Passwort für einen Benutzer gesetzt wird.
Fügen Sie die Base API URL ohne die Ordner validation und notification in API URL hinzu
Fügen Sie das API secret hinzu
Klicken Sie Update