Saltar al contenido principal
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 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. Los trabajos desatendidos pueden iniciar sesión como entidad de servicio; consulta Autenticación para automatización (entidad de servicio).

Iniciar sesión

auth login abre el explorador del sistema para iniciar sesión y, a continuación, indica la cuenta y cuándo expira su token:
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.

Comprobar el estado

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

Cerrar sesión

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. 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. Una entidad de servicio 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 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: Consulta Configuración para ver todas las opciones de configuración.

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

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. 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.
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.
  • 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:
Un trabajo de GitHub Actions con federación de identidades de carga de trabajo; consulta Configurar GitHub Actions para la configuración de Entra ID y GitHub:
La entidad de servicio de la CLI de Azure, por ejemplo después de az login --service-principal:
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:

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 y Crear una relación de confianza entre una aplicación y un proveedor de identidades externo. 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. 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. 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. 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.
Última modificación el 19 de noviembre de 2026