Apification Cloud eingebettet integrieren, ohne Zugangsdaten offenzulegen

Das Problem: Einbetten heißt nicht, Zugangsdaten auszuliefern

Einen Dateimanager mit iframe und API zu integrieren beginnt meist mit einem einfachen Bedarf: Dateien, Ordner, Transformationen oder Downloads innerhalb eines bestehenden Produkts anzeigen. Der häufige Fehler besteht darin anzunehmen, dass die Schlüssel, die Operationen in Cloud erlauben, ebenfalls in den Browser übertragen werden müssen, nur weil die Oberfläche im Browser sichtbar ist. Diese Vermischung bricht die grundlegende Trennung zwischen Nutzererlebnis und Ausführungsautorität auf. Das iframe sollte dazu dienen, eine kontrollierte Sitzung darzustellen; die REST-API sollte vom Server aus genutzt werden, wenn Ressourcen, Benutzer, Konfigurationen oder Transformationsaufträge verwaltet werden müssen.

Apification bietet für dieses Szenario drei Hauptmodalitäten: REST-API, signierte Webhooks und eingebettete Cloud. Die eingebettete Cloud wird über eine kontrollierte und personalisierte Sitzung integriert, mit signierten iframe-Sitzungen, Themes und effektiven Berechtigungen sowie JavaScript-Kommunikation mit dem Host. Das ist nicht gleichbedeutend damit, den gesamten Speicher zu replizieren oder interne Pfade offenzulegen. Ebenso wenig sollte es mit einer kontinuierlichen Synchronisierung externer Quellen verwechselt werden: Wenn Google Drive, OneDrive oder Dropbox als Quellen dienen, kopiert der Import ausgewählte Dateien in die Cloud von Apification.

• Lege keine API-Schlüssel im clientseitigen JavaScript ab.
• Verwandle ein iframe nicht in einen Proxy ohne Geschäftsregeln.
• Behandle die Einbettung nicht als vollständige Kopie des externen Speichers.

Verantwortungskarte: Frontend, Backend und Cloud

Das Frontend sollte für das Erlebnis zuständig sein: den eingebetteten Bereich öffnen, auf erlaubte Ereignisse reagieren, Status anzeigen und Aktionen beim Backend anfordern. Ein iframe ist nach der allgemeinen Definition der Webplattform ein verschachtelter Browsing-Kontext, der eine andere Seite in die aktuelle einbettet. Jedes iframe hat sein eigenes Dokument und seine eigene Navigation und verbraucht zusätzlichen Speicher und weitere Ressourcen. Deshalb sollte es verwendet werden, wenn es ein vollständiges Erlebnis bietet, nicht als undifferenzierter Mechanismus für jede minimale Operation.

Das Backend sollte Zugangsdaten verwahren, die eigenen Produktregeln anwenden und die REST-API von Apification serverseitig aufrufen. Die REST-Integration umfasst API-Schlüssel mit Scopes, idempotente Schreiboperationen und asynchrone Aufträge des File Transformer. Apification Cloud wiederum hält den Arbeitsbereich organisiert und versioniert, ebenso teilbare Ressourcen, Berechtigungen, Benutzer, Gruppen, Rollen und Sichtbarkeit, die steuern, wer jedes Element einsehen oder ändern kann.

• Frontend: Oberfläche, iframe, begrenzte JavaScript-Nachrichten und Statusanzeige.
• Backend: eigene Authentifizierung, Autorisierung, Scopes, Idempotenz und REST-Aufrufe.
• Apification Cloud: Dateien, Dienste, effektive Berechtigungen, Versionen und transformierte Ergebnisse.

Wann iframe, JavaScript, REST-API oder OpenAPI verwenden

Nutze die eingebettete Cloud, wenn Benutzer innerhalb deines Produkts durch ein Dateiverwaltungserlebnis navigieren sollen, ohne dass du die gesamte Oberfläche nachbauen musst. Apification ermöglicht signierte iframe-Sitzungen mit temporärem Zugriff, und der Server löst Theme und effektive Berechtigungen auf, bevor Cloud geöffnet wird. Das passt zu Kundenportalen, SaaS-Dashboards und Backoffices, in denen Benutzer einen kontrollierten Teil des Workspace sehen, Originale oder transformierte Dateien herunterladen oder in einem visuellen Erlebnis arbeiten sollen, das zum Host-Produkt passt.

Nutze die REST-API, wenn die Aktion geschäftliche Folgen hat oder nach Serverregeln ausgeführt werden muss: einen Transformationsauftrag erstellen, Cloud-Ressourcen verwalten, Konfiguration anwenden oder Benutzer koordinieren. Nutze JavaScript nur für begrenzte Kommunikation zwischen der Host-Seite und dem iframe, nicht zur Ausübung sensibler Autorität. Nutze den herunterladbaren OpenAPI-3.1-Vertrag, um Anfrage- und Antwortschemas abzugleichen, interne Clients zu generieren oder Integrationen zu validieren, wobei zu beachten ist, dass Zugangsdaten mit Scopes weiterhin auf den Server gehören.

• Iframe: am besten für ein vollständiges und kontrolliertes Cloud-Erlebnis.
• JavaScript: nützlich für die Koordination der Oberfläche, nicht für Geheimnisse.
• REST-API: geeignet für Automatisierung, Backend-Regeln und Aufträge.
• OpenAPI: nützlich für technischen Vertrag, Typen, Tests und Änderungsprüfung.

Empfohlenes Muster: Backend als Vermittler

Das robusteste operative Muster beginnt mit einer Anfrage des Benutzers an deine Anwendung. Das Backend validiert die eigene Sitzung, prüft anhand deines Geschäftsmodells, was dieser Benutzer tun darf, und entscheidet, ob die eingebettete Cloud geöffnet oder eine Aktion über die API ausgeführt werden soll. Wenn Cloud geöffnet wird, bereitet der Server eine signierte und temporäre Sitzung vor, bei der Theme und effektive Berechtigungen aufgelöst sind, bevor das Erlebnis an den Browser übergeben wird. Der Client erhält das, was zum Anzeigen des iframe nötig ist, nicht wiederverwendbare Zugangsdaten.

Für Schreib- oder Transformationsoperationen nutzt das Backend Zugangsdaten mit Scopes und gewährt nur die erforderlichen Lese- und Schreibberechtigungen. Wenn sich eine Aktion durch Browser-Wiederholungen oder Netzwerkprobleme wiederholen kann, nutze idempotente Operationen, um Duplikate zu vermeiden. Bei schweren Abläufen wie Importen, Transformationen oder Renderings kann Apification Aufträge im Hintergrund verarbeiten. Die empfohlene Sequenz ist klar: Zugangsdaten mit Scopes, idempotente Anfrage, asynchroner Auftrag, signiertes Ereignis und authentifiziertes Ergebnis.

• Validiere den Benutzer in deinem Backend, bevor du eine eingebettete Sitzung erstellst.
• Ordne geschäftliche Berechtigungen den effektiven Cloud-Berechtigungen zu.
• Nutze minimale Scopes für die Server-Zugangsdaten.
• Gestalte Schreibvorgänge so, dass sie Wiederholungen tolerieren, ohne Aktionen zu duplizieren.

Berechtigungen, Themes und Einschränkungen ohne Zugriffserweiterung

Die Sicherheit einer eingebetteten Integration hängt weniger vom iframe selbst ab als davon, wie Berechtigungen vor dem Öffnen aufgelöst werden. Apification nutzt Benutzer, Gruppen, Rollen und Sichtbarkeit als Kontrollen, um zu entscheiden, wer jedes Element einsehen oder ändern kann. In einer Integration müssen diese Kontrollen mit deinem Produkt abgestimmt werden: Wenn ein Kunde nur ein Projekt sehen darf, darf die eingebettete Sitzung ihm nicht erlauben, zu Ressourcen eines anderen Kunden zu navigieren, selbst wenn er eine Kennung kennt oder Parameter in der URL manipuliert.

Auch das visuelle Theme sollte vom Server aufgelöst werden, wenn die eingebettete Sitzung vorbereitet wird, weil es Teil des kontrollierten Erlebnisses ist. Auf Browserseite solltest du standardisierte iframe-Attribute als Teil der Oberflächenabsicherung betrachten: allow definiert eine Permissions Policy für nach Ursprung verfügbare Funktionen, und sandbox kann Einschränkungen für den eingebetteten Inhalt erzwingen. Die allgemeine Empfehlung lautet, dem Client nicht als Quelle für Berechtigungen zu vertrauen und bei sandbox-Kombinationen vorsichtig zu sein, die ihren Sicherheitswert in Same-Origin-Szenarien aufheben.

• Prüfe Benutzer, Gruppe, Rolle und Sichtbarkeit, bevor du öffnest oder Aktionen ausführst.
• Akzeptiere Berechtigungen, Theme oder endgültigen Umfang nicht nur aus Client-Parametern.
• Beschränke iframe-Funktionen auf das, was für das Erlebnis nötig ist.
• Prüfe, dass Downloads von Originalen oder transformierten Dateien zum richtigen Benutzer gehören.

Beispielabläufe: Auswahl, Transformation und Download

Ein eingebetteter Auswahlablauf kann so funktionieren: Der Benutzer betritt dein Portal, wählt ein Projekt aus und klickt auf „Dateien öffnen“. Dein Backend validiert, dass dieser Benutzer zum Projekt gehört, und fordert eine eingebettete Sitzung mit passenden effektiven Berechtigungen an. Das Frontend fügt das iframe ein und kann über begrenzte JavaScript-Kommunikation mit dem Host ein Auswahl- oder Schließsignal empfangen. Die anschließende Aktion sollte sich nicht blind auf eine vom Browser gesendete ID stützen; das Backend muss prüfen, dass das ausgewählte Element zum erlaubten Bereich gehört.

Ein Transformationsablauf folgt einer anderen Logik. Der Benutzer fordert über eine Aktion deines Produkts an, ein Dokument, Bild, Video, Audio oder Datum zu konvertieren, aufzuteilen, zusammenzuführen, zu optimieren oder zu verarbeiten. Das Backend validiert Eigentümer und Berechtigung, ruft die REST-API auf, um den asynchronen Auftrag des File Transformer zu erstellen, und registriert intern den Status „in Bearbeitung“. Wenn das Ergebnis verfügbar ist, sollte der Benutzer über ein authentifiziertes Ergebnis darauf zugreifen, nicht über interne Speicherpfade. Wenn sich die Originaldatei ändert, hilft die Element- und Versionshistorie von Cloud dabei, eine organisierte Quelle zu bewahren.

• Auswahl: eingebettete Sitzung, begrenzte Auswahl und anschließende Validierung im Backend.
• Transformation: Berechtigung, asynchroner Auftrag, sichtbarer Status und authentifiziertes Ergebnis.
• Download: Original oder transformierte Datei nur für den autorisierten Benutzer oder die autorisierte Gruppe.

Webhooks und asynchrone Aktionen ohne Duplikate

Die Webhooks von Apification ermöglichen es, auf relevante Ereignisse zu reagieren, ohne Ressourcen oder Hintergrundaufträge kontinuierlich abzufragen. Sie enthalten mit HMAC signierte Payloads, Zustellhistorie, Wiederholungsversuche und Ereignisse für abgeschlossene Transformationen. Um sie richtig zu verwenden, benötigst du einen erreichbaren und stabilen HTTPS-Endpunkt. Dieser Endpunkt sollte nicht einfach jede Nutzlast akzeptieren: Er muss die Signatur validieren, das empfangene Ereignis protokollieren und es mit dem Auftrag oder der Ressource verknüpfen, die dein Backend zuvor erstellt hat.

Da es Wiederholungsversuche gibt, muss dein Empfänger idempotent sein. In der Praxis registrierst du einen Zustellschlüssel oder eine Ereignisreferenz und verhinderst, dass dieselbe abgeschlossene Transformation dieselbe Geschäftsaktion zweimal auslöst. Außerdem empfiehlt es sich, den technischen Status vom sichtbaren Status zu trennen: „empfangen“, „wird verarbeitet“, „abgeschlossen“ oder „fehlgeschlagen“ in deinen internen Aufzeichnungen; „deine Datei wird vorbereitet“ oder „die Transformation konnte nicht abgeschlossen werden“ in der Oberfläche. So versteht der Benutzer den Fortschritt, ohne interne Details oder Speicherpfade zu sehen.

• Verlange einen stabilen HTTPS-Endpunkt für den Webhook.
• Validiere HMAC, bevor du der Payload vertraust.
• Speichere Zustellhistorie und Verarbeitungsergebnis.
• Sorge dafür, dass der Handler bei Wiederholungen idempotent ist.

Fehlerfälle und Checkliste vor der Produktion

Die gefährlichsten Fehler entstehen, wenn das Team versucht, die Integration zu vereinfachen, indem es das Backend umgeht. Ein API-Schlüssel in JavaScript kann aus dem Client extrahiert werden. Ein generischer Proxy, der jede Operation an die API weiterleitet, kann Berechtigungen unbeabsichtigt erweitern. Ein Endpunkt, der IDs vertraut, die vom Browser gesendet werden, gerät in Probleme mit Autorisierung auf Objektebene: Der Benutzer ändert eine Kennung und greift auf eine fremde Ressource zu. Dieselbe Logik gilt für Eigenschaften: Nicht jedes Feld, das vom Client kommt, sollte als bearbeitbar akzeptiert werden.

Es gibt auch operative Fehler. Wenn du laufende Aufträge, Integrationsfehler oder fehlgeschlagene Transformationen nicht protokollierst, sieht der Benutzer nur Stille. Wenn du schwere Aktionen nicht begrenzt, kannst du unbeabsichtigten Ressourcenverbrauch erleichtern. Wenn du Einbettung nicht von Import aus externen Quellen unterscheidest, kannst du eine Synchronisierung versprechen, die nicht zutrifft. Prüfe vor der Produktion, dass dein Backend die einzige Komponente mit Zugangsdaten ist, dass jede Aktion Eigentümer und Berechtigung validiert und dass Originale und transformierte Ergebnisse eine einzige Quelle der Wahrheit in Cloud beibehalten.

• Zugangsdaten: kein API-Schlüssel im Browser.
• Autorisierung: Objekt, Eigentümer, Gruppe, Rolle und Sichtbarkeit im Backend validieren.
• Scopes: nur erforderliche Lese- und Schreibrechte gewähren.
• Proxy: nur die von deinem Produkt vorgesehenen Operationen erlauben.
• Asynchronität: Aufträge, Webhooks, Wiederholungen und für den Support sichtbare Fehler protokollieren.
• Ressourcen: schwere Aktionen kontrollieren und doppelte Ausführungen vermeiden.
• Benutzermeldungen: verständliche Status anzeigen, ohne interne Details offenzulegen.

Häufige Fragen