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:
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.
--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, executexbox 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 comandosxbox 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çõesAzureAd 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.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.
TENANTIDprecisa ser um GUID de locatário ou um domínio verificado, nãocommon,organizationsnemconsumers.CLIENTIDprecisa ser um GUID.- Essas configurações vêm somente de variáveis de ambiente.
--client-ide--tenant-idsão recusadas em um modo de entidade de serviço;--scopesainda se aplica. - No modo
azurecli, selecione a identidade entrando na CLI do Azure. No modomanagedidentity, 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.
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:
az login --service-principal:
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 modogithuboidc 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.come o públicoapi://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 usamrepo:<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__TENANTIDeXBOX_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 devars.
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.