SSO

Concepto

El SSO de Priority Hunter resuelve dos problemas: en el portal público, restringe votar y publicar a usuarios autenticados en tu app (el portal queda en solo lectura para el resto); y en el widget, hace que la identidad del votante sea verificable criptográficamente en lugar de declarada por el navegador.

El modelo es un secreto por organización: en Studio generas un secreto de firma que solo conoce tu backend (nosotros almacenamos únicamente una copia cifrada). Tu backend firma con él un JWT HS256 con los datos del usuario, y Priority Hunter lo verifica con ese mismo secreto.

Paso 1 — Configurar en Studio

Ve a Studio › Organization Settings › SSO. Ahí encontrarás:

Paso 2 — Construye tu endpoint de login

El SSO Login URL que configuraste arriba es un endpoint de tu app. Su trabajo:

# Your SSO Login URL, e.g. https://app.yourcompany.com/ph-sso
GET /ph-sso?returnTo=<callback-url>

1. read the returnTo query param
2. authenticate the visitor in YOUR app
   (existing session, or run your normal login flow first)
3. sign a JWT (HS256) with your Priority Hunter signing secret:
   { externalId, email, name }  — expires in ~24h
4. redirect the browser to:  returnTo + "&ssoToken=" + jwt

Node.js (jose)

// Node example (jose)
import { SignJWT } from "jose";

const secret = new TextEncoder().encode(PH_SIGNING_SECRET);
const token = await new SignJWT({ externalId: user.id, email: user.email, name: user.name })
  .setProtectedHeader({ alg: "HS256" })
  .setIssuedAt()
  .setExpirationTime("24h")
  .sign(secret);

res.redirect(returnTo + "&ssoToken=" + token);

Python (PyJWT)

# Python example (PyJWT)
import time
import jwt  # pip install pyjwt

token = jwt.encode(
    {
        "externalId": user.id,
        "email": user.email,
        "name": user.name,
        "iat": int(time.time()),
        "exp": int(time.time()) + 24 * 3600,
    },
    PH_SIGNING_SECRET,
    algorithm="HS256",
)

return redirect(f"{return_to}&ssoToken={token}")

Paso 3a — Usar el token en el widget

En el widget no hay redirección: tu página ya tiene sesión, así que genera el token en tu servidor (en el render o vía un endpoint propio) y pásalo a PH:

// Option A — pass the token at init time
PH('init', {
  widgetId: 'YOUR_WIDGET_ID',
  ssoToken: '<token-from-your-server>',
});

// Option B — pass it with identify (e.g. after an async fetch)
PH('identify', {
  id:       currentUser.id,
  email:    currentUser.email,
  name:     currentUser.name,
  ssoToken: '<token-from-your-server>',
});

Cuando hay ssoToken, Priority Hunter verifica la firma con el secreto de tu organización y usa la identidad del token (tiene prioridad sobre los campos planos). Sin token, los campos id/email de identify se aceptan igualmente — la petición está limitada por la lista de orígenes permitidos del widget, pero la identidad no está firmada.

Paso 3b — El portal lo hace solo

Para el portal público no tienes que integrar nada más que el endpoint de login. El flujo completo:

1. El visitante pulsa «Votar» o «Iniciar sesión» en el portal y se abre el modal de SSO.
2. El portal redirige a tu SSO Login URL con ?returnTo=<.../sso/callback?next=...>.
3. Tu endpoint autentica al usuario y firma el token.
4. Rediriges de vuelta a returnTo añadiendo &ssoToken=<jwt>.
5. El callback del portal (/sso/callback) verifica el token con el secreto de tu organización, crea la sesión del visitante y le devuelve a la página donde estaba (next).

Más sobre el comportamiento del portal en Portal público.

Referencia de claims

Expiración y rotación

Firma los tokens con una expiración corta (24 horas o menos) — son credenciales de un solo uso práctico, no sesiones. Si sospechas que el secreto se ha filtrado, pulsa Regenerate en Studio: desde ese momento todos los tokens firmados con el secreto anterior dejan de verificar. Actualiza la variable de entorno de tu backend con el secreto nuevo en el mismo despliegue.

Solución de problemas