Control API - Benutzer und Authenticator Apps

Verwenden Sie die FoxIDs Control API, um interne Benutzer zu provisionieren und die von jedem Benutzer registrierten Authenticator Apps zu verwalten. Dieser Guide konzentriert sich auf Operationen zur Synchronisierung von Registrierungen zwischen FoxIDs-Deployments.

Bevor Sie diese Operationen aufrufen, konfigurieren Sie Control API-Authentifizierung und Zugriffsrechte. Swagger bleibt die exakte Referenz für alle Benutzereigenschaften, Filter, Validierungsregeln und Response-Schemas:

• Swagger (OpenAPI) JSON
• Swagger UI

Endpoint-Basis

Die Beispiele verwenden FoxIDs Cloud:

https://control.foxids.com/api/{tenant_name}/{track_name}

Ersetzen Sie {tenant_name} durch den Tenant-Namen und {track_name} durch den technischen Namen der Umgebung. Ändern Sie den Host für ein self-hosted Deployment. Senden Sie das Control API-Access Token im Header Authorization: Bearer {access_token}.

Benutzer- und Authenticator-App-Operationen erfordern ein Benutzerzugriffsrecht für die Zielumgebung. Gewähren Sie über die Hierarchie der Control API-Zugriffsrechte nur die erforderliche Operation read, create, update oder delete.

Benutzerkennungen

Jeder interne Benutzer muss mindestens eine dieser Anmeldekennungen besitzen: E-Mail-Adresse, Telefonnummer oder Benutzername. E-Mail-Adressen und Benutzernamen werden in Kleinbuchstaben normalisiert; führende und nachfolgende Leerzeichen werden aus allen Kennungen entfernt.

Einzelbenutzer-Operationen identifizieren den Benutzer über den Query-Parameter email, phone oder username. Die Benutzer-Response enthält außerdem eine servergenerierte userId. Diese ID ist eindeutig und dauerhaft, auch wenn eine Anmeldekennung geändert wird, und sollte zur Zuordnung von Authenticator Apps oder anderen Ressourcen verwendet werden.

Benutzeroperationen

Operationen für einzelne Benutzer sind in Swagger unter tenant users gruppiert.

Verwenden Sie in Einzelbenutzer-Beispielen bei Bedarf phone={phone} oder username={username} statt email={email}. Hängen Sie jeden Endpoint an die Endpoint-Basis an.

Benutzer auflisten und filtern

GET /!users akzeptiert filterEmail, filterPhone, filterUsername, filterUserId und filterClaimValue. Jeder Filter führt eine Suche ohne Beachtung der Groß-/Kleinschreibung durch und findet Teilwerte. Werden mehrere Filter angegeben, wird ein Benutzer zurückgegeben, sobald ein Filter passt.

Die Response enthält eine data-Collection und ein undurchsichtiges paginationToken. Rufen Sie die nächste Seite ab, indem Sie denselben Request mit dem zurückgegebenen Wert als paginationToken wiederholen. Fahren Sie fort, bis die Response kein Token mehr enthält. Das Token darf nicht interpretiert oder verändert werden.

Die Benutzer-Response gibt an, ob ein Passwort konfiguriert ist und wann es zuletzt geändert wurde, gibt jedoch niemals das Passwort oder dessen aktuellen Hash zurück.

Benutzer erstellen

Der Create-Request unterstützt Kontostatus, verifizierte Kennungen, benutzerdefinierte Claims, Auswahl der Passwortrichtlinie, Passworteinrichtung per E-Mail oder SMS und benutzerspezifische MFA-Einstellungen. Dieser Request erstellt beispielsweise einen Benutzer ohne Passwort und verlangt die Passworteinrichtung per E-Mail:

POST https://control.foxids.com/api/{tenant_name}/{track_name}/!user
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "email": "alice@example.com",
  "emailVerified": true,
  "setPasswordEmail": true,
  "claims": [
    {
      "claim": "role",
      "values": ["employee"]
    }
  ]
}

Ein Create-Request kann ein Klartextpasswort, unterstützte Passwort-Hashfelder oder keine Passwort-Anmeldedaten enthalten. Senden Sie niemals beide Passwortformate. Klartextpasswörter werden anhand der gewählten Passwortrichtlinie geprüft; importierte Hashes werden nicht gegen die Richtlinie geprüft. Ohne Anmeldedaten können Sie setPasswordEmail oder setPasswordSms verwenden, wenn der Benutzer beim Anmelden ein Passwort einrichten soll.

Das Erstellen eines bereits vorhandenen Benutzers gibt 409 Conflict zurück; außerdem gilt das Benutzerlimit des Tenant-Plans. Eine gleichzeitige Benutzeroperation kann die Erstellung vorübergehend sperren; wiederholen Sie einen mit 423 Locked beantworteten Request nach kurzer Zeit.

Benutzer aktualisieren

PUT /!user ist eine vollständige Aktualisierung und kein Patch. Lesen Sie den aktuellen Benutzer, behalten Sie unveränderte Eigenschaften bei, wenden Sie die gewünschten Änderungen an und senden Sie die vollständige bearbeitbare Repräsentation. Die Claims-Collection sowie Konto- und MFA-Flags werden durch die Request-Werte ersetzt. Passwort-Anmeldedaten und Authenticator-App-Registrierungen werden über eigene Operationen verwaltet.

Identifizieren Sie den vorhandenen Benutzer mit email, phone oder username. Um eine Kennung zu ändern, behalten Sie deren aktuellen Wert im Feld und setzen updateEmail, updatePhone oder updateUsername auf den neuen Wert. Setzen Sie eine Update-Eigenschaft auf einen leeren String, um die Kennung zu entfernen; lassen Sie sie weg, um die Kennung unverändert zu lassen. Stellen Sie sicher, dass mindestens eine Anmeldekennung erhalten bleibt.

Wenn disableAccount von false auf true geändert wird, werden Refresh Token Grants und aktive Sitzungen des Benutzers widerrufen. Die erneute Aktivierung erlaubt neue Anmeldungen, stellt widerrufene Sitzungen jedoch nicht wieder her.

Passwörter verwalten

Verwenden Sie PUT /!usersetpassword zum administrativen Setzen oder zur Migration. Drei Modi werden unterstützt:

• Geben Sie password an, um die gewählte Passwortrichtlinie anzuwenden und die Passworthistorie zu aktualisieren.
• Geben Sie passwordHashAlgorithm, passwordHash und passwordHashSalt an, um einen unterstützten vorberechneten Hash ohne Richtlinienprüfung zu importieren.
• Lassen Sie beide Passwortformate weg, um das aktuelle Passwort des Benutzers zu entfernen.

Der optionale Wert passwordLastChanged ist Unix-Zeit in Sekunden. Mit changePassword verlangen Sie, dass der Benutzer bei der nächsten zutreffenden Anmeldung ein neues Passwort wählt.

Verwenden Sie PUT /!userchangepassword, wenn das aktuelle Passwort bekannt ist. Die Operation verifiziert das aktuelle Passwort und validiert das neue anhand der Passwortrichtlinie und -historie des Benutzers.

Der Endpoint für die Passworthistorie ist für kontrollierte Migrations- und Wiederherstellungsszenarien vorgesehen. Die Detail-Response enthält Passwort-Hashmaterial, und PUT ersetzt die vollständige Historie. Schützen Sie diese Daten wie importierte Passwort-Hashes und protokollieren Sie keine Request- oder Response-Bodies.

Massenprovisionierung

PUT /!users akzeptiert zwischen 1 und 1.000 Benutzer pro Request. Höchstens 100 Einträge dürfen Klartextpasswörter enthalten, da jedes Passwort sicher gehasht werden muss. Requests ohne Klartextpasswörter, einschließlich Requests mit unterstützten vorberechneten Hashes, dürfen bis zu 1.000 Benutzer enthalten.

Ein Massenimport erstellt neue Benutzer oder ersetzt passende Benutzer; einzelne Eigenschaften werden nicht zusammengeführt und E-Mail-, Telefon- oder Benutzernamenkennungen können nicht umbenannt werden. Behandeln Sie ihn als Ersetzungsimport. Verwenden Sie für normale Lebenszyklusänderungen die Einzelbenutzer-Aktualisierung, wenn vorhandener Benutzerstatus und dauerhafte Benutzer-ID erhalten bleiben müssen.

DELETE /!users akzeptiert zwischen 1 und 1.000 E-Mail-Adressen, Telefonnummern oder Benutzernamen in userIdentifiers. Importformate, Performancehinweise und das seed tool finden Sie unter Viele Benutzer hochladen.

Benutzer löschen und Zugriff widerrufen

Beim einzelnen oder massenhaften Löschen werden Refresh Token Grants und aktive Sitzungen des Benutzers widerrufen, bevor das Konto gelöscht wird. Dies ist eine dauerhafte Kontooperation. Verwenden Sie die Delete-Operationen für Authenticator Apps, wenn nur eine oder alle Registrierungen entfernt werden sollen und der Benutzer bestehen bleiben soll.

Requests zum Erstellen, Aktualisieren, Ändern von Passwörtern und Löschen werden im Control-Auditlog erfasst. Leseoperationen werden nicht als Audit-Events geschrieben.

Authenticator-App-Registrierungen

Authenticator-App-Operationen sind in Swagger unter tenant user authenticator apps gruppiert. Eine Listenoperation gibt sichere Registrierungsübersichten zurück, während die Detailoperation die für eine kontrollierte Synchronisierung benötigten sensiblen Daten liefert.

Hängen Sie jeden Endpoint an die Endpoint-Basis an. Beispiel:

GET https://control.foxids.com/api/{tenant_name}/{track_name}/!userauthenticatorapps?userId=e061ed17-7b44-48a8-b224-ecdb800ed5cc
Authorization: Bearer {access_token}

Registrierungsressource

Erstellen und Aktualisieren verwenden die vollständige Registrierungsressource:

{
  "userId": "e061ed17-7b44-48a8-b224-ecdb800ed5cc",
  "id": "7a772286-76a2-4f17-a0f8-4e927bb1772d",
  "createTime": 1785769200,
  "secret": "TOTP-SHARED-SECRET",
  "recoveryCode": {
    "hashAlgorithm": "P2HS512:10",
    "hash": "RECOVERY-CODE-HASH",
    "hashSalt": "RECOVERY-CODE-SALT"
  }
}

Die Eigenschaften verhalten sich wie folgt:

• userId ist die stabile FoxIDs-Benutzer-ID.
• id ist eine dauerhafte Registrierungs-ID, die der Client beim Erstellen angibt. Sie wählt beim Aktualisieren die Registrierung aus und kann nicht geändert werden.
• createTime wird in Unix-Sekunden angegeben. Beim Erstellen ist der Wert optional und standardmäßig die aktuelle Zeit. Wird er beim Aktualisieren ausgelassen, bleibt der vorhandene Wert erhalten.
• secret ist das gemeinsame TOTP-Secret und beim Erstellen und Aktualisieren erforderlich.
• recoveryCode enthält Recovery-Code-Hashdaten und wird ausgelassen, wenn kein Recovery Code konfiguriert ist.

Ein Benutzer kann höchstens fünf Authenticator-App-Registrierungen besitzen. Das Erstellen mit einer bereits vorhandenen Registrierungs-ID gibt 409 Conflict zurück; das Erstellen nach Erreichen des Limits gibt 400 Bad Request zurück.

Registrierungen synchronisieren

Ein Synchronisierungsdienst kann die interaktive Authenticator App notification API mit diesen Control API-Operationen kombinieren:

1. Empfangen Sie die Notification registered mit user_id und registration_id.
2. Rufen Sie die Registrierung mit der Detailoperation aus dem Source Deployment ab.
3. Erstellen Sie die Registrierung im Target Deployment oder aktualisieren Sie sie, wenn dieselbe Registrierungs-ID bereits vorhanden ist.

Control API-Operationen zum Erstellen, Aktualisieren und Löschen rufen die Authenticator App notification API nicht auf. Die Synchronisierung erzeugt daher keine Notification-Schleife.

Sicherheit

Die Detail-, Erstellungs- und Aktualisierungsoperationen geben ein Authenticator-App-Secret und Recovery-Code-Hashdaten aus oder nehmen diese entgegen. Gewähren Sie das erforderliche Benutzerzugriffsrecht nur vertrauenswürdigen Clients, verwenden Sie TLS, schützen Sie Payloads bei der Speicherung und protokollieren Sie keine Request- oder Response-Bodies.

Verwenden Sie die Listenoperation, wenn nur Registrierungs-IDs und Erstellungszeiten benötigt werden. Sie gibt weder das Secret noch Recovery-Code-Hashdaten zurück.

Kompatibilitätseigenschaft

Die Eigenschaft activeTwoFactorApp der allgemeinen Benutzer-API ist deprecated und soll nach dem 1. August 2027 entfernt werden. In einem Update-Request löscht false aus Kompatibilitätsgründen weiterhin alle Authenticator-App-Registrierungen; true oder ein ausgelassener Wert lässt sie unverändert. Neue Integrationen sollten die Authenticator-App-Endpoints verwenden.

Fehlerresponses

Häufige Fehlerresponses für Benutzer- und Authenticator-App-Operationen sind:

• 400 Bad Request, wenn Kennungen, Anmeldedaten, Filter oder Ressourcendaten ungültig sind oder das Registrierungslimit erreicht wurde.
• 401 Unauthorized, wenn das Access Token fehlt oder ungültig ist.
• 403 Forbidden, wenn dem Client das erforderliche Benutzerzugriffsrecht für die Umgebung fehlt.
• 404 Not Found, wenn Benutzer oder Authenticator-App-Registrierung nicht vorhanden sind.
• 409 Conflict, wenn der Benutzer bereits existiert oder eine Registrierungs-ID erneut verwendet wird.
• 423 Locked, wenn Erstellung oder Massenimport vorübergehend gesperrt sind. Wiederholen Sie die Operation nach kurzer Zeit.

Verwenden Sie den Response-Body für Validierungsdetails. Die für jede Operation deklarierten Responses finden Sie in Swagger UI.

Verwandte Dokumentation

• Control API-Authentifizierung und Zugriffsrechte
• Übersicht über FoxIDs Control
• Interne Benutzer
• Zwei-Faktor- und Multi-Faktor-Authentifizierung
• Viele Benutzer hochladen