Inicio de sesión único

Shayan TaslimActualizado

El inicio de sesión único (SSO) reemplaza el flujo de inicio de sesión predeterminado de tu tablero público. Cuando los visitantes hacen clic en Iniciar sesión, UserJot los redirige a tu endpoint de autenticación y tú los rediriges de vuelta con un JWT HS256 firmado.

Los modos de inicio de sesión del tablero (Predeterminado, SSO y Desactivado) requieren el plan Professional.

Activar SSO

  1. Abre Configuración → Inicio de sesión.

  2. En Autenticación, establece Inicio de sesión del tablero en SSO.

  3. En el cuadro de diálogo Enable SSO, introduce tu URL de redirección HTTPS y haz clic en Enable SSO. Puedes editar la URL más adelante en SSO redirect URL (para borrar por completo la URL de redirección, desactiva primero Board login SSO).

  4. Copia tu ID del proyecto y tu Secreto del proyecto de la sección Secretos.

Tu URL de redirección debe usar https:// (usa un túnel HTTPS si haces pruebas localmente).

Modos de inicio de sesión del tablero

  • Predeterminado: Los visitantes inician sesión con cuentas estándar de UserJot.

  • SSO: Al hacer clic en Sign In, los visitantes son redirigidos a tu endpoint de SSO. Las cuentas habituales de usuario final de UserJot no pueden iniciar sesión directamente mientras SSO esté activo (los navegadores con una sesión existente de UserJot que no pertenezca a un equipo se consideran anónimos en un tablero que solo permite SSO, en lugar de cambiarse a invitados). Los propietarios y administradores del espacio de trabajo pueden iniciar sesión con sus cuentas de UserJot o mediante tu redirección de SSO (con SSO, se respeta su rol de equipo existente, se sincronizan traits y companies, y el nombre, el avatar y el correo electrónico que gestionan desde el panel permanecen sin cambios).

  • Desactivado: Oculta por completo el botón Iniciar sesión. Combínalo con Comentarios de invitados para permitir tableros abiertos, o desactiva los envíos de invitados para que el tablero público sea de solo lectura.

Cómo funciona el flujo de redirección de SSO

Cuando un visitante hace clic en Sign In, UserJot abre una ventana emergente de inicio de sesión (y, si se bloquean las ventanas emergentes, recurre a una redirección en la misma pestaña) que apunta a la URL que configuraste con los parámetros de consulta state y redirect:

text
https://yourapp.com/userjot/sso?state=OPAQUE_STATE_FROM_USERJOT&redirect=https%3A%2F%2Fapi.userjot.com%2Fauth%2Fsso

Tu endpoint solo tiene que conservar state:

  1. Leer el parámetro de consulta state.

  2. Autentica al usuario en tu aplicación (si aún no ha iniciado sesión, guíalo por tu flujo de inicio de sesión y devuélvelo a este endpoint con el state original).

  3. Firma un JWT HS256 con tu Secreto del proyecto.

  4. Redirige el navegador a https://api.userjot.com/auth/sso?jwt=<JWT>&state=<STATE>.

No modifiques state. Se puede usar una sola vez, está vinculado a la sesión del navegador y caduca al cabo de 15 minutos.

Contenido del JWT

Firma el token con HS256 usando tu Project secret (guarda el secreto en tu servidor, nunca en el código del cliente). Pasar email vincula al usuario con una cuenta de UserJot existente solo si se ha confirmado la dirección de correo electrónico de esa cuenta (o si ya es miembro del equipo o está vinculada mediante externalId).

Campo

Obligatorio

Descripción

sub

Sí

ID de usuario estable de tu sistema

iss

Sí

Tu ID del proyecto exacto de UserJot

aud

Sí

La cadena exacta userjot

exp

Sí

Marca de tiempo de expiración de Unix (se recomiendan entre 5 y 15 minutos)

iat

No

Marca de tiempo de emisión de Unix (no debe estar en el futuro, salvo por diferencias de reloj)

email

No

Dirección de correo electrónico del usuario (recomendada para vincular el correo electrónico y enviar notificaciones)

firstName

No

Nombre

lastName

No

Apellidos

avatar

No

URL del avatar

traits

No

Mapa plano de pares clave-valor con cadenas, números, valores booleanos o null

companies

No

Matriz de membresías de empresas

Ejemplo de carga útil:

JavaScript
const now = Math.floor(Date.now() / 1000);

const payload = {
  sub: 'user_123',
  email: 'jane@example.com',
  firstName: 'Jane',
  lastName: 'Doe',
  iss: 'YOUR_PROJECT_ID',
  aud: 'userjot',
  iat: now,
  exp: now + 10 * 60
};

Datos de la empresa

JSON
{
  "companies": [
    {
      "id": "company_456",
      "name": "Acme Corp",
      "domain": "acme.com",
      "logo": "https://example.com/acme.png",
      "traits": {
        "plan": "enterprise",
        "seats": 42
      }
    }
  ]
}

Ejemplo de endpoint (Hono)

JavaScript
import { Hono } from 'hono';
import jwt from 'jsonwebtoken';

const app = new Hono();

const USERJOT_PROJECT_ID = process.env.USERJOT_PROJECT_ID;
const USERJOT_PROJECT_SECRET = process.env.USERJOT_PROJECT_SECRET;
const USERJOT_CALLBACK_URL = 'https://api.userjot.com/auth/sso';

app.get('/userjot/sso', async (c) => {
  const state = c.req.query('state');
  if (!state) return c.text('Missing state', 400);

  const user = await getCurrentUser(c);

  const token = jwt.sign(
    {
      sub: user.id,
      email: user.email,
      firstName: user.firstName,
      lastName: user.lastName,
      iss: USERJOT_PROJECT_ID,
      aud: 'userjot'
    },
    USERJOT_PROJECT_SECRET,
    { algorithm: 'HS256', expiresIn: '10m' }
  );

  const callback = new URL(USERJOT_CALLBACK_URL);
  callback.searchParams.set('jwt', token);
  callback.searchParams.set('state', state);

  return c.redirect(callback.toString());
});

Rotar el secreto del proyecto

Si haces clic en Revocar secreto en Configuración → Inicio de sesión → Secretos, UserJot genera inmediatamente un nuevo secreto del proyecto. Actualiza enseguida tu endpoint de SSO (así como los firmantes de Identidad firmada y Swift SDK), ya que los tokens firmados con el secreto anterior dejarán de funcionar de inmediato.

Solución de problemas

En el flujo predeterminado de ventanas emergentes, los errores de devolución de llamada se transfieren al tablero y se muestran en el modal de inicio de sesión. Si el navegador recurre a una redirección en la misma pestaña (por ejemplo, cuando se bloquean las ventanas emergentes), UserJot redirige de vuelta al tablero con un parámetro de consulta sso_error:

Código de error

Significado

invalid_state

El valor state faltaba, se modificó, caducó (han pasado más de 15 minutos) o ya se había usado.

invalid_token

La firma no coincide, iss/aud son incorrectos, faltan sub/exp o el JWT ha caducado.

sso_disabled

Inicio de sesión del tablero ya no está configurado como SSO.

config_error

La configuración de SSO del espacio de trabajo está incompleta (falta la URL de redirección o el secreto).

invalid_return_to

No se pudo validar la URL de retorno posterior al inicio de sesión.

auth_failed / session_error

Error de autenticación o de creación de sesión en el servidor.

¿Respondió esto a tu pregunta?