Control API – tenant Verwaltung

FoxIDs verfügt über separate Control API-Oberflächen für Bereitstellungsoperatoren, die tenants verwalten, und für einen tenant, der sein eigenes Konto verwaltet. Verwenden Sie die Operatoroperationen für die tenant Bereitstellung und die übergreifende tenant Verwaltung. Verwenden Sie die Self-Service-Vorgänge, wenn eine Integration auf ihre eigene tenant beschränkt werden soll.

Bevor Sie diese Vorgänge aufrufen, konfigurieren Sie Control API Authentifizierungs- und Zugriffsrechte. Swagger bleibt die genaue Referenz für tenant-Eigenschaften, Plan- und Zahlungsoptionen, Validierungsregeln und Antwortschemata:

API Oberflächen

Bereitstellungsbetreiber

Operatoroperationen werden in master tenant aufgerufen:

https://control.foxids.com/api/master/master
Betrieb Endpunkt Zweck
Liste GET /!tenants Listen Sie Nicht-master tenants mit optionalen Filtern und Paginierung auf.
Erhalten GET /!tenant?name={name} Lesen Sie die Verwaltungsressource eines tenant.
Erstellen POST /!tenant Stellen Sie einen tenant, einen anfänglichen Administrator und Standardressourcen bereit.
Aktualisieren PUT /!tenant Ersetzen Sie die bearbeitbaren, vom Betreiber verwalteten tenant-Eigenschaften.
Löschen DELETE /!tenant?name={name} Löschen Sie dauerhaft eine tenant- und alle tenant-Daten.

Für diese Vorgänge sind master-tenant-Zugriffsrechte erforderlich. Sie sind für die vertrauenswürdige Bereitstellungsverwaltung und SaaS Bereitstellungsdienste gedacht.

Tenant Selbstbedienung

Ein tenant ruft seine eigenen Operationen über seine master-Umgebung auf:

https://control.foxids.com/api/{tenant_name}/master
Betrieb Endpunkt Zweck
Erhalten GET /!mytenant Lesen Sie das tenant-Konto des Anrufers und die verfügbaren Einstellungen.
Aktualisieren PUT /!mytenant Aktualisieren Sie zulässige Self-Service-Eigenschaften.
Löschen DELETE /!mytenant Löschen Sie die tenant- und alle tenant-Daten des Anrufers dauerhaft.

Self-Service verwendet tenant-Zugriffsrechte und kann keine weiteren tenant verwalten. Planänderungen, Zahlungseinstellungen und benutzerdefinierte Domänen unterliegen ebenfalls den konfigurierten Richtlinien der Bereitstellung.

Ändern Sie den Host in diesen Beispielen für eine selbstgehostete Bereitstellung und senden Sie das Zugriffstoken im Authorization: Bearer {access_token}-Header.

Listen und identifizieren Sie tenants

GET /!tenants akzeptiert filterName, filterCustomDomain und paginationToken. Wenn beide Filter bereitgestellt werden, wird ein tenant zurückgegeben, wenn entweder der Name oder die benutzerdefinierte Domäne übereinstimmt. Die Datensätze master tenant und tenant, die nur für die interne Nutzung bestimmt sind, sind nicht enthalten.

Wiederholen Sie eine paginierte Anfrage mit denselben Filtern und dem zurückgegebenen undurchsichtigen Token, bis kein Token mehr zurückgegeben wird. Interpretieren oder modifizieren Sie das Token nicht.

Der Kleinbuchstabe tenant name ist die stabile Kennung, die in den URLs FoxIDs und Control API verwendet wird. Behandeln Sie es als unveränderlichen Automatisierungsschlüssel. Eine benutzerdefinierte Domäne ist eine separate Routing- und Branding-Eigenschaft und darf nicht als Name der Control API Route tenant verwendet werden.

Stellen Sie einen tenant bereit

Die Tenant-Erstellung ist ein zusammengesetzter Bereitstellungsvorgang. Eine erfolgreiche Anfrage erstellt:

  • der tenant-Datensatz;
  • die master-Umgebung des tenant und seine Standard-Anmeldeauthentifizierungsmethode;
  • der anfängliche Administratorbenutzer;
  • die Control API-Ressource und die Control Client-Anwendung;
  • die konfigurierten Standardumgebungen der Bereitstellung.

Der Erstadministrator kann ein bereitgestelltes Passwort erhalten oder über den konfigurierten E-Mail-Fluss ein Passwort festlegen. Schützen Sie alle bereitgestellten Passwörter und protokollieren Sie den Anforderungstext nicht.

Die Anfrage kann auch einen Plan auswählen und Kunden-, Anspruchs- und benutzerdefinierte Domäneneinstellungen initialisieren, sofern die Bereitstellung dies zulässt. Tenant Eindeutigkeit des Namens, Planregeln, Unterstützung benutzerdefinierter Domänen und erforderliche Administratordaten werden vor Abschluss der Bereitstellung validiert. Wenn ein Konto- oder Datenfehler die Bereitstellung unterbricht, versucht FoxIDs, die durch diese Anfrage erstellten Ressourcen zu bereinigen. Dennoch sollten Clients jeden Fehler als nicht erfolgreich behandeln und den Status überprüfen, bevor sie es mit demselben tenant-Namen erneut versuchen.

Aktualisieren Sie die tenant-Einstellungen

Bei Tenant PUT-Vorgängen handelt es sich um vollständige Updates, nicht um Patches. Rufen Sie die aktuelle Ressource ab, behalten Sie alle bearbeitbaren Eigenschaften bei, die unverändert bleiben sollen, wenden Sie die beabsichtigte Änderung an und senden Sie das vollständige Anforderungsmodell für den ausgewählten Operator oder Self-Service-Endpunkt.

Die Betreiberressource umfasst durch die Bereitstellung verwaltete Eigenschaften wie Planzuweisung, Überprüfung der benutzerdefinierten Domäne, Nutzungs- und Zahlungskonfiguration, Währung, Mehrwertsteuer, Stundenpreis und Kundendaten. Die Self-Service-Ressource stellt nur Einstellungen zur Verfügung, die tenant verwalten darf.

Wenn Sie eine benutzerdefinierte Domäne per Self-Service ändern, wird die Domäne als nicht verifiziert markiert, bis die erforderliche Verifizierung abgeschlossen ist. Der ausgewählte Plan muss eine benutzerdefinierte Domäne unterstützen. Verwenden Sie den Operator API, um den Verifizierungsstatus zu verwalten. Lassen Sie nicht zu, dass ein nicht vertrauenswürdiger tenant-Client behauptet, dass seine eigene Domäne verifiziert ist.

Löschen Sie einen tenant

Tenant Die Löschung ist unumkehrbar und erfolgt kaskadierend. Es löscht jede Umgebung in tenant und alle bereichsbezogenen Anwendungen, Authentifizierungsmethoden, Benutzer, Sitzungen, Gewährungen, Schlüssel und andere FoxIDs-Daten. Außerdem werden die Konfiguration auf tenant-Ebene und das Routing benutzerdefinierter Domänen entfernt. Die master tenant können nicht gelöscht werden. Protokolle, die bereits an ein externes Repository gesendet wurden, unterliegen weiterhin der Aufbewahrungs- und Löschrichtlinie dieses Repositorys.

Stoppen Sie vor dem Löschen den Datenverkehr, exportieren Sie Konfigurationen oder Daten, die aufbewahrt werden müssen, stornieren oder gleichen Sie gegebenenfalls die externe Abrechnung ab und überprüfen Sie den technischen Namen von tenant. Erfordern eine ausdrückliche Bestätigung in den Bedienertools. Verwenden Sie die tenant-Löschung nicht, um den Zugriff vorübergehend zu deaktivieren. Deaktivieren oder aktualisieren Sie stattdessen die relevanten Benutzer, Anwendungen oder Authentifizierungsmethoden.

Anleitung zur Automatisierung und Sicherheit

  • Bevorzugen Sie Self-Service-Endpunkte, wenn ein Client nur sein eigenes tenant verwalten muss.
  • Beschränken Sie die Anmeldeinformationen des Betreibers auf einen kleinen, vertrauenswürdigen Bereitstellungsdienst.
  • Halten Sie den technischen Namen tenant stabil und speichern Sie ihn unabhängig von Anzeige-, Kunden- und benutzerdefinierten Domänendaten.
  • Verwenden Sie get-modify-put, damit neue Eigenschaften nicht durch eine ältere Integration zurückgesetzt werden.
  • Verwenden Sie die Paginierung für tenant Inventare und gleichen Sie sie nach technischem Namen ab.
  • Behandeln Sie das Erstellen und Löschen von tenant als lang andauernde zusammengesetzte Verwaltungsaktionen. Verwenden Sie geeignete Client-Timeouts und überprüfen Sie den Endstatus nach einer unterbrochenen Antwort.
  • Erwarten Sie, dass Erstellungs-, Aktualisierungs- und Löschanforderungen im Control-Audit-Protokoll angezeigt werden. Lesevorgänge werden nicht als Audit-Ereignisse geschrieben.

Häufige Fehlerreaktionen

  • 400 Bad Request, wenn tenant, Administrator-, Plan-, Zahlungs-, Kunden- oder benutzerdefinierte Domaindaten ungültig sind.
  • 401 Unauthorized, wenn das Zugriffstoken fehlt oder ungültig ist.
  • 403 Forbidden, wenn dem Anrufer das erforderliche Zugriffsrecht master oder tenant fehlt.
  • 404 Not Found, wenn die ausgewählte tenant nicht vorhanden ist.
  • 409 Conflict, wenn bereits ein tenant-Name oder ein anderer eindeutiger Wert vorhanden ist.

Verwenden Sie den Antworttext für Validierungsdetails und Swagger UI für die von jedem Vorgang deklarierten Antworten.