Delegierter Zugang mit OAuth 2.1

Nach dieser Seite lässt Ihre Anwendung einen Menschen entscheiden, statt einen Schlüssel zu verlangen: Sie registriert sich selbst, schickt die Person zur Einwilligung, tauscht den Code mit PKCE gegen ein Zugriffstoken oat_… und erneuert oder widerruft es. Das Passwort der Person sieht sie dabei nie.

Wann dieser Weg der richtige ist#

Ein delegierter Zugang trägt immer zwei Seiten: die Anwendung, die handelt, und das Konto, in dessen Auftrag. Zur Laufzeit gilt die Schnittmenge aus beidem. Verliert die Person ein Recht, verliert Ihre Anwendung es im selben Augenblick mit.

Die Adressen#

Ihre Anwendung muss genau eine Adresse fest kennen: die Wegbeschreibung. Alles Übrige steht darin, und zwar absolut. Aussteller und Endpunkte nennen künftig die Metadaten von auth.<ihre-domain>, wenn Ihre Umgebung diesen Wirt hat. Tragen Sie darum keinen Endpunkt von Hand ein, sondern lesen Sie ihn aus der Beschreibung, die Sie dort abrufen. Die Adressen an der Basis-Adresse der API bleiben bis auf Weiteres erreichbar.

Die ersten sechs Adressen tragen kein /v1: Ihre Pfade schreiben die Standards wörtlich vor, und ein fremder Client sucht dort und nirgends sonst. Was hinter der Einwilligung liegt, steht regulär unter /v1 — siehe Basis-URL, /v1 und Stabilität.

Schritte#

1. Holen Sie die Wegbeschreibung. Sie nennt die Endpunkte, die unterstützten Verfahren und unter scopes_supported jedes Recht, das ein delegierter Zugang tragen kann.

   curl -sS "$SZENERA_API/.well-known/oauth-authorization-server" | jq '{issuer, authorization_endpoint, token_endpoint}'
   

2. Registrieren Sie Ihren Client — einmalig, ohne Anmeldung, ohne Geheimnis. Es gibt nur öffentliche Clients: token_endpoint_auth_method ist immer none.

   curl -sS -X POST "$SZENERA_API/oauth/register" \
     -H "Content-Type: application/json" \
     -d '{ "client_name": "Warenwirtschaft-Brücke", "redirect_uris": ["http://127.0.0.1:8765/callback"] }'
   

   { "client_id": "oac_01KQRWJRC0OAUTHCLIENT00001", "token_endpoint_auth_method": "none", "redirect_uris": ["http://127.0.0.1:8765/callback"] }
   

   Die Registrierung ist auf 10 Aufrufe je Stunde und Absenderadresse begrenzt. Legen Sie die Kennung ab und registrieren Sie nicht bei jedem Start neu.

3. Erzeugen Sie ein Prüfwort und seine Prüfsumme. Das Verfahren ist ausschließlich S256; plain gibt es nicht.

   VERIFIER=$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')
   CHALLENGE=$(printf %s "$VERIFIER" | openssl dgst -binary -sha256 | openssl base64 | tr '+/' '-_' | tr -d '=')
   

4. Schicken Sie die Person in den Browser. Sie landet auf der Einwilligungsseite des Portals und sieht dort den Namen Ihrer Anwendung, das Rücksprung-Ziel und die erbetenen Rechte — gebündelt zu Bereichen mit je einem Satz und einem Schalter.

   open "$SZENERA_API/oauth/authorize?response_type=code&client_id=oac_01KQRWJRC0OAUTHCLIENT00001&redirect_uri=http%3A%2F%2F127.0.0.1%3A8765%2Fcallback&scope=scene.read%20playlist.read&state=$(openssl rand -hex 16)&code_challenge=$CHALLENGE&code_challenge_method=S256"
   

   Prüfen Sie beim Rücksprung state gegen den gesendeten Wert, bevor Sie den Code einlösen.

5. Tauschen Sie den Code. Der Rumpf ist formularkodiert, nicht JSON.

   curl -sS -X POST "$SZENERA_API/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d grant_type=authorization_code \
     -d code=ocd_01KQRWJRC0OAUTHCODE0000001 \
     -d redirect_uri=http://127.0.0.1:8765/callback \
     -d client_id=oac_01KQRWJRC0OAUTHCLIENT00001 \
     -d code_verifier=$VERIFIER
   

   { "access_token": "oat_…", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "ort_…", "scope": "playlist.read scene.read" }
   

6. Arbeiten Sie damit wie mit jedem anderen Bearer:

   curl -sS "$SZENERA_API/v1/me" -H "Authorization: Bearer oat_…"
   

7. Erneuern Sie rechtzeitig. Der Erneuerungs-Token rotiert: Nach dem Tausch ist der alte verbraucht, und die Antwort trägt einen neuen.

   curl -sS -X POST "$SZENERA_API/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d grant_type=refresh_token -d refresh_token=ort_… -d client_id=oac_01KQRWJRC0OAUTHCLIENT00001
   

8. Geben Sie zurück, was Sie nicht mehr brauchen. Die Rücknahme antwortet immer 200, auch für einen unbekannten Wert.

   curl -sS -X POST "$SZENERA_API/oauth/revoke" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d token=ort_… -d client_id=oac_01KQRWJRC0OAUTHCLIENT00001
   

Optionen#

Lebensdauern#

Rechte#

Es gibt keinen eigenen Katalog: Ein Scope ist ein Rechte-Schlüssel, denselben, den auch ein API-Schlüssel tragen darf — scene.read, playlist.write und so fort. Die vollständige Liste steht als scopes_supported in beiden Wegbeschreibungen; welche Rechte für Maschinen freigegeben sind, sagt auch GET /v1/permission-catalog über das Feld appliesTo.

Beim Einwilligen greifen zwei Schnitte: Ein Recht, das Maschinen nie tragen, ist nicht erteilbar; ein Recht, das die einwilligende Person selbst nicht hält, ebenfalls nicht. Beides steht mit seinem Grund in seinem Bereich. Erbitten Sie deshalb nur, was Sie wirklich brauchen: Ein zu breiter Wunsch macht die Entscheidung schwerer und wird abgewiesen, statt stillschweigend gekürzt zu werden.

Bereiche und teilweise Einwilligung#

Die Einwilligungsseite zeigt die Rechte nicht als Liste, sondern gebündelt nach der Kategorie des Rechte-Katalogs — „Szenen“, „Playlisten und Zeitpläne“, „Medien“, „Displays und Standorte“, „Berichte“. Jeder Bereich trägt einen Satz, was Ihre Anwendung darin tun kann, einen Schalter und aufklappbar die einzelnen Rechte. Alle angefragten Bereiche sind zu Beginn eingeschaltet; dieselbe Bündelung steht später in der Karte Verbundene Anwendungen, eingeklappt als Bilanz („5 Bereiche, 18 Rechte“).

Rechnen Sie mit einer Teilmenge. Der Mensch darf einzelne Bereiche abschalten, und POST /v1/oauth/authorizations/{id}/approve nimmt jede Teilmenge des Erbetenen an. Das Zugriffstoken trägt dann nur die erteilten Rechte, und die Token-Antwort nennt sie unter scope:

{ "access_token": "oat_…", "scope": "scene.read", "expires_in": 3600 }

Vergleichen Sie scope mit dem, worum Sie gebeten haben, statt es vorauszusetzen. Was fehlt, beantwortet die Plattform beim Aufruf mit 403 — nicht beim Tausch. Brauchen Sie einen Bereich wirklich, sagen Sie es der Person im Klartext und schicken Sie sie ein zweites Mal durch den Rundlauf; einen Weg, eine bestehende Einwilligung nachträglich zu erweitern, gibt es bewusst nicht.

Grenzen#

GET /oauth/authorize, POST /oauth/token und POST /oauth/revoke sind auf 60 Aufrufe je Minute und Absenderadresse begrenzt, die beiden Wegbeschreibungen auf 120, die Registrierung auf 10 je Stunde. Der Echtzeit-Kanal bleibt einem delegierten Zugang verschlossen; Ereignisse holen Sie über Webhooks.

Der Betreiber der Plattform kann einen Client sperren. Dann beginnt kein neuer Rundlauf mehr, und eine laufende Erneuerung scheitert; bestehende Zugriffstoken laufen aus, statt zurückgenommen zu werden. Ebenso kann eine Organisation den delegierten Zugang ganz abschalten: Die Einwilligung scheitert dann mit OAuthAuthorization.DelegationDisabled — dort, wo der Mensch entscheidet, und nicht erst beim Tausch.

Ergebnis prüfen#

• GET /v1/me mit dem Token antwortet 200 und nennt das Konto und die Organisation, in deren Auftrag Sie handeln.
• Die Token-Antwort nennt unter scope die tatsächlich erteilten Rechte — sie können weniger sein als die erbetenen.
• Die Person sieht Ihre Anwendung im Portal unter Einstellungen › Mein Konto › Sicherheit in der Karte Verbundene Anwendungen, aufklappbar nach denselben Bereichen, und kann sie dort mit einem Klick widerrufen.
• Nach einem Widerruf antwortet derselbe Aufruf 401.

Wenn etwas nicht klappt#

Die Endpunkte des Standards antworten im Format des Standards ({ "error": …, "error_description": … }) und nicht im Fehlerformat dieser API. Die Routen unter /v1 antworten regulär.

Die Codes OAuthClient.* und OAuthAuthorization.* stehen vollständig — mit Bedeutung, Auslöser und Status — unter Fehlercodes: Konten und Sitzungen; die beiden Ausweis-Codes Auth.OAuthTokenRevoked und Auth.OAuthClientBlocked unter Fehlercodes: auf jeder Route möglich.

Weiterführendes#

• Anmeldung: Schlüssel und Sitzungen
• Der MCP-Dienst für KI-Assistenten
• Handbuch: Verbundene Anwendungen erlauben und widerrufen