Pular para o conteúdo principal
A XBOX CLI faz seu login com sua conta de desenvolvedor por meio do Microsoft Entra ID. Para fluxos de trabalho do Partner Center, entre com uma conta que tenha acesso ao seu vendedor do Partner Center. Consulte Introdução para escolher um vendedor e listar os jogos dele. O PlayFab verifica as próprias permissões, separadamente do seu acesso ao Partner Center. Os comandos xbox playfab precisam da permissão Admin no título em que atuam; consulte Como a autenticação do PlayFab funciona. Trabalhos autônomos podem entrar como entidade de serviço; consulte Autenticação de automação (entidade de serviço).

Entrar

auth login abre o navegador do sistema para você entrar e, em seguida, informa a conta e quando o token dela expira:
A CLI usa uma conta por vez. Para trocar de conta, execute xbox auth login novamente e escolha a outra conta. Todos os comandos posteriores a usam, inclusive em outros terminais do seu usuário do SO. Consulte Auth.

Verificar o status

auth status mostra a conta armazenada em cache e o token dela. Ele não verifica se você pode usar o PlayFab ou o Partner Center.
Em um script, passe --output json e verifique signedIn. Um código de saída diferente de zero significa que a CLI não conseguiu ler suas configurações ou o cache de tokens. Os padrões salvos, como o vendedor ou o título do PlayFab, são separados do login. Consulte Contexto.

Sair

auth logout remove as contas e os tokens armazenados em cache, o que desconecta todos os terminais do seu usuário do SO. Ele mantém o contexto salvo.

Cache de tokens

Os comandos reutilizam e atualizam o token armazenado em cache; portanto, execute xbox auth login novamente somente quando a CLI solicitar. O token é armazenado no cache protegido do Windows, no Keychain do macOS ou no chaveiro do Linux Secret Service. No Linux sem um chaveiro utilizável, como em um computador sem interface gráfica, a CLI emite um aviso e usa um arquivo não criptografado protegido apenas pelas permissões de arquivo.

Como a autenticação do PlayFab funciona

Para os comandos xbox playfab, a CLI envia seu token de acesso do Entra ID ao PlayFab, para que você nunca precise lidar com uma chave secreta de título do PlayFab. O PlayFab verifica se sua conta tem a permissão Admin no título ou no estúdio, no caso dos comandos playfab service-principal. Um Studio Admin a concede no Game Manager do PlayFab, por exemplo com a função interna Title Admin; consulte Funções de usuário do PlayFab. Uma entidade de serviço obtém acesso ao PlayFab somente quando uma pessoa o concede com xbox playfab service-principal set. Uma entidade de serviço não pode gerenciar concessões por conta própria. Consulte Integração com a API do PlayFab para selecionar um título e chamar APIs do PlayFab.

Substituir as configurações do Entra ID

O aplicativo do Entra ID usado para o login é integrado à CLI. A maioria dos usuários não precisa alterá-lo. Você pode substituir as configurações AzureAd dele com variáveis de ambiente XBOX_AZUREAD__, como XBOX_AZUREAD__CLIENTID, ou, para um único comando, com estas opções: Consulte Configuração para ver todas as configurações.

Autenticação de automação (entidade de serviço)

Uma entidade de serviço pode entrar, e auth status informa um token válido, mas as chamadas dela falham com um erro de autorização até que o serviço a aceite. O PlayFab a aceita depois que uma pessoa concede acesso a ela com xbox playfab service-principal set. Outros comandos que chamam um serviço online, como xbox game e xbox xbl, ainda não aceitam entidades de serviço; consulte Problemas conhecidos.
Pipelines de integração contínua (CI) e outros trabalhos autônomos não conseguem concluir um login pelo navegador. Em vez disso, eles definem XBOX_AUTHENTICATION__MODE como um modo de entidade de serviço, e cada comando obtém um token do Entra ID somente de aplicativo como o registro de aplicativo ou a identidade gerenciada configurada. Nada é armazenado em cache, e auth login e auth logout falham. Uma entidade de serviço não tem contexto salvo; portanto, passe o vendedor e o título com as opções correspondentes ou com variáveis XBOX_. Consulte Contexto.
  • TENANTID precisa ser um GUID de locatário ou um domínio verificado, não common, organizations nem consumers. CLIENTID precisa ser um GUID.
  • Essas configurações vêm somente de variáveis de ambiente. --client-id e --tenant-id são recusadas em um modo de entidade de serviço; --scopes ainda se aplica.
  • No modo azurecli, selecione a identidade entrando na CLI do Azure. No modo managedidentity, a identidade determina o locatário.
  • A CLI nunca recorre a outro modo nem a um login de usuário armazenado em cache. Um modo desconhecido, uma configuração ausente, uma configuração que o modo não usa ou um arquivo de credencial ilegível falha com um erro que nomeia a variável.
Passe segredos somente em arquivos, nunca em variáveis de ambiente ou argumentos, que podem vazar por listagens de processos e logs. Restrinja cada arquivo à conta que executa a CLI e exclua-o quando o trabalho terminar.

Exemplos

Um segredo do cliente no Linux ou no macOS, lido de um arquivo. $RUNNER_TEMP é a pasta temporária do GitHub Actions; em outros lugares, use qualquer arquivo que somente o trabalho possa ler:
Um trabalho do GitHub Actions com federação de identidade de carga de trabalho; consulte Configurar o GitHub Actions para a configuração do Entra ID e do GitHub:
A entidade de serviço da CLI do Azure, por exemplo após az login --service-principal:
O login da CLI do Azure é compartilhado por todos os terminais do seu usuário do SO; portanto, dê aos trabalhos simultâneos que entram com identidades diferentes o próprio AZURE_CONFIG_DIR. No Azure Pipelines, execute xbox dentro de uma tarefa AzureCLI@2 com uma conexão de serviço do Azure Resource Manager, de preferência uma que use federação de identidade de carga de trabalho. A conexão de serviço seleciona o locatário e a identidade; portanto, não defina XBOX_AUTHENTICATION__TENANTID nem XBOX_AUTHENTICATION__CLIENTID. Substitua o nome da conexão de serviço pelo seu:

Configurar o GitHub Actions

O modo githuboidc conecta um trabalho do GitHub Actions como entidade de serviço no seu locatário do Entra ID, sem nenhum segredo para armazenar ou rotacionar. A CLI solicita ao GitHub o token OIDC do trabalho, e o Entra ID o troca por um token de acesso se ele corresponder a uma credencial federada no registro do seu aplicativo. A credencial federada decide quais trabalhos podem entrar; ela não concede acesso a nenhuma API. Para criar o registro de aplicativo, a entidade de serviço dele e uma credencial federada que confie no seu repositório, siga Configuring OpenID Connect in Azure e Criar uma relação de confiança entre um aplicativo e um provedor de identidade externo. Ignore a etapa azure/login e as atribuições de função do Azure nesses guias, porque a CLI solicita o token por conta própria e não chama o Azure Resource Manager. A configuração precisa atender a estes requisitos:
  • A credencial federada usa o emissor https://token.actions.githubusercontent.com e o público api://AzureADTokenExchange.
  • O assunto dela corresponde ao assunto que o GitHub emite para o ambiente do trabalho. O padrão anterior é repo:<OWNER>/<REPO>:environment:<ENVIRONMENT>. No GitHub.com, repositórios criados, renomeados ou transferidos após 15 de julho de 2026 usam repo:<OWNER>@<OWNER-ID>/<REPO>@<REPO-ID>:environment:<ENVIRONMENT>; consulte as orientações do GitHub sobre assuntos imutáveis. Organizações e repositórios também podem personalizar os assuntos.
  • O trabalho declara esse ambiente e permissions: id-token: write. Sem o ambiente, o GitHub apresenta um assunto de branch ou de pull request, e o Entra ID o recusa.
  • O trabalho define XBOX_AUTHENTICATION__MODE, XBOX_AUTHENTICATION__TENANTID e XBOX_AUTHENTICATION__CLIENTID, como no exemplo. As IDs de locatário e de cliente não são segredos; portanto, armazene-as como variáveis de ambiente e leia-as por meio de vars.
O assunto nomeia o ambiente, não o branch; portanto, as regras de proteção do ambiente controlam quem pode entrar. Restrinja um ambiente de produção a branches protegidos e exija aprovação. Os administradores podem ignorar essas regras, a menos que isso esteja desativado nas configurações do ambiente. Um fluxo de trabalho pull_request_target é executado com as permissões do repositório base e pode solicitar um token OIDC, mesmo para um pull request de um fork. Nunca faça checkout nem execute código de pull request não confiável em um trabalho que possa entrar como a entidade de serviço. Se o assunto não corresponder, o Entra ID recusará o token com AADSTS700213 (“No matching federated identity record found for presented assertion subject ’…’”). O erro cita o assunto que o GitHub enviou; portanto, compare-o com o assunto da credencial. Para manter as configurações de cada ambiente junto ao ambiente, armazene-as como variáveis de ambiente do GitHub com os mesmos nomes das variáveis da CLI, como XBOX_AUTHENTICATION__CLIENTID, e passe-as para a CLI sem alterações.

Confirmar a identidade

Em um modo de entidade de serviço, auth status obtém um token e informa o modo, o tipo de entidade, o locatário, a ID do aplicativo, a ID do objeto, o público e as funções do aplicativo. Ele nunca imprime o token. Se não conseguir obter um token, ele sai com 1, de modo que uma etapa de pipeline que o executa falha. Consulte Auth. O objectId é a ID do objeto da entidade de serviço, não a do registro de aplicativo. Passe-o como --principal-object-id para xbox playfab service-principal set para conceder à entidade de serviço acesso ao PlayFab.
Última modificação em 19 de novembro de 2026