Requesting a User Store ID from your service with XSTS tokens or OAuth 2.0

Article
03/16/2023

This topic describes how your service can generate User Store IDs from your service without having to exchange Access Tokens and the User Store ID from your game client. The following scenarios benefit this method of generating the User Store IDs:

Experiences where there is not a game client within the flow
Linking the user's Xbox account to your own service's account for the user
Games and services that are already using XSTS token authentication for client-to-service and service-to-service calls

For information on User Store IDs in general, please see Requesting a User Store ID for service-to-service authentication.

XSTS token requirement

This process requires the use of a Delegated Auth XSTS Token to identify the user that the User Store ID will represent.

For more information on Delegated Auth XSTS Tokens and how to create them, see Title service calls to Xbox services (NDA topic)Authorization required.

OAuth 2.0 requirements to generate the User Store IDs

If your service uses OAuth to have the user sign in with their Microsoft Account (MSA), the following are required:

User must have an Xbox identity tied to their Microsoft Account as the OAuth credentials will need to be exchanged for an XSTS token (see above).
The OAuth scope you request must include both xboxlive.signin and xboxlive.offline_access to ensure proper user consent for this flow and ability to retrieve the required XSTS token.

For more information on using Xbox services login with OAuth on your service, see Xbox services sign-in for title websites (NDA topic)Authorization required.

Steps when using OAuth 2.0 credentials

With OAuth we can obtain the user's consent and an exchange the OAuth credentials and tokens to create an XSTS token for the user against your own relying party. Once we have the XSTS token for the user, you use it in the same flow as outlined in the Steps when using XSTS Tokens below.

Outline flow to exchange OAuth credentials for an XSTS token:

Obtain the OAuth 2.0 authorization code
Exchange the authorization code for an RPS token (also called a Microsoft Account access token)
Exchange the RPS token for an Xbox User Token
Exchange the Xbox User Token for an XSTS Token against your own Relying Party
Use the X-token in the Steps when using XSTS Tokens below.

For full implementation details of the steps above see Xbox services sign-in for title websites (NDA topic)Authorization required.

Steps when using XSTS Tokens

Once we have an XSTS token that identifies the user for our own Relying Party, we can then use the DelegationToken claim in the token to create the Delegated Auth XSTS token needed to create the User Store IDs. The initial XSTS token for this flow can either come from the game client, or from the OAuth2.0 flow listed above.

Outline flow to create a Delegated Auth XSTS token:

Extract the DelegationToken claim (dlt) from the user's XSTS token.
Obtain a Service Token from the XSAS service using your Business Partner certificate.
Exchange the DelegationToken, Service Token, and target Relying Party (see table below) for a Delegated Auth XSTS token.

For full implementation details on how to create Delegated Auth XSTS tokens please see Title service calls to Xbox services (NDA topic)Authorization required.

In step 3, the Relying Party that you will use depends on if you are generating a User Collections ID or a User Purchase ID for the user:

User Store ID type	Delegated Auth XSTS token Relying Party	URI to create User Store ID
User Collections ID	`http://licensing.xboxlive.com`	`https://collections.mp.microsoft.com/v7.0/beneficiaries/me/keys`
User Purchase ID	`http://mp.microsoft.com/`	`https://purchase.mp.microsoft.com/v7.0/users/me/keys`

Request

Once we have the Delegated Auth XSTS token for the user and against the corresponding Relying Party, we can request the User Store ID.
To do so we make an HTTPS POST request to the corresponding URI based on which type of User Store ID we are generating (see table above).

Request syntax

Method	Request URI
`POST`	`collections.mp.microsoft.com/v7.0/beneficiaries/me/keys`
`POST`	`purchase.mp.microsoft.com/v7.0/users/me/keys`

Request header

Header	Type	Description
`Authorization`	`string`	Required. The Delegated Auth XSTS Token representing the User in format `XBL3.0 x=[User Hash];[Token]`
`Host`	`string`	Must match the host of the URI being called
`Content-Length`	`number`	The length of the request body.
`Content-Type`	`string`	Specifies the request and response type. Currently, the only supported value is `application/json`.

Request body

Parameter	Type	Description	Required
`serviceTicket`	`string`	Your service's Collections Access Token or Purchase Access Token based on which of the URIs you are calling. For information on creating these access tokens see Understanding the different tokens and audience URIs.	Yes
`publisherUserId`	`string`	Optional value that will be stamped into the User Store ID and can be used for your own tracking	No

Request example

POST https://collections.mp.microsoft.com/v7.0/beneficiaries/me/keys HTTP/1.1
Authorization: XBL3.0 x=13178812777611882182;eyJlbmMiOiJBMTI4Q0JDK...
Content-Length: 1352
Content-Type: application/json;
Host: collections.mp.microsoft.com
 
{
    "serviceTicket": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn...",
    "publisherUserId": "CustomPublisherUserId"
}

Response

Response body

Parameter	Type	Description	Required
`key`	`string`	The User Store ID that can then be used for service-to-service authentication with the Microsoft Store Services	Yes

Response example

HTTP/1.1 200 OK
Date: Wed, 23 Mar 2022 23:06:25 GMT
Content-Type: application/json; 
Content-Length: 1716
MS-CorrelationId: dd5be303-f9a0-408a-bd01-e8c63afa721a
MS-RequestId: 0b9c8e5e-dfdd-4cf8-bfbe-93a5be3a7f48
MS-CV: rqFUH3gA+UOmTyXe.0

{"key":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjY..."}

Share via