> ## 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.

# Autenticação

> Entre na XBOX CLI interativamente ou como entidade de serviço, gerencie credenciais armazenadas em cache e atenda aos requisitos de permissão do PlayFab.

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](https://docs.xbox.com/pt-BR/tools/xbox-cli/getting-started.md) 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](#how-playfab-authentication-works). Trabalhos autônomos podem entrar
como entidade de serviço; consulte
[Autenticação de automação (entidade de serviço)](#automation-service-principal-authentication).

## Entrar

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

`auth login` abre o navegador do sistema para você entrar e, em seguida, informa a conta e quando o token dela
expira:

```text theme={null}
Successfully signed in as: dev@nodpublishers.com
Token expires at: YYYY-MM-DD HH:MM:SS
```

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](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/auth.md).

## Verificar o status

```bash theme={null}
xbox auth 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.

```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
```

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](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/context.md).

## Sair

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

`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`](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/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](https://docs.xbox.com/services/playfab/identity/dev-identity/permissions/playfab-user-roles.md).

Uma [entidade de serviço](#automation-service-principal-authentication) 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](https://docs.xbox.com/pt-BR/tools/xbox-cli/playfab-api.md) 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:

| Opção | Substitui |
| - | - |
| `--client-id` | `AzureAd:ClientId` para o login do usuário; recusada nos modos de entidade de serviço |
| `--tenant-id` | `AzureAd:TenantId` para o login do usuário; recusada nos modos de entidade de serviço |
| `--scopes` | `AzureAd:Scopes` |

Consulte [Configuração](https://docs.xbox.com/pt-BR/tools/xbox-cli/configuration.md) para ver todas as configurações.

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

> [!NOTE]
>
> 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`](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/playfab/service-principal). 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](https://docs.xbox.com/pt-BR/tools/xbox-cli/known-issues.md#xbox-game-xbox-xbl-and-similar-commands-dont-accept-service-principals-yet).

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](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/context.md#behavior).

| Modo | Credencial | Configurações (cada uma com o prefixo `XBOX_AUTHENTICATION__`) |
| - | - | - |
| `user` (padrão) | Login interativo com `auth login`. | Nenhuma. |
| `clientsecret` | Segredo do cliente lido de um arquivo. | `TENANTID`, `CLIENTID`, `CLIENTSECRET__FILE` |
| `certificate` | Certificado PKCS#12 (`.pfx`) com a respectiva chave privada. | `TENANTID`, `CLIENTID`, `CERTIFICATE__PATH`, `CERTIFICATE__PASSWORDFILE` opcional |
| `federatedtoken` | Um token de identidade federada, por exemplo do Azure Pipelines ou do Kubernetes, lido de um arquivo. Um token rotacionado é obtido quando o token de acesso é atualizado. | `TENANTID`, `CLIENTID`, `FEDERATEDTOKEN__FILE` |
| `githuboidc` | O token OpenID Connect (OIDC) do GitHub Actions. O trabalho precisa de `permissions: id-token: write`. Consulte [Configurar o GitHub Actions](#set-up-github-actions). | `TENANTID`, `CLIENTID` |
| `azurecli` | A entidade de serviço ou a identidade gerenciada conectada à CLI do Azure. Uma pessoa conectada à CLI do Azure é recusada; uma pessoa usa `auth login`. | Nenhuma. |
| `managedidentity` | A identidade gerenciada do computador hospedado no Azure. Omita a ID do cliente para uma identidade atribuída pelo sistema. | `CLIENTID` opcional |

* `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:

```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
```

Um trabalho do GitHub Actions com federação de identidade de carga de trabalho; consulte
[Configurar o GitHub Actions](#set-up-github-actions) para a configuração do Entra ID e do GitHub:

```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 }}
```

A entidade de serviço da CLI do Azure, por exemplo após `az login --service-principal`:

```powershell theme={null}
$env:XBOX_AUTHENTICATION__MODE = "azurecli"
xbox auth status --output json
```

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:

```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
```

### 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](https://docs.github.com/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-azure)
e
[Criar uma relação de confiança entre um aplicativo e um provedor de identidade externo](https://learn.microsoft.com/entra/workload-id/workload-identity-federation-create-trust).
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](https://docs.github.com/en/actions/reference/security/oidc#immutable-subject-claims).
  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](#examples). 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](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/auth.md#auth-status).

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.


## Related topics

- [Autenticação](https://docs.xbox.com/pt-BR/services/playfab/identity/player-identity/authentication/index.md)
- [Autenticação de serviços](https://docs.xbox.com/pt-BR/services/xbox-services/fundamentals/s2s-auth-calls/service-authentication/index.md)
- [Autenticação e S2S](https://docs.xbox.com/pt-BR/services/xbox-services/fundamentals/s2s-auth-calls/live-s2s-auth-calls-nav.md)
- [Autenticação de dois fatores](https://docs.xbox.com/pt-BR/services/playfab/identity/dev-identity/authentication/two-factor-authentication.md)
- [Autenticação de usuários e propriedade](https://docs.xbox.com/pt-BR/build/steam-porting-guide/features/user-authentication-and-ownership.md)
