单点登录

Shayan Taslim更新

单点登录 (SSO) 会替换公开看板上的默认登录流程。访客点击 登录 后,UserJot 会将其重定向到你的身份验证端点;然后你再使用经过签名的 HS256 JWT 将他们重定向回来。

看板登录模式(默认、SSO 和 已禁用)需要使用 Professional 套餐。

启用 SSO

  1. 打开 设置 → 登录。

  2. 在 身份验证 下,将 看板登录 设置为 SSO。

  3. 在 启用 SSO 对话框中,输入你的 HTTPS 重定向 URL,然后点击 启用 SSO。之后,你可以在 SSO 重定向 URL 下编辑该 URL(若要彻底清除重定向 URL,请先关闭 SSO 的 Board 登录)。

  4. 在 密钥 部分复制你的 项目 ID 和 项目密钥。

你的重定向 URL 必须使用 https://(在本地测试时请使用 HTTPS 隧道)。

看板登录模式

  • 默认:访客使用标准 UserJot 账户登录。

  • SSO:访客点击 登录 后,会被重定向到你的 SSO 端点。启用 SSO 后,普通终端用户 UserJot 账户无法直接登录(在仅支持 SSO 的看板上,浏览器中已有的非团队 UserJot 会话会被视为匿名用户,而不是降级为访客)。工作区所有者和管理员可以使用自己的 UserJot 账户登录,也可以通过你的 SSO 重定向登录(使用 SSO 时,他们现有的团队角色会得到保留,traits 和 companies 会同步,且其通过控制面板管理的姓名、头像和电子邮件地址保持不变)。

  • 已禁用:完全隐藏 登录 按钮。对于开放看板,可搭配使用 访客反馈;若要创建只读公开看板,则可关闭访客提交功能。

SSO 重定向流程的工作方式

访客点击 登录 后,UserJot 会打开一个登录弹窗(如果弹窗被阻止,则改为在同一标签页中重定向),指向你配置的 URL,并附带 state 和 redirect 查询参数:

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

你的端点只需保留 state:

  1. 读取 state 查询参数。

  2. 在你的应用中验证用户身份(如果用户尚未登录,则引导其完成登录流程,然后携带原始的 state 返回此端点)。

  3. 使用你的 项目密钥 对 HS256 JWT 进行签名。

  4. 将浏览器重定向到 https://api.userjot.com/auth/sso?jwt=<JWT>&state=<STATE>。

请勿修改 state。它只能使用一次,与浏览器会话绑定,并会在 15 分钟后过期。

JWT 载荷

Sign the token with HS256 using your Project secret (keep the secret on your server, never in client code). Passing email links to an existing UserJot account only if that account's email address has been confirmed (or if it is already an existing team member or bound by externalId).

声明

必填

说明

sub

是

你系统中的稳定用户 ID

iss

是

你的 UserJot 项目 ID,必须完全一致

aud

是

字符串必须与 userjot 完全一致

exp

是

Unix 过期时间戳(建议设置为 5 到 15 分钟后)

iat

否

Unix 签发时间戳(考虑时钟偏差后,不得设置为未来时间)

email

否

用户的电子邮件地址(建议提供,以便关联邮箱和发送通知)

firstName

否

名字

lastName

否

姓氏

avatar

否

头像 URL

traits

否

由字符串、数字、布尔值或 null 组成的扁平键值映射

companies

否

公司成员关系数组

示例载荷:

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
};

公司数据

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

端点示例(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());
});

轮换项目密钥

如果你在 设置 → 登录 → 密钥 中点击 撤销密钥,UserJot 会立即生成新的项目密钥。请立即更新你的 SSO 端点(以及任何 签名身份 和 Swift SDK 签名器),因为使用旧密钥签名的令牌会立即失效。

故障排除

在默认的弹窗流程中,回调错误会转交给看板,并显示在登录模态框中。如果浏览器改为在同一标签页中重定向(例如弹窗被阻止时),UserJot 会重定向回看板,并附带一个 sso_error 查询参数:

错误代码

含义

invalid_state

state 值缺失、已被修改、已过期(超过 15 分钟)或已使用。

invalid_token

签名不匹配、iss/aud 错误、缺少 sub/exp,或 JWT 已过期。

sso_disabled

看板登录不再设置为 SSO。

config_error

工作区 SSO 配置不完整(缺少重定向 URL 或密钥)。

invalid_return_to

登录后的返回 URL 未通过验证。

auth_failed / session_error

服务器上的身份验证或会话创建失败。

这是否解答了您的问题?