Schnellstart

Führen Sie mit minimalem Code einmal einen vollständigen „Identitäts-Handshake" durch – nachdem Nutzer:innen eines Workspace Ihre Organisations-Erweiterungs-App öffnen, werden die Identitätsinformationen übergeben, sodass das Backend der Erweiterungs-App der Entwickler:innen die aktuelle Nutzeridentität korrekt erkennen und die Nutzeridentitätsinformationen abrufen kann.

• Die GitHub-Adresse des Workspace-Extension-SDK lautet: https://github.com/GPTBOTS/Workspace-Extension-SDK
• Zum Pull-Login siehe 04-Pull-Login.

Das folgende Kurz-Tutorial verwendet zur einfachen Veranschaulichung den Push-Modus:

Voraussetzung: Schlüssel beschaffen

Sie müssen zunächst den HS256-Signaturschlüssel der Organisations-Erweiterungs-App beschaffen, um den Identitäts-Handshake der Organisations-Erweiterungs-App durchzuführen.

• Lassen Sie den OWNER/ADMIN des Workspace zu Workspace → Space-Verwaltung → Erweiterungs-Apps gehen und auf „Hinzufügen" klicken
• App-Name, App-Symbol, App-Einstiegs-URL (app_home_url)
• Wählen Sie als Authentifizierungsmodus workspace_account (Identität muss übergeben werden)
• Nach dem Absenden zeigt das System das App Secret einmalig im Klartext an. Kopieren und speichern Sie es sofort – nach dem Schließen kann es nicht erneut eingesehen, sondern nur rotiert werden.

Der Schlüssel hat die Form wext_ + 64-stelliger Hexadezimalwert (Tier 2). Speichern Sie ihn ausschließlich in Ihrem Backend (Umgebungsvariablen / Schlüsselverwaltungsdienst) und schreiben Sie ihn niemals ins Frontend, in Git oder in Logs.

Schritt 1: Backend – die Schnittstelle zur Token-Prüfung

Erstellen Sie eine neue Backend-Schnittstelle, die das vom Frontend per POST gesendete wsa entgegennimmt, es mit dem Schlüssel prüft und nach erfolgreicher Prüfung Ihre eigene Session aufbaut.

                      
                      // Node-/Express-Beispiel
import express from 'express';
import { verifyWsa, WsaVerificationError } from '@gptbots/workspace-extension-verify';

const app = express();
app.use(express.json());

app.post('/session/exchange', (req, res) => {
  try {
    const identity = verifyWsa(req.body.wsa, {
      secret: process.env.EXTENSION_APP_SECRET, // Ihr Schlüssel (nur im Backend)
      audience: 'app.example.com',              // Ihr App-Host, muss gleich dem Token-aud sein
    });
    // identity = { accountId, role, workspaceId, username?, email?, avatar?, appName?, issuedAt?, expiresAt? }

    const sid = createYourSession(identity);    // durch Ihre eigene Session ersetzen
    res.cookie('sid', sid, { httpOnly: true, secure: true, sameSite: 'lax' });
    res.json(identity);
  } catch (e) {
    const code = e instanceof WsaVerificationError ? e.code : 'Error';
    res.status(401).json({ code });             // bei Prüffehler grundsätzlich ablehnen
  }
});

                    

verifyWsa prüft in dieser Reihenfolge: Signatur → iss → aud → exp (inkl. iat/nbf) → Pflichtangaben. Schlägt eine davon fehl, wird ein WsaVerificationError geworfen. Details siehe 06-SDK-API-Referenz.

Schritt 2: Frontend – Landingpage konsumiert das Token

Nutzer:innen werden von der Plattform zu Ihrer app_home_url?wsa=<JWT> geleitet. Lesen Sie auf dieser Landingpage das wsa, senden Sie es per POST an Ihr eigenes Backend und entfernen Sie es anschließend aus der URL.

                      
                      // Ihre Landingpage
import { consumeHandoff } from '@gptbots/workspace-extension-sdk';

const identity = await consumeHandoff({ exchangeUrl: '/session/exchange' });
// consumeHandoff erledigt der Reihe nach:
// 1) Liest das ?wsa= aus der aktuellen URL
// 2) POST { wsa } an /session/exchange (Ihr Backend führt hier verifyWsa aus)
// 3) Entfernt bei Erfolg mit history.replaceState das ?wsa= aus der URL
// 4) Gibt die von Ihrem Backend zurückgesendete identity zurück

console.log('Aktuelle:r Workspace-Nutzer:in:', identity.username, identity.role);
if (identity.role === 'MEMBER') hideAdminUI();

                    

So einfach schließen diese beiden Code-Abschnitte einen sicheren Identitäts-Handshake ab.

Gesamtablauf auf einen Blick

                      
                      Workspace-Seite „Erweiterungen"           GPTBots-Plattform          Ihre App
────────────────                         ───────────                ────────
Nutzer:in klickt Ihr App-Symbol ──────▶ Prüft, ob Klickende:r Mitglied dieses Workspace ist
                                          Signiert mit dem Schlüssel ein 5 Minuten gültiges wsa (JWT)
Öffnet https://app.example.com/?wsa=<JWT> ──────────────────────────▶ Landingpage
                                                                     consumeHandoff()
                                          ◀── POST /session/exchange { wsa } ──
                                                                     Ihr Backend verifyWsa() → identity
                                                                     Baut eigene Session auf
                                                                     Entfernt ?wsa= aus der URL

                    

Tipps für lokales Debugging

• Das wsa ist nur 5 Minuten gültig und ist ein einmaliges Bootstrap-Token – nach dem Wechsel zur eigenen Session nicht mehr wsa an nachfolgende Anfragen anhängen.
• audience muss exakt gleich dem registrierten Host sein (app.example.com); Port/Protokoll fließen nicht in aud ein, aber der Host muss übereinstimmen, sonst WrongAudience.
• Schauen Sie bei einem Prüffehler zunächst auf WsaVerificationError.code (InvalidSignature / Expired / WrongAudience …) und gleichen Sie mit 07-Fehlerbehebung ab.
• Möchten Sie keine Session aufbauen und die Identität nur zur Anzeige lesen? Ersetzen Sie einfach consumeHandoff durch readHandoffToken() (siehe 02 Nutzungsstufen).
  Nächster Schritt: Lesen Sie 02-Kernkonzepte, um den Token-Vertrag und die beiden Modi zu verstehen, oder gehen Sie direkt zu 03-Push-Anbindung / 04-Pull-Login für die vollständigen Details.
  Binden Sie Ihr eigenes Web-System als „Erweiterungs-App" in den GPTBots-Workspace ein. Wenn Workspace-Nutzer:innen Ihre App über Workspace → Erweiterungen (Extensions) öffnen, übergibt GPTBots die Workspace-Identität der Nutzer:innen sicher an Sie in Form eines kurzlebigen signierten Tokens (wsa, ein JWT). Ihre App erkennt Nutzer:innen dadurch ohne erneute Anmeldung und schaltet Funktionen rollenbasiert frei.

Inhaltsverzeichnis

SDK-Überblick

Die offiziellen SDKs sind zwei framework-unabhängige Pakete ohne Laufzeitabhängigkeiten (beide im Archiv workspace-extension-sdk-0.1.0.zip):

Sie müssen das SDK nicht verwenden – wsa ist ein standardmäßiges HS256-JWT, das jede JWT-Bibliothek in jeder Sprache prüfen kann. Siehe 05-Token-Prüfung und Sicherheit.

Lokale Installation aus dem Archiv

                      
                      # Nach dem Entpacken bringen beide Pakete ein vorgebautes dist mit und können direkt lokal als Abhängigkeit eingebunden werden:
unzip workspace-extension-sdk-0.1.0.zip
npm i ./workspace-extension-sdk/packages/verify   # Backend
npm i ./workspace-extension-sdk/packages/browser  # Frontend

                    

Nach der öffentlichen Veröffentlichung des SDK auf npm können Sie direkt npm i @gptbots/workspace-extension-verify / npm i @gptbots/workspace-extension-sdk ausführen.

Abstimmungs-Checkliste vor der Integration

• Sichergestellt, dass Sie bereits eine Organisations-Erweiterungs-App erstellt und den zugehörigen Schlüssel erhalten haben
• Integrationsmodus festgelegt: Push oder Pull (M-Auth)
• app_home_url (Push) / Host der redirect_uri (Pull) stimmt vollständig mit den Registrierungsdaten überein
• Backend hat die wsa-Prüfung implementiert: die vier verpflichtenden Prüfungen Signatur + iss + aud + exp
• Nach dem Landen sofort mit history.replaceState das wsa / code aus der URL entfernen
• Token in die app-eigene Session umgewandelt, sodass nachfolgende Anfragen kein wsa mehr weiterreichen
• Die Serveruhr der Anwendung ist per NTP synchronisiert