Skip to main content
Verwenden Sie OAuth-Client-Credentials, wenn Ihre Backend-Integration kurzlebige Zugriffstoken benötigt oder Ihre Sicherheitsrichtlinie sie vorschreibt. Jeder Client gehört zu genau einem Service-Account und einer Organisation. OAuth ist optional: Ein API-Schlüssel mit eingeschränktem Umfang reicht für eine private Server-Integration aus, die einen Schlüssel sicher speichern und rotieren kann. Unter Authentifizierung erfahren Sie, wie Sie zwischen den beiden Methoden wählen und wie Service-Accounts dazu passen.
Der OAuth-Zugriff muss für Ihre Organisation aktiviert sein. Im Rahmen Ihrer Einrichtung erhalten Sie den regionalen Token-Endpunkt, den Issuer, die Audience und die Methode zur Client-Authentifizierung. Wenn Sie diese Einstellungen benötigen oder nicht auf die Client-Verwaltung zugreifen können, wenden Sie sich an den Living Security Support.
Der Client-Credentials-Grant steht für Ihren Service-Account. Er meldet weder eine Person an noch fordert er einen Kunden auf, eine Anwendung zu autorisieren. Die delegierte Autorisierung über einen Browser ist eine separate OAuth-Funktion und wird von diesen Operationen nicht angeboten.

Vorbereitung

  • Erstellen Sie einen Service-Account, der nur die Berechtigungen besitzt, die die Integration benötigt.
  • Verwenden Sie eine Verwaltungs-Credential mit service_account:manage und jeder Berechtigung, die Sie dem neuen Client erteilen möchten. Der Ziel-Account muss diese Berechtigungen ebenfalls besitzen. Ein Client kann die Befugnisse keines der beiden Accounts erweitern.
  • Wählen Sie die Region der Organisation. API-Credentials und OAuth-Zugriffstoken gehören auf den passenden regionalen API-Host.
  • Bewahren Sie das Client-Secret und die Token in Ihrem serverseitigen Secret-Speicher auf. Legen Sie sie niemals in Browser-Code, mobilen Anwendungen, Versionsverwaltung oder Anfrageprotokollen ab.

Client erstellen

POST /v1/oauth_clients erfordert service_account_id, eine nicht leere Liste expliziter scopes und einen Idempotency-Key. Platzhalterzeichen (Wildcards) werden nicht akzeptiert. Ein Client unterstützt bis zu 100 Scopes mit einer Gesamtlänge von höchstens 4.096 Zeichen. Jeder Service-Account kann höchstens 20 Clients oder ungelöste Erstellungs-/Bereinigungsvorgänge haben. Das Widerrufen verweigert den API-Zugriff sofort. Ein Client oder eine unklare Erstellung beim Provider zählt so lange auf das Limit, bis die Bereinigung auf der Gegenseite bestätigt ist. Eine verworfene Reservierung oder eine Erstellung, die nachweislich fehlgeschlagen ist, bevor die Arbeit beim Provider begann, kann ihren Platz gefahrlos freigeben. Der zugehörige Wiederholungsschlüssel gehört weiterhin zum ursprünglichen Versuch; stellen Sie diesen Beleg wieder her, bevor Sie entscheiden, ob Sie einen Ersatz erstellen. Wählen Sie für diesen Erstellungsversuch einen Wiederholungsschlüssel und speichern Sie ihn dauerhaft, bevor Sie die Anfrage senden. Verwenden Sie 1–255 sichtbare ASCII-Zeichen ohne Leerzeichen. Verwenden Sie ihn nach einer verlorenen Antwort erneut mit demselben Account, denselben Scopes, demselben Verwaltungs-Principal, derselben Region und derselben API-Version. Die Rotation der Verwaltungs-Credential unter demselben Service-Account erzeugt keine neue Wiederholungsidentität. Installieren Sie das Python-Paket requests. Laden Sie die folgenden Umgebungswerte über Ihre übliche Secret- und Konfigurationsverwaltung:
Python
Das Beispiel sendet eine Anfrage und hält das Ergebnis im Arbeitsspeicher. Fügen Sie an der markierten Stelle den Schreibvorgang Ihres Secret-Managers hinzu, bevor Sie es in der Produktion ausführen. Nach einem unklaren Ergebnis verlangt es bewusst eine Entscheidung, statt stillschweigend einen weiteren Client zu erstellen. Auch Netzwerkausnahmen erfordern die unten beschriebenen Schritte zur Wiederherstellung. Antworten auf Erstellung und Beleg verwenden 201 und enthalten eine oauth_client-Ressource mit id, service_account_id, client_id, scopes, status, created_at und client_secret. Antworten sind mit Cache-Control: no-store gekennzeichnet.
  • id identifiziert die Plattformressource. Speichern Sie ihn für Abruf und Widerruf.
  • client_id identifiziert den Client beim Token-Austausch. Er ist nicht die ID der Plattformressource. Er kann null sein, solange die Erstellung aussteht.
  • client_secret wird nur an die Anfrage zurückgegeben, die die Erstellung abschließt. Jede wiederholte Erstellungsanfrage liefert null, auch eine Wiederholung nach einer verlorenen Erfolgsantwort. Beim Abruf wird nie ein Secret zurückgegeben.

Verlorene oder unterbrochene Antwort wiederherstellen

Wiederholen Sie dieselbe Erstellungsanfrage mit dem gespeicherten Wiederholungsschlüssel, um einen Ressourcenbeleg wiederherzustellen. Der Beleg gibt den aktuellen Zustand wieder; ein widerrufener Client bleibt also widerrufen. Dieser Vorgang verwendet nicht den allgemeinen Vertrag zur Wiedergabe zwischengespeicherter Antworten über 24 Stunden und gibt keinen Idempotent-Replayed-Header zurück. Informationen zu Anfrage-IDs und zur Wiederherstellung finden Sie unter Fehler. Senden Sie niemals ein Client-Secret oder ein Zugriffstoken mit einer Support-Anfrage.

Prüfen und widerrufen

Verwenden Sie Ihre Verwaltungs-Credential und die Plattformressource id: Der Widerruf blockiert nachfolgende API-Anfragen des Clients, einschließlich Anfragen mit bereits ausgestellten Token. Von der API bereits angenommene Arbeit wird dadurch nicht abgebrochen. Die Bereinigung der Credentials auf der Gegenseite kann später abgeschlossen werden. Ein wiederholter Widerruf ist unbedenklich und erfordert keinen Wiederholungsschlüssel. Verwenden Sie weiterhin die Verwaltungs-Credential, wenn der zu widerrufende Client selbst ein API-Aufrufer ist.

Rotieren ohne Zugriffsverlust

Erstellen Sie einen zweiten Client mit der erforderlichen Scope-Obergrenze. Speichern Sie sein Secret, beziehen Sie über Ihren regionalen Token-Endpunkt ein Token und prüfen Sie, ob die Integration damit funktioniert. Stellen Sie die Integration auf den Ersatz um und widerrufen Sie dann die alte Ressource. Behalten Sie eine unabhängige Verwaltungs-Credential, damit Sie sich von einem fehlerhaften Rollout erholen können. Zugriffstoken können nicht mehr gewähren als die Scopes des Clients und die aktuellen Berechtigungen des Service-Accounts. Das Entfernen von Account-Berechtigungen oder das Widerrufen eines Clients hat Vorrang vor der verbleibenden Lebensdauer eines Tokens. Betrachten Sie ein zwischengespeichertes Token nicht als Nachweis dafür, dass die Autorisierung noch gültig ist. Beziehen Sie vor Ablauf ein neues Zugriffstoken, indem Sie den Client erneut authentifizieren; dieser Grant verwendet keine Refresh-Token.