> ## 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 以您的開發人員帳戶將您登入。若是 Partner Center 工作流程，請使用可存取您 Partner Center 賣方的帳戶登入。如需選擇賣方並列出其遊戲的相關資訊，請參閱[開始使用](https://docs.xbox.com/zh-TW/tools/xbox-cli/getting-started.md)。

PlayFab 會檢查自己的權限，與您的 Partner Center 存取權分開。`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 一次只使用一個帳戶。若要切換帳戶，請再次執行 `xbox auth login` 並選擇另一個帳戶。之後的每個命令都會使用該帳戶，包括您作業系統使用者的其他終端機。請參閱[驗證](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/auth.md)。

## 檢查狀態

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

`auth status` 會顯示快取的帳戶及其權杖。它不會檢查您是否能使用 PlayFab 或 Partner Center。

```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`。非零的結束代碼表示 CLI 無法讀取其設定或權杖快取。

已儲存的預設值 (例如賣方或 PlayFab 遊戲) 與登入是分開的。請參閱[內容](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/context.md)。

## 登出

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

`auth logout` 會移除快取的帳戶和權杖，這會將您作業系統使用者的每個終端機登出。它會保留您已儲存的內容。

## 權杖快取

命令會重複使用並重新整理您快取的權杖，因此只有在 CLI 要求時，才需要再次執行 `xbox auth login`。權杖會儲存在 Windows 受保護的快取、macOS 鑰匙圈或 Linux Secret Service 金鑰圈中。在沒有可用金鑰圈的 Linux 上 (例如無周邊電腦)，CLI 會發出警告，並使用僅受檔案權限保護的未加密檔案。

## PlayFab 驗證的運作方式

對於 `xbox playfab` 命令，CLI 會將您的 Entra ID 存取權杖傳送給 PlayFab，因此您永遠不需要處理 PlayFab 遊戲祕密金鑰。PlayFab 會檢查您的帳戶是否在遊戲上具備 **Admin** 權限，或者對於 [`playfab service-principal`](https://docs.xbox.com/zh-TW/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)只有在有人使用 `xbox playfab service-principal set` 授與時，才會取得 PlayFab 存取權。服務主體無法自行管理授與。

如需選取遊戲及呼叫 PlayFab API 的相關資訊，請參閱 [PlayFab API 整合](https://docs.xbox.com/zh-TW/tools/xbox-cli/playfab-api.md)。

## 覆寫 Entra ID 設定

用於登入的 Entra ID 應用程式內建於 CLI 中。大多數使用者不需要變更它。您可以使用 `XBOX_AZUREAD__` 環境變數 (例如 `XBOX_AZUREAD__CLIENTID`) 覆寫其 `AzureAd` 設定，或使用下列選項針對單一命令進行覆寫：

| 選項 | 覆寫 |
| - | - |
| `--client-id` | 使用者登入的 `AzureAd:ClientId`；在服務主體模式中會被拒絕 |
| `--tenant-id` | 使用者登入的 `AzureAd:TenantId`；在服務主體模式中會被拒絕 |
| `--scopes` | `AzureAd:Scopes` |

如需所有設定，請參閱[組態](https://docs.xbox.com/zh-TW/tools/xbox-cli/configuration.md)。

## 自動化 (服務主體) 驗證

> [!NOTE]
>
> 服務主體可以登入，且 `auth status` 會回報有效的權杖，但在服務接受它之前，其呼叫會因授權錯誤而失敗。PlayFab 會在有人使用 [`xbox playfab service-principal set`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/playfab/service-principal) 授與其存取權之後接受它。其他呼叫線上服務的命令 (例如 `xbox game` 和 `xbox xbl`) 尚不接受服務主體；請參閱[已知問題](https://docs.xbox.com/zh-TW/tools/xbox-cli/known-issues.md#xbox-game-xbox-xbl-and-similar-commands-dont-accept-service-principals-yet)。

持續整合 (CI) 管線和其他無人值守的作業無法完成瀏覽器登入。它們會改為將 `XBOX_AUTHENTICATION__MODE` 設定為服務主體模式，而每個命令都會以設定的應用程式註冊或受控識別身分取得僅限應用程式的 Entra ID 權杖。不會快取任何內容，且 `auth login` 和 `auth logout` 會失敗。

服務主體沒有已儲存的內容，因此請使用賣方和遊戲的選項或 `XBOX_` 變數傳遞它們。請參閱[內容](https://docs.xbox.com/zh-TW/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。重新整理存取權杖時，會取用輪替後的權杖。 | `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 的服務主體或受控識別。登入 Azure CLI 的人員會被拒絕；人員應使用 `auth login`。 | 無。 |
| `managedidentity` | Azure 託管電腦的受控識別。若為系統指派的身分識別，請省略用戶端 ID。 | 選用的 `CLIENTID` |

* `TENANTID` 必須是租用戶 GUID 或已驗證的網域，而不是 `common`、`organizations` 或 `consumers`。`CLIENTID` 必須是 GUID。
* 這些設定只來自環境變數。在服務主體模式中，`--client-id` 和 `--tenant-id` 會被拒絕；`--scopes` 仍然適用。
* 在 `azurecli` 模式中，透過登入 Azure CLI 來選取身分識別。在 `managedidentity` 模式中，身分識別會決定租用戶。
* 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
```

使用工作負載身分識別同盟的 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 登入會由您作業系統使用者的每個終端機共用，因此請為以不同身分識別登入的並行作業各自提供 `AZURE_CONFIG_DIR`。

在 Azure Pipelines 中，請在使用 Azure Resource Manager 服務連線的 `AzureCLI@2` 工作內執行 `xbox`，最好是使用工作負載身分識別同盟的服務連線。服務連線會選取租用戶和身分識別，因此請勿設定 `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 的存取權。

若要建立應用程式註冊、其服務主體，以及信任您存放庫的同盟認證，請依照[在 Azure 中設定 OpenID Connect](https://docs.github.com/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-azure) 和[在應用程式與外部識別提供者之間建立信任關係](https://learn.microsoft.com/entra/workload-id/workload-identity-federation-create-trust)進行。請略過這些指南中的 `azure/login` 步驟和 Azure 角色指派，因為 CLI 會自行要求權杖，且不會呼叫 Azure Resource Manager。

設定必須符合下列需求：

* **同盟認證**使用簽發者 `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 不是祕密，因此請將它們儲存為環境變數，並透過 `vars` 讀取。

主體指定的是環境，而不是分支，因此環境的保護規則會控制誰可以登入。請將生產環境限制為受保護的分支，並要求核准。除非在環境的設定中關閉此功能，否則系統管理員可以略過這些規則。

`pull_request_target` 工作流程會以基底存放庫的權限執行，且可以要求 OIDC 權杖，即使是來自分支存放庫的提取要求也一樣。絕不要在可以服務主體身分登入的作業中簽出或執行不受信任的提取要求程式碼。

如果主體不相符，Entra ID 會以 `AADSTS700213` ("No matching federated identity record found for presented assertion subject '…'") 拒絕權杖。此錯誤會引述 GitHub 傳送的主體，因此請將其與認證的主體進行比較。

若要將每個環境的設定與環境保存在一起，請將它們儲存為以 CLI 變數命名的 GitHub 環境變數 (例如 `XBOX_AUTHENTICATION__CLIENTID`)，並將它們原封不動地傳遞給 CLI。

### 確認身分識別

在服務主體模式中，`auth status` 會取得權杖，並回報模式、主體類型、租用戶、應用程式 ID、物件 ID、對象和應用程式角色。它絕不會列印權杖。如果無法取得權杖，它會以 `1` 結束，因此執行它的管線步驟會失敗。請參閱[驗證](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/auth.md#auth-status)。

`objectId` 是服務主體的物件 ID，而不是應用程式註冊的物件 ID。將它作為 `--principal-object-id` 傳遞給 `xbox playfab service-principal set`，即可授與服務主體 PlayFab 存取權。


## Related topics

- [驗證](https://docs.xbox.com/zh-TW/services/playfab/identity/player-identity/authentication/index.md)
- [服務驗證](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/s2s-auth-calls/service-authentication/index.md)
- [驗證 API 原則](https://docs.xbox.com/zh-TW/services/playfab/api-references/rest/admin/authentication/validate-api-policy.md)
- [驗證 iOS 收據](https://docs.xbox.com/zh-TW/services/playfab/api-references/rest/client/platform-specific-methods/validate-ios-receipt.md)
- [驗證和 S2S](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/s2s-auth-calls/live-s2s-auth-calls-nav.md)
