Passer au contenu principal
La XBOX CLI vous connecte avec votre compte de développeur via Microsoft Entra ID. Pour les workflows Partner Center, connectez-vous avec un compte qui a accès à votre vendeur Partner Center. Consultez Prise en main pour choisir un vendeur et répertorier ses jeux. PlayFab vérifie ses propres autorisations, indépendamment de votre accès à Partner Center. Les commandes xbox playfab nécessitent l’autorisation Admin sur le titre sur lequel elles agissent ; consultez Fonctionnement de l’authentification PlayFab. Les tâches sans surveillance peuvent plutôt se connecter en tant que principal de service ; consultez Authentification pour l’automatisation (principal de service).

Se connecter

auth login ouvre le navigateur de votre système pour la connexion, puis indique le compte et la date d’expiration de son jeton :
La CLI utilise un seul compte à la fois. Pour changer de compte, exécutez de nouveau xbox auth login et choisissez l’autre compte. Toutes les commandes suivantes l’utilisent, y compris dans d’autres terminaux de votre utilisateur du système d’exploitation. Consultez Auth.

Vérifier l’état

auth status affiche le compte mis en cache et son jeton. Elle ne vérifie pas que vous pouvez utiliser PlayFab ou Partner Center.
Dans un script, passez --output json et vérifiez signedIn. Un code de sortie différent de zéro signifie que la CLI n’a pas pu lire ses paramètres ou son cache de jetons. Les valeurs par défaut enregistrées, comme le vendeur ou le titre PlayFab, sont distinctes de la connexion. Consultez Contexte.

Se déconnecter

auth logout supprime les comptes et jetons mis en cache, ce qui déconnecte tous les terminaux de votre utilisateur du système d’exploitation. Elle conserve votre contexte enregistré.

Cache de jetons

Les commandes réutilisent et actualisent votre jeton mis en cache : exécutez donc de nouveau xbox auth login uniquement lorsque la CLI vous le demande. Le jeton est stocké dans le cache protégé de Windows, le trousseau macOS (Keychain) ou le trousseau Secret Service de Linux. Sous Linux sans trousseau utilisable, par exemple sur une machine sans interface graphique, la CLI affiche un avertissement et utilise un fichier non chiffré protégé uniquement par les autorisations de fichier.

Fonctionnement de l’authentification PlayFab

Pour les commandes xbox playfab, la CLI envoie votre jeton d’accès Entra ID à PlayFab : vous ne manipulez donc jamais de clé secrète de titre PlayFab. PlayFab vérifie que votre compte dispose de l’autorisation Admin sur le titre, ou sur le studio pour les commandes playfab service-principal. Un Studio Admin l’accorde dans le Game Manager de PlayFab, par exemple avec le rôle intégré Title Admin ; consultez Rôles d’utilisateur PlayFab. Un principal de service n’obtient l’accès à PlayFab que lorsqu’une personne le lui accorde avec xbox playfab service-principal set. Un principal de service ne peut pas gérer lui-même les autorisations accordées. Consultez Intégration de l’API PlayFab pour sélectionner un titre et appeler les API PlayFab.

Remplacer les paramètres Entra ID

L’application Entra ID utilisée pour la connexion est intégrée à la CLI. La plupart des utilisateurs n’ont pas besoin de la modifier. Vous pouvez remplacer ses paramètres AzureAd avec les variables d’environnement XBOX_AZUREAD__, comme XBOX_AZUREAD__CLIENTID, ou pour une seule commande avec ces options : Consultez Configuration pour tous les paramètres.

Authentification pour l’automatisation (principal de service)

Un principal de service peut se connecter, et auth status indique un jeton valide, mais ses appels échouent avec une erreur d’autorisation tant que le service ne l’accepte pas. PlayFab l’accepte après qu’une personne lui a accordé l’accès avec xbox playfab service-principal set. Les autres commandes qui appellent un service en ligne, comme xbox game et xbox xbl, n’acceptent pas encore les principaux de service ; consultez Problèmes connus.
Les pipelines d’intégration continue (CI) et les autres tâches sans surveillance ne peuvent pas effectuer une connexion via le navigateur. Ils définissent plutôt XBOX_AUTHENTICATION__MODE sur un mode principal de service, et chaque commande obtient un jeton Entra ID d’application uniquement (app-only) au nom de l’inscription d’application ou de l’identité managée configurée. Rien n’est mis en cache, et auth login et auth logout échouent. Un principal de service n’a pas de contexte enregistré : passez donc le vendeur et le titre avec leurs options ou les variables XBOX_. Consultez Contexte.
  • TENANTID doit être un GUID de locataire ou un domaine vérifié, et non common, organizations ou consumers. CLIENTID doit être un GUID.
  • Ces paramètres proviennent uniquement des variables d’environnement. --client-id et --tenant-id sont refusées dans un mode principal de service ; --scopes s’applique toujours.
  • En mode azurecli, sélectionnez l’identité en vous connectant à Azure CLI. En mode managedidentity, l’identité détermine le locataire.
  • La CLI ne revient jamais à un autre mode ni à une connexion utilisateur mise en cache. Un mode inconnu, un paramètre manquant, un paramètre que le mode n’utilise pas ou un fichier d’informations d’identification illisible provoque une erreur qui nomme la variable.
Passez les secrets uniquement dans des fichiers, jamais dans des variables d’environnement ou des arguments, qui peuvent fuiter via les listes de processus et les journaux. Limitez l’accès à chaque fichier au compte qui exécute la CLI, et supprimez-le à la fin de la tâche.

Exemples

Un secret client sous Linux ou macOS, lu à partir d’un fichier. $RUNNER_TEMP est le dossier temporaire de GitHub Actions ; ailleurs, utilisez n’importe quel fichier que seule la tâche peut lire :
Une tâche GitHub Actions avec la fédération d’identité de charge de travail ; consultez Configurer GitHub Actions pour la configuration d’Entra ID et de GitHub :
Le principal de service d’Azure CLI, par exemple après az login --service-principal :
La connexion Azure CLI est partagée par tous les terminaux de votre utilisateur du système d’exploitation : attribuez donc aux tâches simultanées qui se connectent avec des identités différentes leur propre AZURE_CONFIG_DIR. Dans Azure Pipelines, exécutez xbox dans une tâche AzureCLI@2 avec une connexion de service Azure Resource Manager, de préférence une connexion qui utilise la fédération d’identité de charge de travail. La connexion de service sélectionne le locataire et l’identité : ne définissez donc pas XBOX_AUTHENTICATION__TENANTID ni XBOX_AUTHENTICATION__CLIENTID. Remplacez le nom de la connexion de service par le vôtre :

Configurer GitHub Actions

Le mode githuboidc connecte une tâche GitHub Actions en tant que principal de service dans votre locataire Entra ID, sans secret à stocker ni à renouveler. La CLI demande le jeton OIDC de la tâche à GitHub, et Entra ID l’échange contre un jeton d’accès s’il correspond à des informations d’identification fédérées de votre inscription d’application. Les informations d’identification fédérées déterminent quelles tâches peuvent se connecter ; elles n’accordent l’accès à aucune API. Pour créer l’inscription d’application, son principal de service et des informations d’identification fédérées qui approuvent votre dépôt, suivez Configuring OpenID Connect in Azure et Créer une relation d’approbation entre une application et un fournisseur d’identité externe. Ignorez l’étape azure/login et les attributions de rôles Azure de ces guides, car la CLI demande elle-même le jeton et n’appelle pas Azure Resource Manager. La configuration doit respecter ces exigences :
  • Les informations d’identification fédérées utilisent l’émetteur https://token.actions.githubusercontent.com et l’audience api://AzureADTokenExchange.
  • Leur sujet correspond au sujet que GitHub émet pour l’environnement de la tâche. L’ancien format par défaut est repo:<OWNER>/<REPO>:environment:<ENVIRONMENT>. Sur GitHub.com, les dépôts créés, renommés ou transférés après le 15 juillet 2026 utilisent repo:<OWNER>@<OWNER-ID>/<REPO>@<REPO-ID>:environment:<ENVIRONMENT> ; consultez les recommandations de GitHub sur les sujets immuables. Les organisations et les dépôts peuvent également personnaliser les sujets.
  • La tâche déclare cet environnement et permissions: id-token: write. Sans l’environnement, GitHub présente un sujet de branche ou de pull request, et Entra ID le refuse.
  • La tâche définit XBOX_AUTHENTICATION__MODE, XBOX_AUTHENTICATION__TENANTID et XBOX_AUTHENTICATION__CLIENTID, comme dans l’exemple. Les ID de locataire et de client ne sont pas des secrets : stockez-les donc comme variables d’environnement et lisez-les via vars.
Le sujet nomme l’environnement, et non la branche : ce sont donc les règles de protection de l’environnement qui contrôlent qui peut se connecter. Limitez un environnement de production aux branches protégées et exigez une approbation. Les administrateurs peuvent contourner ces règles, sauf si cette possibilité est désactivée dans les paramètres de l’environnement. Un workflow pull_request_target s’exécute avec les autorisations du dépôt de base et peut demander un jeton OIDC, même pour une pull request provenant d’une duplication (fork). N’extrayez ni n’exécutez jamais de code de pull request non approuvé dans une tâche qui peut se connecter en tant que principal de service. Si le sujet ne correspond pas, Entra ID refuse le jeton avec AADSTS700213 (« No matching federated identity record found for presented assertion subject ’…’ »). L’erreur cite le sujet envoyé par GitHub : comparez-le avec le sujet des informations d’identification. Pour conserver les paramètres de chaque environnement avec celui-ci, stockez-les comme variables d’environnement GitHub nommées d’après les variables de la CLI, comme XBOX_AUTHENTICATION__CLIENTID, et transmettez-les à la CLI sans modification.

Confirmer l’identité

Dans un mode principal de service, auth status obtient un jeton et indique le mode, le type de principal, le locataire, l’ID d’application, l’ID d’objet, l’audience et les rôles d’application. Elle n’affiche jamais le jeton. Si elle ne peut pas obtenir de jeton, elle se termine avec le code 1, de sorte qu’une étape de pipeline qui l’exécute échoue. Consultez Auth. L’objectId est l’ID d’objet du principal de service, et non celui de l’inscription d’application. Passez-le comme --principal-object-id à xbox playfab service-principal set pour accorder au principal de service l’accès à PlayFab.
Dernière modification le 19 novembre 2026