> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 認証

> XBOX CLI に対話形式またはサービス プリンシパルとしてサインインし、キャッシュされた資格情報を管理して、PlayFab の権限要件を満たします。

XBOX CLI では、Microsoft Entra ID を介して開発者アカウントでサインインします。
パートナー センターのワークフローでは、パートナー センターの販売者へのアクセス権を持つアカウントで
サインインしてください。販売者の選択とそのゲームの一覧表示については、[はじめに](https://docs.xbox.com/ja-jp/tools/xbox-cli/getting-started.md)を参照してください。

PlayFab は、パートナー センターへのアクセス権とは別に、独自の権限を確認します。`xbox playfab`
コマンドには、操作対象のタイトルに対する **Admin** 権限が必要です。
[PlayFab 認証のしくみ](#how-playfab-authentication-works)を参照してください。無人ジョブでは、代わりに
サービス プリンシパルとしてサインインできます。
[自動化 (サービス プリンシパル) の認証](#automation-service-principal-authentication)を参照してください。

## サインイン

```bash theme={null}
xbox auth login
```

`auth login` はシステムのブラウザーを開いてサインインし、アカウントとそのトークンの有効期限を
報告します。

```text theme={null}
Successfully signed in as: dev@nodpublishers.com
Token expires at: YYYY-MM-DD HH:MM:SS
```

CLI は一度に 1 つのアカウントを使用します。アカウントを切り替えるには、もう一度 `xbox auth login` を実行し、
別のアカウントを選択します。以降のすべてのコマンドでそのアカウントが使用されます。これには、同じ OS ユーザーの他のターミナルも含まれます。
[Auth](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/auth.md) を参照してください。

## 状態を確認する

```bash theme={null}
xbox auth status
```

`auth status` は、キャッシュされたアカウントとそのトークンを表示します。PlayFab やパートナー センターを
使用できるかどうかは確認しません。

```text theme={null}
Signed in as: dev@nodpublishers.com
Home Account ID: 00000000-0000-0000-0000-000000000000.00000000-0000-0000-0000-000000000000
Environment: login.microsoftonline.com
Tenant ID: 00000000-0000-0000-0000-000000000000
Token type: Bearer
Token expires at: YYYY-MM-DD HH:MM:SS
Scopes: <scope>/.default
```

スクリプトでは、`--output json` を渡して `signedIn` を確認します。0 以外の終了コードは、CLI が
設定またはトークン キャッシュを読み取れなかったことを意味します。

販売者や PlayFab タイトルなどの保存された既定値は、サインインとは別のものです。
[コンテキスト](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/context.md)を参照してください。

## サインアウト

```bash theme={null}
xbox auth logout
```

`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`](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/playfab/service-principal)
コマンドの場合は、スタジオに対する権限を確認します。この権限は、Studio Admin が PlayFab の Game Manager で付与します。
たとえば、組み込みの **Title Admin** ロールを使用します。
[PlayFab のユーザー ロール](https://docs.xbox.com/services/playfab/identity/dev-identity/permissions/playfab-user-roles.md)を参照してください。

[サービス プリンシパル](#automation-service-principal-authentication)が PlayFab へのアクセス権を取得できるのは、
ユーザーが `xbox playfab service-principal set` でアクセス権を付与した場合のみです。サービス プリンシパルは、
自分自身でアクセス権の付与を管理できません。

タイトルの選択と PlayFab API の呼び出しについては、[PlayFab API の統合](https://docs.xbox.com/ja-jp/tools/xbox-cli/playfab-api.md)を参照してください。

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

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

| オプション | オーバーライドする設定 |
| - | - |
| `--client-id` | ユーザー サインイン用の `AzureAd:ClientId`。サービス プリンシパル モードでは拒否されます |
| `--tenant-id` | ユーザー サインイン用の `AzureAd:TenantId`。サービス プリンシパル モードでは拒否されます |
| `--scopes` | `AzureAd:Scopes` |

すべての設定については、[構成](https://docs.xbox.com/ja-jp/tools/xbox-cli/configuration.md)を参照してください。

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

> [!NOTE]
>
> サービス プリンシパルはサインインでき、`auth status` も有効なトークンを報告しますが、サービスがそのサービス プリンシパルを
> 受け入れるまで、呼び出しは承認エラーで失敗します。PlayFab は、ユーザーが
> [`xbox playfab service-principal set`](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/playfab/service-principal) でアクセス権を
> 付与した後に受け入れます。`xbox game` や `xbox xbl` など、オンライン サービスを呼び出すその他の
> コマンドは、まだサービス プリンシパルを受け入れません。
> [既知の問題](https://docs.xbox.com/ja-jp/tools/xbox-cli/known-issues.md#xbox-game-xbox-xbl-and-similar-commands-dont-accept-service-principals-yet)を参照してください。

継続的インテグレーション (CI) パイプラインやその他の無人ジョブでは、ブラウザーでのサインインを完了できません。
代わりに、`XBOX_AUTHENTICATION__MODE` をサービス プリンシパル モードに設定すると、各コマンドは構成された
アプリ登録またはマネージド ID として、アプリ専用の Entra ID トークンを取得します。何もキャッシュされず、
`auth login` と `auth logout` は失敗します。

サービス プリンシパルには保存されたコンテキストがないため、販売者とタイトルはそれぞれのオプションまたは
`XBOX_` 変数で渡します。[コンテキスト](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/context.md#behavior)を参照してください。

| モード | 資格情報 | 設定 (それぞれ `XBOX_AUTHENTICATION__` のプレフィックスが付きます) |
| - | - | - |
| `user` (既定) | `auth login` による対話型サインイン。 | なし。 |
| `clientsecret` | ファイルから読み取られるクライアント シークレット。 | `TENANTID`、`CLIENTID`、`CLIENTSECRET__FILE` |
| `certificate` | 秘密キーを含む PKCS#12 (`.pfx`) 証明書。 | `TENANTID`、`CLIENTID`、`CERTIFICATE__PATH`、省略可能な `CERTIFICATE__PASSWORDFILE` |
| `federatedtoken` | Azure Pipelines や Kubernetes などから取得し、ファイルから読み取られるフェデレーション ID トークン。ローテーションされたトークンは、アクセス トークンの更新時に取得されます。 | `TENANTID`、`CLIENTID`、`FEDERATEDTOKEN__FILE` |
| `githuboidc` | GitHub Actions の OpenID Connect (OIDC) トークン。ジョブには `permissions: id-token: write` が必要です。[GitHub Actions をセットアップする](#set-up-github-actions)を参照してください。 | `TENANTID`、`CLIENTID` |
| `azurecli` | Azure CLI にサインインしているサービス プリンシパルまたはマネージド ID。Azure CLI にサインインしているユーザー (人) は拒否されます。ユーザーは `auth login` を使用します。 | なし。 |
| `managedidentity` | Azure でホストされているマシンのマネージド ID。システム割り当て ID の場合は、クライアント ID を省略します。 | 省略可能な `CLIENTID` |

* `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 の一時
フォルダーです。それ以外の環境では、ジョブだけが読み取れる任意のファイルを使用してください。

```bash theme={null}
export XBOX_AUTHENTICATION__MODE=clientsecret
export XBOX_AUTHENTICATION__TENANTID=00000000-0000-0000-0000-000000000000
export XBOX_AUTHENTICATION__CLIENTID=11111111-1111-1111-1111-111111111111
export XBOX_AUTHENTICATION__CLIENTSECRET__FILE="$RUNNER_TEMP/xbox-secret"
xbox auth status
```

ワークロード ID フェデレーションを使用する GitHub Actions ジョブの例です。Entra ID と GitHub のセットアップについては、
[GitHub Actions をセットアップする](#set-up-github-actions)を参照してください。

```yaml theme={null}
jobs:
  example:
    runs-on: ubuntu-latest
    environment: production
    permissions:
      id-token: write
      contents: read
    steps:
      - run: xbox --playfab-title-id ABC123 playfab api /Admin/GetTitleData
        env:
          XBOX_AUTHENTICATION__MODE: githuboidc
          XBOX_AUTHENTICATION__TENANTID: ${{ vars.ENTRA_TENANT_ID }}
          XBOX_AUTHENTICATION__CLIENTID: ${{ vars.ENTRA_CLIENT_ID }}
```

Azure CLI のサービス プリンシパルを使用する例です (`az login --service-principal` の実行後など)。

```powershell theme={null}
$env:XBOX_AUTHENTICATION__MODE = "azurecli"
xbox auth status --output json
```

Azure CLI のサインインは同じ OS ユーザーのすべてのターミナルで共有されるため、異なる ID でサインインする
同時実行ジョブには、それぞれ独自の `AZURE_CONFIG_DIR` を指定してください。

Azure Pipelines では、Azure Resource Manager サービス接続 (できればワークロード ID フェデレーションを使用するもの) を
指定した `AzureCLI@2` タスク内で `xbox` を実行します。サービス接続によってテナントと ID が選択されるため、
`XBOX_AUTHENTICATION__TENANTID` と `XBOX_AUTHENTICATION__CLIENTID` は設定しないでください。
サービス接続名は、自分のものに置き換えてください。

```yaml theme={null}
steps:
  - task: AzureCLI@2
    displayName: Check XBOX CLI identity
    inputs:
      azureSubscription: 'nod-ci-service-connection'
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        xbox auth status --output json
    env:
      XBOX_AUTHENTICATION__MODE: azurecli
```

### GitHub Actions をセットアップする

`githuboidc` モードでは、保存やローテーションが必要なシークレットを使用せずに、GitHub Actions ジョブを
Entra ID テナント内のサービス プリンシパルとしてサインインさせます。CLI は GitHub にジョブの OIDC トークンを要求し、
そのトークンがアプリ登録のフェデレーション資格情報と一致する場合、Entra ID はそれをアクセス トークンと交換します。
フェデレーション資格情報は、どのジョブがサインインできるかを決定するものであり、API へのアクセス権を
付与するものではありません。

アプリ登録、そのサービス プリンシパル、およびリポジトリを信頼するフェデレーション資格情報を作成するには、
[Configuring OpenID Connect in Azure](https://docs.github.com/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-azure)
と
[アプリと外部 ID プロバイダーの間に信頼関係を作成する](https://learn.microsoft.com/entra/workload-id/workload-identity-federation-create-trust)
の手順に従います。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 の不変サブジェクトに関するガイダンス](https://docs.github.com/en/actions/reference/security/oidc#immutable-subject-claims)を参照してください。
  組織とリポジトリでは、サブジェクトをカスタマイズすることもできます。
* **ジョブで、その環境と `permissions: id-token: write` を宣言します。** 環境を宣言しないと、
  GitHub はブランチまたはプル リクエストのサブジェクトを提示し、Entra ID はそれを拒否します。
* **ジョブで `XBOX_AUTHENTICATION__MODE`、`XBOX_AUTHENTICATION__TENANTID`、
  `XBOX_AUTHENTICATION__CLIENTID` を設定します。** [例](#examples)を参照してください。テナント 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](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/auth.md#auth-status) を参照してください。

`objectId` は、アプリ登録のオブジェクト ID ではなく、サービス プリンシパルのオブジェクト ID です。サービス プリンシパルに
PlayFab へのアクセス権を付与するには、これを `--principal-object-id` として `xbox playfab service-principal set` に渡します。


## Related topics

- [認証](https://docs.xbox.com/ja-jp/services/playfab/identity/player-identity/authentication/index.md)
- [2 要素認証](https://docs.xbox.com/ja-jp/services/playfab/identity/dev-identity/authentication/two-factor-authentication.md)
- [XBOX services 認証](https://docs.xbox.com/ja-jp/services/xbox-services/fundamentals/s2s-auth-calls/service-authentication/live-xbox-live-authentication.md)
- [XBOX services 認証 (目次)](https://docs.xbox.com/ja-jp/services/xbox-services/fundamentals/s2s-auth-calls/service-authentication/live-service-authentication-nav.md)
- [サービス認証](https://docs.xbox.com/ja-jp/services/xbox-services/fundamentals/s2s-auth-calls/service-authentication/index.md)
