Tokens federados

Un token federado es una credencial de corta duración que tu servidor genera con su propia credencial y entrega al código al que no le confías esa credencial: una página web, una app móvil, un reproductor de video o un cliente que se comunica con una cámara de tu red local. El token actúa con la misma organización y el mismo rol que la credencial que lo generó, hasta que vence o hasta que se revoca esa credencial.

Generar un token

Llama a POST /api/org/generateFederatedSessionToken desde tu servidor:

curl -X POST "https://api2.rhombussystems.com/api/org/generateFederatedSessionToken" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: $RHOMBUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"durationSec": 3600, "deviceUUid": "CAMERA_UUID"}'

// Tu backend: primero autentica a tu propio usuario y luego genera un token para la página que usa.
app.post("/api/federated-token", requireUser, async (req, res) => {
  const r = await fetch(
    "https://api2.rhombussystems.com/api/org/generateFederatedSessionToken",
    {
      method: "POST",
      headers: {
        "x-auth-scheme": "api-token",
        "x-auth-apikey": process.env.RHOMBUS_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        durationSec: 3600,
        deviceUUid: req.body.cameraUuid,
        domain: "https://app.example.com", // el origen de la página que usa el token
      }),
    },
  );
  if (!r.ok) return res.status(502).json(await r.json());
  const { federatedSessionToken, expiresAtMs } = await r.json();
  res.json({ federatedSessionToken, expiresAtMs });
});

import os
import requests

res = requests.post(
    "https://api2.rhombussystems.com/api/org/generateFederatedSessionToken",
    headers={
        "x-auth-scheme": "api-token",
        "x-auth-apikey": os.environ["RHOMBUS_API_KEY"],
        "Content-Type": "application/json",
    },
    json={"durationSec": 3600, "deviceUUid": "CAMERA_UUID"},
)
res.raise_for_status()
body = res.json()
token = body["federatedSessionToken"]
expires_at_ms = body["expiresAtMs"]

Respuesta:

{ "federatedSessionToken": "AAAAAAAAAAAAAAAAAAAAAA", "expiresAtMs": 1792371600000 }

Campos

Puedes generarlo con una clave de API, con un access token de OAuth (el token actúa como el usuario que inició sesión) o con una credencial de partner más x-auth-org (el token pertenece a esa organización cliente). Un token federado no puede generar otro token federado (403), y las sesiones de la consola (navegador) no pueden generar tokens federados.

Usar un token

Envía el esquema y el token como x-auth-scheme: federated-token y x-auth-ft: <token>, como encabezados o como parámetros de consulta. Los mismos dos valores funcionan en todas partes:

Los navegadores no pueden definir encabezados en un <img>, un <video> ni un WebSocket, así que en esos casos pon ambos valores en la URL:

<!-- Una instantánea de cámara en una página web -->
<img src="https://media.rhombussystems.com/media/CAMERA_UUID/MEDIA_REGION/snapshot.jpeg?x-auth-scheme=federated-token&x-auth-ft=TOKEN" />

Medios y transmisiones muestra cada tipo de URL de medios con el token agregado, incluidos los reproductores HLS, DASH y WebSocket.

El campo domain

domain vincula un token a un origen web. Un token con domain solo funciona cuando el encabezado Origin de la solicitud coincide con él o, si la solicitud no tiene Origin, cuando coincide su Referer. Cualquier otro caso, incluida una solicitud sin ninguno de los dos encabezados, recibe 403 DOMAIN_NOT_ALLOWED. Rhombus lo verifica en la API REST, los hosts de medios y el WebSocket de eventos. Un token sin domain no se verifica.

Los navegadores envían Origin en las llamadas fetch, las solicitudes entre orígenes y los handshakes de WebSocket, y un Referer en imágenes y video, a menos que la política de referencia de la página lo suprima. Los servidores, los reproductores nativos y las apps móviles normalmente no envían ninguno de los dos.

Al generar el token, domain debe ser un origen absoluto http o https, como https://app.example.com. Un valor que no lo es (example.com, .example.com) se rechaza con 400.

Cuál usar:

domain limita el uso desde un navegador; no protege un token robado, porque cualquier cosa fuera de un navegador puede enviar el Origin o el Referer que quiera. Lo que limita un token filtrado son las vigencias cortas, deviceUUid y la revocación.

Vigencia y renovación

• Un token funciona hasta expiresAtMs: durationSec después de generarse, una hora de forma predeterminada y 24 horas como máximo. Las apps de dispositivos de Rhombus (TV, videowall, quiosco, teclado y estación de puerta) pueden generar tokens de hasta 30 días; ningún token federado dura más de 30 días.
• Un token deja de funcionar antes cuando se revoca la credencial que lo generó: se elimina la clave de API, se revoca la autorización de OAuth o termina la sesión de la app móvil. También puedes revocar un token tú mismo.
• Las cámaras de tu LAN guardan en caché una verificación exitosa, así que un token puede seguir funcionando ahí hasta un minuto después de vencer.
• Los tokens están vinculados a una región: un token generado en hosts de EE. UU. solo funciona en hosts de EE. UU.

Renuévalo desde tu backend antes de que venza. Un cliente que recibió un token de una hora pide uno nuevo a los 54 minutos, aproximadamente, y lo reemplaza en sus URL:

async function getToken() {
  const r = await fetch("/api/federated-token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ cameraUuid }),
  });
  const { federatedSessionToken, expiresAtMs } = await r.json();
  setTimeout(getToken, (expiresAtMs - Date.now()) * 0.9); // renueva al 90% de la vigencia restante
  useToken(federatedSessionToken);
}

El React SDK hace esto por ti: llama al endpoint de tokens de tu backend y renueva el token antes de que venza.

Revocar un token

Para terminar un token antes de que venza, por ejemplo cuando tu usuario cierra sesión, llama a POST /api/org/revokeFederatedSessionToken con el token. Llámalo con cualquier credencial de la organización del token: el propio token federado (así un navegador puede revocar su token cuando su usuario cierra sesión), la clave de API de tu servidor o un token de OAuth; la sesión de la consola en el navegador no puede. Solo revoca tokens de la organización de quien llama y siempre devuelve 200, sea que el token siguiera vigente o no, así que es seguro llamarlo en cada cierre de sesión:

curl -X POST "https://api2.rhombussystems.com/api/org/revokeFederatedSessionToken" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: $RHOMBUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"federatedSessionToken": "TOKEN"}'

Lista de verificación de seguridad

• Genera tokens solo en tu servidor. Nunca pongas en un navegador o una app la clave de API que genera los tokens.
• Genera tokens con una credencial cuyo rol cubra solo lo que el cliente necesita; el token hereda ese rol. Consulta Permisos y rotación de claves.
• Usa deviceUUid siempre que el cliente necesite una sola cámara.
• Define domain con el origen de tu página para los tokens que se usan en una página web.
• Mantén durationSec corto, renueva antes de expiresAtMs y revoca los tokens cuando tu usuario cierra sesión.
• Trata un token como una contraseña mientras esté vigente: no lo registres en logs, y no pongas URL que contengan tokens en herramientas de analítica ni en reportes de errores.