单点登录
单点登录 (SSO) 会替换公开看板上的默认登录流程。访客点击 登录 后,UserJot 会将其重定向到你的身份验证端点;然后你再使用经过签名的 HS256 JWT 将他们重定向回来。
看板登录模式(默认、SSO 和 已禁用)需要使用 Professional 套餐。
启用 SSO
打开 设置 → 登录。
在 身份验证 下,将 看板登录 设置为 SSO。
在 启用 SSO 对话框中,输入你的 HTTPS 重定向 URL,然后点击 启用 SSO。之后,你可以在 SSO 重定向 URL 下编辑该 URL(若要彻底清除重定向 URL,请先关闭 SSO 的 Board 登录)。
在 密钥 部分复制你的 项目 ID 和 项目密钥。
你的重定向 URL 必须使用 https://(在本地测试时请使用 HTTPS 隧道)。
看板登录模式
默认:访客使用标准 UserJot 账户登录。
SSO:访客点击 登录 后,会被重定向到你的 SSO 端点。启用 SSO 后,普通终端用户 UserJot 账户无法直接登录(在仅支持 SSO 的看板上,浏览器中已有的非团队 UserJot 会话会被视为匿名用户,而不是降级为访客)。工作区所有者和管理员可以使用自己的 UserJot 账户登录,也可以通过你的 SSO 重定向登录(使用 SSO 时,他们现有的团队角色会得到保留,
traits和companies会同步,且其通过控制面板管理的姓名、头像和电子邮件地址保持不变)。已禁用:完全隐藏 登录 按钮。对于开放看板,可搭配使用 访客反馈;若要创建只读公开看板,则可关闭访客提交功能。
SSO 重定向流程的工作方式
访客点击 登录 后,UserJot 会打开一个登录弹窗(如果弹窗被阻止,则改为在同一标签页中重定向),指向你配置的 URL,并附带 state 和 redirect 查询参数:
https://yourapp.com/userjot/sso?state=OPAQUE_STATE_FROM_USERJOT&redirect=https%3A%2F%2Fapi.userjot.com%2Fauth%2Fsso你的端点只需保留 state:
读取
state查询参数。在你的应用中验证用户身份(如果用户尚未登录,则引导其完成登录流程,然后携带原始的
state返回此端点)。使用你的 项目密钥 对
HS256JWT 进行签名。将浏览器重定向到
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).
声明 | 必填 | 说明 |
|---|---|---|
| 是 | 你系统中的稳定用户 ID |
| 是 | 你的 UserJot 项目 ID,必须完全一致 |
| 是 | 字符串必须与 |
| 是 | Unix 过期时间戳(建议设置为 5 到 15 分钟后) |
| 否 | Unix 签发时间戳(考虑时钟偏差后,不得设置为未来时间) |
| 否 | 用户的电子邮件地址(建议提供,以便关联邮箱和发送通知) |
| 否 | 名字 |
| 否 | 姓氏 |
| 否 | 头像 URL |
| 否 | 由字符串、数字、布尔值或 |
| 否 | 公司成员关系数组 |
示例载荷:
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
};公司数据
{
"companies": [
{
"id": "company_456",
"name": "Acme Corp",
"domain": "acme.com",
"logo": "https://example.com/acme.png",
"traits": {
"plan": "enterprise",
"seats": 42
}
}
]
}端点示例(Hono)
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 查询参数:
错误代码 | 含义 |
|---|---|
|
|
| 签名不匹配、 |
| 看板登录不再设置为 SSO。 |
| 工作区 SSO 配置不完整(缺少重定向 URL 或密钥)。 |
| 登录后的返回 URL 未通过验证。 |
| 服务器上的身份验证或会话创建失败。 |