跳转到主要内容
本文提供由 XBOX 安全令牌服务 (XSTS) 创建的 XBOX services 安全令牌的结构概述。 这些令牌在某些文档中也称为 X 令牌或 XSTS 令牌。 XBOX services 使用由 XSTS 创建的安全令牌对用户和设备进行身份验证。 XSTS 令牌也可供游戏使用。 游戏 XSTS 令牌在 Partner Center 中配置，以根据其预期受众和用途提供各种声明和信息。 令牌是为特定的信赖方准备的，信赖方代表一组共享相同令牌配置、加密类型和签名策略的服务端点。它们的详细描述如下。
  • **令牌配置：**令牌中的声明；令牌生命周期
  • **加密密钥：**用于加密令牌的密钥
  • **签名策略：**指定必须签名以进行完整性验证的请求部分（标头和/或正文）
XBOX services 使用相同的预配置信赖方，该信赖方对游戏是不透明的。 拥有自己的服务并由其游戏调用的发行商必须通过 Partner Center XBOX services 配置来配置信赖方。

​
具有多个用户的令牌

对于 XBOX，令牌包含当前登录到控制台的任何用户的用户身份。令牌中的 xui 声明是一个数组，其中包含一个或多个这些用户对象。传入的请求具有以下格式的授权标头： XBL3.0 x=<user hash>;<token> 用户哈希值是以下三个值之一。
  • 与令牌中某个用户身份的用户哈希声明匹配的数字，表明该请求针对该特定用户。
  • 星号 (*)，表示该请求针对令牌中包含的所有用户。
  • 连字符 (-)，表示该请求不在令牌中任何用户的上下文中。
如果标头中的用户哈希值与 令牌中用户身份 之一的 user/hash 声明匹配，则该请求仅针对该用户。用户哈希值对该实例是唯一的，但不能保证在未来的 XSTS 令牌中对给定用户始终相同。它们不应用作永久标识符或被缓存。

​
令牌结构

XSTS 令牌使用带有加密有效负载的自定义 JSON Web 令牌 (JWT) 格式，该有效负载称为外部令牌。 该格式遵循 JWT RFC 7519，并具有两个其他部分以便于对有效负载进行解密。 令牌的每个部分在编码令牌字符串中由一个句点分隔。 一旦解密，有效负载是标准的 JSON Web 令牌 (JWT RFC 7519)，称为内部令牌。 内部令牌包含来自相应信赖方配置的声明和身份验证信息。 有关分解为这些不同部分和区段的示例令牌，请参阅 XBOX services 安全令牌示例。 XSTS 令牌结构图。 具有上述所有区段的 XSTS 令牌的最大大小为 64 KB。

​
外部令牌加密

外部令牌使用两个加密密钥来保护内部令牌及其声明。 首先，有效负载使用生成 XSTS 令牌时创建的内容加密密钥进行加密。 然后，此内容加密密钥本身使用与令牌所创建的相应信赖方绑定的非对称公共证书密钥进行加密。 配置信赖方时，此公共证书密钥会上传到 Partner Center。 要访问表示内部令牌的解密有效负载，服务必须：
  1. 检查外部令牌的 x5t 标头以获取用于加密内容加密密钥的证书的缩略图
  2. 使用信赖方的私有证书密钥解密内容加密密钥
  3. 使用内容加密密钥和初始化向量解密外部令牌有效负载

​
旧版加密和令牌格式

某些游戏和发行商可能仍在使用较旧的旧版 XSTS 令牌格式，该格式不遵循 JWT RFC 7519 格式。 此选项仅适用于从 XBOX 开发人员门户 (XDP) 迁移的游戏或出于兼容性目的需要此格式的游戏。 新令牌配置不应使用此 JWT 格式。 此外，Partner Center 以前包含对称共享密钥加密选项。 由于安全问题，此选项已弃用，不可用于新的信赖方配置。

​
内部令牌

在有效负载解密后，它是一个 UTF8 数组，表示遵循 JWT RFC 7516 的内部令牌。 内部令牌的有效负载包含为创建令牌所针对的信赖方配置的声明。 未在 Partner Center 为信赖方配置的声明不会包含在令牌有效负载中。 声明值可以是传统类型（例如，字符串、整数和 GUID）。 它们也可以是表示更复杂结构的 JSON 对象。 有关更多信息，请参阅 XBOX services 安全令牌声明。
没有数据的声明值可以通过 null 值表示，或者可以完全从令牌中缺失。游戏服务在解析声明值时应考虑到这一点。

​
内部令牌标头和签名验证

内部令牌具有一个标头，其中包含与生成和验证内部令牌签名相关的信息。 此签名验证证明令牌来自 XBOX Live 服务，并且未被篡改。 当前有两种支持的密钥类型用于生成验证签名，并可以在 Partner Center 为您的信赖方进行配置：
  1. 当前的 XSTS 签名 JWK（JSON Web 密钥）
  2. 当前的 XSTS 签名证书
自 2024 年 12 月起，所有内部令牌标头都包含与 JWK 相关的值 (kid & jku)，即使您的令牌配置为使用 XBL 签名证书。 这意味着内部令牌标头可能同时具有 x5u/x5t 和 jku/kid 值，两对值都指向相同的签名证书。 证书以分别从 x5u 或 jku URI 读取证书时预期的正确格式托管。 XSTS 签名证书和 JWK 方法都旨在根据需要更新和刷新，无需事先通知合作伙伴。 因此，服务永远不应硬编码或依赖于安装用于验证令牌的 XSTS 签名证书或当前 JWK 的保存副本。 服务应缓存签名密钥/证书，然后在收到不在缓存中的 x5t 或 kid 时下载并将任何新密钥/证书添加到缓存。 确保在推出新的 XSTS 签名 JWK 或证书时，您的服务无需采取任何操作或工作即可支持新的签名密钥。 在下载任何密钥或证书之前，您应验证 URI 的主机是否与预期值匹配，以确保您正在下载由 XBOX Live 服务生成的有效密钥或证书。 有关更多信息以及每种类型的预期 URI 主机值，请参阅 使用 XSTS JKW 签名密钥 和 使用 XSTS 签名证书。 由于 XSTS 签名 JWK 会频繁轮换，因此建议合作伙伴在 Partner Center 的信赖方上启用 JKU 选项。 Game Service 示例 强调了这些建议。
使用 XSTS JKW 签名密钥
如果您的信赖方配置了 JKU 选项，则您的令牌使用当前的 XSTS 签名 JWK，并在内部令牌中具有以下标头值：
在您的服务下载新的签名密钥之前，请验证 jku URL 是否属于 xsts-keys.auth.xboxlive.com 域。如果不是，应拒绝该令牌并且不应下载密钥。
所有有效的签名证书密钥都可在 https://xsts-keys.auth.xboxlive.com/keys 找到。 建议您的服务在服务实例启动时，使用在该 URL 找到的密钥预填充您的签名密钥缓存。 您的服务需要在运行时处理尚未在缓存中的令牌上的新密钥，方法是遍历完整密钥列表，找到与 kid 匹配的密钥，然后将其缓存。
使用 XSTS 签名证书
如果您的信赖方在 Partner Center 中没有启用 JKU 选项，则您的令牌使用当前的 XSTS 签名证书，并在内部令牌中具有以下标头值：
即使您的信赖方未配置为 JKU / KID，这些声明也会出现在您的内部令牌标头中。这些值反映 x5t 和 x5u 的值。
在您的服务下载新的签名证书密钥之前，请验证来自 x5u 或 jku 的 URL 是否属于 xsts.auth.xboxlive.com 域。如果不是，应拒绝该令牌并且不应下载证书。
所有有效的签名证书密钥都可在 https://xsts.auth.xboxlive.com/xsts/signingkeys 上以 Base64 编码证书的 json 数组形式获得。 建议您的服务在服务实例启动时，使用来自此端点的证书密钥预填充您的签名密钥缓存。 您的服务仍需要在运行时处理不在缓存中的令牌上的新密钥。 来自 JWT RFC 7519 文档：
4.1.5 “x5u” (X.509 URL) 标头参数 “x5u” (X.509 URL) 标头参数是一个 URI [RFC3986]，它引用了对应于用于对 JWS 进行数字签名的密钥的 X.509 公钥证书或证书链 [RFC5280] 的资源。所标识的资源必须提供符合 RFC 5280 [RFC5280] 的 PEM 编码形式的证书或证书链表示，每个证书按 RFC 4945 [RFC4945] 第 6.1 节所述进行分隔。包含对应于用于对 JWS 进行数字签名的密钥的公钥的证书必须是第一个证书。该证书之后可能跟随其他证书，每个后续证书都是用于对前一个证书进行认证的证书。用于获取资源的协议必须提供完整性保护；用于检索证书的 HTTP GET 请求必须使用 TLS [RFC2818] [RFC5246]；服务器的身份必须按照 RFC 6125 [RFC6125] 第 6 节进行验证。 另请参阅第 8 节中的 TLS 要求。使用此标头参数是可选的。

​
身份

描述主体各个方面的一组相关声明称为身份。从结构角度看，它们是值为 JSON 对象的声明。该对象是一组声明或一个声明集的数组。 XBOX One 令牌中可以包含的身份如下列出并描述（其特定的短名称显示在括号中）。

​
设备身份 (xdi)

设备身份中的声明提供有关请求令牌的设备的详细信息。令牌中只能有一个设备身份。这意味着设备身份是一个声明和值的列表。

​
游戏身份 (xti)

游戏身份中的声明提供有关在 XBOX One 上运行并请求令牌的游戏的详细信息。令牌只能包含一个游戏身份。如果存在于令牌中，游戏身份是一个简单的声明和值列表。 有关声明值的完整列表，请参阅 XBOX services 安全令牌声明。

​
服务身份 (xsi)

服务身份中的声明提供有关服务的详细信息，如果请求来自该服务而不是来自 XBOX One。令牌中只能有一个服务身份。如果存在，服务身份是一个简单的声明和值列表。

​
用户身份 (xui)

用户身份中的声明提供有关用户的详细信息。如果控制台上登录了多个用户，则令牌中有多个用户身份。如果存在，用户身份是一个声明集数组（即使它是一个只有一个对象的数组）。 请求的授权标头包含确定令牌中请求适用于哪个用户的必要信息。有关处理具有多个用户的令牌的更多信息，请参阅 具有多个用户的令牌。

​
聚合身份 (xai)

聚合身份中的声明提供了一组合并的值，代表令牌中的所有用户，例如年龄组（该值与最年轻用户的值匹配）和权限。将这些值组合为一个单独的身份使服务能够无需直接执行分析即可做出决定。此外，它确保因禁令操作被阻止的权限得到执行。

​
另请参阅

XBOX services 安全令牌声明 XBOX Live 安全令牌示例 游戏服务的 XBOX services 身份验证
最后修改于 2026年10月20日