Control API – Anwendungen und Authentifizierungsmethoden

Verwenden Sie FoxIDs Control API, um die Anwendungen zu konfigurieren, die FoxIDs vertrauen, und die Authentifizierungsmethoden, denen FoxIDs vertraut. In Control API-Routen und -Schemas wird eine Anwendungsregistrierung als downparty und eine Authentifizierungsmethode als upparty bezeichnet.

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

Endpunktbasis und Zugriffsrechte

Die Beispiele verwenden FoxIDs Cloud:

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

Ersetzen Sie {tenant_name} und {track_name} durch die technischen Namen tenant und der Umgebung. Ändern Sie den Host für eine selbstgehostete Bereitstellung. Senden Sie das Control API-Zugriffstoken im Authorization: Bearer {access_token}-Header.

Für diese Vorgänge ist ein party-Zugriffsrecht für die Zielumgebung erforderlich. Gewähren Sie nur den erforderlichen read-, create-, update- oder delete-Vorgang über die Control API Zugriffsrechtehierarchie.

Registrierungen auflisten und identifizieren

Verwenden Sie diese Endpunkte, um Registrierungen zu erkennen, bevor Sie einen typspezifischen Endpunkt aufrufen:

Ressource Endpunkt Filter
Anwendungen GET /!downparties filterName, paginationToken
Authentifizierungsmethoden GET /!upparties filterName, filterHrdDomains, paginationToken

Die Listenantworten enthalten sichere Zusammenfassungen, den Registrierungstyp und ein undurchsichtiges Paginierungstoken. Verwenden Sie die typspezifische Get-Operation für die vollständige bearbeitbare Darstellung. Wiederholen Sie eine paginierte Anfrage mit denselben Filtern und dem zurückgegebenen Token, bis kein Token mehr zurückgegeben wird.

Der technische name ist der stabile Bezeichner, der von Abruf-, Aktualisierungs-, Lösch-, Geheim-, Schlüssel- und Beziehungsvorgängen verwendet wird. Namen werden in Kleinbuchstaben geschrieben. Geben Sie beim Erstellen einen Namen an, wenn eine Integration eine vorhersehbare Kennung erfordert, oder lassen Sie FoxIDs eine generieren. Verwenden Sie den !newpartyname-Helfer, wenn ein eindeutiger Name benötigt wird, bevor eine Ressource erstellt wird.

Typspezifische Operationen

Jeder Ressourcentyp hat seinen eigenen Endpunkt, da die Protokollkonfiguration unterschiedlich ist. Die wichtigsten Endpunkte sind:

Ressourcentyp Anwendungsendpunkt Endpunkt der Authentifizierungsmethode
OpenID Connect !oidcdownparty !oidcupparty
OAuth 2.0 !oauthdownparty !oauthupparty
SAML 2.0 !samldownparty !samlupparty
WS-Federation !wsfeddownparty !wsfedupparty
Environment Link !tracklinkdownparty !tracklinkupparty
Login Nicht anwendbar !loginupparty
External Login Nicht anwendbar !externalloginupparty

Die üblichen Vorgänge sind GET ?name={name}, POST zum Erstellen, PUT zum Aktualisieren und DELETE ?name={name}. Hängen Sie den Endpunkt an die Endpunktbasis an. Informationen zu den von den einzelnen Typen unterstützten Vorgängen finden Sie unter Swagger.

Das Erstellen von Anwendungen oder Authentifizierungsmethoden unterliegt den Einschränkungen der Umgebung und des tenant-Plans. Einige gleichzeitige, planbeschränkte Erstellungsvorgänge können 423 Locked zurückgeben. Versuchen Sie es nach einer kurzen Verzögerung erneut.

Sicher aktualisieren und umbenennen

Bei den Vorgängen der Partei PUT handelt es sich um vollständige Updates, nicht um Patches. Verwenden Sie diesen Workflow:

  1. Listen Sie die Ressourcen auf oder rufen Sie die bekannte Ressource anhand des technischen Namens ab.
  2. Erhalten Sie die vollständige typspezifische Darstellung.
  3. Behalten Sie Eigenschaften bei, die unverändert bleiben sollen, und übernehmen Sie die beabsichtigten Änderungen.
  4. Senden Sie die vollständige bearbeitbare Darstellung an den passenden typspezifischen PUT-Endpunkt.

Verwenden Sie newName, wenn der technische Name geändert werden muss. Referenzen werden im Rahmen des Umbenennungsablaufs aktualisiert. Die standardmäßige Anmeldeauthentifizierungsmethode namens login kann nicht umbenannt oder gelöscht werden.

Client-Geheimnisse, Client-Schlüssel und einige externe API-Geheimnisse werden von dedizierten Endpunkten verwaltet. Sie werden in der allgemeinen Parteidarstellung bewusst nicht als Klartext zurückgegeben und sollten nicht in eine normale Update-Anfrage kopiert werden.

Verbinden Sie Anwendungen mit Authentifizierungsmethoden

Die allowUpParties-Sammlung einer Anwendung steuert, welche Authentifizierungsmethoden für die Anmeldung bei dieser Anwendung verwendet werden können. Die referenzierten Authentifizierungsmethoden müssen in derselben Umgebung vorhanden und mit der Konfiguration kompatibel sein.

Behandeln Sie diese Beziehung beim Aktualisieren als Teil der vollständigen Konfiguration der Anwendung. Durch das Löschen einer Authentifizierungsmethode kann sich das Anmelderouting für Anwendungen ändern, die darauf verweisen. Überprüfen Sie abhängige Anwendungen vor dem Löschen. Verwenden Sie eine Environment Link, wenn die Authentifizierungsmethode oder Anwendung absichtlich über FoxIDs-Umgebungen hinweg verbunden ist.

Geheimnisse und Schlüssel verwalten

Die Anwendungen OAuth 2.0 und OpenID Connect stellen dedizierte Client-Secret-Vorgänge bereit. Ein Geheimnis wird bei der Erstellung akzeptiert, als Hash gespeichert und nicht im Klartext zurückgegeben. Die Listenantwort enthält die Bezeichner und sicheren Informationen, die zur Verwaltung vorhandener Geheimnisse erforderlich sind.

Verwenden Sie überlappende Anmeldeinformationen für die Rotation:

  1. Generieren Sie ein neues Client-Geheimnis und speichern Sie es sicher.
  2. Erstellen Sie das Client-Geheimnis in FoxIDs und stellen Sie denselben Wert für die nutzende Anwendung bereit.
  3. Stellen Sie sicher, dass die Anwendung das neue Geheimnis verwendet.
  4. Löschen Sie das alte Geheimnis anhand seiner Anwendungs- und Geheimkennungen.

Die Authentifizierungsmethoden OpenID Connect und OAuth 2.0 können abhängig von der ausgewählten Clientauthentifizierungsmethode dedizierte Client-Secret- oder Client-Key-Vorgänge verwenden. Eine Private-Key-Operation akzeptiert Zertifikate und Private-Key-Material. External Login verfügt über einen dedizierten geheimen Endpunkt. Verwenden Sie für den ausgewählten Registrierungstyp genau den in Swagger gezeigten Endpunkt und das Anforderungsschema.

Geheimnisse, private Schlüssel und vollständige Zertifikatsnutzlasten sind vertraulich. Verwenden Sie TLS, gewähren Sie nur vertrauenswürdigen Automatisierungsclients Zugriff, schützen Sie ruhende Werte und protokollieren Sie keine Anforderungs- oder Antworttexte.

Metadaten- und Erkennungshelfer

Protokollhilfsvorgänge reduzieren die manuelle Konfiguration, ersetzen jedoch nicht die Validierung der resultierenden Ressource:

  • Die Authentifizierungsmethoden OpenID Connect und OAuth 2.0 können Erkennungsmetadaten lesen und kompatible Einstellungen füllen.
  • SAML 2.0 Anwendungsregistrierungen und Authentifizierungsmethoden können Metadaten lesen.
  • WS-Federation Anwendungsregistrierungen und Authentifizierungsmethoden können Metadaten lesen.
  • Zu den WS-Federation-Authentifizierungsmethoden gehört ein Microsoft Entra ID-Synchronisierungsassistent.

Überprüfen Sie nach Verwendung eines Hilfsprogramms die zurückgegebene Konfiguration, wenden Sie lokale Richtlinien- und Anspruchseinstellungen an und speichern Sie sie über den typspezifischen Erstellungs- oder Aktualisierungsendpunkt. Metadaten können sich im Laufe der Zeit ändern. Definieren Sie daher, ob die Synchronisierung eine explizite Verwaltungsaktion oder ein kontrollierter, wiederkehrender Prozess ist.

Lösch- und Abhängigkeitseffekte

Durch das Löschen einer Anwendung werden neue Protokollanforderungen für diese Anwendung gestoppt. Das Löschen einer Authentifizierungsmethode kann dazu führen, dass Anwendungen die Anmeldung nicht abschließen können, und kann die Home Realm Discovery-Auswahl ändern. Entfernen oder aktualisieren Sie zunächst Abhängigkeiten und behandeln Sie beide Vorgänge als dauerhafte Konfigurationsänderungen.

Erstellungs-, Aktualisierungs-, Geheim-/Schlüssel-, Hilfs- und Löschanforderungen sind im Control-Audit-Protokoll enthalten. Lesevorgänge werden nicht als Audit-Ereignisse geschrieben.

Häufige Fehlerreaktionen

  • 400 Bad Request wenn Protokolleinstellungen, Referenzen, Metadaten, Geheimnisse, Schlüssel oder Namen ungültig sind oder ein Planlimit erreicht ist.
  • 401 Unauthorized, wenn das Zugriffstoken fehlt oder ungültig ist.
  • 403 Forbidden, wenn dem Anrufer das erforderliche Teilnehmerzugriffsrecht fehlt.
  • 404 Not Found, wenn die ausgewählte Registrierung, das ausgewählte Geheimnis oder der ausgewählte Schlüssel nicht vorhanden ist.
  • 409 Conflict, wenn bereits ein technischer Name oder eine geheime Kennung 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.