Sync- und Fachdienste an App-Berechtigungen anbinden

Nutzen Sie diesen Integrationsvertrag, wenn ein separater Sync-Service oder Fachdienst dieselben App-Rechte wie Workspace durchsetzen muss. Nach der Einrichtung kann der Dienst Rechte online prüfen, lokal synchronisieren oder einen kurzlebigen signierten Grant validieren. Payment-, Identity- und Provider-Rohdaten verlassen Workspace dabei nicht.

Integrationsart wählen

Variante	Geeignet für	Verhalten
Nativer Resolver	Modul im selben Workspace-Prozess	Direkter, tenantisolierter Domänenaufruf
Introspection	Einzelne Online-Entscheidung	Aktueller Zustand eines App-Akteurs
Snapshot plus Change-Feed	Eigene lokale Projektion	Vollständiger Startstand, danach sequenzielle Änderungen
Ed25519-Grant	Kurze Offline-Entscheidung	Audience-gebundener, kurzlebiger signierter Nachweis
Webhook	Schnelle Benachrichtigung	Mindestens einmal zugestellt; Feed bleibt Reconciliation-Vertrag

Für einen eigenständig deployten Sync-Service ist Snapshot plus Change-Feed der Standard. Webhooks verkürzen die Reaktionszeit, ersetzen aber keine Reconciliation.

Service-Bindung und Credential

Ein Administrator legt eine tenant- und appgebundene Service-Bindung mit Audience und erlaubten Fähigkeiten an. Rotieren Sie anschließend das Credential. Workspace zeigt dessen Secret nur bei der Ausgabe.

Senden Sie bei jedem authentisierten Request:

X-Workspace-Service-Credential: ausgegebene Credential-ID und Secret gemäß Ausgabeformat,
X-Workspace-Service-Timestamp: Unix-Zeit in Sekunden,
X-Workspace-Service-Nonce: pro Request neuer kryptografischer Zufallswert,
X-Workspace-Service-Signature: Signatur über den kanonischen Requestvertrag.

Die Signatur bindet HTTP-Methode, vollständigen Request-Pfad einschließlich Query, Zeitstempel, Nonce und SHA-256-Hash des Bodys. Verwenden Sie für jeden Versuch eine neue Nonce. Veraltete Zeitstempel, falsche Signaturen und wiederholte Nonces schlagen fehl.

Endpunkte verwenden

Methode und Pfad	Zweck
`GET /api/v1/public/v1/app-entitlements/service/introspect/{actorId}`	Einzelnen App-Akteur prüfen
`GET /api/v1/public/v1/app-entitlements/service/snapshot`	Seitenweisen Startstand laden
`GET /api/v1/public/v1/app-entitlements/service/changes?afterSequence=...`	Änderungen in Reihenfolge nachladen
`POST /api/v1/public/v1/app-entitlements/service/grants/{actorId}`	Kurzlebigen Grant ausstellen
`GET /api/v1/public/v1/app-entitlements/jwks`	Öffentliche Ed25519-Verifikationsschlüssel laden

Speichern Sie asOfSequence aus der ersten Snapshot-Seite. Senden Sie bei jeder Folgeseite sowohl cursor als auch dieselbe asOfSequence. Laden Sie danach Änderungen strikt aufsteigend ab dieser Sequenz. Antwortet der Feed mit ERR_APP_ENTITLEMENT_CURSOR_EXPIRED, verwerfen Sie die lokale Projektion und beginnen Sie mit einem neuen Snapshot.

Grants prüfen

Laden und cachen Sie die JWKS. Prüfen Sie Signatur, Schlüssel-ID, Issuer, Audience sowie Ablaufzeit und verwenden Sie nur Features und Limits aus dem verifizierten Token. Akzeptieren Sie keinen abgelaufenen Grant und verwenden Sie ihn nicht für eine andere Service-Bindung.

Webhooks sicher verarbeiten

Bestätigen Sie eine Lieferung erst nach dauerhafter Verarbeitung. Verwenden Sie Ereignis-ID und Sequenz zur Deduplizierung. Lieferungen können wiederholt oder verzögert eintreffen. Bei einer Lücke laden Sie den Change-Feed nach.

Workspace akzeptiert nur abgesicherte HTTPS-Ziele und blockiert private, Loopback- und anderweitig nicht zulässige Ziele. Legen Sie keine Credentials in die Ziel-URL.

Ergebnis prüfen

Testen Sie mindestens:

gültige Introspection und Snapshot/Feed-Fortsetzung,
falsche Audience und abgelaufenen Grant,
Nonce-Replay und veralteten Zeitstempel,
eine doppelte Webhook-Lieferung,
einen abgelaufenen Feed-Cursor mit anschließendem Snapshot.

Der Dienst darf aus einer Benachrichtigung oder einem Store-Payload niemals selbst Rechte ableiten. Workspace bleibt die Entitlement-Autorität.