跳到主要内容

登录验证

游戏客户端在调用 Combo SDK 的 Login() 成功完成登录后，会得到 Identity Token。

Identity Token 是世游服务端签发的一个 JWT，包含了客户端的可信身份信息。

游戏客户端应当将 Identity Token 发送给游戏服务端，由游戏服务端对其做登录验证，并从中获得游戏客户端的身份信息。

签名算法​

Identity Token 是用 HS256 算法进行签名的。

签名的私钥是世游给游戏分配的 Secret Key，游戏服务端需要用它验证 JWT 的签名。

Claims​

Identity Token 的 payload 中会包含的 claim 如下：

ClaimTypeDescription
issstring颁发 JWT 的服务器，即世游 REST API 的端点。
audstring世游分配的游戏 ID，也就是 Game ID，用于标识游戏项目。
substring用户 ID。使用世游分配的聚合用户 ID，也就是 Combo ID。
iatintegerJWT 颁发时间。Unix timestamp in seconds。
expintegerJWT 的过期时间。Unix timestamp in seconds。
scopestringJWT 的作用域，固定为 auth。
idpstring世游定义的 Identity Provider (IdP) 标识。取值参见 Go SDK 中的 IdP 常量定义。
external_idstring和 idp 对应的外部身份的标识。
external_namestring和 idp 对应的外部身份中的全名，用于展示在 UI 上。
weixin_unionidstring微信登录的 UnionID。仅在 idp 为 weixin 时才有值。游戏侧可用它实现与微信小游戏的互通。
distrostring游戏客户端的发行版本标识。游戏侧可将它用于服务端数据埋点。
variantstring游戏客户端的分包标识。仅在客户端是分包时才有值。游戏侧可将它用于服务端数据埋点。
ageinteger根据用户的实名认证信息得到的年龄。0 表示未知。
device_idstring游戏客户端运行设备的唯一 ID，用于标识设备。

示例​

假定：

  • 世游 API 端点 https://api.seayoo.com
  • Game ID 为 xcom
  • Secret Key 为 sk_secret

则一个长期有效的，具有合法 Claims 与 Signature 的 Identity Token 示例是：

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5zZWF5b28uY29tIiwiYXVkIjoieGNvbSIsInN1YiI6IjkxMjMxMjIzMzQ2MTMwMDAxIiwiaWF0IjoxNzAzNzQ4NDM3LCJleHAiOjQxMDM4MzQ4MzcsInNjb3BlIjoiYXV0aCIsImlkcCI6InNlYXlvbyIsImV4dGVybmFsX2lkIjoiMTk5OSIsImV4dGVybmFsX25hbWUiOiIqKuWzsCIsImRpc3RybyI6ImFuZHJvaWQiLCJ2YXJpYW50IjoiaHlrYiIsImFnZSI6MTYsImRldmljZV9pZCI6ImU0NmFlZjNjZmE1NzE5NTUifQ.4gp4Fr5wfxZxiG9G_OXTwWnswcRCZ7R-Uqkzw7Yjpuk

这个 Identity Token 解码出的 Claims 为：

{
  "iss": "https://api.seayoo.com",
  "aud": "xcom",
  "sub": "91231223346130001",
  "iat": 1703748437,
  "exp": 4103834837,
  "scope": "auth",
  "idp": "seayoo",
  "external_id": "1999",
  "external_name": "**峰",
  "distro": "android",
  "variant": "hykb",
  "age": 16,
  "device_id": "e46aef3cfa571955"
}
游戏侧可用 age 来自行处理防沉迷

age 不保证返回精确的年龄信息，仅保证用于防沉迷处理时的准确度够用。例如：

  • 当某个用户真实年龄为 35 岁时，age 可能返回 18
  • 当某个用户真实年龄为 17 岁时，age 可能返回 16

验证逻辑​

游戏服务端应当对 Identity Token 进行验证，验证不通过说明游戏客户端身份不可信，应当拒绝客户端进入游戏。

验证内容如下：

  1. Token 能够被解析成一个结构正确的 JWT
  2. Token 的 iss 和当前 API 服务端点匹配，举例 https://api.seayoo.com
  3. Token 的 scope 为 auth
  4. Token 的 aud 与世游分配的 Game ID 匹配
  5. Token 的 exp 字段指示的过期时间，服务端的当前时间尚未达到
  6. Token 的 HS256 签名与服务端使用 Secret Key 计算出的签名匹配

如果上述验证均通过，说明 Identity Token 是可信的，游戏服务端可以使用 Claims 用于登录环节的业务逻辑处理。

有效期​

Identity Token 的有效期目前为 168 小时（7 天）。

开源库​

JWT 的开源库非常多，游戏服务端可在 https://jwt.io/libraries 中选择适合自己的。

最后于 更新