简介
什么是 JWT？
1. 提供方签发 token：将用户信息以 JSON 编码方式包含其中，并对 token 进行电子签名（对称或非对称签名算法）。
2. 使用方消费 token：验证签名和有效期通过后，从 token 中解析出用户信息，完成对用户的认证或鉴权。
什么是 ID Token？
ID Token 是 OpenID Connect 定义的一种标准数据结构, 它定义了一套标准的字段(claim)来描述用户信息, 而 ID Token 的编码方式就是 JWT, 所以对于认证流程, JWT 和 ID Token 通常是配套使用的。
腾讯统一身份使用以下字段表示用户信息以及 token 相关信息：
字段 | 类型 | 必填 | 说明 | 示例 |
sub | string | 必填 | 用户唯一标识, 生成后不变 | f99530d4-8317-4900-bd02-0127bb8c44de |
name | string | 必填 | 用户显示名或姓名 | 张三 |
preferred_username | string | 建议 | 用户登录名 | zhangsan |
email | string | 建议 | 邮箱 | zhangsan@example.com |
phone_number | string | 建议 | 手机号, 推荐格式为+<国家或地区号> <手机号> | +86 13411112222 |
iss | string | 必填 | 签发者的唯一标识, 建议为 URI 格式,需要和管理界面配的 Issuer 保持一致 | https://www.example.com |
jti | string | 必填 | token 唯一标识, 建议为 uuid | f4bbd3f267c04704a4926af6e35ad1a7 |
iat | int64 | 必填 | token 颁发的时间戳(秒) | 1737092953 |
exp | int64 | 必填 | token 过期的时间戳(秒), 有效期建议控制在5分钟以内 | 1737093253 |
补充说明：上述 preferred_username、email、phone_number 3 个字段必须至少提供 1 个。
配置步骤
步骤1：配置凭证信息
1. 在企业管理后台 > 组织与成员 > 认证源管理中，单击展开添加认证源。选择 JWT 认证源，单击添加。
2. 填写第三方身份提供商提供的 Issuer。
3. 部分第三方身份提供商设置的 token 有效期过长，存在安全风险。企业控制台支持自定义“Token 最长有效期”，该项设置需沟通确认，建议设置为 300 秒（5 分钟）。
4. 系统会为您生成“登录链接”，请复制并妥善记录。该项信息需提供给第三方身份提供商进行配置。
5. 由于第三方身份提供商服务器时间与企业控制台时间可能存在偏差，企业控制台支持设置“Max Clock Skew”（时间偏移量）。在偏移范围内，Token 均视为有效。建议设置为 60 秒，不宜设置过长。
步骤2：配置签名密钥对
JWT 认证源集成需要配置验证签名密钥对，进行 JWT 验证。签名密钥对可以由企业控制台生成也可以由第三方身份提供商生成。所以您有两种配置方式：
1. 当签名密钥对由企业控制台生成时，您需要单击生成新的密钥对并下载，企业控制台将生成公私钥对，私钥下载成文件并提供给第三方身份提供商进行配置。 注意：出于安全考虑，企业控制台并不会保存私钥信息，所以请谨慎保存私钥文件，如有丢失无法找回，只能重新生成并下载。
2. 当签名密钥对由第三方身份提供商生成时，您需要选择“手动上传公钥”，并单击上传公钥文件。
步骤3：配置关联关系
1. 匹配逻辑预置字段
属性字段名称 | 属性字段标识 | 属性字段类型 |
用户唯一标识 | user.sub | String |
用户登录名 | user.preferred_username | String |
手机号 | user.phone_number | String |
邮箱 | user.email | String |
2. 新建用户预置属性字段
属性字段名称 | 属性字段标识 | 属性字段类型 |
用户唯一标识 | user.sub | String |
用户名 | user.name | String |
用户登录名 | user.preferred_username | String |
手机号 | user.phone_number | String |
邮箱 | user.email | String |
3. 以上信息配置完成后，单击保存。
4. 保存完成后，您也可以在认证源列表页执行启动操作。
对接流程
1. 生成 ID Token：参考下述 SDK。
2. 生成免登链接：
从腾讯统一身份管理后台获取“登录链接”，例如 https://oauth2.account.tencent.com/v1/sso/jwtp/xxxxxx/xxxxx/kit/{app_type}
指定要免登的应用：将上述链接中的 {app_type} 替换为目标应用标识。当前支持的应用包括：
腾讯会议：meeting
腾讯文档：doc
将 ID Token 作为参数拼接到免登链接：参数为 id_token，值为步骤 1 生成的 token。例如
https://oauth2.account.tencent.com/v1/sso/jwtp/xxxxxx/xxxxx/kit/meeting?id_token=xxxxxx拼接其他自定义参数，例如
https://oauth2.account.tencent.com/v1/sso/jwtp/xxxxxx/xxxxx/kit/meeting?id_token=xxxxxx&state=xxxxx&meeting_common=xxxxxx3. 发起免登请求：在浏览器中打开步骤 2 生成的免登链接。
4. 获取 SDK：参考 SDK 实现上述对接流程，通过以下方式获取 SDK：
github
常见问题
2. 公钥长度：至少 2048 位。
3. 公钥格式：当前仅支持上传 .pem 格式的公钥。注意：不同格式的公钥可以通过 openssl 等工具进行互转：
从私钥导出公钥：openssl rsa -in private.key -pubout > public.pem rsa -in private.key -pubout > public.pem
从证书导出公钥：openssl x509 -pubkey -noout -in ./cert.pem > public.pem x509 -pubkey -noout -in ./cert.pem > public.pem
查看公钥：openssl rsa -noout -text -pubin -in ./public.pem rsa -noout -text -pubin -in ./public.pem
将 DER 格式的公钥转换为 PEM 格式：openssl rsa -pubin -inform der -in ./public.der -outform PEM -out ./public.pem rsa -pubin -inform der -in ./public.der -outform PEM -out ./public.pem
4. ID Token 示例：可通过在线工具 jwt.io 解码查看。
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsic3NvX2FwaSJdLCJlbWFpbCI6InpoYW5nc2FuQGV4YW1wbGUuY29tIiwiZXhwIjoxNzM3MDkzMjUzLCJpYXQiOjE3MzcwOTI5NTMsImlzcyI6Imh0dHBzOi8vbWVldGluZy5jb20iLCJqdGkiOiJmNGJiZDNmMjY3YzA0NzA0YTQ5MjZhZjZlMzVhZDFhNyIsIm5hbWUiOiLlvKDkuIkiLCJwaG9uZV9udW1iZXIiOiIrODYgMTM0MTExMTIyMjIiLCJwaWN0dXJlIjoiaHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vYXZhdGFyMS5wbmciLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ6aGFuZ3NhbiIsInN1YiI6ImY5OTUzMGQ0LTgzMTctNDkwMC1iZDAyLTAxMjdiYjhjNDRkZSJ9.ZzM2KC_HYUXTtFzDER5K1MXluLKoJfo_5RxvdZHjDsj29O00bAqFBUmpko3LU-Tvuts1e7gr-ixoZTGg5OsxBK7v8i8MWK3bwIQTYJFjIL7Ucvt8EC74hEVm99bXXe6F6ASJ2JyiQui7vTkw4_ScMkx1R751Y7QuABiRdZjQ5wT9Ufw9BlQY5AzYuGU3QRD0eF8e6SEqQLhhJTRtdBzOZhV_Gr2GpGBmkyY_ik66CQHD6gIYIHYef5WTbTaxQsRgmgeedj9DOqmtQdULhlJ89qyaeLbJzKfUw_Aa6B3rz_J8GAwQ3JRkAulYFhKsFy_wU1OS8_mk9Bu4zEPIVH3L7Q
token 解码后的内容如下图所示：
