Requesting a User Store ID for service-to-service authentication

  • Article

This topic describes the required configuration and steps to get a User Store ID for service-to-service authentication with the Microsoft Store service APIs.

A User Store ID can be used to authenticate a call from your own service to the Microsoft Store API. This method of authentication is tied to the user who is signed in to the Microsoft Store app on the device that's the purchasing account for in-game commerce, regardless of which account is playing the game on a Windows PC.

There are two types of User Store IDs.

  1. UserCollectionsID to authenticate with the Microsoft Store Collections service
  2. UserPurchaseID to authenticate with the Microsoft Store Purchase service

This topic provides the following steps as the process for getting a User Store ID to call their respective services from your own service.

  1. Configure an application in Microsoft Entra ID.
  2. Associate your Entra application ID with your client app in Partner Center.
  3. In your service, create Microsoft Entra ID access tokens that represent your publisher identity.
  4. In your game, create a User Store ID key that represents the identity of the user who's currently signed in to the store app. Pass this key back to your service.
  5. Authenticate through a User Store ID for Windows PC titles.
  6. Renew a Microsoft Store ID key when it expires.

This process involves two software components that perform different tasks.

  • Your service: This is an application that runs securely in the context of your business environment, and it can be implemented by using any development platform that you choose. Your service is responsible for creating the Entra ID access tokens that are needed for calling the REST URIs for the Microsoft Store Collections service.
  • Your game: This is the game for which you want to access and manage use entitlement information (including add-ons for the game). This game is responsible for creating the User Store ID keys that you need to call the Microsoft Store APIs.

The Microsoft.StoreServices .NET library and sample

To help streamline integration of this authentication flow, we've created a publicly available GitHub project for the Microsoft.StoreServices library. This library helps manage the authentication keys and provides wrapper APIs to call into Microsoft Store Services. The sample highlights how a web service can integrate with the Microsoft.StoreServices library and example logic for managing consumable products, reconciling refunded purchases, renewing expired User Store IDs, and more. The sample provides a configuration guide that includes the steps in this topic about how to configure and set up your Entra ID for this authentication method.

Step 1: Configure an application in Microsoft Entra ID

Before you can use the Microsoft Store APIs, you must create an Entra web application, retrieve the tenant ID and application ID for the application, and generate a key. The Microsoft Entra ID web application represents the service from which you want to call the Microsoft Store APIs. You need the tenant ID, application ID, and key to generate the Entra ID access tokens that you need to call the API.

Note

You need to perform the tasks in this section only once. After you have your tenant ID, application ID, and secret key, you can reuse these values whenever you need to create a new Entra ID access token.

  1. If you haven't done so already, follow the instructions in Quickstart: Register an application with the Microsoft identity platform to register a Web app / API application with Microsoft Entra ID.

    Note

    When you register your application, you must choose Web app / API as the application type. This enables you to retrieve a key (also called a client secret) for your application. To call the Microsoft Store APIs, you must provide a client secret when you request an access token from Microsoft Entra ID in a later step.

  2. In the Azure Management Portal, go to Microsoft Entra ID. Select your directory, select App registrations in the left pane, and then select your application. The application's main registration page appears.

  3. Copy the Application ID value to use later.

  4. Create a key (a client secret) that you'll need later. In the left pane, select Settings and then select Keys. On this page, complete the steps to Add a client secret. Copy this key to use later.

Step 2: Associate your Entra application ID with your client app in Partner Center

Before you can use the Microsoft Store APIs to configure the ownership and purchases for your app or add-on, you must associate your Entra application ID with your game in Partner Center.

Note

You need to perform this task only once.

  1. Sign in to Partner Center, and then select your game.
  2. Select Services > Product collections and purchases. Enter your Entra application ID into one of the available Client ID fields.

Step 3: Creating Microsoft Entra ID access tokens

Before you can retrieve a User Store ID key or call the Microsoft Store APIs, your service must create several different Entra ID access tokens that represent your publisher identity. Each token is used with a different API. The lifetime of each token is 60 minutes. You can refresh them after they expire.

Important

Create Entra ID access tokens only in the context of your service, not in your app. Your client secret could be compromised if it's sent to your app.

Understanding the different access tokens and audience URIs

Depending on which API you want to call in the Microsoft Store Collections service, you must create either two or three different tokens. Each access token is associated with a different audience URI.

Service Access Token

Created with the https://onestore.microsoft.com audience URI.

This token is used in all calls from your service to the Microsoft Store APIs as the Authorization header.

Important

Use the https://onestore.microsoft.com audience only with access tokens that are stored securely within your service. Exposing access tokens with this audience outside your service could make your service vulnerable to replay attacks.

Collections Access Token

Created with the https://onestore.microsoft.com/b2b/keys/create/collections audience URI.

This token is passed to the client and used as a parameter when calling the GDK XStoreGetUserCollectionsIdAsync API to request a User Collections ID.
The User Collections ID can then be used in your service calls to the Microsoft Store Collections APIs.

Purchase Access Token

Created with the https://onestore.microsoft.com/b2b/keys/create/purchase audience URI.

This token is passed to the client and used as a parameter when calling the GDK XStoreGetUserPurchaseIdAsync API to request a User Purchase ID.
The User Purchase ID can then be used in your service calls to the Microsoft Store Purchase APIs.

Create the tokens

To create the access tokens, use the OAuth 2.0 API in your service by following the instructions in Microsoft identity platform and the OAuth 2.0 client credentials flow to send an HTTP POST to the https://login.microsoftonline.com/<tenant_id>/oauth2/token endpoint. Following is a sample request.

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

For each token, specify the following parameter data.

  • For the client_id and client_secret parameters, specify the application ID and the client secret for your application that you retrieved from the Azure Management Portal. Both of these parameters are required to create an access token with the level of authentication that's required by the Microsoft Store APIs.

  • For the resource parameter, specify one of the audience URIs that's listed in the previous section, depending on the type of access token that you're creating.

After your access token expires, you can refresh it by following the instructions in the Refresh the access token section in the Microsoft identity platform and OAuth 2.0 authorization code flow topic. For more details about the structure of an access token, see Security tokens.

Step 4: Create a User Store ID key

Before you can call any Microsoft Store APIs, your game must create a corresponding key on the client and send it to your service. This key is a JSON Web Token (JWT) that represents the identity of the user who's currently signed in to the Microsoft Store App and whose product ownership information you want to access. For more information about the claims in this key, see Claims in a User Store ID key. The format for both types of User Store ID keys is the same. The only difference is which corresponding service they can be used to authenticate with.

Note

Each User Store ID key is valid for 30 days. You can renew the key, but this must be done within 14 days of the creation or last renewal. We recommend that you renew your Microsoft Store ID keys rather than create new ones. For more information, see Renewing a User Store ID key.

To create a User Collections ID key for the Microsoft Store Collections service

Follow these steps to create a User Store ID key that you can use with the Microsoft Store collection API to query for products that are owned by a user or report a consumable product as fulfilled.

  1. Pass the Entra ID access token that has the audience URI value https://onestore.microsoft.com/b2b/keys/create/collections from your service to your game. This is one of the tokens that you created previously in step 3.

  2. In your game, call XStoreGetUserCollectionsIdAsync to retrieve a User Collections ID key:

    Pass your Entra ID access token to the serviceTicket parameter of the method.

    If you maintain anonymous user IDs in the context of services that you manage as the publisher of the current app, you can also pass a user ID to the publisherUserId parameter. This associates the current user with the new User Collections ID key (the user ID will be embedded in the key).

    Otherwise, if you don't need to associate a user ID with the User Collections ID key, you can pass any string value to the publisherUserId parameter.

  3. After your app successfully creates a User Collections ID key, pass the key back to your service.

To create a User Purchase ID key for the Microsoft Store Purchase service

Follow these steps to create a User Purchase ID key that you can use with the Microsoft Store Purchase service to grant a free product to a user, get subscriptions for a user, or change the billing state of a subscription for a user.

  1. Pass the Entra ID access token that has the audience URI value https://onestore.microsoft.com/b2b/keys/create/purchase from your service to your game. This is one of the tokens that you created previously in step 3.

  2. In your app code, call XStoreGetUserPurchaseIdAsync to retrieve a User Purchase ID key:

    Pass your Entra ID access token to the serviceTicket parameter of the method.

    If you maintain anonymous user IDs in the context of services that you manage as the publisher of the current app, you can also pass a user ID to the publisherUserId parameter. This associates the current user with the new User Purchase ID key (the user ID will be embedded in the key).

    Otherwise, if you don't need to associate a user ID with the User Purchase ID key, you can pass any string value to the publisherUserId parameter.

  3. After your app successfully creates a User Purchase ID key, pass the key back to your service.

Step 5: Authenticate through a User Store ID for Windows PC titles

For instructions, see Authenticating through a User Store ID.

Step 6: Renew a Microsoft Store ID key when it expires

For instructions, see Renewing a User Store ID key.

Additional information

Diagram of creating a User Store ID key

The following diagram illustrates the process of creating a User Store ID key.

Image of a diagram that shows the process of creating a User Store ID key. From left to right, there are blocks for Your service, Microsoft Entra ID, and your app with the previous two arranged vertically, Windows SDK, and Store. There are four numbered arrows that show the flow from Your service to Microsoft Entra ID, Your service to Your app, Your app to Windows SDK and Store, and then from Your app to Your service. There are dotted arrows from Store to Windows SDK, Windows SDK to Your app, and from Microsoft Entra ID to your service.

Claims in a User Store ID key

A User Store ID key is a JWT that represents the identity of the user whose product ownership information you want to access. When decoded by using Base64, a User Store ID key contains the claims as shown in the following table.

Parameter Type Description
iat int Identifies the time at which the key was issued. This claim can be used to determine the age of the token. This value is expressed as epoch time.
iss string Identifies the issuer. This has the same value as the aud claim.
aud string Identifies the audience. It must be one of the following values: https://collections.mp.microsoft.com/v6.0/keys or https://purchase.mp.microsoft.com/v6.0/keys.
exp int Identifies the expiration time on which or after which the key will no longer be accepted for processing anything except for renewing keys. The value of this claim is expressed as epoch time.
nbf int Identifies the time at which the token will be accepted for processing. The value of this claim is expressed as epoch time.
https://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId string The client ID that identifies the developer.
https://schemas.microsoft.com/marketplace/2015/08/claims/key/payload string An opaque payload (encrypted and Base64-encoded) that contains information that's intended only for use by Microsoft Store Services.
https://schemas.microsoft.com/marketplace/2015/08/claims/key/userId string A user ID that identifies the current user in the context of your services. This is the same value that you pass into the optional publisherUserId parameter of the method you use to create the User Store ID key.
https://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri string The URI that you can use to renew the key.

Following is an example of a decoded User Store ID key header.

{
    "typ":"JWT",
    "alg":"RS256",
    "kid": "36D101AF67A9F61B8017FB96F91EDD4B22F05804",
    "x5t":"agA_pgJ7Twx_Ex2_rEeQ2o5fZ5g"
}

The JWT signature and kid claim of the User Store ID key should be treated as opaque to the client or title services and are intended to be validated by Store APIs only.

Following is an example of a decoded User Store ID key claim set.

{
    "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
}

See also

Manage products from your services

Authenticating your service with the Microsoft Store APIs

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

Renewing a User Store ID key

Microsoft.StoreServices library

Microsoft.StoreServices sample