メインコンテンツへスキップ
XBOX CLI では、Microsoft Entra ID を介して開発者アカウントでサインインします。 パートナー センターのワークフローでは、パートナー センターの販売者へのアクセス権を持つアカウントで サインインしてください。販売者の選択とそのゲームの一覧表示については、はじめにを参照してください。 PlayFab は、パートナー センターへのアクセス権とは別に、独自の権限を確認します。xbox playfab コマンドには、操作対象のタイトルに対する Admin 権限が必要です。 PlayFab 認証のしくみを参照してください。無人ジョブでは、代わりに サービス プリンシパルとしてサインインできます。 自動化 (サービス プリンシパル) の認証を参照してください。

サインイン

auth login はシステムのブラウザーを開いてサインインし、アカウントとそのトークンの有効期限を 報告します。
CLI は一度に 1 つのアカウントを使用します。アカウントを切り替えるには、もう一度 xbox auth login を実行し、 別のアカウントを選択します。以降のすべてのコマンドでそのアカウントが使用されます。これには、同じ OS ユーザーの他のターミナルも含まれます。 Auth を参照してください。

状態を確認する

auth status は、キャッシュされたアカウントとそのトークンを表示します。PlayFab やパートナー センターを 使用できるかどうかは確認しません。
スクリプトでは、--output json を渡して signedIn を確認します。0 以外の終了コードは、CLI が 設定またはトークン キャッシュを読み取れなかったことを意味します。 販売者や PlayFab タイトルなどの保存された既定値は、サインインとは別のものです。 コンテキストを参照してください。

サインアウト

auth logout はキャッシュされたアカウントとトークンを削除するため、同じ OS ユーザーのすべてのターミナルで サインアウトされます。保存されたコンテキストは保持されます。

トークン キャッシュ

コマンドはキャッシュされたトークンを再利用および更新するため、xbox auth login を再度実行するのは、CLI から 求められた場合だけで十分です。トークンは、Windows の保護されたキャッシュ、macOS のキーチェーン、または Linux の Secret Service キーリングに保存されます。ヘッドレス マシンなど、使用可能なキーリングがない Linux では、 CLI は警告を表示し、ファイルのアクセス許可のみで保護された暗号化されていないファイルを使用します。

PlayFab 認証のしくみ

xbox playfab コマンドでは、CLI が Entra ID のアクセス トークンを PlayFab に送信するため、PlayFab の タイトル シークレット キーを扱う必要はありません。PlayFab は、アカウントがタイトルに対する Admin 権限を 持っているかどうかを確認します。playfab service-principal コマンドの場合は、スタジオに対する権限を確認します。この権限は、Studio Admin が PlayFab の Game Manager で付与します。 たとえば、組み込みの Title Admin ロールを使用します。 PlayFab のユーザー ロールを参照してください。 サービス プリンシパルが PlayFab へのアクセス権を取得できるのは、 ユーザーが xbox playfab service-principal set でアクセス権を付与した場合のみです。サービス プリンシパルは、 自分自身でアクセス権の付与を管理できません。 タイトルの選択と PlayFab API の呼び出しについては、PlayFab API の統合を参照してください。

Entra ID の設定をオーバーライドする

サインインに使用される Entra ID アプリケーションは CLI に組み込まれています。ほとんどのユーザーは、これを変更する 必要はありません。AzureAd の設定は、XBOX_AZUREAD__CLIENTID などの XBOX_AZUREAD__ 環境変数でオーバーライドできます。 また、1 つのコマンドだけであれば、次のオプションでオーバーライドすることもできます。 すべての設定については、構成を参照してください。

自動化 (サービス プリンシパル) の認証

サービス プリンシパルはサインインでき、auth status も有効なトークンを報告しますが、サービスがそのサービス プリンシパルを 受け入れるまで、呼び出しは承認エラーで失敗します。PlayFab は、ユーザーが xbox playfab service-principal set でアクセス権を 付与した後に受け入れます。xbox game や xbox xbl など、オンライン サービスを呼び出すその他の コマンドは、まだサービス プリンシパルを受け入れません。 既知の問題を参照してください。
継続的インテグレーション (CI) パイプラインやその他の無人ジョブでは、ブラウザーでのサインインを完了できません。 代わりに、XBOX_AUTHENTICATION__MODE をサービス プリンシパル モードに設定すると、各コマンドは構成された アプリ登録またはマネージド ID として、アプリ専用の Entra ID トークンを取得します。何もキャッシュされず、 auth login と auth logout は失敗します。 サービス プリンシパルには保存されたコンテキストがないため、販売者とタイトルはそれぞれのオプションまたは XBOX_ 変数で渡します。コンテキストを参照してください。
  • TENANTID は、テナント GUID または確認済みドメインである必要があり、common、organizations、 consumers は使用できません。CLIENTID は GUID である必要があります。
  • これらの設定は環境変数からのみ取得されます。サービス プリンシパル モードでは --client-id と --tenant-id は 拒否されますが、--scopes は引き続き適用されます。
  • azurecli モードでは、Azure CLI にサインインすることで ID を選択します。managedidentity モードでは、ID によってテナントが決まります。
  • CLI が別のモードやキャッシュされたユーザー サインインにフォールバックすることはありません。不明なモード、 不足している設定、そのモードで使用されない設定、または読み取れない資格情報ファイルがあると、 変数名を示すエラーで失敗します。
シークレットはファイルでのみ渡し、環境変数や引数では絶対に渡さないでください。環境変数や引数は、プロセスの一覧やログを通じて 漏洩する可能性があります。各ファイルへのアクセスは CLI を実行するアカウントに制限し、ジョブの終了時に 削除してください。

例

Linux または macOS で、ファイルから読み取るクライアント シークレットの例です。$RUNNER_TEMP は GitHub Actions の一時 フォルダーです。それ以外の環境では、ジョブだけが読み取れる任意のファイルを使用してください。
ワークロード ID フェデレーションを使用する GitHub Actions ジョブの例です。Entra ID と GitHub のセットアップについては、 GitHub Actions をセットアップするを参照してください。
Azure CLI のサービス プリンシパルを使用する例です (az login --service-principal の実行後など)。
Azure CLI のサインインは同じ OS ユーザーのすべてのターミナルで共有されるため、異なる ID でサインインする 同時実行ジョブには、それぞれ独自の AZURE_CONFIG_DIR を指定してください。 Azure Pipelines では、Azure Resource Manager サービス接続 (できればワークロード ID フェデレーションを使用するもの) を 指定した AzureCLI@2 タスク内で xbox を実行します。サービス接続によってテナントと ID が選択されるため、 XBOX_AUTHENTICATION__TENANTID と XBOX_AUTHENTICATION__CLIENTID は設定しないでください。 サービス接続名は、自分のものに置き換えてください。

GitHub Actions をセットアップする

githuboidc モードでは、保存やローテーションが必要なシークレットを使用せずに、GitHub Actions ジョブを Entra ID テナント内のサービス プリンシパルとしてサインインさせます。CLI は GitHub にジョブの OIDC トークンを要求し、 そのトークンがアプリ登録のフェデレーション資格情報と一致する場合、Entra ID はそれをアクセス トークンと交換します。 フェデレーション資格情報は、どのジョブがサインインできるかを決定するものであり、API へのアクセス権を 付与するものではありません。 アプリ登録、そのサービス プリンシパル、およびリポジトリを信頼するフェデレーション資格情報を作成するには、 Configuring OpenID Connect in Azure と アプリと外部 ID プロバイダーの間に信頼関係を作成する の手順に従います。CLI はトークンを自分で要求し、Azure Resource Manager を呼び出さないため、これらのガイドにある azure/login ステップと Azure ロールの割り当ては省略してください。 セットアップは次の要件を満たす必要があります。
  • フェデレーション資格情報で、発行者 https://token.actions.githubusercontent.com と対象ユーザー api://AzureADTokenExchange を使用します。
  • そのサブジェクトが、ジョブの環境に対して GitHub が発行するサブジェクトと一致します。 以前の 既定値は repo:<OWNER>/<REPO>:environment:<ENVIRONMENT> です。GitHub.com では、2026 年 7 月 15 日より後に 作成、名前変更、または移管されたリポジトリでは repo:<OWNER>@<OWNER-ID>/<REPO>@<REPO-ID>:environment:<ENVIRONMENT> が使用されます。 GitHub の不変サブジェクトに関するガイダンスを参照してください。 組織とリポジトリでは、サブジェクトをカスタマイズすることもできます。
  • ジョブで、その環境と permissions: id-token: write を宣言します。 環境を宣言しないと、 GitHub はブランチまたはプル リクエストのサブジェクトを提示し、Entra ID はそれを拒否します。
  • ジョブで XBOX_AUTHENTICATION__MODE、XBOX_AUTHENTICATION__TENANTID、 XBOX_AUTHENTICATION__CLIENTID を設定します。 例を参照してください。テナント ID とクライアント ID は シークレットではないため、環境変数として保存し、vars を通じて読み取ります。
サブジェクトはブランチではなく環境を示すため、環境の保護ルールによってサインインできるユーザーが 制御されます。運用環境は保護されたブランチに制限し、承認を必須にしてください。管理者は、環境の 設定で無効にしない限り、これらのルールをバイパスできます。 pull_request_target ワークフローはベース リポジトリの権限で実行され、フォークからのプル リクエストであっても OIDC トークンを要求できます。サービス プリンシパルとしてサインインできるジョブでは、信頼されていないプル リクエストの コードをチェックアウトしたり実行したりしないでください。 サブジェクトが一致しない場合、Entra ID は AADSTS700213 (“No matching federated identity record found for presented assertion subject ’…’”) でトークンを拒否します。このエラーには GitHub が送信したサブジェクトが含まれるため、資格情報のサブジェクトと比較してください。 各環境の設定を環境と一緒に管理するには、XBOX_AUTHENTICATION__CLIENTID など CLI の変数と同じ名前の GitHub 環境変数として保存し、そのまま CLI に渡します。

ID を確認する

サービス プリンシパル モードでは、auth status はトークンを取得し、モード、プリンシパルの種類、 テナント、アプリ ID、オブジェクト ID、対象ユーザー、アプリ ロールを報告します。トークン自体は出力しません。トークンを 取得できない場合は 1 で終了するため、これを実行するパイプライン ステップは失敗します。 Auth を参照してください。 objectId は、アプリ登録のオブジェクト ID ではなく、サービス プリンシパルのオブジェクト ID です。サービス プリンシパルに PlayFab へのアクセス権を付与するには、これを --principal-object-id として xbox playfab service-principal set に渡します。
最終更新日 2026年11月19日