xbox playfab 命令需要在其作用的遊戲上具備 Admin 權限;請參閱 PlayFab 驗證的運作方式。無人值守的作業則可以改為以服務主體身分登入;請參閱自動化 (服務主體) 驗證。
登入
auth login 會開啟您的系統瀏覽器進行登入,然後回報帳戶及其權杖的到期時間:
xbox auth login 並選擇另一個帳戶。之後的每個命令都會使用該帳戶,包括您作業系統使用者的其他終端機。請參閱驗證。
檢查狀態
auth status 會顯示快取的帳戶及其權杖。它不會檢查您是否能使用 PlayFab 或 Partner Center。
--output json 並檢查 signedIn。非零的結束代碼表示 CLI 無法讀取其設定或權杖快取。
已儲存的預設值 (例如賣方或 PlayFab 遊戲) 與登入是分開的。請參閱內容。
登出
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 命令,則檢查是否在工作室上具備該權限。Studio Admin 會在 PlayFab 的 Game Manager 中授與此權限,例如使用內建的 Title Admin 角色;請參閱 PlayFab 使用者角色。
服務主體只有在有人使用 xbox playfab service-principal set 授與時,才會取得 PlayFab 存取權。服務主體無法自行管理授與。
如需選取遊戲及呼叫 PlayFab API 的相關資訊,請參閱 PlayFab API 整合。
覆寫 Entra ID 設定
用於登入的 Entra ID 應用程式內建於 CLI 中。大多數使用者不需要變更它。您可以使用XBOX_AZUREAD__ 環境變數 (例如 XBOX_AZUREAD__CLIENTID) 覆寫其 AzureAd 設定,或使用下列選項針對單一命令進行覆寫:
如需所有設定,請參閱組態。
自動化 (服務主體) 驗證
服務主體可以登入,且
auth status 會回報有效的權杖,但在服務接受它之前,其呼叫會因授權錯誤而失敗。PlayFab 會在有人使用 xbox playfab service-principal set 授與其存取權之後接受它。其他呼叫線上服務的命令 (例如 xbox game 和 xbox xbl) 尚不接受服務主體;請參閱已知問題。XBOX_AUTHENTICATION__MODE 設定為服務主體模式,而每個命令都會以設定的應用程式註冊或受控識別身分取得僅限應用程式的 Entra ID 權杖。不會快取任何內容,且 auth login 和 auth logout 會失敗。
服務主體沒有已儲存的內容,因此請使用賣方和遊戲的選項或 XBOX_ 變數傳遞它們。請參閱內容。
TENANTID必須是租用戶 GUID 或已驗證的網域,而不是common、organizations或consumers。CLIENTID必須是 GUID。- 這些設定只來自環境變數。在服務主體模式中,
--client-id和--tenant-id會被拒絕;--scopes仍然適用。 - 在
azurecli模式中,透過登入 Azure CLI 來選取身分識別。在managedidentity模式中,身分識別會決定租用戶。 - CLI 絕不會回復為其他模式或快取的使用者登入。未知的模式、缺少的設定、模式未使用的設定,或無法讀取的認證檔案,都會失敗並顯示指出該變數名稱的錯誤。
範例
在 Linux 或 macOS 上從檔案讀取的用戶端密碼。$RUNNER_TEMP 是 GitHub Actions 的暫存資料夾;在其他環境中,請使用只有作業可以讀取的任何檔案:
az login --service-principal 之後:
AZURE_CONFIG_DIR。
在 Azure Pipelines 中,請在使用 Azure Resource Manager 服務連線的 AzureCLI@2 工作內執行 xbox,最好是使用工作負載身分識別同盟的服務連線。服務連線會選取租用戶和身分識別,因此請勿設定 XBOX_AUTHENTICATION__TENANTID 或 XBOX_AUTHENTICATION__CLIENTID。請將服務連線名稱取代為您自己的名稱:
設定 GitHub Actions
githuboidc 模式會將 GitHub Actions 作業以服務主體身分登入您的 Entra ID 租用戶,無須儲存或輪替任何祕密。CLI 會向 GitHub 要求作業的 OIDC 權杖,如果該權杖符合您應用程式註冊上的同盟認證,Entra ID 就會將其交換為存取權杖。同盟認證會決定哪些作業可以登入;它不會授與任何 API 的存取權。
若要建立應用程式註冊、其服務主體,以及信任您存放庫的同盟認證,請依照在 Azure 中設定 OpenID Connect 和在應用程式與外部識別提供者之間建立信任關係進行。請略過這些指南中的 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 的不可變主體指引。組織和存放庫也可以自訂主體。 - **作業宣告該環境和
permissions: id-token: write。**若沒有環境,GitHub 會提供分支或提取要求主體,而 Entra ID 會拒絕它。 - **作業設定
XBOX_AUTHENTICATION__MODE、XBOX_AUTHENTICATION__TENANTID和XBOX_AUTHENTICATION__CLIENTID,**如範例所示。租用戶和用戶端 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 結束,因此執行它的管線步驟會失敗。請參閱驗證。
objectId 是服務主體的物件 ID,而不是應用程式註冊的物件 ID。將它作為 --principal-object-id 傳遞給 xbox playfab service-principal set,即可授與服務主體 PlayFab 存取權。