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

# Authentification

> Connectez-vous à l'XBOX CLI de façon interactive ou en tant que principal de service, gérez les informations d'identification mises en cache et respectez les exigences d'autorisation de PlayFab.

L'XBOX CLI vous connecte avec votre compte de développeur au moyen de Microsoft Entra ID.
Pour les flux de travail Partner Center, connectez-vous avec un compte qui a accès à votre vendeur Partner Center.
Consultez [Prise en main](https://docs.xbox.com/fr-CA/tools/xbox-cli/getting-started.md) pour choisir un vendeur et répertorier ses jeux.

PlayFab vérifie ses propres autorisations, séparément 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](#how-playfab-authentication-works). Les tâches sans surveillance peuvent plutôt se
connecter en tant que principal de service; consultez
[Authentification pour l'automatisation (principal de service)](#automation-service-principal-authentication).

## Se connecter

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

`auth login` ouvre le navigateur de votre système pour la connexion, puis indique le compte et le moment où son jeton
expire :

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

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

## Vérifier l'état

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

`auth status` affiche le compte mis en cache et son jeton. La commande ne vérifie pas que vous pouvez utiliser
PlayFab ou 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
```

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

## Se déconnecter

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

`auth logout` supprime les comptes et les jetons mis en cache, ce qui déconnecte tous les terminaux de votre
utilisateur du système d'exploitation. La commande 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 ou le
trousseau Secret Service de Linux. Sous Linux sans trousseau utilisable, comme sur un ordinateur 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`](https://docs.xbox.com/fr-CA/tools/xbox-cli/commands/playfab/service-principal). Un administrateur de studio
l'accorde dans le Game Manager de PlayFab, par exemple avec le rôle intégré **Title Admin**; consultez
[Rôles d'utilisateur PlayFab](https://docs.xbox.com/services/playfab/identity/dev-identity/permissions/playfab-user-roles.md).

Un [principal de service](#automation-service-principal-authentication) obtient l'accès à PlayFab uniquement
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 octrois d'accès.

Consultez [Intégration de l'API PlayFab](https://docs.xbox.com/fr-CA/tools/xbox-cli/playfab-api.md) 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` au moyen des variables d'environnement `XBOX_AZUREAD__`, comme
`XBOX_AZUREAD__CLIENTID`, ou pour une seule commande au moyen de ces options :

| Option | Remplace |
| - | - |
| `--client-id` | `AzureAd:ClientId` pour la connexion d'un utilisateur; refusée dans les modes principal de service |
| `--tenant-id` | `AzureAd:TenantId` pour la connexion d'un utilisateur; refusée dans les modes principal de service |
| `--scopes` | `AzureAd:Scopes` |

Consultez [Configuration](https://docs.xbox.com/fr-CA/tools/xbox-cli/configuration.md) pour connaître tous les paramètres.

## Authentification pour l'automatisation (principal de service)

> [!NOTE]
>
> Un principal de service peut se connecter, et `auth status` signale 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`](https://docs.xbox.com/fr-CA/tools/xbox-cli/commands/playfab/service-principal). 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](https://docs.xbox.com/fr-CA/tools/xbox-cli/known-issues.md#xbox-game-xbox-xbl-and-similar-commands-dont-accept-service-principals-yet).

Les pipelines d'intégration continue (CI) et les autres tâches sans surveillance ne peuvent pas effectuer une connexion dans un 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 seulement en tant qu'inscription d'application ou identité managée configurée. Rien n'est
mis en cache, et `auth login` et `auth logout` échouent.

Un principal de service n'a aucun contexte enregistré; passez donc le vendeur et le titre au moyen de leurs options ou
des variables `XBOX_`. Consultez [Contexte](https://docs.xbox.com/fr-CA/tools/xbox-cli/commands/context.md#behavior).

| Mode | Informations d'identification | Paramètres (chacun précédé de `XBOX_AUTHENTICATION__`) |
| - | - | - |
| `user` (par défaut) | Connexion interactive avec `auth login`. | Aucun. |
| `clientsecret` | Clé secrète client lue à partir d'un fichier. | `TENANTID`, `CLIENTID`, `CLIENTSECRET__FILE` |
| `certificate` | Certificat PKCS#12 (`.pfx`) avec sa clé privée. | `TENANTID`, `CLIENTID`, `CERTIFICATE__PATH`, `CERTIFICATE__PASSWORDFILE` facultatif |
| `federatedtoken` | Un jeton d'identité fédérée, par exemple provenant d'Azure Pipelines ou de Kubernetes, lu à partir d'un fichier. Un jeton renouvelé est pris en compte lorsque le jeton d'accès est actualisé. | `TENANTID`, `CLIENTID`, `FEDERATEDTOKEN__FILE` |
| `githuboidc` | Le jeton OpenID Connect (OIDC) de GitHub Actions. La tâche a besoin de `permissions: id-token: write`. Consultez [Configurer GitHub Actions](#set-up-github-actions). | `TENANTID`, `CLIENTID` |
| `azurecli` | Le principal de service ou l'identité managée connecté à Azure CLI. Une personne connectée à Azure CLI est refusée; une personne utilise `auth login`. | Aucun. |
| `managedidentity` | L'identité managée de l'ordinateur hébergé dans Azure. Omettez l'ID client pour une identité attribuée par le système. | `CLIENTID` facultatif |

* `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 se rabat jamais sur un autre mode ni sur une connexion d'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 entraîne
  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 par
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

Une clé secrète client sous Linux ou macOS, lue à 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 :

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

Une tâche GitHub Actions avec fédération des identités de charge de travail; consultez
[Configurer GitHub Actions](#set-up-github-actions) pour la configuration d'Entra ID et de 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 }}
```

Le principal de service d'Azure CLI, par exemple après `az login --service-principal` :

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

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 des identités 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 :

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

### Configurer GitHub Actions

Le mode `githuboidc` connecte une tâche GitHub Actions en tant que principal de service dans votre locataire Entra ID,
sans aucun 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 font confiance à
votre dépôt, suivez
[Configuration d'OpenID Connect dans Azure](https://docs.github.com/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-azure)
et
[Créer une relation d'approbation entre une application et un fournisseur d'identité externe](https://learn.microsoft.com/entra/workload-id/workload-identity-federation-create-trust).
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 directives de GitHub sur les sujets immuables](https://docs.github.com/en/actions/reference/security/oidc#immutable-subject-claims).
  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 demande de tirage, et Entra ID le refuse.
* **La tâche définit `XBOX_AUTHENTICATION__MODE`, `XBOX_AUTHENTICATION__TENANTID` et
  `XBOX_AUTHENTICATION__CLIENTID`,** comme dans l'[exemple](#examples). Les ID de locataire et de client
  ne sont pas des secrets; stockez-les donc comme variables d'environnement et lisez-les au moyen de `vars`.

Le sujet nomme l'environnement, et non la branche; ce sont donc les règles de protection de l'environnement qui
déterminent 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 flux de travail `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 demande de tirage provenant d'une duplication. N'extrayez ou n'exécutez jamais le code d'une demande de tirage non fiable
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 donc avec le sujet des informations d'identification.

Pour conserver les paramètres de chaque environnement avec l'environnement, stockez-les comme variables
d'environnement GitHub nommées d'après les variables de la CLI, comme `XBOX_AUTHENTICATION__CLIENTID`, et passez-les
à la CLI sans les modifier.

### 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. La commande n'affiche jamais le jeton. Si elle ne peut pas obtenir
de jeton, elle se termine avec le code `1`; une étape de pipeline qui l'exécute échoue donc. Consultez
[Auth](https://docs.xbox.com/fr-CA/tools/xbox-cli/commands/auth.md#auth-status).

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.


## Related topics

- [Authentification](https://docs.xbox.com/fr-CA/services/playfab/identity/player-identity/authentication/index.md)
- [Authentification unique](https://docs.xbox.com/fr-CA/services/xbox-services/fundamentals/s2s-auth-calls/custom-service-config/single-sign-on/index.md)
- [Authentification des services](https://docs.xbox.com/fr-CA/services/xbox-services/fundamentals/s2s-auth-calls/service-authentication/index.md)
- [Authentification à deux facteurs](https://docs.xbox.com/fr-CA/services/playfab/identity/dev-identity/authentication/two-factor-authentication.md)
- [Authentification et S2S](https://docs.xbox.com/fr-CA/services/xbox-services/fundamentals/s2s-auth-calls/live-s2s-auth-calls-nav.md)
