Inicio rápido

Complete un «handshake de identidad» completo con la menor cantidad de código posible: cuando un usuario del espacio de trabajo abre la app de extensión de tu organización, se transmite su información de identidad, para que el backend de tu app de extensión pueda identificar correctamente la identidad del usuario actual y obtener su información de identidad.

• La dirección de GitHub del Workspace-Extension-SDK es: https://github.com/GPTBOTS/Workspace-Extension-SDK
• Para el inicio de sesión pull, consulta 04-Inicio de sesión pull.

El siguiente tutorial rápido utiliza el modo push (Push) para una demostración sencilla:

Requisito previo: obtener la clave

Primero debes obtener la clave de firma HS256 de la app de extensión de la organización, que se utiliza para completar el handshake de identidad de la app de extensión de la organización.

• Pide al OWNER/ADMIN del espacio de trabajo que acceda a Espacio de trabajo → Gestión del espacio → Apps de extensión y haga clic en «Añadir»
• Nombre de la app, icono de la app, URL de entrada de la app (app_home_url)
• En el modo de autenticación, selecciona workspace_account (requiere transmitir la identidad)
• Tras enviar, el sistema muestra el App Secret en texto plano una única vez; cópialo y guárdalo de inmediato, ya que una vez cerrado no podrás volver a verlo, solo rotarlo.

La clave tiene la forma wext_ + 64 dígitos hexadecimales (Tier 2). Guárdala únicamente en tu backend (variables de entorno / servicio de gestión de secretos); nunca la escribas en el frontend, en git ni en los logs.

Paso 1: Backend — el endpoint que verifica el token

Crea un nuevo endpoint de backend que reciba el wsa enviado por POST desde el frontend, lo verifique con la clave y, tras el éxito, establezca tu propia sesión.

                      
                      // Ejemplo con 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, // tu clave (solo en el backend)
      audience: 'app.example.com',              // el host de tu app, debe ser igual al aud del token
    });
    // identity = { accountId, role, workspaceId, username?, email?, avatar?, appName?, issuedAt?, expiresAt? }

    const sid = createYourSession(identity);    // reemplaza por tu propia sesión
    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 });             // ante un fallo de verificación, siempre rechazar
  }
});

                    

verifyWsa verifica en orden: firma → iss → aud → exp (incluidos iat/nbf) → claims obligatorios. Si cualquiera falla, lanza WsaVerificationError. Para más detalles, consulta 06-Referencia de la API del SDK.

Paso 2: Frontend — la página de aterrizaje consume el token

La plataforma lleva al usuario a tu app_home_url?wsa=<JWT>. En esta página de aterrizaje, lee el wsa, hazle POST a tu propio backend y luego elimínalo de la URL.

                      
                      // tu página de aterrizaje
import { consumeHandoff } from '@gptbots/workspace-extension-sdk';

const identity = await consumeHandoff({ exchangeUrl: '/session/exchange' });
// consumeHandoff hace, en orden:
// 1) lee el ?wsa= de la URL actual
// 2) hace POST { wsa } a /session/exchange (aquí tu backend ejecuta verifyWsa)
// 3) tras el éxito, elimina el ?wsa= de la URL con history.replaceState
// 4) devuelve el identity que tu backend retornó

console.log('Usuario actual del espacio de trabajo:', identity.username, identity.role);
if (identity.role === 'MEMBER') hideAdminUI();

                    

Así, con dos fragmentos de código, has completado un handshake de identidad seguro.

El flujo completo en un diagrama

                      
                      Página «Extensiones» del espacio de trabajo    Plataforma GPTBots         Tu app
────────────────                               ───────────                ────────
El usuario hace clic en el icono de tu app ──▶ Verifica que quien hace clic es miembro de ese espacio de trabajo
                                               Firma con la clave un wsa (JWT) válido durante 5 minutos
Abre https://app.example.com/?wsa=<JWT> ─────────────────────────────────▶ página de aterrizaje
                                                                     consumeHandoff()
                                          ◀── POST /session/exchange { wsa } ──
                                                                     tu backend verifyWsa() → identity
                                                                     establece la sesión propia
                                                                     elimina el ?wsa= de la URL

                    

Consejos para pruebas de integración locales

• El wsa solo es válido durante 5 minutos y es un token de arranque de un solo uso: una vez canjeado por tu propia sesión, no vuelvas a enviar el wsa en las peticiones posteriores.
• El audience debe ser exactamente igual al host que registraste (app.example.com); el puerto/protocolo no participan en el aud, pero el host debe coincidir, de lo contrario obtendrás WrongAudience.
• Ante un fallo de verificación, revisa primero el WsaVerificationError.code (InvalidSignature / Expired / WrongAudience …) y compáralo con 07-Preguntas frecuentes y solución de problemas.
• ¿Quieres solo leer la identidad para mostrarla, sin crear una sesión? Simplemente reemplaza consumeHandoff por readHandoffToken() (consulta 02 Niveles de uso de la identidad).
  Siguiente paso: lee 02-Conceptos clave para comprender el contrato del token y los dos modos, o ve directamente a 03-Integración push / 04-Inicio de sesión pull para ver todos los detalles.
  Integra tu propio sistema web como una «app de extensión» en el espacio de trabajo de GPTBots. Cuando un usuario del espacio de trabajo abre tu app desde Espacio de trabajo → Extensiones (Extensions), GPTBots te transfiere de forma segura la identidad del espacio de trabajo del usuario mediante un token de firma de corta duración (wsa, un JWT); tu app, en base a ello, identifica al usuario sin necesidad de inicio de sesión y habilita funciones según el rol.

Navegación por el índice

Vista general del SDK

El SDK oficial son dos paquetes independientes del framework y sin dependencias en tiempo de ejecución (ambos están en el paquete comprimido workspace-extension-sdk-0.1.0.zip):

Si no quieres usar el SDK, también es posible: el wsa es un JWT HS256 estándar, y cualquier librería JWT de cualquier lenguaje puede verificarlo. Consulta 05-Verificación de token y seguridad.

Instalación local desde el paquete comprimido

                      
                      # Tras descomprimir, ambos paquetes incluyen un dist preconstruido y pueden usarse como dependencia local directamente:
unzip workspace-extension-sdk-0.1.0.zip
npm i ./workspace-extension-sdk/packages/verify   # backend
npm i ./workspace-extension-sdk/packages/browser  # frontend

                    

Una vez que el SDK se publique en npm, podrás usar directamente npm i @gptbots/workspace-extension-verify / npm i @gptbots/workspace-extension-sdk.

Lista de comprobación previa a la integración

• Has confirmado que ya creaste la app de extensión de la organización y obtuviste la clave correspondiente
• Has decidido el modo de integración: push o pull (M-Auth)
• El app_home_url (push) / el host del redirect_uri (pull) coinciden exactamente con la información de registro
• El backend ya implementa la verificación del wsa: los cuatro elementos obligatorios firma + iss + aud + exp
• Tras el aterrizaje, elimina de inmediato el wsa / code de la URL con history.replaceState
• Ya has canjeado el token por la sesión propia de la app, y las peticiones posteriores ya no transmiten el wsa
• El reloj del servidor de la app ya está sincronizado por NTP