> ## 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-CN/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` 并选择另一个帐户。之后的每个命令都会使用该帐户,包括你的操作系统用户的其他终端中的命令。
请参阅 [Auth](https://docs.xbox.com/zh-CN/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-CN/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-CN/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)。

只有在有人使用 `xbox playfab service-principal set` 授予访问权限时,[服务主体](#automation-service-principal-authentication)才能获得 PlayFab 访问权限。服务主体无法自行管理授权。

有关选择游戏和调用 PlayFab API 的信息,请参阅 [PlayFab API 集成](https://docs.xbox.com/zh-CN/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-CN/tools/xbox-cli/configuration.md)。

## 自动化(服务主体)身份验证

> [!NOTE]
>
> 服务主体可以登录,并且 `auth status` 会报告有效令牌,但在服务接受该服务主体之前,其调用会因授权错误而失败。在有人使用
> [`xbox playfab service-principal set`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playfab/service-principal) 授予其访问权限后,PlayFab 会接受它。其他调用联机服务的命令(例如 `xbox game` 和 `xbox xbl`)尚不接受服务主体;请参阅
> [已知问题](https://docs.xbox.com/zh-CN/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-CN/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 资源管理器服务连接的 `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 资源管理器。

设置必须满足以下要求:

* **联合凭据**使用颁发者 `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 发送的使用者,因此请将其与凭据的使用者进行比较。

若要将每个环境的设置与该环境一起保存,请将它们存储为以 CLI 变量命名的 GitHub 环境变量(例如 `XBOX_AUTHENTICATION__CLIENTID`),并将它们原样传递给 CLI。

### 确认标识

在服务主体模式下,`auth status` 会获取令牌并报告模式、主体类型、租户、应用 ID、对象 ID、受众和应用角色。它从不输出令牌。如果无法获取令牌,它会以 `1` 退出,因此运行它的管道步骤会失败。请参阅
[Auth](https://docs.xbox.com/zh-CN/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-CN/services/xbox-services/fundamentals/identity/auth/index.md)
- [身份](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/identity/index.md)
- [服务身份验证](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/s2s-auth-calls/service-authentication/index.md)
- [双重身份验证](https://docs.xbox.com/zh-CN/services/playfab/identity/dev-identity/authentication/two-factor-authentication.md)
- [XBOX services 身份验证](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/s2s-auth-calls/service-authentication/live-xbox-live-authentication.md)
