Referencias públicas y arranque seguro

Trata una referencia pública como un identificador y una aserción de inicialización como una credencial. La aplicación puede configurar en el cliente una referencia pública externalAgentRef, pero solo un servidor autenticado debería generar la aserción firmada que acredita al usuario actual. Después, el SDK crea una sesión cuyo token debe protegerse como una credencial portadora.

El navegador, el servidor, el agente, el resultado y las rutas de sesión y error marcan límites distintos de la integración.

Distingue los identificadores de las credenciales

Una referencia pública señala un recurso del entorno de ejecución de agentes externos. El registro de sesión que guarda el SDK incluye referencias públicas como externalAgentRef, sessionRef y, cuando existen, externalUserRef o workspaceBindingRef. Esas referencias no reemplazan la autenticación de la persona ni convierten una solicitud del navegador en una solicitud autorizada.

La aserción de inicialización cumple otra función. La guía de primeros pasos la describe como una cadena breve que produce y firma tu servidor para acreditar al usuario final actual. El SDK la solicita mediante getBootstrapAssertion; no la crea ni la firma. Mantén en el servidor la credencial que firma las aserciones y autentica a la persona en el endpoint que genera una.

Hay un tercer valor que proteger en el almacenamiento de sesiones: el token de sesión. getStoredSession() devuelve metadatos públicos de la sesión sin el token, pero el registro guardado que utiliza el adaptador RuntimeStorage sí lo incluye. Cualquiera que pueda leer ese almacenamiento puede actuar como esa sesión hasta que caduque o se revoque. El SDK usa almacenamiento en memoria de forma predeterminada; conservar datos de manera persistente es una decisión deliberada de seguridad y producto.

Sigue una sesión del navegador

En un portal interno de solicitudes, imagina que una persona inicia sesión, abre un asistente de servicio y consulta el estado de la solicitud SR-204. La aplicación puede exponer una referencia pública del agente al cliente del navegador. El servidor debe verificar a la persona antes de generar la aserción, y el asistente solo debe recibir la política y las herramientas configuradas para su tarea.

1. Autentica a la persona en el servidor. Vincula la solicitud de aserción con la sesión de usuario de la aplicación; no aceptes una identidad indicada únicamente en los datos del navegador.
2. Devuelve una aserción, no el secreto de firma. La función de retorno del SDK llama al endpoint autenticado y devuelve la cadena de aserción. Nunca incluyas en el paquete del cliente ni en la respuesta la credencial que la firma.
3. Crea o reutiliza una sesión. ensure() obtiene una aserción cuando la necesita y guarda el token de sesión. Si ya existe una sesión guardada y válida, la reutiliza sin llamar a la función de retorno de aserción.
4. Elige dónde guardar la sesión. La opción predeterminada es la memoria. Si necesitas persistencia, evalúa qué scripts y usuarios pueden leer el adaptador. Usa una storageKey distinta para cada agente integrado en la misma página.
5. Finaliza la sesión de forma intencional. Al cerrar la sesión, llama al método de revocación del servidor y elimina los datos de sesión guardados localmente según el ciclo de vida de la aplicación.

Comprobación de límites (portal ficticio)

Configuración del navegador: Solo la referencia pública externalAgentRef.

Comprobación del servidor: La persona está autenticada antes de generar la aserción.

Sesión: ensure() devuelve una sessionRef pública; la credencial de firma permanece en el servidor.

Almacenamiento: En memoria durante esta visita breve; no se configura un adaptador persistente de sesiones.

Registro consultado: El registro aprobado del sistema de servicio SR-204 tiene el estado «En revisión».

Resultado: Después de consultar el registro, el agente muestra a la persona el estado «En revisión». No muestra la clave que firma la aserción ni el token de sesión.

El ejemplo supone que el agente dispone de otra vía autorizada para consultar la solicitud. La referencia, la aserción y la sesión no le conceden una herramienta que la política del agente no expone.

Revisa el estado almacenado

Comprueba el valor exacto que puede leer cada capa: la configuración del navegador, la respuesta del endpoint de aserciones, la función de retorno del SDK, el contenido del adaptador y el objeto que devuelve getStoredSession(). No des por sentado que el token está ausente solo porque el método público no lo devuelve. Para ver la configuración completa, consulta primeros pasos y sesiones y almacenamiento. Continúa con cómo integrar un agente y espacios de trabajo y agentes externos.