请求用户 Store ID 用于服务间身份验证。
本主题介绍使用Microsoft Store服务 API 获取服务到服务身份验证的用户Store ID所需的配置和步骤。
用户 Store ID 可用于对从你自己的服务到 Microsoft Store API 的调用进行身份验证。 这种身份验证方法与在设备上登录 Microsoft Store 应用的用户绑定，该用户是游戏内交易的购买帐户，与哪个帐户正在 Windows 电脑上玩游戏无关。
用户 Store ID 有两种类型：
- UserCollectionsID，向 Microsoft Store 收藏服务进行身份验证
- UserPurchaseID，向 Microsoft Store 购买服务进行身份验证
本主题提供以下步骤，作为获取用户Store ID从你自己的服务调用其各自服务的过程。
- 在 Microsoft Entra ID 中配置应用程序。
- 在合作伙伴中心将 Azure AD 应用程序 ID 与客户端应用相关联。
- 在你的服务中，创建表示你的发布者身份的 Microsoft Entra ID 访问令牌。
- 在游戏中，创建一个用户Store ID密钥，该密钥表示当前登录到应用商店应用的用户的标识。 将此密钥传递回服务。
- 通过用户 Store ID 为 Windows 电脑游戏进行身份验证。
- 续订过期的 Microsoft Store ID 密钥。
此过程涉及两个执行不同任务的软件组件。
- 你的服务：这是一个在你的业务环境上下文中安全运行的应用程序，可使用你选择的任何开发平台来实施。 你的服务负责创建为 Microsoft Store 收藏服务调用 REST URI 所需的 Entra ID 访问令牌。
- 你的游戏：这是你要为其访问和管理客户权利信息的游戏（包括游戏加载项）。 此游戏负责创建调用 Microsoft Store API 所需的用户 Store ID 密钥。
Microsoft.StoreServices .NET 库和示例
为了帮助简化这一认证流程的整合，我们为 Microsoft.StoreServices 库创建了公开可用的 GitHub 项目。 此库有助于管理身份验证密钥，并提供用于调用Microsoft Store服务的包装器 API。 该示例强调了 Web 服务如何与 Microsoft.StoreServices 库集成，以及管理消耗品、核对退款购买、更新过期用户商店 ID 等的示例逻辑。 该示例提供了一个配置指南，其中包括本主题中有关如何为此身份验证方法配置和设置 Entra ID 的步骤。
步骤 1：在 Microsoft Entra ID 中配置应用程序
必须先创建 Entra Web 应用程序，检索应用程序的租户 ID 和应用程序 ID，并生成密钥，然后才能使用 Microsoft Store API。 Microsoft Entra ID Web 应用程序代表你要从中调用 Microsoft Store API 的服务。 你需要租户 ID、应用程序 ID 和密钥来生成调用 API 所需的 Entra ID 访问令牌。
注意
只需执行一次本节中的任务。 获得租户 ID、应用程序 ID 和密钥后，每当需要创建新的 Entra ID 访问令牌时，就可以重复使用这些值。
如果尚未执行此操作，请按照快速入门：向 Microsoft 标识平台注册应用程序中的说明，向 Microsoft Entra ID 注册 Web 应用/API应用程序。
注意
注册应用程序时，必须选择 Web 应用/ API 作为应用程序类型。 这使你能够检索应用程序的密钥（也称为客户端机密）。 若要调用 Microsoft Store API，在稍后步骤中向 Microsoft Entra ID 请求访问令牌时，必须提供客户端密码。
在 Azure 管理门户中，转到“Microsoft Entra ID”。 选择目录，在左窗格中选择 应用注册 ，然后选择应用程序。 将显示应用程序的主注册页。
复制应用程序 ID值以稍后使用。
创建一个密钥（客户端密码），你之后需要用到它。 在左侧窗格中，选择“设置”，然后选择“密钥”。 在此页上，完成 添加客户端密码 的步骤。 复制此密钥以稍后使用。
步骤 2：在合作伙伴中心将 Entra 应用程序 ID 与客户端应用相关联
你必须先在合作伙伴中心中将你的 Entra 应用程序 ID 与你的游戏相关联，然后才能使用 Microsoft Store API 来配置应用或附加内容的所有权和购买。
注意
只需执行一次此任务。
- 登录到合作伙伴中心，然后选择你的游戏。
- 选择服务>产品系列和购买。 将 Entra 应用程序 ID 输入到某一个可用的“客户端 ID”字段中。
步骤 3：创建 Microsoft Entra ID 访问令牌
你的服务必须先创建多个代表你的发布者身份的不同 Entra ID 访问令牌，然后你才可以检索用户 Store ID 密钥或调用 Microsoft Store API。 每个令牌与不同的 API 一起使用。 每个令牌的生存期为 60 分钟。 可以在它们过期后刷新它们。
重要
请仅在服务的上下文（而非应用中）创建 Entra ID 访问令牌。 如果将客户端密码发送到你的应用，则可能会泄露。
了解不同令牌和受众 URI
根据要在 Microsoft Store 收藏服务中调用的 API，你必须创建两个或三个不同的令牌。 每个访问令牌都与不同的访问群体 URI 相关联。
| 访问令牌类型 | 受众 URI | 使用 |
|---|---|---|
| 服务访问令牌 | https://onestore.microsoft.com |
Store 服务终结点的授权标头中的持有者令牌 |
| 集合访问令牌 | https://onestore.microsoft.com/b2b/keys/create/collections |
创建 UserCollectionsID 以调用 b2bLicensePreview 或 PublisherQuery |
| 购买访问令牌 | https://onestore.microsoft.com/b2b/keys/create/purchase |
创建 UserPurchaseID 以调用定期或其他购买服务 |
可以将集合和购买访问令牌发送到客户端，并分别与 GDK API XStoreGetUserCollectionsIdAsync API 或 XStoreGetUserPurchaseIdAsync API 一起使用，以生成相应的用户集合 ID 或用户购买 ID。 这些访问令牌还可用于生成这些用户存储 ID，如 使用 XSTS 令牌或 OAuth 2.0 从服务请求用户存储 ID 中所述。
重要
不应将使用受众的服务 https://onestore.microsoft.com 访问令牌发送到客户端，并且应安全地存储在服务中。
创建访问令牌
若要创建访问令牌，请按照 Microsoft 标识平台和 OAuth 2.0 客户端凭据流 中的说明，在服务中使用 OAuth 2.0 API 将 HTTP POST 发送到 https://login.microsoftonline.com/<tenant_id>/oauth2/token 终结点。
下面是一个示例请求。
POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8
grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://onestore.microsoft.com
对于每个令牌，请指定以下参数数据。
对于
client_id和client_secret参数，请为从 Azure 管理门户中检索到的应用程序指定应用程序 ID 和客户端密码。 这两个参数都是使用 Microsoft Store API 所需的身份验证级别创建访问令牌所必需的。对于
resource参数，请指定上一部分列出的其中一个受众 URI，具体取决于所创建的访问令牌类型。
访问令牌过期后，可以按照Microsoft 标识平台和 OAuth 2.0 授权代码流主题中的"刷新访问令牌"部分中的说明进行刷新。 有关访问令牌结构的详细信息，请参阅安全令牌。
步骤4：创建用户 Store ID 密钥
在调用任何Microsoft应用商店 API 之前，服务必须获取用于标识你代表调用的用户的用户存储 ID 密钥。 可以使用下面介绍的 GDK API 在客户端上生成用户存储 ID 密钥，也可以按照使用 XSTS 令牌或 OAuth 2.0 从服务请求用户存储 ID 中的说明在自己的服务上生成密钥。
使用来自客户端的 GDK API 时，此密钥是 JSON Web 令牌 (JWT) ，表示当前登录到 Microsoft 应用商店应用的用户的标识，并且要访问其产品所有权信息。 有关此密钥中声明的详细信息，请参见用户 Store ID 密钥中的声明。 这两种类型的用户 Store ID 密钥具有相同的格式。 唯一区别是可使用它们向哪个对应的服务进行身份验证。
注意
每个用户 Store ID 密钥的有效期为 30 天。 你可以续订密钥，但这必须在创建或上次续订后的 14 天内进行。 我们建议续订 Microsoft Store ID 密钥，而不是创建新密钥。 有关详细信息，请参阅重新生成用户Store ID密钥。
为 Microsoft Store 收藏服务创建用户收藏 ID 密钥
按照以下步骤创建可用于 Microsoft Store 收藏 API 的用户 Store ID 密钥，以查询用户拥有的产品或将某易耗品报告为已实现。
将具有受众 URI 值
https://onestore.microsoft.com/b2b/keys/create/collections的 Entra ID 访问令牌从你的服务传递到你的游戏。 这是 之前在步骤 3 中创建的令牌之一。在你的游戏中，调用 XStoreGetUserCollectionsIdAsync 来检索用户收藏 ID 密钥：
将 Entra ID 访问令牌传递到该方法的
serviceTicket参数。如果在作为当前应用的发布者管理的服务的上下文中维护匿名用户 ID，则还可以将用户 ID 传递给
publisherUserId参数。 这会将当前用户与新的用户集合 ID 密钥相关联（用户 ID 将嵌入在密钥中）。或者，如果无需将用户 ID 与用户收藏 ID 密钥相关联，则可以将任何字符串值传递到
publisherUserId参数。在应用成功创建用户收藏 ID 密钥后，请将该密钥传递回服务。
为 Microsoft Store 购买服务创建用户购买 ID 密钥
请按照以下步骤创建可用于 Microsoft Store 购买服务的用户购买 ID 密钥，以向用户授予免费产品、获取用户订阅或更改用户的订阅计费状态。
将具有受众 URI 值
https://onestore.microsoft.com/b2b/keys/create/purchase的 Entra ID 访问令牌从你的服务传递到你的游戏。 这是 之前在步骤 3 中创建的令牌之一。在你的应用代码中，调用 XStoreGetUserPurchaseIdAsync 来检索用户购买 ID 密钥：
将 Entra ID 访问令牌传递到该方法的
serviceTicket参数。如果在作为当前应用的发布者管理的服务的上下文中维护匿名用户 ID，则还可以将用户 ID 传递给
publisherUserId参数。 这会将当前用户与新的用户购买 ID 密钥相关联（用户 ID 将嵌入到密钥中）。或者，如果无需将用户 ID 与用户购买 ID 密钥相关联，则可以将任何字符串值传递到
publisherUserId参数。在应用成功创建用户购买 ID 密钥后，请将该密钥传递回服务。
步骤 5：通过用户 Store ID 为 Windows 电脑游戏进行身份验证
有关说明，请参阅通过用户Store ID进行身份验证。
步骤 6：在 Microsoft Store ID 密钥过期时续订该密钥
有关说明，请参阅重新创建用户Store ID密钥。
其他信息
显示用户 Store ID 密钥创建情形的关系图
下图显示了用户 Store ID 密钥的创建过程。
用户 Store ID 密钥中的声明
用户 Store ID 密钥是一个 JWT，它表示你想要访问其产品所有权信息的用户的标识。 使用 Base64 解码时，用户 Store ID 密钥包含下表所示的声明。
| 参数 | 类型 | 说明 |
|---|---|---|
iat |
int |
标识颁发密钥的时间。 此声明可用于确定标记的使用期限。 此值表示为纪元时间。 |
iss |
string |
标识颁发者。 这与 aud 声明具有相同的值。 |
aud |
string |
标识受众。 它必须是下列值之一：https://collections.mp.microsoft.com/v6.0/keys 或 https://purchase.mp.microsoft.com/v6.0/keys。 |
exp |
int |
标识到期时间，该时间后不再接受该密钥处理除续订密钥之外的任何操作。 此声明的值表示为纪元时间。 |
nbf |
int |
标识接受令牌进行处理的时间。 此声明的值表示为纪元时间。 |
https://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId |
string |
标识开发人员的客户端 ID。 |
https://schemas.microsoft.com/marketplace/2015/08/claims/key/payload |
string |
模糊有效负载（已加密和 Base64 编码），其中包含仅供 Microsoft Store 服务使用的信息。 |
https://schemas.microsoft.com/marketplace/2015/08/claims/key/userId |
string |
标识服务上下文中的当前用户的用户 ID。 此值与你传递到密钥创建方法的可选 publisherUserId 参数中的值相同。 |
https://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri |
string |
可用于续订密钥的 URI。 |
下面是已解码的用户 Store ID 密钥标头的示例。
{
"typ":"JWT",
"alg":"RS256",
"kid": "36D101AF67A9F61B8017FB96F91EDD4B22F05804",
"x5t":"agA_pgJ7Twx_Ex2_rEeQ2o5fZ5g"
}
用户 Store ID 密钥的 JWT 签名和 kid 声明应被视为对客户端或游戏服务不透明，并且仅供 Store API 进行验证。
下面是已解码的用户 Store ID 密钥声明集的示例。
{
"https://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId": "1d577369placeholder7393beef1e13d",
"https://schemas.microsoft.com/marketplace/2015/08/claims/key/payload": "placeholderytCRzCHSqnfczv3f0343wfSydx7hghfu0snWzMqyoAGy5DSJ5rMSsKoQFAccs1iNlwlGrX+/eIwh/VlUhLrncyP8c18mNAzAGK+lTAd2oiMQWRRAZxPwGrJrwiq2fTq5NOVDnQS9Za6/GdRjeiQrv6c0x+WNKxSQ7LV/uH1x+IEhYVtDu53GiXIwekltwaV6EkQGphYy7tbNsW2GqxgcoLLMUVOsQjI+FYBA3MdQpalV/aFN4UrJDkMWJBnmz3vrxBNGEApLWTS4Bd3cMswXsV9m+VhOEfnv+6PrL2jq8OZFoF3FUUpY8Fet2DfFr6xjZs3CBS1095J2yyNFWKBZxAXXNjn+zkvqqiVRjjkjNajhuaNKJk4MGHfk2rZiMy/aosyaEpCyncdisHVSx/S4JwIuxTnfnlY24vS0OXy7mFiZjjB8qL03cLsBXM4utCyXSIggb90GAx0+EFlVoJD7+ZKlm1M90xO/QSMDlrzFyuqcXXDBOnt7rPynPTrOZLVF+ODI5HhWEqArkVnc5MYnrZD06YEwClmTDkHQcxCvU+XUEvTbEk69qR2sfnuXV4cJRRWseUTfYoGyuxkQ2eWAAI1BXGxYECIaAnWF0W6ThweL5ZZDdadW9Ug5U3fZd4WxiDlB/EZ3aTy8kYXTW4Uo0adTkCmdLibw=",
"https://schemas.microsoft.com/marketplace/2015/08/claims/key/userId": "infusQplaceholder/SZWoPB4FqLEwHXgZFuMJ6TuTY=",
"https://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri": "https://collections.mp.microsoft.com/v6.0/b2b/keys/renew",
"iat": 1442395542,
"iss": "https://collections.mp.microsoft.com/v6.0/keys",
"aud": "https://collections.mp.microsoft.com/v6.0/keys",
"exp": 1450171541,
"nbf": 1442391941
}