Démarrage rapide

Réalisez une « poignée de main d'identité » complète avec un minimum de code : lorsqu'un utilisateur de l'espace de travail ouvre l'application d'extension de votre organisation, ses informations d'identité sont transmises, ce qui permet au backend de l'application d'extension du développeur d'identifier correctement l'utilisateur courant et de récupérer ses informations d'identité.

• L'adresse GitHub du Workspace-Extension-SDK est : https://github.com/GPTBOTS/Workspace-Extension-SDK
• Pour la connexion pull, voir 04-Connexion pull.

Le tutoriel rapide ci-dessous utilise le mode push (Push) pour une démonstration simple :

Prérequis : obtenir la clé

Vous devez d'abord obtenir la clé de signature HS256 de l'application d'extension de votre organisation, qui sert à réaliser la poignée de main d'identité de l'application d'extension.

• Demandez au OWNER/ADMIN de l'espace de travail d'accéder à Espace de travail → Gestion de l'espace → Applications d'extension, puis de cliquer sur « Ajouter »
• Nom de l'application, icône de l'application, URL d'accès de l'application (app_home_url)
• Choisissez workspace_account comme mode d'authentification (nécessite la transmission de l'identité)
• Après validation, le système affiche une seule fois l'App Secret en clair ; copiez-le et sauvegardez-le immédiatement — une fois la fenêtre fermée, il ne peut plus être consulté, seulement renouvelé.

La clé a la forme wext_ + 64 caractères hexadécimaux (Tier 2). Conservez-la uniquement dans votre backend (variables d'environnement / service de gestion des secrets), ne l'écrivez jamais dans le frontend, git ou les logs.

Étape 1 : Backend — l'interface de vérification du jeton

Créez une nouvelle interface backend qui reçoit le wsa envoyé en POST par le frontend, le vérifie avec la clé, puis établit votre propre session en cas de succès.

                      
                      // Exemple Node / Express
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, // votre clé (uniquement dans le backend)
      audience: 'app.example.com',              // le host de votre application, doit être égal au aud du jeton
    });
    // identity = { accountId, role, workspaceId, username?, email?, avatar?, appName?, issuedAt?, expiresAt? }

    const sid = createYourSession(identity);    // remplacez par votre propre session
    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 });             // tout échec de vérification est rejeté
  }
});

                    

verifyWsa vérifie dans l'ordre : signature → iss → aud → exp (avec iat/nbf) → claims obligatoires. Tout échec lève une WsaVerificationError. Voir en détail 06-Référence de l'API SDK.

Étape 2 : Frontend — la page d'atterrissage consomme le jeton

L'utilisateur est amené par la plateforme vers votre app_home_url?wsa=<JWT>. Sur cette page d'atterrissage, lisez le wsa, envoyez-le en POST à votre propre backend, puis effacez-le de l'URL.

                      
                      // Votre page d'atterrissage
import { consumeHandoff } from '@gptbots/workspace-extension-sdk';

const identity = await consumeHandoff({ exchangeUrl: '/session/exchange' });
// consumeHandoff effectue successivement :
// 1) lit le ?wsa= de l'URL courante
// 2) POST { wsa } vers /session/exchange (votre backend y appelle verifyWsa)
// 3) en cas de succès, efface le ?wsa= de l'URL via history.replaceState
// 4) retourne l'identity renvoyée par votre backend

console.log('Utilisateur courant de l\'espace de travail :', identity.username, identity.role);
if (identity.role === 'MEMBER') hideAdminUI();

                    

Voilà, deux fragments de code suffisent pour réaliser une poignée de main d'identité sécurisée.

Vue d'ensemble du flux complet

                      
                      Page « Extensions » de l'espace de travail      Plateforme GPTBots         Votre application
────────────────                                ───────────                ────────
L'utilisateur clique sur l'icône ─────────────▶ Vérifie que le cliqueur est membre de cet espace de travail
                                                Signe avec la clé un wsa (JWT) valable 5 minutes
Ouvre https://app.example.com/?wsa=<JWT> ────────────────────────────▶ Page d'atterrissage
                                                                     consumeHandoff()
                                                ◀── POST /session/exchange { wsa } ──
                                                                     Votre backend verifyWsa() → identity
                                                                     Établit sa propre session
                                                                     Efface le ?wsa= de l'URL

                    

Astuces pour le débogage local

• Le wsa n'est valable que 5 minutes ; c'est un jeton d'amorçage à usage unique — une fois échangé contre votre propre session, ne renvoyez plus le wsa dans les requêtes suivantes.
• L'audience doit être exactement égale au host que vous avez enregistré (app.example.com) ; le port/protocole ne participent pas à aud, mais le host doit être identique, sinon WrongAudience.
• En cas d'échec de vérification, regardez d'abord le WsaVerificationError.code (InvalidSignature / Expired / WrongAudience …), et référez-vous à 07-Questions fréquentes et dépannage.
• Vous voulez seulement lire l'identité pour l'affichage, sans créer de session ? Remplacez consumeHandoff par readHandoffToken() (voir 02 Trois niveaux de consommation).
  Étape suivante : lisez 02-Concepts clés pour comprendre le contrat de jeton et les deux modes, ou passez directement à 03-Intégration push / 04-Connexion pull pour tous les détails.
  Intégrez votre propre système web en tant qu'« application d'extension » dans l'espace de travail GPTBots. Lorsqu'un utilisateur de l'espace de travail ouvre votre application depuis Espace de travail → Extensions (Extensions), GPTBots transmet en toute sécurité l'identité d'espace de travail de l'utilisateur sous la forme d'un jeton signé à courte durée de vie (wsa, un JWT). Votre application peut ainsi identifier l'utilisateur sans connexion et ouvrir les fonctionnalités selon le rôle.

Navigation dans le sommaire

Aperçu du SDK

Le SDK officiel se compose de deux paquets indépendants du framework et sans dépendance d'exécution (tous deux inclus dans l'archive workspace-extension-sdk-0.1.0.zip) :

Vous pouvez aussi ne pas utiliser le SDK — le wsa est un JWT HS256 standard, vérifiable par n'importe quelle bibliothèque JWT dans n'importe quel langage. Voir 05-Vérification du jeton et sécurité.

Installation locale depuis l'archive

                      
                      # Après décompression, les deux paquets embarquent un dist pré-compilé et peuvent être ajoutés comme dépendances locales :
unzip workspace-extension-sdk-0.1.0.zip
npm i ./workspace-extension-sdk/packages/verify   # backend
npm i ./workspace-extension-sdk/packages/browser  # frontend

                    

Une fois le SDK publié publiquement sur npm, vous pourrez directement faire npm i @gptbots/workspace-extension-verify / npm i @gptbots/workspace-extension-sdk.

Liste de vérification préalable à l'intégration

• Vous avez confirmé avoir créé l'application d'extension de l'organisation et obtenu la clé correspondante
• Vous avez déterminé le mode d'intégration : push ou pull (M-Auth)
• Le host de app_home_url (push) / redirect_uri (pull) correspond exactement aux informations enregistrées
• Le backend implémente la vérification du wsa : les quatre vérifications obligatoires signature + iss + aud + exp
• Effacez immédiatement le wsa / code de l'URL avec history.replaceState après l'atterrissage
• Le jeton a été échangé contre la propre session de l'application, et les requêtes suivantes ne transmettent plus le wsa
• L'horloge du serveur de l'application est synchronisée par NTP