External Login - API

Mit External Login können Sie Benutzer in einer bestehenden Benutzerdatenbank über einen API-Aufruf authentifizieren. Sie implementieren die API; FoxIDs ruft sie mit Benutzername und Passwort auf, und die API validiert die Kombination und gibt Erfolg oder Fehler zurück. Verwenden Sie eine External Login Authentifizierungsmethode, wenn Sie einen bestehenden User Store als Authentifizierungsquelle in FoxIDs nutzen möchten. Nach erfolgreichem Login können Sie external users erstellen und optional einen Dialog anzeigen, um z. B. Name oder E-Mail zu erfassen.

Mit der Zeit können Sie Benutzer in FoxIDs migrieren und die externe API sowie den User Store ausphasen.

Für einen Überblick über Benutzerkonzepte (internal users, external users und external user stores) siehe users overview.

External Login unterstützt zwei Benutzerkennungen (username) Typen:

• Email - die E-Mail des Benutzers
• Text - ein frei formuliertes Username Feld

Wenn Sie den Text-Typ wählen, wird das Format in FoxIDs nicht validiert (gemischte Formate sind erlaubt, einschließlich E-Mails). Home realm discovery (HRD) basierend auf Domain ist nur mit dem Email-Typ verfügbar.

Default External Login UI mit textbasiertem Benutzernamen:

Die UI kann angepasst werden.

API implementieren

Sie müssen eine einfache API implementieren, die FoxIDs für jede Authentifizierungsanfrage aufruft (siehe sample).

Die API hat eine Base URL; die Funktionalität ist in Ordner gruppiert. Aktuell wird nur der Ordner authentication (Benutzername/Passwort validieren) unterstützt. Ordner für Passwortänderung und Benutzererstellung können später hinzugefügt werden.

Wenn die Base URL https://somewhere.org/mystore ist, lautet der Authentication Endpoint: https://somewhere.org/mystore/authentication

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

Request

Gesichert mit HTTP Basic auth: Benutzername external_login, Passwort = konfiguriertes Secret.

Der Aufruf erfolgt per HTTP POST mit einem JSON Body.

Sie können zusätzliche Parameter konfigurieren; sie werden im JSON Payload enthalten.

Email Typ Request:

{
  "usernameType": 100,
  "username": "user1@somewhere.org",
  "password": "testpass1"
}

Text Username Typ Request:

{
  "usernameType": 200,
  "username": "user1",
  "password": "testpass1"
}

Username Typ Codes:

• email = 100
• text = 200

Response

Success Bei Erfolg sollte die API den HTTP Code 200 und optional eine Liste von claims für den authentifizierten Benutzer zurückgeben.

Beispielsweise das Sub (eindeutige ID / Username), Name, E-Mail und evtl. eine Rolle:

{
  "claims": [
    { "type": "sub", "value": "somewhere/user2" },
    { "type": "given_name", "value": "Joe" },
    { "type": "family_name", "value": "Smith" },
    { "type": "email", "value": "user2@somewhere.org" },
    { "type": "role", "value": "some_access" }
  ]
}

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

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

Die API muss HTTP Code 400, 401 oder 403 und einen error (erforderlich) zurückgeben, wenn die Kombination aus Benutzername und Passwort abgelehnt wird. Optional fügen Sie eine Fehlerbeschreibung in ErrorMessage hinzu.

{
  "error": "invalid_username_password",
  "ErrorMessage": "Invalid username or password."
}

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

API Sample

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

Postman Collection external-login-api.postman_collection.json, um Ihre API mit Postman aufzurufen und zu testen.

Configure

Konfigurieren Sie eine External API Login Authentifizierungsmethode im FoxIDs Control Client.

1. Navigieren Sie zum Tab Authentication
2. Klicken Sie New authentication
3. Wählen Sie Show advanced
4. Wählen Sie External API Login
5. Fügen Sie Name hinzu
6. Wählen Sie Username type (z. B. Text)
7. Fügen Sie die Base API URL ohne den authentication Ordner in API URL hinzu
8. Fügen Sie das API secret hinzu
9. Klicken Sie Create

Optional klicken Sie Show advanced oben rechts im Konfigurationsabschnitt, um die Login UI zu customize.