签名身份
普通的 uj.identify 调用来自浏览器,因此任何人都可以修改它。签名身份可防止身份伪造:您的服务器会签署一个短时效的 HS256 JWT,以证明用户身份,而小组件会将该令牌传递给 UserJot。
令牌中的所有信息(用户 ID、电子邮件、姓名、头像、属性和公司信息)都将视为已验证。
何时需要使用此功能
您希望验证反馈、投票和对话确实来自已登录的账户。
您希望客户能够在小组件中编辑和删除自己的反馈帖子和评论(未签名的
uj.identify会话无法在小组件中编辑或删除内容)。您在 设置 → 登录 中启用了要求使用签名令牌(启用自动登录后,Starter 和 Professional 套餐可使用此功能)。此设置会拒绝未签名的 identify 调用,并要求将公司成员关系包含在签名令牌中(忽略未签名的客户端
companies,并显示UNSIGNED_COMPANY_IGNORED警告)。工作区管理员或所有者正在使用小组件。对于特权账户,系统始终不会接受未签名的身份识别。签名令牌会应用其属性和公司信息;其姓名、头像和电子邮件仍由控制面板管理,如果这些信息随令牌发送,系统会返回
PRIVILEGED_PROFILE_IGNORED警告。
如果您的产品同时使用网页小组件和 Swift SDK,启用 Require signed tokens 会在两者上强制执行验证。网页小组件使用 HS256 JWT(token),而 Swift SDK 使用由同一个工作区密钥签名的 HMAC-SHA256 signature。
1. 在服务器上创建令牌
使用工作区密钥通过 HS256 签署 JWT。您可以在 Settings → Login 下的 Secrets 中找到 Project ID 和 Project secret。
切勿在浏览器中签署令牌。请将密钥保存在服务器上。
必需声明
声明 | 值 |
|---|---|
| 用户在您系统中的稳定 ID。必需。 |
| 您的 UserJot Project ID。必需。 |
| 必须是准确的字符串 |
| 以 Unix 秒为单位的签发时间戳。必需。 |
| 以 Unix 秒为单位的过期时间戳。必需。过期时间最多为 |
可选的已验证声明
您还可以包含 email、firstName、lastName、avatar、traits 和 companies。companies 中的每个条目都支持:
{
"companies": [
{
"id": "acme",
"name": "ACME Inc.",
"domain": "acme.com",
"logo": "https://acme.com/logo.png",
"traits": { "plan": "enterprise" }
}
]
}服务器示例
Node.js
import jwt from 'jsonwebtoken';
export function createUserJotToken(user, secret, projectId) {
return jwt.sign(
{
sub: user.id,
email: user.email,
firstName: user.firstName,
lastName: user.lastName,
iss: projectId,
aud: 'userjot'
},
secret,
{ algorithm: 'HS256', expiresIn: '1h' }
);
}Python
import time
import jwt
def create_userjot_token(user, secret, project_id):
now = int(time.time())
return jwt.encode(
{
"sub": user["id"],
"email": user["email"],
"firstName": user["first_name"],
"lastName": user["last_name"],
"iss": project_id,
"aud": "userjot",
"iat": now,
"exp": now + 3600,
},
secret,
algorithm="HS256",
)PHP
<?php
use Firebase\JWT\JWT;
function createUserJotToken(array $user, string $secret, string $projectId): string
{
$now = time();
return JWT::encode([
'sub' => $user['id'],
'email' => $user['email'],
'firstName' => $user['firstName'],
'lastName' => $user['lastName'],
'iss' => $projectId,
'aud' => 'userjot',
'iat' => $now,
'exp' => $now + 3600,
], $secret, 'HS256');
}Ruby
require 'jwt'
def create_userjot_token(user, secret, project_id)
now = Time.now.to_i
payload = {
sub: user[:id],
email: user[:email],
firstName: user[:first_name],
lastName: user[:last_name],
iss: project_id,
aud: 'userjot',
iat: now,
exp: now + 3600
}
JWT.encode(payload, secret, 'HS256')
end每次加载页面时,或通过经过身份验证的后端端点签发新令牌。由于令牌的有效期最长为 1 小时,请勿将其缓存超过此时长。
2. 传递令牌以进行身份识别
在 token 字段中传递 JWT:
uj.identify({
token: 'TOKEN_FROM_YOUR_SERVER'
});您也可以将 user 和 companies 与 token 一起传递,以提供额外的未验证字段;如果某个字段同时出现在两者中,则以签名令牌中的值为准(除非启用了要求使用签名令牌,此时会忽略未签名的公司)。通过返回的 promise 确认验证:
const result = await uj.identify({ token });
result.identityTrust; // 'signed'无效令牌会导致失败,不会回退
如果令牌已过期、格式错误或使用了错误的密钥签名,uj.identify 会以 IDENTIFY_FAILED 拒绝,而不会静默回退到未签名会话。
签名身份与对话
如果匿名访客先发起访客对话,之后再使用签名令牌进行身份识别,其访客对话会转移到已验证的成员账户。
在签名身份下发起的对话会持续受到保护。如果访客在没有签名会话的情况下重新打开对话,系统会要求其先验证身份,才能查看历史记录。
启用 Require signed tokens 后,匿名访客仍可发起仅限浏览器会话的访客对话;此设置只会阻止未签名的
identify调用关联到成员账户。
身份信息会延续到你的公开页面
完成身份识别后,小组件会自动将会话传递给指向您 UserJot 公共页面(看板、路线图、更新日志或帮助中心)的链接。若要让访客打开这些页面时已处于登录状态,请在 Settings → Login 中启用 Automatic login(Starter 或 Professional 套餐)。请参阅 Automatic login。
故障排除
身份识别调用返回 IDENTIFY_FAILED 错误
请确认令牌使用 HS256 和您当前的 Project secret 签名。
请确认
iss与您的 Project ID 相符,且aud完全等于userjot。请确认
iat和exp均已提供,且使用 Unix 秒表示,并且exp - iat <= 3600。请确认服务器时钟准确(如果令牌的签发时间比当前时间超前 60 秒以上,系统会拒绝该令牌)。
未签名的身份识别不再起作用
请在 Settings → Login 中启用 Require signed tokens(此选项会在开启 Automatic login 时显示)。启用后,每次 identify 调用都必须包含有效的签名 token。