Wenn ein entferntes Geschäftssystem an die Plattform angebunden wird, liegt das Problem selten im API-Aufruf selbst. Es liegt bei der Frage, wer welche Zugangsdaten hält, wie lange sie gültig sind und wie schnell eine entzogene Mitgliedschaft wirkt. Diese drei Fragen entscheiden darüber, ob das System auch Monate später noch korrekt arbeitet. Im Folgenden steht, was wir auf diesem Weg einhalten und wo die Grenzen liegen.

Zwei Stufen von Zugangsdaten, die langlebige verlässt den Server nicht

Die Plattform kennt zwei Arten von Identität. Die Modul-Service-Identität ist langlebig, liegt ausschließlich auf dem Server des Geschäftssystems und wird verwendet, um einen Launch Grant zu tauschen (POST /integration/v1/sso/launch-grants/exchange) und ein Instanz-Service-Token anzufordern (POST /integration/v1/service-tokens). Das Instanz-Service-Token ist kurzlebig: höchstens fünf Minuten, feste Audience und Scopes, die auf die aktuelle Anfrage verengt sind, ausgeliefert mit no-store.

Der Browser erhält damit nie Modul-Zugangsdaten. Das Frontend übergibt den Launch Code an das eigene Backend, und jeder Austausch findet serverseitig statt. Kurzlebige Token cached das SDK pro Instanz und angeforderter Scope-Menge für höchstens 300 Sekunden, ohne Refresh: Unterschreitet die Restlaufzeit ein Sicherheitsfenster, wird neu angefordert; parallele Aufrufe lösen genau einen Austausch aus; und über Instanzen hinweg wird ein Token nie wiederverwendet.

Launch ist ein einmaliger Austausch und endet in Ihrer eigenen Sitzung

Wer von der Plattform kommt, bringt einen Launch Code mit und keine langlebigen Zugangsdaten. Das Backend tauscht den Grant mit der Modul-Service-Identität und verbraucht ihn, danach entsteht die lokale Sitzung des Geschäftssystems. Diese Sitzung enthält nur abgeleitete Identität: kein Plattform-Token, keinen Launch Code, kein Client Secret und keine vollständigen Claims.

Austausch und spätere Sitzungsprüfungen verifizieren Signaturen: Das Runtime-JWKS der Plattform prüft Algorithmus, Issuer, Audience, Gültigkeitsdauer, token_use, Account und App-Instanz sowie Scopes, wobei die Schlüsselquelle Weiterleitungen ablehnt und die Antwortgröße begrenzt. Ein Punkt wird leicht verwechselt: „Verbindung in Ordnung“ auf der Anmeldeseite belegt nur, dass das Backend die öffentlichen Schlüssel lesen kann. Es belegt weder, dass der Besucher angemeldet ist, noch dass der Launch-Weg funktioniert. Halten Sie diese drei Aussagen getrennt.

Wird eine Mitgliedschaft entzogen, müssen lokale Sitzungen konvergieren

Eine gültige Plattformsitzung bedeutet nicht, dass eine lokale Sitzung unbegrenzt weiterläuft. Während einer langen Sitzung müssen entfernte Mitglieder, geänderte Rollen und gesperrte Instanzen das Geschäftssystem innerhalb eines begrenzten Fensters erreichen. Das Mittel dafür ist eine Sammelprüfung unter der Instanz-Service-Identität (POST /integration/v1/session-checks): active ist nur wahr, wenn Instanz, Instanzmitgliedschaft, Account und Account-Mitgliedschaft zugleich gültig sind. Nicht-Mitglieder und unbekannte Nutzer liefern beide active=false, sodass die Existenz einer Mitgliedschaft nicht durchsickert. Jedes Geschäftssystem konvergiert in dem Fenster, das es selbst deklariert; in der Praxis darf das Fenster für Schreibzugriffe kürzer sein als für Lesezugriffe.

Reichen die Scopes nicht, scheitert der Aufruf lokal

Jede Laufzeitanfrage trägt Scopes. Das SDK gibt nur dann nutzbare Zugangsdaten zurück, wenn die tatsächlich erteilten Scopes die aktuelle Anfrage abdecken; andernfalls scheitert es lokal und sendet keine Geschäftsanfrage. Der Sinn dieser Regel ist die Trennung von „die Plattform hat nicht autorisiert“ und „der Plattformaufruf ist fehlgeschlagen“: Ersteres ist ein Konfigurationsproblem und sollte sofort sichtbar sein, statt in einem undurchsichtigen Fehler von oben zu verschwinden.

Idempotenz und Wiederholungen liegen beim Aufrufer

Das SDK wiederholt keine Anfrage von sich aus. Schreibende Operationen brauchen einen stabilen Idempotenzschlüssel, den der Aufrufer liefert, und eine fehlgeschlagene Anfrage wird nicht erneut gesendet — denn „Ergebnis unbekannt“ und „fehlgeschlagen“ sind zwei verschiedene Zustände, und nur das Geschäftssystem weiß, ob es erneut senden, nachfragen oder den Nutzer informieren soll. Bei Fehlern werden Problem Details der Plattform auf stabile Klassen abgebildet (nicht authentifiziert, verboten, Konflikt, Ratenlimit, Serverfehler und weitere) samt Hinweis auf Wiederholbarkeit; Zugangsdaten und Antwortinhalte landen nicht in Logs oder Fehlerserialisierung.

Zwei Artefakte, zwei Bezugswege

Die beiden SDKs sind unterschiedlich verfügbar, klären Sie also zuerst, welches für Sie gilt. Auf TypeScript- und Node-Seite ist es @td-runlume/platform-integration-sdk auf öffentlichem npm unter Apache-2.0 zur serverseitigen Nutzung. Auf Java-Seite lautet die Koordinate app.runlume.platform:platform-integration-sdk-java, bereitgestellt aus dem Nexus-Repository der Plattform und nicht auf Maven Central; die Nutzung ist auf von der Plattform erteilte Zugangsdaten und Lizenzen beschränkt, und die Artefakte dürfen nicht weitergegeben werden. Java-Integrationen nutzen üblicherweise zusätzlich den Spring Boot Starter, der die SDK-Komponenten und die Prüfkette für lokale Sitzungen verdrahtet; das Geschäftssystem liefert nur zwei Erweiterungspunkte: Sitzungsgrenze und Workspace-Lesen.

Endpunktpfade, Scope-Namen und verfügbare Fähigkeiten richten sich nach dem zur Onboarding-Zeit vereinbarten Vertrag und der Plattformdokumentation. Dieser Beitrag behandelt nur die Grenzen der Serverseite; die Fähigkeiten selbst beginnen bei den Plattformfähigkeiten.