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

# Autenticación

> Inicia sesión en la XBOX CLI de forma interactiva o como entidad de servicio, administra las credenciales almacenadas en caché y cumple los requisitos de permisos de PlayFab.

La XBOX CLI inicia tu sesión con tu cuenta de desarrollador mediante Microsoft Entra ID.
Para los flujos de trabajo de Partner Center, inicia sesión con una cuenta que tenga acceso a tu vendedor
de Partner Center. Consulta [Introducción](https://docs.xbox.com/es/tools/xbox-cli/getting-started.md) para elegir un vendedor y enumerar sus juegos.

PlayFab comprueba sus propios permisos, independientemente de tu acceso a Partner Center. Los comandos `xbox playfab`
necesitan el permiso **Admin** en el título sobre el que actúan; consulta
[Cómo funciona la autenticación de PlayFab](#how-playfab-authentication-works). Los trabajos desatendidos pueden iniciar
sesión como entidad de servicio; consulta
[Autenticación para automatización (entidad de servicio)](#automation-service-principal-authentication).

## Iniciar sesión

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

`auth login` abre el explorador del sistema para iniciar sesión y, a continuación, indica la cuenta y cuándo expira su
token:

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

La CLI usa una cuenta cada vez. Para cambiar de cuenta, vuelve a ejecutar `xbox auth login` y elige
la otra cuenta. Todos los comandos posteriores la usan, también en otros terminales de tu usuario del sistema operativo.
Consulta [Auth](https://docs.xbox.com/es/tools/xbox-cli/commands/auth.md).

## Comprobar el estado

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

`auth status` muestra la cuenta almacenada en caché y su token. No comprueba si puedes usar
PlayFab 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
```

En un script, pasa `--output json` y comprueba `signedIn`. Un código de salida distinto de cero significa que la CLI no pudo
leer su configuración o su caché de tokens.

Los valores predeterminados guardados, como el vendedor o el título de PlayFab, son independientes del inicio de sesión. Consulta
[Contexto](https://docs.xbox.com/es/tools/xbox-cli/commands/context.md).

## Cerrar sesión

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

`auth logout` quita las cuentas y los tokens almacenados en caché, lo que cierra la sesión en todos los terminales de tu
usuario del sistema operativo. Conserva el contexto guardado.

## Caché de tokens

Los comandos reutilizan y actualizan el token almacenado en caché, así que vuelve a ejecutar `xbox auth login` solo cuando la CLI
te lo pida. El token se almacena en la caché protegida de Windows, el Llavero de macOS o el
conjunto de claves de Linux Secret Service. En Linux sin un conjunto de claves utilizable, como en una máquina sin interfaz gráfica, la
CLI muestra una advertencia y usa un archivo sin cifrar protegido solo por los permisos de archivo.

## Cómo funciona la autenticación de PlayFab

Para los comandos `xbox playfab`, la CLI envía tu token de acceso de Entra ID a PlayFab, de modo que nunca
manejas una clave secreta de título de PlayFab. PlayFab comprueba que tu cuenta tenga el permiso **Admin** en
el título, o en el estudio para los comandos
[`playfab service-principal`](https://docs.xbox.com/es/tools/xbox-cli/commands/playfab/service-principal). Un Studio Admin
lo concede en el Game Manager de PlayFab, por ejemplo con el rol integrado **Title Admin**; consulta
[Roles de usuario de PlayFab](https://docs.xbox.com/services/playfab/identity/dev-identity/permissions/playfab-user-roles.md).

Una [entidad de servicio](#automation-service-principal-authentication) obtiene acceso a PlayFab solo
cuando una persona se lo concede con `xbox playfab service-principal set`. Una entidad de servicio no puede
administrar las concesiones por sí misma.

Consulta [Integración de la API de PlayFab](https://docs.xbox.com/es/tools/xbox-cli/playfab-api.md) para seleccionar un título y llamar a las API de PlayFab.

## Invalidar la configuración de Entra ID

La aplicación de Entra ID que se usa para iniciar sesión está integrada en la CLI. La mayoría de los usuarios no necesitan
cambiarla. Puedes invalidar su configuración `AzureAd` con variables de entorno `XBOX_AZUREAD__`, como
`XBOX_AZUREAD__CLIENTID`, o para un solo comando con estas opciones:

| Opción | Invalida |
| - | - |
| `--client-id` | `AzureAd:ClientId` para el inicio de sesión de usuario; se rechaza en los modos de entidad de servicio |
| `--tenant-id` | `AzureAd:TenantId` para el inicio de sesión de usuario; se rechaza en los modos de entidad de servicio |
| `--scopes` | `AzureAd:Scopes` |

Consulta [Configuración](https://docs.xbox.com/es/tools/xbox-cli/configuration.md) para ver todas las opciones de configuración.

## Autenticación para automatización (entidad de servicio)

> [!NOTE]
>
> Una entidad de servicio puede iniciar sesión, y `auth status` indica un token válido, pero sus llamadas fallan
> con un error de autorización hasta que el servicio la acepta. PlayFab la acepta después de que una persona
> le concede acceso con
> [`xbox playfab service-principal set`](https://docs.xbox.com/es/tools/xbox-cli/commands/playfab/service-principal). Otros
> comandos que llaman a un servicio en línea, como `xbox game` y `xbox xbl`, todavía no aceptan
> entidades de servicio; consulta
> [Problemas conocidos](https://docs.xbox.com/es/tools/xbox-cli/known-issues.md#xbox-game-xbox-xbl-and-similar-commands-dont-accept-service-principals-yet).

Las canalizaciones de integración continua (CI) y otros trabajos desatendidos no pueden completar un inicio de sesión en el explorador.
En su lugar, establecen `XBOX_AUTHENTICATION__MODE` en un modo de entidad de servicio, y cada comando obtiene
un token de Entra ID solo de aplicación como el registro de aplicación o la identidad administrada configurados. No se almacena nada
en caché, y `auth login` y `auth logout` fallan.

Una entidad de servicio no tiene contexto guardado, así que pasa el vendedor y el título con sus opciones o con
variables `XBOX_`. Consulta [Contexto](https://docs.xbox.com/es/tools/xbox-cli/commands/context.md#behavior).

| Modo | Credencial | Configuración (cada una con el prefijo `XBOX_AUTHENTICATION__`) |
| - | - | - |
| `user` (predeterminado) | Inicio de sesión interactivo con `auth login`. | Ninguna. |
| `clientsecret` | Secreto de cliente leído de un archivo. | `TENANTID`, `CLIENTID`, `CLIENTSECRET__FILE` |
| `certificate` | Certificado PKCS#12 (`.pfx`) con su clave privada. | `TENANTID`, `CLIENTID`, `CERTIFICATE__PATH`, `CERTIFICATE__PASSWORDFILE` opcional |
| `federatedtoken` | Un token de identidad federada, por ejemplo de Azure Pipelines o Kubernetes, leído de un archivo. Un token rotado se recoge cuando se actualiza el token de acceso. | `TENANTID`, `CLIENTID`, `FEDERATEDTOKEN__FILE` |
| `githuboidc` | El token de OpenID Connect (OIDC) de GitHub Actions. El trabajo necesita `permissions: id-token: write`. Consulta [Configurar GitHub Actions](#set-up-github-actions). | `TENANTID`, `CLIENTID` |
| `azurecli` | La entidad de servicio o la identidad administrada que ha iniciado sesión en la CLI de Azure. Se rechaza a una persona que ha iniciado sesión en la CLI de Azure; una persona usa `auth login`. | Ninguna. |
| `managedidentity` | La identidad administrada de la máquina hospedada en Azure. Omite el id. de cliente para una identidad asignada por el sistema. | `CLIENTID` opcional |

* `TENANTID` debe ser un GUID de inquilino o un dominio comprobado, no `common`, `organizations` ni
  `consumers`. `CLIENTID` debe ser un GUID.
* Esta configuración solo procede de variables de entorno. `--client-id` y `--tenant-id` se
  rechazan en un modo de entidad de servicio; `--scopes` sigue aplicándose.
* En el modo `azurecli`, selecciona la identidad iniciando sesión en la CLI de Azure. En el modo `managedidentity`,
  la identidad determina el inquilino.
* La CLI nunca recurre a otro modo ni a un inicio de sesión de usuario almacenado en caché. Un modo desconocido, una
  opción de configuración que falta, una opción que el modo no usa o un archivo de credenciales ilegible producen
  un error que indica el nombre de la variable.

Pasa los secretos solo en archivos, nunca en variables de entorno ni en argumentos, que pueden filtrarse a través de
las listas de procesos y los registros. Restringe cada archivo a la cuenta que ejecuta la CLI y elimínalo
cuando termine el trabajo.

### Ejemplos

Un secreto de cliente en Linux o macOS, leído de un archivo. `$RUNNER_TEMP` es la carpeta temporal de GitHub Actions;
en otros entornos, usa cualquier archivo que solo pueda leer el trabajo:

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

Un trabajo de GitHub Actions con federación de identidades de carga de trabajo; consulta
[Configurar GitHub Actions](#set-up-github-actions) para la configuración de Entra ID y 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 }}
```

La entidad de servicio de la CLI de Azure, por ejemplo después de `az login --service-principal`:

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

Todos los terminales de tu usuario del sistema operativo comparten el inicio de sesión de la CLI de Azure, así que asigna a los trabajos simultáneos que
inician sesión como identidades distintas su propio `AZURE_CONFIG_DIR`.

En Azure Pipelines, ejecuta `xbox` dentro de una tarea `AzureCLI@2` con una conexión de servicio de Azure Resource Manager,
preferiblemente una que use la federación de identidades de carga de trabajo. La conexión de servicio selecciona
el inquilino y la identidad, así que no establezcas `XBOX_AUTHENTICATION__TENANTID` ni
`XBOX_AUTHENTICATION__CLIENTID`. Reemplaza el nombre de la conexión de servicio por el tuyo:

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

El modo `githuboidc` inicia la sesión de un trabajo de GitHub Actions como entidad de servicio en tu inquilino de Entra ID,
sin ningún secreto que almacenar ni rotar. La CLI solicita a GitHub el token de OIDC del trabajo, y Entra
ID lo intercambia por un token de acceso si coincide con una credencial federada de tu registro
de aplicación. La credencial federada decide qué trabajos pueden iniciar sesión; no concede acceso
a ninguna API.

Para crear el registro de aplicación, su entidad de servicio y una credencial federada que confíe en
tu repositorio, sigue
[Configuring OpenID Connect in Azure](https://docs.github.com/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-azure)
y
[Crear una relación de confianza entre una aplicación y un proveedor de identidades externo](https://learn.microsoft.com/entra/workload-id/workload-identity-federation-create-trust).
Omite el paso `azure/login` y las asignaciones de roles de Azure de esas guías, porque la CLI solicita
el token por sí misma y no llama a Azure Resource Manager.

La configuración debe cumplir estos requisitos:

* **La credencial federada** usa el emisor `https://token.actions.githubusercontent.com`
  y la audiencia `api://AzureADTokenExchange`.
* **Su sujeto coincide con el sujeto que GitHub emite para el entorno del trabajo.** El valor
  predeterminado anterior es `repo:<OWNER>/<REPO>:environment:<ENVIRONMENT>`. En GitHub.com, los repositorios
  creados, renombrados o transferidos después del 15 de julio de 2026 usan
  `repo:<OWNER>@<OWNER-ID>/<REPO>@<REPO-ID>:environment:<ENVIRONMENT>`; consulta
  [las indicaciones de GitHub sobre sujetos inmutables](https://docs.github.com/en/actions/reference/security/oidc#immutable-subject-claims).
  Las organizaciones y los repositorios también pueden personalizar los sujetos.
* **El trabajo declara ese entorno y `permissions: id-token: write`.** Sin el
  entorno, GitHub presenta un sujeto de rama o de solicitud de incorporación de cambios, y Entra ID lo rechaza.
* **El trabajo establece `XBOX_AUTHENTICATION__MODE`, `XBOX_AUTHENTICATION__TENANTID` y
  `XBOX_AUTHENTICATION__CLIENTID`,** como en el [ejemplo](#examples). Los id. de inquilino y de cliente
  no son secretos, así que almacénalos como variables de entorno y léelos a través de `vars`.

El sujeto indica el entorno, no la rama, por lo que las reglas de protección del entorno
controlan quién puede iniciar sesión. Restringe un entorno de producción a ramas protegidas y exige
aprobación. Los administradores pueden omitir estas reglas a menos que esa opción esté desactivada en la configuración
del entorno.

Un flujo de trabajo `pull_request_target` se ejecuta con los permisos del repositorio base y puede solicitar un
token de OIDC, incluso para una solicitud de incorporación de cambios desde una bifurcación. Nunca extraigas ni ejecutes código de solicitudes de incorporación de cambios
que no sea de confianza en un trabajo que pueda iniciar sesión como la entidad de servicio.

Si el sujeto no coincide, Entra ID rechaza el token con `AADSTS700213` ("No matching
federated identity record found for presented assertion subject '…'"). El error cita el
sujeto que envió GitHub, así que compáralo con el sujeto de la credencial.

Para mantener la configuración de cada entorno junto con el entorno, almacénala como variables de entorno de GitHub
con los nombres de las variables de la CLI, como `XBOX_AUTHENTICATION__CLIENTID`, y pásalas
a la CLI sin cambios.

### Confirmar la identidad

En un modo de entidad de servicio, `auth status` obtiene un token e indica el modo, el tipo de entidad de seguridad, el
inquilino, el id. de aplicación, el id. de objeto, la audiencia y los roles de aplicación. Nunca muestra el token. Si no puede obtener
un token, sale con `1`, por lo que el paso de canalización que lo ejecuta falla. Consulta
[Auth](https://docs.xbox.com/es/tools/xbox-cli/commands/auth.md#auth-status).

El `objectId` es el id. de objeto de la entidad de servicio, no el del registro de aplicación. Pásalo como
`--principal-object-id` a `xbox playfab service-principal set` para conceder a la entidad de servicio
acceso a PlayFab.


## Related topics

- [Autenticación](https://docs.xbox.com/es/services/xbox-services/fundamentals/identity/auth/index.md)
- [Autenticación de servicios](https://docs.xbox.com/es/services/xbox-services/fundamentals/s2s-auth-calls/service-authentication/index.md)
- [Autenticación y S2S](https://docs.xbox.com/es/services/xbox-services/fundamentals/s2s-auth-calls/live-s2s-auth-calls-nav.md)
- [Autenticación en dos fases](https://docs.xbox.com/es/services/playfab/identity/dev-identity/authentication/two-factor-authentication.md)
- [Autenticación de usuarios y propiedad](https://docs.xbox.com/es/build/steam-porting-guide/features/user-authentication-and-ownership.md)
