サービス間認証にユーザー Store ID を要求する
このトピックでは、Microsoft Store サービス API でサービス間認証用のユーザー Store ID を取得するために必要な構成と手順について説明します。
ユーザー Store ID を使用して、独自のサービスから Microsoft Store API に対して行う呼び出しを認証できます。 この認証方式は、Windows PC 上でゲームをプレイしているアカウントとは関係なく、デバイス上で Microsoft Store アプリにサインインした、ゲーム内コマースの購入アカウントとしてのユーザーに関係します。
ユーザー Store ID には次の 2 種類があります。
- UserCollectionsID: Microsoft Store コレクション サービスでの認証に使用されます。
- UserPurchaseID: Microsoft Store 購入サービスでの認証に使用されます。
このトピックでは、ユーザー ストア ID を取得して、独自のサービスからそれぞれのサービスを呼び出すプロセスとして、次の手順を示します。
- Microsoft Entra ID でアプリケーションを構成します。
- パートナー センターで Entra アプリケーション ID とクライアント アプリを関連付けます。
- 独自のサービスで、発行元の身元を表す Microsoft Entra ID アクセス トークンを作成します。
- ゲームで、ストア アプリに現在サインインしているユーザーの ID を表すユーザー ストア ID キーを作成します。 このキーをサービスに戻します。
- Windows PC タイトルのユーザー Store ID により認証を行います。
- キーの有効期限が切れたら、Microsoft Store ID キーを更新します。
このプロセスには、異なるタスクを実行する 2 つのソフトウェア コンポーネントが含まれます。
- 独自のサービス: ビジネス環境のコンテキストで安全に実行されるアプリケーションであり、選択した任意の開発プラットフォームを使用して実装できます。 独自のサービスでは、Microsoft Store コレクション サービスの REST URI を呼び出しに必要な Entra ID アクセス トークンを作成します。
- 独自のゲーム: ユーザーの利用資格情報にアクセスして管理する対象となるゲーム (ゲームのアドオンを含む) です。 このゲームで、Microsoft Store API を呼び出すために必要なユーザー Store ID キーを作成します。
Microsoft.Store Services .NET ライブラリとサンプル
この認証フローの統合を合理化するために、Microsoft.StoreServices ライブラリ用に公開されている GitHub プロジェクトを作成しました。 このライブラリは、認証キーの管理に役立ち、Microsoft Store サービスを呼び出すためのラッパー API を提供します。 このサンプルは、Web サービスを Microsoft.StoreServices ライブラリと統合する方法と、消耗品の管理、返金された購入の調整、期限切れのユーザー ストア ID の更新などのロジックの例を示しています。 このサンプルは、この認証方法用に Entra ID を構成およびセットアップする方法に関するこのトピックの手順を含む構成ガイドを提供します。
手順 1: Microsoft Entra ID でアプリケーションを構成する
Microsoft Store API を使用するには、その前に、Entra Web アプリケーションを作成し、そのアプリケーションのテナント ID とアプリケーション ID を取得して、キーを生成する必要があります。 Microsoft Entra ID Web アプリケーションは、Microsoft Store API を呼び出すサービスを表します。 この API を呼び出すために必要な Entra ID アクセス トークンを生成するには、テナント ID、アプリケーション ID、キーが必要です。
注意
このセクションで説明するタスクを行う必要があるのは 1 回限りです。 テナント ID、アプリケーション ID、秘密鍵を取得した後は、いつでもこれらの値を再利用して新しい Entra ID アクセス トークンを作成できます。
「クイック スタート: Microsoft ID プラットフォームにアプリケーションを登録する」で説明している手順をまだ行っていない場合は、この手順に従って Web アプリ/API アプリケーションを Microsoft Entra ID に登録します。
注意
アプリケーションを登録するときは、アプリケーションの種類として Web アプリ / API を選択する必要があります。 これにより、アプリケーションのキー (クライアント シークレットとも呼ばれます) を取得できます。 Microsoft Store API を呼び出すには、後の手順で Microsoft Entra ID にアクセス トークンを要求するときにクライアント シークレットを渡す必要があります。
Azure 管理ポータルで、Microsoft Entra ID に移動します。 該当するディレクトリを選択し、左側のウィンドウで [アプリの登録] を選択して、作成したアプリケーションを選択します。 メインのアプリケーション登録ページが表示されます。
後で使用するために [アプリケーション ID] の値をコピーします。
後で必要になるキー (クライアント シークレット) を作成します。 左側のウィンドウで [設定] を選択し、[キー] を選択します。 これにより表示されるページで、クライアント シークレットを追加する手順に従います。 このキーをコピーして、後で使用します。
手順 2: パートナー センターで Entra アプリケーション ID とクライアント アプリを関連付ける
Microsoft Store API を使用してアプリまたはアドオンの所有権と購入を構成するには、その前に、パートナー センターで Entra アプリケーション ID とゲームを関連付ける必要があります。
注意
このタスクは 1 回だけ実行する必要があります。
- パートナー センターにサインインして、該当するゲームを選択します。
- [サービス]>[製品の収集と購入] の順に選択します。 使用可能なクライアント ID フィールドの 1 つに Entra アプリケーション ID を入力します。
手順 3: Microsoft Entra ID アクセス トークンを作成する
ユーザー Store ID キーを取得したり、Microsoft Store API を呼び出したりするには、その前に、サービスで発行元の身元を表す数種類の Entra ID アクセス トークンを作成する必要があります。 各トークンは異なる API で使用されます。 各トークンの有効期間は 60 分です。 有効期限が切れたら更新することができます。
Important
Entra ID アクセス トークンは、アプリ内ではなく、サービスのコンテキスト内でのみ作成してください。 クライアント シークレットがアプリに送信されると、不正に使用される恐れがあります。
各種のアクセス トークンと対象ユーザー URI について
Microsoft Store コレクション サービスで呼び出す API に応じて、2 つまたは 3 つの異なるトークンを作成する必要があります。 各アクセス トークンは、異なる対象ユーザー URI に関連付けられています。
| アクセス トークンの種類 | 対象ユーザーの URI | 使用 |
|---|---|---|
| サービス アクセス トークン | https://onestore.microsoft.com |
Authorization ヘッダーにある Store Service エンドポイントへのベアラー トークン |
| コレクションのアクセス トークン | https://onestore.microsoft.com/b2b/keys/create/collections |
b2bLicensePreview または PublisherQuery を呼び出す UserCollectionsID の作成 |
| 購入アクセス トークン | https://onestore.microsoft.com/b2b/keys/create/purchase |
繰り返しまたはその他の購入サービスを呼び出す UserPurchaseID の作成 |
コレクションと購入アクセス トークンをクライアントに送信し、GDK API XStoreGetUserCollectionsIdAsync API または XStoreGetUserPurchaseIdAsync API でそれぞれ使用して、対応するユーザー コレクション ID またはユーザー購入 ID を生成できます。 これらのアクセス トークンは、「XSTS トークンまたは OAuth 2.0 を使用してサービスからユーザー Store IDを要求する」で説明されているように、これらのユーザー Store ID を生成するためにも使用できます。
Important
https://onestore.microsoft.com 対象ユーザーを使用するサービス アクセス トークンは、クライアントに送信せずに、サービス内に安全に格納する必要があります。
アクセス トークンの作成
アクセス トークンを作成するには、「Microsoft ID プラットフォームの指示と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 ID プラットフォームおよび OAuth 2.0 認証コード フロー」 トピックの「アクセス トークンの更新」セクションの手順に従って更新できます。 アクセス トークンの構造の詳細については、「セキュリティ トークン」を参照してください。
手順 4: ユーザー Store ID キーを作成する
Microsoft Store API を呼び出すには、サービスで代わりに呼び出しているユーザーを識別するユーザー Store ID キーを取得する必要があります。 ユーザー Store ID キーは、以下で説明する GDK API を使用してクライアント上で生成するか、「XSTS トークンまたは OAuth 2.0 を使用してサービスからユーザー Store IDを要求する」の手順に従って、独自のサービスで生成できます。
クライアントから GDK API を使用する場合、このキーは現在 Microsoft Store アプリにサインインしていて、アクセス対象の製品所有権情報を持っているユーザーの身元を表す JSON Web トークン (JWT) です。 このキーに含まれる要求の詳細については、「ユーザー Store ID キーに含まれる要求」のセクションを参照してください。 2 種類のユーザー Store ID キーの形式は、どちらも同じです。 この 2 つの唯一の違いは、そのキーを使用して認証を行うことができる対象のサービスのみです。
注意
各ユーザー Store ID キーは 30 日間有効です。 キーは更新できますが、作成から 14 日以内または最後の更新から 14 日以内に行う必要があります。 新しい Microsoft Store ID キーを作成するのではなく、更新することをお勧めします。 詳細については、「ユーザー Store ID キーの更新」を参照してください。
Microsoft Store コレクション サービスのユーザー コレクション ID キーを作成するには
次の手順に従って、ユーザー Store ID キーを作成します。このキーを Microsoft Store コレクション API で使用することで、ユーザーが所有している製品をクエリしたり、消費型の製品をフルフィルメント完了として報告したりできます。
サービスからゲームに、対象ユーザー URI の値
https://onestore.microsoft.com/b2b/keys/create/collectionsが含まれる Entra ID アクセス トークンを渡します。 これは、前に手順 3 で作成したトークンのいずれかです。ゲームで XStoreGetUserCollectionsIdAsync を呼び出して、ユーザー コレクション ID キーを取得します。
メソッドの
serviceTicketパラメーターには、Entra ID アクセス トークンを渡します。現在のアプリの発行元として管理しているサービスのコンテキストで匿名ユーザー ID を維持している場合は、ユーザー ID を
publisherUserIdパラメーターに渡すこともできます。 これにより、現在のユーザーが新しいユーザー コレクション ID キーに関連付けられます (ユーザー ID はキーに埋め込まれます)。ユーザー ID を匿名ユーザー ID としてユーザー コレクション ID キーに関連付ける必要がない場合は、任意の文字列値を
publisherUserIdパラメーターに渡すことができます。アプリで正しくユーザー コレクション ID キーを作成した後、そのキーをサービスに渡します。
Microsoft Store 購入サービスのユーザー購入 ID キーを作成するには
次の手順に従って、ユーザー購入 ID キーを作成します。このキーを Microsoft Store 購入サービスで使用することで、無料の製品をユーザーに付与したり、ユーザーのサブスクリプションを取得したり、ユーザーのサブスクリプションの課金状態を変更したりできます。
サービスからゲームに、対象ユーザー URI の値
https://onestore.microsoft.com/b2b/keys/create/purchaseが含まれる Entra ID アクセス トークンを渡します。 これは、前に手順 3 で作成したトークンのいずれかです。アプリ コードで XStoreGetUserPurchaseIdAsync を呼び出して、ユーザー購入 ID キーを取得します。
メソッドの
serviceTicketパラメーターには、Entra ID アクセス トークンを渡します。現在のアプリの発行元として管理しているサービスのコンテキストで匿名ユーザー ID を維持している場合は、ユーザー ID を
publisherUserIdパラメーターに渡すこともできます。 これにより、現在のユーザーが新しいユーザー 購入 ID キーに関連付けられます (ユーザー ID はキーに埋め込まれます)。ユーザー ID を匿名ユーザー ID としてユーザー購入 ID キーに関連付ける必要がない場合は、任意の文字列値を
publisherUserIdパラメーターに渡すことができます。アプリで正しくユーザー購入 ID キーを作成した後、そのキーをサービスに渡します。
手順 5: Windows PC タイトルのユーザー Store ID を使用して認証を行う
手順については、「ユーザー ストア 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 |
Microsoft Store サービスでのみ使用されるよう意図された情報を含む、不透明なペイロード (暗号化されて Base64 でエンコードされます)。 |
https://schemas.microsoft.com/marketplace/2015/08/claims/key/userId |
string |
サービスのコンテキストで現在のユーザーを識別するユーザー ID。 これは、User Store 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"
}
ユーザー ストア ID キーの JWT 署名と kid 要求は、クライアントまたはタイトル サービスに対して不透明として扱う必要があり、ストア 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
}
関連項目
Microsoft Store API によるサービスの認証
XSTS トークンまたは OAuth 2.0 を使用してサービスからユーザー Store IDを要求する