Skip to main content
本主题介绍如何将 XBOX services 身份验证与自定义游戏服务配合使用。 除了 XBOX services 之外，XSTS 令牌还可用于自定义游戏服务的身份验证和授权。自定义 Web 服务可以使用 XBOX services 颁发的声明，这些声明包含在合作伙伴 XSTS 令牌中。 合作伙伴 XSTS 令牌保存一组专门为目标服务定义的声明。令牌声明由 XBOX services 颁发和签名，因此比任何游戏客户端数据都更防篡改。自定义游戏服务必须使用 XSTS 令牌声明来验证用户/设备身份和权限。涉及合作伙伴 XSTS 令牌的一些声明示例包括 gamertag、玩家权限、年龄组以及该游戏发行商下唯一的合作伙伴 XUID (pXUID)。有关声明的完整列表，请参阅 XBOX services 安全令牌声明。 XBOX services 构造合作伙伴 XSTS 令牌，使其只能由自定义 Web 服务读取，并对客户端不透明。为此，令牌是加密的 JSON Web 令牌 (JWT)，并遵循 RFC 7519 标准。令牌通过使用私钥和公钥的非对称加密进行保护。这样，只有拥有私钥的 Web 服务才能解密和检查合作伙伴 XSTS 令牌。 每个令牌配置在合作伙伴中心以发行商级别执行和可用。开发人员为令牌名称、可用声明和加密证书（密钥）以及令牌过期时间指定配置。此配置针对特定的信赖方。 合作伙伴 XSTS 令牌使用仅限于 HTTPS 连接以确保安全，并通过合作伙伴中心中的 Webservice Endpoint 配置定义。此配置指定合作伙伴 XSTS 令牌和 Web 服务 URI 的配对。与信赖方配置不同，Webservice Endpoint 在合作伙伴中心中按游戏配置。

​
信赖方配置

要使用自定义 Web 服务，游戏必须先在合作伙伴中心完成单一登录配置。有关详细信息，请参阅 配置信赖方。 信赖方配置在发行商级别和所有沙盒中配置。最佳做法是尽可能对相同的游戏服务（跨不同的游戏）使用相同的信赖方配置。

​
Webservice Endpoint 配置

除了信赖方配置之外，还必须在合作伙伴中心中为游戏服务配置服务端点才能使用合作伙伴 XSTS 令牌。有关详细信息，请参阅 Web 服务。 Web 服务端点在全局 DefaultNsal 配置中按游戏级别配置。DefaultNsal 是当前游戏的唯一配置类型。以前配置的游戏可能使用反映其他环境的其他配置类型，例如 CertificationNsal 和 RetailNsal。为简化配置，新游戏无法使用这些配置类型。

​
Web 服务 SSL 证书

所有 Web 服务端点都必须使用 HTTPS 并使用由受信任证书颁发机构 (CA) 颁发的 SSL 证书。这些证书不得在 Web 服务端点配置中指定。 对于开发和测试，游戏可以使用自签名 SSL 证书，但如果可以使用受信任的根证书，则不建议这样做。 XBOX 控制台默认不信任自签名 SSL 通信。 除非将证书添加到合作伙伴中心内游戏单一登录页面上的 Webservice Endpoint 定义中，否则 HTTPS 连接将失败。 有关已识别 CA 的列表，请参阅安全文档中的 参与者列表 - Microsoft 受信任根程序。服务还可以从 letsencrypt.org 等组织获取免费的、受信任的 SSL 证书。

​
令牌检索和连接流程

所有游戏服务端点都应要求合作伙伴 XSTS 令牌进行身份验证和授权。如果没有此信息，应拒绝与服务的通信。 对于 Web 服务，合作伙伴 XSTS 令牌和用户标识（用户哈希）必须包含在请求的 Authentication 标头中。有关这些标头结构的详细信息，请参阅 XBOX services 安全令牌 (XSTS 令牌)。 对于安全 TCP/UDP 服务，合作伙伴 XSTS 令牌和用户标识（用户哈希）应包含在初始授权/握手消息中。如果没有此信息，应拒绝与服务的通信。对于这些连接，可以指定占位符作为 Webservice Endpoint URI，以反映服务的域。

​
在客户端获取合作伙伴 XSTS 令牌并发送 HTTPS 请求

游戏客户端通过 XUserGetTokenAndSignatureUtf16Async API 使用以下流程获取合作伙伴 XSTS 令牌和签名标头数据。
  1. 对当前用户调用 XUserGetTokenAndSignatureUtf16Async。在 API 调用中包含服务的 URL 和（如果适用）自定义标头或消息正文。 该 API 检索 XSTS 令牌和消息签名，供目标端点或 XBOX 服务使用。
  2. 通过 XUserGetTokenAndSignatureUtf16Result 从异步结果中检索 XSTS 令牌和签名。 XUserGetTokenAndSignatureUtf16Result 返回加密的 XSTS 令牌。游戏应将返回的令牌视为不透明数据。令牌数据不得写入磁盘或缓存在游戏空间中，除非用于随后的服务调用。令牌缓存由 XUserGetTokenAndSignatureUtf16Async 为您处理。
  3. 使用 Microsoft Windows HTTP Services (WinHTTP)、XSTS 令牌和签名值创建对目标端点的 HTTPS 请求。 所有 HTTPS 调用都必须通过 WinHTTP API 执行，将 XSTS 令牌值添加到 Authentication 标头，将签名值作为 Signature 标头。
对于安全 TCP/UDP 服务，使用相同的流程，但有以下更改。
  • 游戏指定服务的占位符 URI，而不是服务调用 URL。
  • 身份验证数据在 TCP/UDP 连接的初始授权/握手期间使用。

​
在服务器上处理合作伙伴 XSTS 令牌

游戏服务接收合作伙伴 XSTS 令牌后，该服务必须解析、解密并验证令牌的真实性。 有关解析和验证 XSTS 令牌的详细信息，请参阅 XBOX services 安全令牌 (XSTS 令牌)。 我们还强烈鼓励服务开发人员使用 Game Service 示例 和 Xfest 2019 演示文稿 XSTS Auth and Server to Server Made Easy 进行审查和测试。 该示例具有带有令牌处理的完整服务库。

​
身份验证和授权

在解析、解密和验证令牌后，服务可以信任令牌的声明。 有关所有 XSTS 令牌声明的列表，请参阅 XBOX services 安全令牌声明。 服务应首先使用这些声明进行服务级身份验证和授权。 合作伙伴 XSTS 令牌中包含的信息应始终被视为权威信息。 服务调用不需要通过请求的其他部分复制此信息。 必须特别注意用户身份。它必须始终通过 XSTS 令牌声明进行验证，并且不能在未经其他来源验证的情况下用于服务请求。要识别用于身份验证目的的用户，游戏服务有两个选项。
  • /user/pXUID (ptx) 声明。 对于只需要用于帐户链接身份的任何场景，应使用合作伙伴 XUID (pXUID)。此声明公开当前发行商下用户的 XBOX services 帐户的唯一标识符。
  • /user/XID 声明。 对于需要服务返回用户身份或对 XBOX services 执行服务到服务调用的任何场景，都需要用户的 XUID。此类服务的示例包括自定义排行榜或匹配服务，或通过 XBOX services 服务调用验证购买的服务。
游戏服务必须获得授权才能在合作伙伴 XSTS 令牌中启用 XUID 并存储 XUID 信息。请与您的开发人员合作伙伴经理合作完成该流程。但是，使用 pXUID 不需要额外的安全审查或许可。 尽管 gamertag 在令牌声明中可用，但绝不能将其用作用户的唯一标识符。gamertag 可能会更改，因此只能用于临时显示或缓存目的。 出于授权目的，您可以通过 /user/privileges 声明获得用户的 XBOX services 权限。这些权限与在 XBOX services 上公开的权限相同，并且必须经过验证才能进行服务访问。如果用户没有足够的访问权限，服务应提供 HTTP/401 错误代码。 在验证用户身份和权限后，服务可以使用其他合作伙伴令牌声明来检索有关用户和设备的更多信息，以用于服务逻辑。
PXUID 的范围限定为在合作伙伴中心创建您的信赖方时选择的业务合作伙伴。如果您正在使用多个信赖方的 x-token，则它们必须共享相同的业务合作伙伴，PXUID 值才能匹配。有关业务合作伙伴和信赖方配置的详细信息，请参阅 在合作伙伴中心设置 Web 服务。

​
令牌过期和刷新

XSTS 令牌在合作伙伴中心相应信赖方中配置的特定持续时间内有效。 XSTS 令牌的默认过期时间为四小时。 每个令牌都包含一个时间戳，服务应在接受令牌声明之前对其进行验证。 如果向自定义服务出示已过期的令牌，服务应返回 HTTP/401 错误。 由于客户端上的 XUserGetTokenAndSignatureUtf16Async 处理 XSTS 令牌过期和缓存，因此在向您的游戏服务发送请求之前每次都应调用它。 该 API 确保游戏始终收到有效令牌。 否则游戏不得缓存令牌。
最后修改于 2026年8月25日

相关主题

XBOX services 身份验证（目录）XSTS 令牌、解密和验证示例XBOX services 身份验证身份验证和 S2S服务身份验证