Microsoft Store API によるサービスの認証

このトピックでは、代理認証トークンまたはユーザー Store ID を取得して使用し、Microsoft Store サービスで認証する方法を説明します。

Microsoft Store API による認証は、次の 2 つの方法で行うことができます。

• ユーザー Store ID および Microsoft Entra ID Microsoft Store アプリにサインインしているユーザー アカウントに認証と結果を結び付けます。
• 代理認証 XSTS トークン: 現在ゲームをプレイしているユーザーの Xbox サービス アカウントに認証と結果を結び付けます。

新しいタイトルとサービスでは PC タイトルと Xbox タイトルの両方でユーザー Store ID の認証方法を使用することをお勧めします。 XSTS トークンは、ゲームをプレイしているユーザーにスコープされます。PC の場合、購入トランザクションを実行しているアカウントでない場合もあります。 (詳細については、「PC で一致しないストア アカウントを処理するシナリオ」を参照してください。) また、XSTS トークンは、定期サービスや購買サービスなど、一部のMicrosoft Store サービスではサポートされていません。 Microsoft Store の将来のサービスと開発では、XSTS トークンではなく、ユーザー Store ID を活用します。

クロスプラットフォームのコマース ソリューションまたはサービスで計画しているタイトルは、クライアントの操作なしで更新できるため、ユーザー Store ID を使用する必要があります。 サービスの XSTS 認証フローには、アクティブなクライアントへの接続が再び必要になる前に 30 日の最大有効期間があります。

以下は、前述のタイプから適切な承認を取得する方法に関するリソースと構成です。

代理認証 XSTS トークンによる認証

次の形式で要求の Authorization ヘッダーを追加して、代理認証 XSTS トークンを使用してサービス間呼び出しを認証します。

Authorization: XBL3.0 x=<user hash>;<XSTS token>

XSTS トークンのターゲット証明書利用者は、https://licensing.xboxlive.com である必要があります。これは、従来の Xbox の Inventory サービスと同じです。 以前のサービスが Xbox の Inventory を呼び出すようにセットアップされていた場合は、このエンドポイントと同じトークンを再利用できます。 また、生成された署名が指定されたエンドポイントの署名ポリシーと一致する場合にも、署名ヘッダーが必要です。

代理認証 XSTS トークンと署名を取得、管理、および使用する方法の詳細については、次のリソースを参照してください。

• ゲーム サービスのサンプル クライアントからの XSTS トークン、サーバー間の認証、コマース サービスなどの検証と処理を示す包括的な Web サービスのサンプル。 最新バージョンを GDK ダウンロード サイトからダウンロードします。 すべてのサンプルの最新リリースをダウンロードします。 ゲーム サービス サンプルは、ダウンロードした zip ファイルの samples\Live\GameService にあります。
• Xfest 2019 - 容易な XSTS 認証とサーバー間転送 XSTS トークンの概要と説明、およびゲーム サービスのサンプルでサーバー間認証の独自の作業を開始するのに役立つ方法。 プレゼンテーション情報をダウンロードするには、アーカイブ サイトの [GDK トラッキングのダウンロード] を選択します。
• Xbox サービス認証とサービス間呼び出し (NDA トピック)認可が必須です: 認証、XSTS トークン、Xbox サービスへのサービス間呼び出しを行うために必要な手順と呼び出しに関する詳細なドキュメント。

代理認証XSTS トークンを使用して製品を表示および管理するために必要な追加構成

代理認証XSTS トークンはパートナー センターのビジネス パートナーに関連付けられているため、表示または管理する製品は、XSTS トークンに関連付けられているビジネス パートナーにリンクする必要があります。 これは、アイテムを製品に構成し、パートナー センターのゲームの Xbox 設定ページで対象のビジネス パートナーが選択されていることを確認することで行われます。 この製品グループは、パートナー センターで定義されたスタジオ ID とひも付けられています。 スタジオ ID は、XSTS トークンがひも付けられるビジネス パートナーと同じ ID である必要があります。

XSTS トークンのビジネス パートナー ID に製品が正しくリンクされていない場合の最も一般的な症状は、コレクションの呼び出しは成功するものの、結果に項目がないことです。 (詳細については、フォーラムの投稿「コレクションの LicensePreview サービスへの B2B 呼び出しが空の結果を返す (パートナー センターで定義されたゲーム)」を参照してください。)

パートナー センターで製品とWeb サービスを適切に構成するには

1. ビジネス パートナー証明書は、Web サービスの [証明書を作成] リンクを使用して作成します。 ([開発者設定]、>[Xbox Live]、>[Web サービス] の順に選択します。) 証明書利用者が関連付けられているWeb サービスの行のリンクを選択します。

2. ビジネス パートナー管理 UI ([開発者設定]>[Xbox Live]>[ビジネス パートナー]] の順に選択) に移動し、上記で使用した Web サービスのビジネス パートナー ID に一致するビジネス パートナー ID をコピーします。 (ビジネス パートナー ID の例: 12345678-9012-3456-7890-123456789012)

3. 該当する製品の[パートナー センターの概要] ページから、[新規作成] を選択して、[製品グループ] を選択します。

4. この製品グループを開発スタジオに割り当てるか、それがない場合は [新しい開発者スタジオの作成] を選択します。

5. 選択または作成する開発スタジオ ID は、この説明の手順 2 で取得したビジネス パートナー ID と一致している必要があります。 この値をDev Studio ID (オプション) テキスト ボックスにコピーします。 このボックスに既に値が入力されている場合は、既存の値を変更せず、新しい開発スタジオを作成することをお勧めします。 値を変更しても、既存のタイトルで既に使用されている場合、この変更により既存のサービスや企業間通話ができなくなる可能性があります。

6. 開発スタジオにビジネス パートナーの一致する ID が設定されたら、作成した製品グループに戻ります。 ゲームとすべての製品をこの製品グループに含まれる一覧に追加します。

7. [保存] を選択して製品グループの作成を完了します。

8. ゲームの Xbox 設定 UI に移動し、リンクされているビジネス パートナーが上記の手順で使用したものと同じであることを確認します。

9. 製品グループ内のすべてのアイテムを、Sandbox または開発者環境の Microsoft Store に再公開します。

発行処理が完了すると、サービス呼び出しから適切なアイテムが返却されるのが確認できるようになります。

Microsoft Entra ID とユーザー ストア ID を使用した認証

すべての Microsoft Store サービス API は、Microsoft Entra ID (旧称 Azure Active Directory) とユーザー ストア ID を使用した認証をサポートします。 この認証の種類を使用するには、ユーザー (または組織) に Microsoft Entra ID テナントがあり、その下にアプリケーション ID を登録する必要があります。 アプリケーションを登録するには、アカウントにテナントの グローバル管理者 ロールが必要です。 Microsoft Office 365 または Microsoft の他のビジネス サービスを既に使用している場合は、Azure portal で管理できる Microsoft Entra ID テナントが既にあります。

この認証タイプに必要なユーザー ストア ID を取得するガイダンスについては、「サーバー間認証にユーザー Store ID を要求する」を参照してください。

注意

PC では、資格は、現在タイトルをプレイしているユーザーではなく、Microsoft Store アプリにサインインしているユーザーに関連付けられています。 このような場合や、アカウントが異なる場合があるため、PC タイトルは、「PC でのストア アカウントの不一致シナリオの処理」の情報を確認することをお勧めします。

Entra ID フローを使用して Microsoft Store API を呼び出すと、次のように Authorization 要求のヘッダーに Entra アクセス トークンが使用されます。

Authorization: Bearer <Entra ID access token>  

サンドボックスで作業している場合は、要求の JSON 本文に次の要求を追加して、どのサンドボックスなのかを指定する必要があります。 この値がない場合、結果のサンドボックス スコープは既定で RETAIL に設定されます。

例:

  "sbx": "XDKS.1"

また、クライアントから取得したユーザー Store ID を使用して、要求の JSON 本文に、次の表に示すパラメーターを追加する必要があります。

パラメーター	型	説明	必須
identityType	string	文字列値 b2b を指定します。	はい
identityValue	string	消費型製品をフルフィルメント完了として報告するユーザーの ID を表すユーザー Store ID キー。	はい
localTicketReference	string	返された応答で必要な識別子。 ユーザー ストア ID キーの userId要求と同じ値を使用することをお勧めします。	はい

例:

  "beneficiaries": [
    {
        "identitytype" : "b2b",
        "identityValue" : "eyJ0eXAiOiJ...",
        "localTicketReference" : "testReference"
    }
  ],

ユーザー Store ID を取得、管理、使用する方法の詳細については、次のリソースを参照してください。

• Microsoft.StoreServices (GitHub) 独自のバック エンド サービスから Microsoft Store Services を認証して呼び出すプロセスを簡素化できるソース コードとライブラリ。 これらのサービスを使用すると、Microsoft Store (Xbox コンソールを含む) 内でアプリまたはゲーム用に行われたユーザー購入を確認して管理できます。
• Microsoft.StoreServices Sample (GitHub) 独自のバック エンド サービスから Microsoft Store Services を認証して呼び出すプロセスを簡素化するために、Microsoft.StoreServices ライブラリの使用を強調する Web サービス サンプル。 このサンプルでは、クローバック サービスを使用して消耗品を管理し、払い戻し済みの購入を調整するロジックのサンプルも提供します。
• サービス間認証にユーザー Store ID を要求する
• ユーザー Store ID キーを更新する
• サービスによる製品の権利の管理

Microsoft Store API 呼び出しの図

次の図は、サービスからユーザー Store ID を使用して Microsoft Store API を呼び出すプロセスを説明したものです。

ユーザー Store ID/AAD 認証を使用して製品を表示および管理するために必要な追加の構成

Microsoft Entra ID 認証とユーザー Store ID を使用するようにサービスを設定する場合は、パートナー センターでゲームの製品収集と購入リストに Entra アプリケーション クライアント ID を追加する必要があります。 収集と購入サービスを呼び出すときに、製品とそのアドオンを表示できる 2 つの個別のクライアント アプリ ID を設定できます。 Entra アプリケーション クライアント ID に製品が正しくリンクされていない場合の最も一般的な症状は、収集の呼び出しは成功するものの、結果に項目がないことです。

Microsoft Entra ID とユーザー Store ID を介してサービスに表示されるように製品を構成する

1. ゲームのパートナー センター ページで、左側のパネルから [製品の収集と購入] を選択します。

2. サービスの認証に使用している Entra アプリケーションのクライアント ID を入力します。

3. [Save] ボタンをクリックします。

4. サンドボックスまたは開発者環境の Microsoft Store に、製品のゲーム製品とすべてのアドオンを再発行します。

発行処理が完了すると、サービス呼び出しから適切なアイテムが返却されるのが確認できるようになります。

関連項目

Microsoft Store のサービス API

サービスからサービスへの認証にユーザー Store ID を要求する

ユーザー Store ID キーを更新する