証明書利用者 (Relying Party) の構成
カスタム Web サービスを使用するには、タイトルはまず Partner Center でシングル サインオン構成を完了する必要があります。詳細は 証明書利用者の構成 を参照してください。 証明書利用者の構成は、パブリッシャー レベル かつすべてのサンドボックスにわたって構成されます。可能な限り、同じタイトル サービス (異なるタイトル間) には同じ証明書利用者の構成を使用することがベスト プラクティスです。Web サービス エンドポイントの構成
証明書利用者の構成に加えて、タイトル サービスが partner XSTS トークンを使用するには、Partner Center でサービス エンドポイントを構成する必要があります。詳細は Web サービス を参照してください。 Web サービス エンドポイントは、グローバルなDefaultNsal 構成において タイトル レベル で構成されます。DefaultNsal は現行のタイトルで唯一の構成タイプです。以前に構成されたタイトルでは、CertificationNsal や RetailNsal など、他の環境を反映する他の構成タイプが使用されている場合があります。構成を簡素化するため、これらの構成タイプは新しいタイトルでは利用できません。
Web サービス SSL 証明書
すべての Web サービス エンドポイントは HTTPS を使用し、信頼された認証局 (CA) によって発行された SSL 証明書を使用する必要があります。これらの証明書は Web サービス エンドポイント構成で指定してはなりません。 開発およびテストでは、タイトルは自己署名の SSL 証明書を使用できますが、信頼されたルート証明書を使用できる場合は推奨されません。 自己署名の SSL 通信は既定では XBOX コンソール上では信頼されません。 証明書が Partner Center のタイトルのシングル サインオン ページの Web サービス エンドポイント定義に追加されていない限り、HTTPS 接続は失敗します。 認識されている CA の一覧については、セキュリティ ドキュメントの 参加者リスト - Microsoft Trusted Root Program を参照してください。また、letsencrypt.org などの組織から、無料で信頼された SSL 証明書を取得することもできます。トークン取得と接続フロー
すべてのタイトル サービス エンドポイントは、認証と認可のために partner XSTS トークンを必須とすべきです。この情報がない場合、サービスとの通信は拒否されるべきです。 Web サービスでは、partner XSTS トークンとユーザー識別 (user hash) を要求のAuthentication ヘッダーに含める必要があります。これらのヘッダーの構造の詳細については、XBOX services セキュリティ トークン (XSTS トークン) を参照してください。
セキュアな TCP/UDP サービスでは、partner XSTS トークンとユーザー識別 (user hash) を初回の認可/ハンドシェイク メッセージに含める必要があります。この情報がない場合、サービスとの通信は拒否されるべきです。これらの接続では、サービスのドメインを反映するプレースホルダーを Web サービス エンドポイント URI として指定できます。
クライアントでの partner XSTS トークンの取得と HTTPS 要求の送信
partner XSTS トークンと署名ヘッダー データは、次のフローで XUserGetTokenAndSignatureUtf16Async API を通じてゲーム クライアントによって取得されます。- 現在のユーザーで
XUserGetTokenAndSignatureUtf16Asyncを呼び出します。API 呼び出しにサービスの URL と (該当する場合) カスタム ヘッダーまたはメッセージ本文を含めます。 API は、対象エンドポイントまたは XBOX service で使用する XSTS トークンとメッセージ署名を取得します。 - 非同期結果から
XUserGetTokenAndSignatureUtf16Resultを介して XSTS トークンと署名を取得します。XUserGetTokenAndSignatureUtf16Resultは暗号化された XSTS トークンを返します。タイトルは返されたトークンを不透明なデータとして扱う必要があります。トークン データは、次のサービス呼び出しを超えてディスクに書き込んだり、タイトル領域にキャッシュしたりしてはなりません。トークンのキャッシュはXUserGetTokenAndSignatureUtf16Asyncによって行われます。 - Microsoft Windows HTTP Services (WinHTTP) と XSTS トークンおよび Signature 値を使用して、対象エンドポイントへの HTTPS 要求を作成します。
すべての HTTPS 呼び出しは WinHTTP API を通じて実行し、XSTS Token 値を
Authenticationヘッダーに、Signature 値をSignatureヘッダーとして追加する必要があります。
- サービス呼び出しの URL の代わりに、タイトルはサービスのプレースホルダー URI を指定します。
- 認証データは、TCP/UDP 接続の初回認可/ハンドシェイク時に使用されます。
サーバーでの partner XSTS トークンの処理
partner XSTS トークンがタイトル サービスによって受信された後、サービスはトークンを解析、復号し、トークンの真正性を検証する必要があります。 XSTS トークンの解析と検証の詳細については、XBOX services セキュリティ トークン (XSTS トークン) を参照してください。 また、サービス開発者には Game Service サンプル と Xfest 2019 プレゼンテーション XSTS Auth and Server to Server Made Easy を確認およびテストのために強く推奨します。 このサンプルには、トークン処理を含む完全なサービス ライブラリが含まれています。認証と認可
トークンを解析、復号、および検証した後、サービスはトークンのクレームを信頼できます。 すべての XSTS トークン クレームの一覧については、XBOX services セキュリティ トークン クレーム を参照してください。 サービスはまず、これらのクレームをサービス レベルの認証と認可に使用する必要があります。 partner XSTS トークンに含まれる情報は常に権威あるものとして扱うべきです。 サービス呼び出しでは、この情報を要求の他の部分で複製する必要はありません。 ユーザー ID には特別な注意が必要です。ユーザー ID は常に XSTS トークン クレームを通じて検証されなければならず、サービス要求のために他のソースからの検証なしに使用してはなりません。認証目的でユーザーを識別するには、タイトル サービスには次の 2 つのオプションがあります。- /user/pXUID (ptx) クレーム。 アカウント リンク用途のみで ID が必要なシナリオでは、Partner XUID (pXUID) を使用する必要があります。このクレームは、現行のパブリッシャー配下でのユーザーの XBOX services アカウントの一意識別子を公開します。
- /user/XID クレーム。 サービスがユーザー ID を返す必要がある場合、または XBOX services に対してサービス間呼び出しを実行する必要がある場合は、ユーザーの XUID が必要です。そのようなサービスの例としては、カスタムのリーダーボードやマッチメイキング サービス、または XBOX services サービス呼び出しを通じて購入を検証するサービスがあります。
PXUID は、Partner Center で証明書利用者を作成する際に選択された Business Partner にスコープされます。複数の証明書利用者で x-token を扱う場合、PXUID 値が一致するためには同じ Business Partner を共有する必要があります。Business Partner および証明書利用者の構成の詳細については、Partner Center での Web サービスのセットアップ を参照してください。