External Password API

Verwenden Sie eine External Password API, wenn Sie (a) die Passwortvalidierung an einen bestehenden Passwortspeicher oder eine Policy Engine delegieren, (b) ein externes System über Passwortänderungen informieren oder (c) beide Szenarien abdecken müssen.

Sie implementieren die External Password API und konfigurieren FoxIDs so, dass sie diese aufruft.

• Validation API: validiert ein Passwort (z. B. beim Login oder bevor eine Passwortänderung akzeptiert wird) und kann optional im selben Aufruf eine Passwortänderung melden.
• Notification API: informiert über eine Passwortänderung, nachdem das Passwort alle Policy Checks bestanden hat. Sie wird nur bei neuen Passwörtern (state 200) aufgerufen.

Wenn die eingebaute Password Policy das Passwort ablehnt, wird die External Password API nicht aufgerufen. Die Notification Methode der External Password API wird nur aufgerufen, wenn das Passwort alle konfigurierten Policy Checks bestanden hat und nur bei Passwortstate 200 (new password).

Wenn Sie sowohl Validierung als auch Änderungsbenachrichtigung benötigen und beides vom selben System verarbeitet werden kann, implementieren Sie nur die Validation API. Wenn Sie eine Validation Request erhalten, bei der das Passwort akzeptiert wird, führen Sie Ihre Benachrichtigungslogik intern aus. Implementieren Sie beide Endpoints nur, wenn nötig, z. B. wenn Sie zwei unterschiedliche Backend Systeme aufrufen müssen.

External Password API kann als password check für internal users 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.

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