Delegierte Subkonten ohne offengelegte Schlüssel: sicheres Muster für Agenturen

Das Problem: Kundenautonomie, ohne die Kontrolle zu verlieren

Eine Agentur, die Ergebnisse für mehrere Kunden verwaltet, braucht häufig zwei Dinge, die gegensätzlich wirken: Jeder Kunde soll Dateien mit einer gewissen Autonomie ansehen, prüfen, hochladen oder herunterladen können, während privilegierte Vorgänge weiterhin unter technischer Kontrolle der Agentur bleiben. Das Risiko entsteht, wenn man versucht, dies schnell durch das Teilen von Zugangsdaten, das Anlegen eines generischen Benutzers für alle oder dadurch zu lösen, dass der Browser interne Aktionen mit einem API-Schlüssel ausführt. Dieser Weg kann Bereiche vermischen, die Nachvollziehbarkeit zerstören und es sehr schwierig machen, Zugriffe zu widerrufen, ohne andere Kunden zu beeinträchtigen.

Das richtige Ziel ist nicht, eine Oberfläche zu verstecken, sondern Verantwortlichkeiten zu trennen. Der Kunde soll nur seinen autorisierten Kontext sehen; das Backend der Agentur soll die Aktionen mit Privilegien ausführen; und Apification Cloud soll Berechtigungen, Sichtbarkeit, Gruppen, Einschränkungen und begrenzte eingebettete Sitzungen anwenden. Dieses Muster ermöglicht es, Subkonten zu delegieren, ohne API-Schlüssel offenzulegen, die geheimen Schlüssel auf dem Server zu halten und die Abhängigkeit von manuellen Vorgängen wie dem Verschieben von Dateien, dem Erzeugen von Links oder dem einzelnen Prüfen von Transformationsjobs zu reduzieren.

• Gib dem Kunden keine API-Zugangsdaten und binde sie nicht in JavaScript ein.
• Verwende kein gemeinsames Konto für mehrere Kunden, wenn du operative Isolation brauchst.
• Definiere von Anfang an, welche Aktionen Benutzeraktionen sind und welche über das Backend laufen.
• Behandle jede Offenlegung von Inhalten als explizite Ausnahme für standardmäßig private Ressourcen.

Denkmodell: drei getrennte Ebenen

Die erste Ebene ist die eingebettete Oberfläche. Apification ermöglicht die Integration von Cloud per iframe, geerbter Konfiguration und visuellen Themes, sodass eine Agentur oder ein Reseller eine integrierte Erfahrung im eigenen Ökosystem anbieten kann. In diesem Modell muss die iframe-Sitzung aufgebaut werden, bevor sie angezeigt wird: Identität, gültige Richtlinie und visuelle Konfiguration werden bei jedem Start auf dem Server aufgelöst. Die eingebettete Sitzung kann auf das Subkonto, den Benutzer und die erlaubten Ressourcen beschränkt werden, wodurch verhindert wird, dass der Browser selbst entscheidet, was er öffnen darf.

Die zweite Ebene ist das eigene Backend. Dort befinden sich API-Zugangsdaten, Webhook-Secrets und Signaturmaterial, denn die Apification-Dokumentation beschreibt, dass sie auf dem Server bleiben müssen und der Browser nur begrenzten oder temporären Kontext erhalten darf. Die dritte Ebene sind die Cloud-Kontrollen: Berechtigungen, Benutzer, Gruppen, Sichtbarkeit, Einschränkungen, OTP, externe Authentifizierung, sofern relevant, und Veröffentlichungsfenster. Die Designregel ist einfach: Die Oberfläche führt den Benutzer, das Backend führt privilegierte Aktionen aus und Cloud bewahrt die dem jeweiligen Ressourcenzugriff zugeordnete Richtlinie.

• Iframe: Benutzererlebnis und Auswahl innerhalb eines begrenzten Kontexts.
• Backend: Erstellung signierter Sitzungen, API-Aufrufe und Validierung der Kundenregeln.
• Cloud: Dateien, Ordner, editierbare Dienste, Ergebnisse, Verlauf, Berechtigungen und Sichtbarkeit.
• Webhooks: Ereignisbenachrichtigungen mit Signatur, Wiederholungen, Verlauf und Statistiken.

Was Apification zu diesem Muster beiträgt

Apification bringt die notwendigen Bausteine für eine kontrollierte Delegation zusammen. Cloud bewahrt Dateien, Ordner, editierbare Dienste und erzeugte Ergebnisse in einem gemeinsamen, organisierten und versionierten Arbeitsbereich auf. Neue Ressourcen sind standardmäßig privat und werden nur dann veröffentlicht oder geteilt, wenn ihre Sichtbarkeit oder Empfänger ausdrücklich konfiguriert werden. Außerdem können sie mit Benutzern oder Gruppen geteilt werden, ohne die öffentliche Sichtbarkeit zu ändern. Das ist wichtig, wenn eine Agentur internen Prüfern beim Kunden Zugriff geben muss, ohne ein Ergebnis öffentlich zu machen.

Für die Integration bietet Apification eine Server-zu-Server-REST-API, um Cloud-Ressourcen, Benutzer, Konfiguration und Transformationsjobs aus dem Backend heraus zu verwalten, außerdem einen herunterladbaren OpenAPI-Vertrag mit Anfrage- und Antwortschemata. Apification ermöglicht auch die Integration von Cloud und Diensten über iframe, API, Webhooks und JavaScript, doch entscheidend ist, „Integration mit JavaScript“ nicht mit „geheime Schlüssel im Browser“ zu verwechseln. Für asynchrone Abläufe sind signierte Webhooks mit Wiederholungen, Verlauf und Statistiken in der Produktion dem Polling vorzuziehen, wenn Ereignisse zu abgeschlossenen oder fehlgeschlagenen Transformationen erwartet werden.

• Verwende spezifische API-Schlüssel mit nur den erforderlichen Berechtigungsbereichen, also Scopes.
• Stütze dich auf OpenAPI, um Verträge vor der Programmierung zu validieren.
• Nutze Webhooks in der Produktion, um wiederholte Abfragen zu reduzieren und die Nachvollziehbarkeit zu verbessern.
• Reserviere OTP für öffentliche Interaktionen; nutze Benutzer, Gruppen und Sichtbarkeit für internen Zugriff.

Empfohlene Architektur für delegierte Subkonten

Der empfohlene Ablauf beginnt im Portal der Agentur. Der Benutzer des Kunden authentifiziert sich im System der Agentur und fordert an, seinen Dateibereich oder einen konkreten Vorgang zu öffnen. Das Backend validiert, zu welchem Kunden er gehört, welche Rolle er hat und welche Ressourcen er verwenden darf. Erst dann fordert es aus dem vertrauenswürdigen Backend heraus eine signierte, kurzlebige iframe-Sitzung mit isoliertem Kundenkontext an: Subkonto, Benutzer und erlaubte Ressourcen. Der Browser erhält diese begrenzte Sitzung, keinen API-Schlüssel und kein wiederverwendbares Secret.

Wenn der Kunde eine privilegierte Aktion benötigt, etwa das Erstellen eines Transformationsjobs, das Abfragen einer Ressource oder das Vorbereiten eines transformierten Downloads, muss der Browser das Backend der Agentur aufrufen, nicht direkt mit permanenten Zugangsdaten. Das Backend wendet Geschäftsregeln an, ruft die REST-API von Apification mit Bearer-Authentifizierung vom Server aus auf und protokolliert die Aktion. Wenn Host und iframe über Browser-Nachrichten koordiniert werden, müssen diese Nachrichten validiert werden: Der Empfänger muss Ursprung, Absicht und erwartete Daten prüfen, nach dem allgemeinen Prinzip der Validierung von Kommunikation zwischen Fenstern.

• Schritt 1: Authentifiziere den Kunden im Portal der Agentur.
• Schritt 2: Löse Identität, gültige Richtlinie und visuelles Theme auf dem Server auf.
• Schritt 3: Fordere eine signierte, begrenzte und kurzlebige iframe-Sitzung an.
• Schritt 4: Führe REST-Aufrufe nur aus dem Backend heraus mit einem Schlüssel mit minimalen Berechtigungsbereichen aus.
• Schritt 5: Protokolliere Ereignisse und Antworten für operative Audits.

Delegation pro Kunde: Berechtigungen, Bereiche und Regeln

Die Trennung sollte nicht allein vom Namen eines Ordners abhängen. In Apification ändert das Verschieben eines Cloud-Elements seine Organisation, nicht seine Identität: Seine Eigenschaften und Zugriffsregeln bleiben mit demselben Element verbunden. Das ist nützlich, um Ergebnisse neu zu ordnen, ohne Kontrollen zu verlieren, zeigt aber auch, warum Isolation auf Berechtigungen, Benutzern, Gruppen, Sichtbarkeit und autorisierten Ressourcen beruhen muss, nicht auf fragilen Konventionen wie „alles unter /kunde-a“. Die Agentur sollte die Zugriffsmatrix pro Kunde dokumentieren und sie prüfen, wenn sich der Servicevertrag ändert.

Eine praktische Matrix unterscheidet mindestens fünf Aktionen: Dateien hochladen oder einbringen, Inhalte transformieren oder verarbeiten, Versionen prüfen, Originale oder generierte Formate herunterladen und Links oder Zugriffe veröffentlichen. Cloud ermöglicht es, die Quelldatei herunterzuladen oder aus dem Teilen-Ablauf heraus ein kompatibles Format zu erzeugen. Daher ist es sinnvoll zu entscheiden, wer Originale bereitstellen darf und wer nur abgeleitete Dateien erhalten soll. Wenn editierbare Dienste verwendet werden, etwa Office-Dokumente, Bildbearbeitung oder Multimedia-Editoren, gilt dieselbe Logik: Der Kunde braucht keine universelle Berechtigung, sondern die minimale Menge an Aktionen für seinen Fall.

• Definiere Gruppen pro Kunde oder pro Rolle innerhalb des Kunden.
• Trenne Prüfung, Transformation, Download und Veröffentlichung in deinem Design als unterschiedliche Berechtigungen.
• Vermeide, dass eine Ordneränderung der einzige Kontrollmechanismus ist.
• Halte ein Widerrufsverfahren bereit, wenn ein Kundenkontakt nicht mehr beteiligt ist.

Typische Vorgänge und wie man sie automatisiert

Im Tagesgeschäft kann der Kunde Dateien aus dem iframe auswählen, Ergebnisse in Cloud prüfen, ein Original herunterladen oder eine transformierte Version anfordern. Die Agentur wiederum kann Jobs aus dem Backend heraus erstellen, Kundenregeln anwenden und den Verlauf der Elemente nutzen, um frühere Versionen zu prüfen oder Inhalte bei Bedarf wiederherzustellen. Dieser Ansatz reduziert lose E-Mail-Kommunikation und verhindert, dass das interne Team für jeden Download oder jede einfache Prüfung als Zwischenstelle agieren muss.

Für asynchrone Prozesse solltest du rund um Ereignisse designen. Wenn eine Transformation abgeschlossen wird oder fehlschlägt, kann ein signierter Webhook das Backend der Agentur benachrichtigen. Dieses Backend muss die Signatur mit dem auf dem Server gespeicherten Secret prüfen, doppelte Ereignisse erkennen und den eigenen Status aktualisieren. Apification unterstützt idempotente Schreibvorgänge über einen Idempotenzschlüssel in kompatiblen Operationen. Daher sollten Aktionen, die sich durch Wiederholungen, Doppelklicks oder Verbindungswiederaufbau wiederholen könnten, einen stabilen Schlüssel senden. So vermeidest du, doppelte Jobs anzulegen oder dasselbe Ergebnis zweimal zu veröffentlichen.

• Nutze Webhooks für Jobabschlüsse und Fehler, nicht nur regelmäßige Abfragen.
• Verifiziere die Signatur, bevor du dem Inhalt des Ereignisses vertraust.
• Speichere Ereignis- oder Ergebniskennungen, um doppelte Verarbeitung zu vermeiden.
• Wende Idempotenzschlüssel bei kompatiblen Schreibvorgängen an, die sich wiederholen können.
• Bewahre ein operatives Protokoll darüber auf, wer etwas angefordert hat, welche Ressource betroffen war und welches Ergebnis erzielt wurde.

Häufige Fehler und Ausfallmodi

Der schwerwiegendste Fehler ist, Schlüssel in JavaScript abzulegen. Auch wenn eine Oberfläche privat ist oder hinter einem Login liegt, muss jedes an den Browser übergebene Secret als offengelegt betrachtet werden. Ein weiterer häufiger Fehler ist die Verwendung eines einzigen Benutzers für alle Kunden: Das mag anfangs bequem wirken, verhindert aber die Zuordnung von Aktionen, erschwert den Widerruf von Zugriffen und erhöht die Auswirkungen jedes Konfigurationsfehlers. Ebenso gefährlich ist es, nur Ordnernamen zu vertrauen, denn die visuelle Organisation ersetzt keine Zugriffsregeln, die mit Ressourcen und Benutzern verknüpft sind.

In der Automatisierung treten Fehler häufig dadurch auf, dass Webhook-Signaturen nicht geprüft werden, dass dasselbe Ereignis zweimal verarbeitet wird oder dass eine einmalige Importaktion mit kontinuierlicher Synchronisierung gleichgesetzt wird. Wenn eine Webhook-Zustellung wiederholt wird und dein Backend nicht idempotent ist, kannst du Jobs oder Benachrichtigungen duplizieren. Wenn du nicht mit Benutzern mit geringeren Privilegien testest, stellst du möglicherweise spät fest, dass eine Rolle Originale herunterladen kann, obwohl sie nur transformierte Dateien sehen sollte. Die Verteidigung besteht darin, negative Fälle zu testen: falscher Benutzer, Ressource eines anderen Kunden, abgelaufene Sitzung, ungültige Signatur und Ereigniswiederholung.

• Lege keine Bearer-Tokens, Webhook-Secrets oder Signaturmaterial im Frontend offen.
• Vermische Kunden nicht unter einer einzigen operativen Identität.
• Verarbeite Webhooks nicht, ohne Signaturprüfung und Prüfung auf doppelte Ereignisse durchzuführen.
• Behandle einen einmaligen Import von externen Anbietern nicht als kontinuierliche Synchronisierung.
• Vergib keine breiten API-Berechtigungsbereiche, wenn die Integration nur einen Teil davon benötigt.

Implementierungs-Checkliste vor der Produktion

Bevor du den Zugang für Kunden öffnest, bereite eine technische und eine operative Checkliste vor. In der technischen Checkliste erstellst du einen spezifischen API-Schlüssel für die Integration und vergibst nur die erforderlichen Berechtigungsbereiche für Konto, Cloud, Transformationen, Benutzer oder Webhooks. Speichere den Schlüssel und die Secrets in Variablen oder in serverseitigem Speicher, niemals im Client. Implementiere Kundenvalidierung an jedem internen Endpoint: Keine Anfrage aus dem Browser darf frei einen anderen Kunden, ein anderes Subkonto oder eine andere Ressource angeben können, ohne dass das Backend dies gegen seine eigene Autorisierung prüft.

In der operativen Checkliste dokumentierst du, wer hochladen, transformieren, prüfen, herunterladen, teilen und widerrufen darf. Erstelle Tests mit Benutzern mit geringeren Privilegien, validiere abgelaufene iframe-Sitzungen und prüfe, dass Ressourcen privat bleiben, sofern sie nicht ausdrücklich veröffentlicht werden. Teste bei Webhooks ungültige Signaturen, doppelte Ereignisse und Wiederholungen. Wende bei Schreibvorgängen Idempotenz an, wenn sie verfügbar ist. Definiere schließlich, wie du einem Kunden oder Benutzer den Zugriff entziehst, ohne andere zu beeinträchtigen: Diese Widerrufsfähigkeit ist einer der Hauptgründe, Subkonten zu trennen und nicht von gemeinsamen Zugangsdaten abhängig zu sein.

• Berechtigungsmatrix pro Kunde, Rolle und Aktion.
• Spezifische API-Schlüssel, minimale Berechtigungsbereiche und Secrets nur auf dem Server.
• Signierte, kurze iframe-Sitzung, die aus einem vertrauenswürdigen Backend erstellt wird.
• Validierung von Subkonto, Benutzer und Ressource bei jedem Vorgang.
• Prüfung von Webhook-Signaturen, Erkennung doppelter Ereignisse und Idempotenz.
• Negative Tests mit eingeschränkten Rollen und Ressourcen anderer Kunden.
• Dokumentierter Plan zum Widerruf von Benutzern, Gruppen und veröffentlichten Zugriffen.

Häufige Fragen