Zum Hauptinhalt springen

API Proxy

Die API Proxy-Funktion ermöglicht es Ihnen, API-Aufrufe über den Widget Builder Server zu leiten, anstatt sie direkt vom Browser des Benutzers auszuführen. Dadurch bleiben sensible Daten wie API-Schlüssel, Authentifizierungs-Tokens und Endpunkt-URLs vor Endnutzern verborgen.

Warum den API Proxy verwenden?​

Wenn ein Widget eine API-Anfrage direkt vom Browser aus durchführt, ist alles im Netzwerk-Inspektor des Browsers sichtbar: die URL, Header, der Request-Body sowie alle enthaltenen Tokens oder API-Schlüssel. Jeder mit geöffneten Entwicklertools kann diese Daten einsehen.

Mit aktiviertem API Proxy ändert sich der Anfrage-Fluss:

Browser  -->  Widget Builder Server  -->  Externe API
Browser  <--  Widget Builder Server  <--  Externe API

Der Browser sieht nur eine Anfrage an den Widget Builder Server. Die tatsächliche externe API-URL, Header (einschließlich Authentifizierungs-Tokens) und Request-Body-Details werden dem Client niemals offengelegt.

Wichtige Vorteile​

  • Verborgene Zugangsdaten -- API-Schlüssel, Bearer-Tokens und Authentifizierungs-Header verbleiben auf dem Server
  • Verborgene Endpunkte -- Die tatsächliche API-URL ist im Browser nicht sichtbar
  • Keine CORS-Probleme -- Da die Anfrage vom Server kommt, gelten keine Browser-CORS-Einschränkungen
  • Serverseitiges Handlebars -- Handlebars Helpers wie {{staffbaseIdToken}} und {{staffbaseAccessToken}} werden auf dem Server aufgelöst, sodass Token-Werte niemals an den Browser gesendet werden

So aktivieren Sie den Proxy​

Aktivieren Sie im API-Anfrageformular (entweder im eigenständigen API-Bereich oder im API-Panel eines Widgets) den Schalter "Route using Widget Builder".

Das ist alles, was Sie tun müssen. Wenn der Schalter aktiviert ist, schreibt der Widget Builder die Anfrage automatisch so um, dass sie zur Laufzeit über den Server geleitet wird.

Was wird verborgen​

Wenn der Proxy-Modus aktiv ist, sind folgende Informationen für den Browser des Endnutzers niemals sichtbar:

Vor dem Browser verborgenBeispiel
API-Endpunkt-URLhttps://api.example.com/v2/data
Request-HeaderAuthorization: Bearer sk-secret-key-123
Authentifizierungs-Tokens{{staffbaseIdToken}}, {{staffbaseAccessToken}}
Integrations-Tokens{{microsoftAccessToken}}, {{googleAccessToken}}, etc.
Request-Body-InhaltAlle sensiblen Daten in POST/PUT-Request-Bodies

Der Browser sieht nur eine POST-Anfrage an den eigenen /api/proxy/...-Endpunkt des Widget Builders.

Funktionsweise im Detail​

Wenn der Proxy für eine API-Anfrage aktiviert ist, transformiert der Widget Builder die API-Konfiguration des Widgets zur Auslieferungszeit:

  1. Die ursprüngliche URL, Methode, Header und der Body werden in der Datenbank gespeichert, aber nicht an den Browser gesendet
  2. Stattdessen erhält das Widget eine umgeschriebene Anfrage, die auf den Proxy-Endpunkt des Widget Builders zeigt
  3. Zur Laufzeit sendet das Widget eine POST-Anfrage an den Widget Builder Server
  4. Der Server sucht die ursprüngliche API-Konfiguration heraus, löst alle Handlebars-Templates (einschließlich Authentifizierungs-Tokens) auf und führt die eigentliche Anfrage an die externe API durch
  5. Die Antwort wird an den Browser weitergeleitet

Handlebars im Proxy-Modus​

Handlebars Helpers funktionieren serverseitig, wenn der Proxy aktiviert ist. Dies ist besonders wichtig für Authentifizierungs-Helpers:

  • {{staffbaseIdToken}} -- Wird aus der authentifizierten Sitzung des Benutzers auf dem Server aufgelöst
  • {{staffbaseAccessToken}} -- Wird aus dem Access-Token-Header auf dem Server aufgelöst
  • {{microsoftAccessToken}}, {{googleAccessToken}}, {{boxAccessToken}}, {{atlassianAccessToken}}, {{serviceNowAccessToken}} -- Integrations-Tokens, die auf dem Server aufgelöst werden

Da diese serverseitig aufgelöst werden, erscheinen die tatsächlichen Token-Werte niemals im Netzwerkverkehr des Browsers.

Alle anderen Handlebars Helpers (wie {{json ...}}, {{encode ...}}, {{formatDate ...}}) funktionieren ebenfalls im Proxy-Modus, da die vollständige Handlebars-Engine auf dem Server läuft, bevor die ausgehende Anfrage gesendet wird.

Einschränkungen​

  • Ratenlimitierung -- Proxy-Anfragen sind ratenlimitiert (standardmäßig 300 Anfragen pro 60-Sekunden-Fenster pro Client). Dies schützt vor Missbrauch, kann aber Widgets mit hohem Traffic beeinflussen
  • Weiterleitungsbehandlung -- Der Proxy folgt automatisch bis zu 5 Weiterleitungen. Weiterleitungsantworten (3xx) werden als 200-Antworten mit Weiterleitungs-Metadaten verpackt und zurückgegeben, um zu verhindern, dass der Browser ihnen folgt
  • Antwort-Weiterleitung -- Nur bestimmte Antwort-Header werden an den Browser weitergeleitet: Content-Type, Content-Disposition, Content-Length, Ratenlimit-Header und Location
  • Nur Proxy-Anfragen -- Der Proxy funktioniert nur für API-Anfragen, die innerhalb des Widget Builders definiert sind. Sie können ihn nicht für beliebige externe Aufrufe aus benutzerdefiniertem JavaScript verwenden

Wann den Proxy verwenden​

Verwenden Sie den Proxy, wenn:

  • Ihre API-Anfrage API-Schlüssel, Geheimnisse oder Authentifizierungs-Tokens in Headern oder im Body enthält
  • Sie die tatsächliche API-Endpunkt-URL vor Endnutzern verbergen möchten
  • Die externe API kein CORS unterstützt und nicht direkt vom Browser aufgerufen werden kann
  • Sie Staffbase- oder Drittanbieter-Integrations-Tokens verwenden, die nicht exponiert werden sollten

Direkte Anfragen sind ausreichend, wenn:

  • Die API öffentlich ist und keine Authentifizierung erfordert
  • CORS für Ihre Domain korrekt konfiguriert ist
  • Keine sensiblen Daten in der Anfrage enthalten sind