签名身份

Shayan Taslim更新

普通的 uj.identify 调用来自浏览器,因此任何人都可以修改它。签名身份可防止身份伪造:您的服务器会签署一个短时效的 HS256 JWT,以证明用户身份,而小组件会将该令牌传递给 UserJot。

令牌中的所有信息(用户 ID、电子邮件、姓名、头像、属性和公司信息)都将视为已验证。

何时需要使用此功能

  • 您希望验证反馈、投票和对话确实来自已登录的账户。

  • 您希望客户能够在小组件中编辑和删除自己的反馈帖子和评论(未签名的 uj.identify 会话无法在小组件中编辑或删除内容)。

  • 您在 设置 → 登录 中启用了要求使用签名令牌(启用自动登录后,Starter 和 Professional 套餐可使用此功能)。此设置会拒绝未签名的 identify 调用,并要求将公司成员关系包含在签名令牌中(忽略未签名的客户端 companies,并显示 UNSIGNED_COMPANY_IGNORED 警告)。

  • 工作区管理员或所有者正在使用小组件。对于特权账户,系统始终不会接受未签名的身份识别。签名令牌会应用其属性和公司信息;其姓名、头像和电子邮件仍由控制面板管理,如果这些信息随令牌发送,系统会返回 PRIVILEGED_PROFILE_IGNORED 警告。

Note

如果您的产品同时使用网页小组件和 Swift SDK,启用 Require signed tokens 会在两者上强制执行验证。网页小组件使用 HS256 JWT(token),而 Swift SDK 使用由同一个工作区密钥签名的 HMAC-SHA256 signature。

1. 在服务器上创建令牌

使用工作区密钥通过 HS256 签署 JWT。您可以在 Settings → Login 下的 Secrets 中找到 Project ID 和 Project secret。

切勿在浏览器中签署令牌。请将密钥保存在服务器上。

必需声明

声明

值

sub

用户在您系统中的稳定 ID。必需。

iss

您的 UserJot Project ID。必需。

aud

必须是准确的字符串 userjot。必填。

iat

以 Unix 秒为单位的签发时间戳。必需。

exp

以 Unix 秒为单位的过期时间戳。必需。过期时间最多为 3600 秒(iat)之后。

可选的已验证声明

您还可以包含 email、firstName、lastName、avatar、traits 和 companies。companies 中的每个条目都支持:

JSON
{
  "companies": [
    {
      "id": "acme",
      "name": "ACME Inc.",
      "domain": "acme.com",
      "logo": "https://acme.com/logo.png",
      "traits": { "plan": "enterprise" }
    }
  ]
}

服务器示例

Node.js

JavaScript
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

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
<?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

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:

JavaScript
uj.identify({
  token: 'TOKEN_FROM_YOUR_SERVER'
});

您也可以将 user 和 companies 与 token 一起传递,以提供额外的未验证字段;如果某个字段同时出现在两者中,则以签名令牌中的值为准(除非启用了要求使用签名令牌,此时会忽略未签名的公司)。通过返回的 promise 确认验证:

JavaScript
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。

这是否解答了您的问题?