Control API – Umgebungen
Verwenden Sie FoxIDs Control API, um Umgebungen in einem tenant aufzulisten, zu erstellen, zu konfigurieren und zu löschen. Eine Umgebung wird in Control API-Routen und -Schemas als track bezeichnet.
Bevor Sie diese Vorgänge aufrufen, konfigurieren Sie Control API Authentifizierungs- und Zugriffsrechte. Swagger bleibt die genaue Referenz für alle Umgebungseigenschaften, Validierungsregeln und Antwortschemata:
Endpunktbasis
Die Umgebungsverwaltung erfolgt über die master-Umgebung von tenant. Die Beispiele verwenden FoxIDs Cloud:
https://control.foxids.com/api/{tenant_name}/master
Ersetzen Sie {tenant_name} durch den technischen Namen von tenant. Ändern Sie den Host für eine selbstgehostete Bereitstellung. Senden Sie das Control API-Zugriffstoken im Authorization: Bearer {access_token}-Header.
Für Umgebungsvorgänge ist das entsprechende tenant- oder Umgebungszugriffsrecht erforderlich. Die von Listenvorgängen zurückgegebenen Umgebungen sind auf diejenigen beschränkt, auf die der Aufrufer zugreifen kann. Verwenden Sie die Control API Zugriffsrechtehierarchie, um nur den erforderlichen read-, create-, update- oder delete-Vorgang zu gewähren.
Umwelteinsätze
Umgebungsvorgänge sind unter tenant tracks in Swagger gruppiert.
| Betrieb | Endpunkt | Zweck |
|---|---|---|
| Liste | GET /!tracks |
Listen Sie zugängliche Umgebungen mit optionaler Filterung und Paginierung auf. |
| Erhalten | GET /!track?name={name} |
Holen Sie sich die vollständige Konfiguration für eine Umgebung. |
| Erstellen | POST /!track |
Erstellen Sie eine Umgebung und ihre Standard-Anmeldeauthentifizierungsmethode. |
| Aktualisieren | PUT /!track |
Ersetzen Sie die bearbeitbare Umgebungskonfiguration. |
| Löschen | DELETE /!track?name={name} |
Löschen Sie eine Umgebung und ihre Daten dauerhaft. |
Hängen Sie jeden Endpunkt an die Endpunktbasis an.
Umgebungen auflisten und identifizieren
GET /!tracks akzeptiert filterName und paginationToken. Der Filter entspricht unabhängig von der Groß- und Kleinschreibung entweder dem technischen name oder dem displayName.
Die Antwort enthält eine data-Sammlung und eine undurchsichtige paginationToken. Um die nächste Seite zu lesen, wiederholen Sie dieselbe Anfrage mit dem zurückgegebenen Token und demselben Filter. Fahren Sie fort, bis die Antwort kein Token mehr enthält. Interpretieren oder modifizieren Sie das Token nicht.
Der technische name identifiziert die Umgebung in Control API URLs und in nachfolgenden Abruf-, Aktualisierungs- und Löschvorgängen. Behandeln Sie es als stabilen Automatisierungsschlüssel. Verwenden Sie displayName für Text, der Administratoren angezeigt wird.
Schaffen Sie eine Umgebung
Umgebungsnamen werden in Kleinbuchstaben geschrieben. Geben Sie einen name an, wenn eine Integration eine vorhersehbare URL erfordert, oder lassen Sie ihn weg und lassen Sie FoxIDs einen eindeutigen Namen generieren. Eine Anfrage muss entweder einen Namen oder einen Anzeigenamen enthalten.
Durch das Erstellen einer Umgebung wird auch die standardmäßige Anmeldeauthentifizierungsmethode erstellt. Andere Anwendungen, Authentifizierungsmethoden, Benutzer, Schlüssel und Umgebungsressourcen werden nach der Erstellung separat konfiguriert.
Der tenant-Plan kann die Anzahl der Umgebungen begrenzen. Eine Erstellungsanforderung kann daher fehlschlagen, wenn das Limit erreicht ist. Gleichzeitige planbeschränkte Erstellungsvorgänge können 423 Locked zurückgeben. Versuchen Sie es nach einer kurzen Verzögerung erneut.
Umgebungseinstellungen aktualisieren
PUT /!track ist ein vollständiges Update, kein Patch. Rufen Sie zunächst die aktuelle Umgebung ab, behalten Sie alle Eigenschaften bei, die unverändert bleiben sollen, wenden Sie die beabsichtigten Änderungen an und senden Sie die vollständige bearbeitbare Darstellung.
Der technische name wählt die Umgebung aus und wird durch ein Update nicht umbenannt. Zu den bearbeitbaren Einstellungen gehören die Anzeige- und Firmendetails, die Sequenzlebensdauer, das Anspruchszuordnungsverhalten, der Schutz vor Anmeldefehlern, Passwortrichtlinien, die Integration externer Passwörter und Verzeichnisse sowie zulässige Iframe-Domänen. Einige zugehörige Ressourcen, darunter SMS, E-Mail, Anspruchszuordnungen, Texte, Schlüssel und Zertifikate, verfügen über dedizierte Endpunkte und werden nicht durch den Umgebungsvorgang ersetzt.
Aktualisierte Einstellungen werden von nachfolgenden Anfragen verwendet, nachdem FoxIDs den Umgebungskonfigurationscache ungültig macht.
Löschen Sie eine Umgebung
Das Löschen einer Umgebung ist ein irreversibler, kaskadierender Vorgang. Es entfernt die Umgebungskonfiguration und alle Daten, die sich auf diese Umgebung beziehen, einschließlich ihrer Anwendungen, Authentifizierungsmethoden, Benutzer, Sitzungen, Berechtigungen, Schlüssel und anderer Ressourcen. Links von anderen Umgebungen zur gelöschten Umgebung werden ebenfalls entfernt.
Verwenden Sie das Löschen der Umgebung nicht als Möglichkeit, ausgewählte Ressourcen zu löschen. Löschen oder aktualisieren Sie diese Ressourcen einzeln, wenn die Umgebung verfügbar bleiben muss. Bevor Sie eine Umgebung löschen, stoppen Sie den Datenverkehr zu ihr, exportieren Sie alle Konfigurationen oder Daten, die beibehalten werden müssen, und überprüfen Sie den technischen Namen in der Anfrage.
Anleitung zur Automatisierung
- Halten Sie technische Namen stabil und speichern Sie sie getrennt von Anzeigenamen.
- Verwenden Sie die Listenpaginierung auch dann, wenn ein tenant derzeit nur über wenige Umgebungen verfügt.
- Verwenden Sie einen Get-Modify-Put-Workflow, um zu vermeiden, dass in einer neueren FoxIDs-Version hinzugefügte Einstellungen unbeabsichtigt zurückgesetzt werden.
- Erstellen Sie abhängige Ressourcen erst, nachdem die Anforderung zum Erstellen der Umgebung erfolgreich war.
- Behandeln Sie das Löschen als permanenten Abbauvorgang und verlangen Sie eine explizite Bestätigung in den Verwaltungstools.
- 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 die Umgebungsdaten oder der Name ungültig sind, ein reservierter Name verwendet wird oder ein Planlimit erreicht ist.401 Unauthorized, wenn das Zugriffstoken fehlt oder ungültig ist.403 Forbidden, wenn dem Anrufer das erforderliche Zugriffsrecht fehlt.404 Not Found, wenn die ausgewählte Umgebung nicht vorhanden ist.409 Conflict, wenn bereits eine Umgebung mit demselben technischen Namen vorhanden ist.423 Locked, wenn ein planbeschränkter Erstellungsvorgang vorübergehend gesperrt ist.
Verwenden Sie den Antworttext für Validierungsdetails und Swagger UI für die von jedem Vorgang deklarierten Antworten.