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

# Principal de service

> Accordez, inspectez et révoquez l'accès PlayFab d'un principal de service Entra à un studio et à ses titres.

La famille de commandes `playfab service-principal` est expérimentale. Son interface CLI peut
changer ou être supprimée en fonction des retours.

Un pipeline d'intégration continue (CI) ou une autre tâche sans surveillance se connecte en tant que principal de service
Microsoft Entra ID ; consultez
[Authentification pour l'automatisation (principal de service)](https://docs.xbox.com/fr/tools/xbox-cli/authentication.md#automation-service-principal-authentication).
PlayFab n'accepte le principal de service qu'une fois qu'une personne lui a accordé l'accès dans un studio
PlayFab. Ces commandes gèrent ces octrois d'accès.

Seule une personne connectée disposant de l'autorisation **Admin** sur le studio peut exécuter ces commandes. Elles
refusent de s'exécuter lorsque `XBOX_AUTHENTICATION__MODE` sélectionne un mode principal de service : connectez-vous donc plutôt
avec `xbox auth login`.

| Commande | Chemin de l'API PlayFab | Description |
| - | - | - |
| `playfab service-principal list` | `/Studio/ListServicePrincipals` | Répertorie les principaux de service inscrits dans un studio. |
| `playfab service-principal get` | `/Studio/GetServicePrincipalAccess` | Affiche les octrois d'accès d'un principal de service. |
| `playfab service-principal set` | `/Studio/SetServicePrincipalAccess` | Inscrit un principal de service si nécessaire, et **remplace** tous ses octrois d'accès. |
| `playfab service-principal revoke` | `/Studio/DeleteServicePrincipalAccess` | Supprime un principal de service et tous ses octrois d'accès d'un studio. Demande d'abord une confirmation ; consultez [Sécurité et opérations destructives](https://docs.xbox.com/fr/tools/xbox-cli/safety.md). |

| Commande | Options |
| - | - |
| `service-principal list` | `--studio-id` (obligatoire), `--limit` (1-100), `--continuation-token`. |
| `service-principal get` | `--studio-id`, `--principal-tenant-id`, `--principal-object-id` (toutes obligatoires). |
| `service-principal set` | `--studio-id`, `--principal-tenant-id`, `--principal-object-id`, `--display-name`, `--grants-file` (toutes obligatoires), `--expected-version`. |
| `service-principal revoke` | `--studio-id`, `--principal-tenant-id`, `--principal-object-id` (toutes obligatoires). |

`list` accepte `--output table` ; les autres commandes non. `list` renvoie une page : lorsqu'il
en existe davantage, le `ContinuationToken` de la réponse est défini, et exécuter de nouveau `list` avec
`--continuation-token` défini sur cette valeur permet d'obtenir la page suivante.

## Identificateurs

* `--studio-id` désigne le studio propriétaire des octrois d'accès. Ces commandes n'acceptent pas de
  titre PlayFab : `--playfab-title-id` et le contexte enregistré ne s'appliquent donc pas.
* `--principal-tenant-id` et `--principal-object-id` identifient le principal de service : son
  locataire Entra ID, et l'ID d'objet de son application d'entreprise, et non de son inscription
  d'application. `xbox auth status` le signale sous la forme `objectId` lorsque vous êtes connecté en tant que principal
  de service.
* Vous ne passez pas l'ID d'application (client). PlayFab l'enregistre à partir du premier jeton du principal
  de service, et `list` et `get` le signalent sous la forme `ClientId`.
* Les options globales `--tenant-id` et `--client-id` configurent votre propre connexion, et non le
  principal de service auquel vous accordez l'accès.

## Fichier d'octrois d'accès

> [!WARNING]
>
> `set` remplace tous les octrois d'accès du principal de service par le contenu de
> `--grants-file`, et supprime toute autorisation de studio ou tout titre que le fichier omet.

Partez des octrois d'accès actuels plutôt que d'écrire un fichier à partir de zéro. Enregistrez la sortie de
`get`, modifiez ses `StudioPermissions` et `TitleGrants`, puis passez-la à `set`, avec sa
`Version` en tant que `--expected-version` :

```bash theme={null}
xbox playfab service-principal get \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777 \
  > grants.json
```

Un fichier d'octrois d'accès peut être la sortie complète de `get`, son `data`, l'objet `ServicePrincipal`
qu'il contient, ou uniquement les octrois d'accès :

```json theme={null}
{
  "StudioPermissions": [],
  "TitleGrants": [
    { "TitleId": "ABC123", "Permissions": ["Admin"] }
  ]
}
```

* Les deux propriétés sont obligatoires. Une liste vide n'accorde rien de ce type.
* Chaque titre a besoin d'au moins une autorisation. Pour supprimer l'octroi d'accès d'un titre, omettez le titre.
* Les noms de propriétés ne respectent pas la casse. Une propriété non reconnue est une erreur : ainsi, un
  `TitleGrants` mal orthographié ne peut pas supprimer tous les octrois d'accès aux titres.
* Les champs `TenantId`, `ObjectId` et `DisplayName` du fichier, lorsqu'ils sont présents, doivent correspondre à
  `--principal-tenant-id`, `--principal-object-id` et `--display-name`. Pour renommer le
  principal de service, modifiez également `DisplayName` dans le fichier, ou supprimez-le.

### Version attendue

Chaque modification des octrois d'accès d'un principal de service leur attribue une nouvelle `Version`, que renvoient `get` et
`set`. Avec `--expected-version`, `set` ne modifie rien, sauf si les octrois d'accès sont toujours
à cette version : elle ne peut donc pas annuler une modification effectuée par quelqu'un après votre lecture.
`--expected-version 0` exige que le principal de service n'ait encore aucun accès. Sans
`--expected-version`, `set` remplace les octrois d'accès quels qu'ils soient actuellement.

Lorsque le fichier d'octrois d'accès comporte une `Version`, `--expected-version` est obligatoire et doit lui être égale.
Si elles diffèrent, exécutez de nouveau `get` et refaites vos modifications sur sa sortie. Pour remplacer les octrois d'accès
dans tous les cas, supprimez `Version` du fichier et omettez `--expected-version`.

### En cas d'échec de `set`

> [!WARNING]
>
> Si `set` échoue, le principal de service peut n'avoir aucun accès dans le studio jusqu'à ce qu'un `set`
> réussisse, ce qui peut interrompre un pipeline.

Un échec n'indique pas si les octrois d'accès ont changé : n'exécutez donc pas de nouveau `set` avec l'ancienne
version. Exécutez `get`, vérifiez ses octrois d'accès et sa `Version`, et s'ils ne correspondent pas à ce que vous vouliez
définir, modifiez cette sortie et passez-la à `set` avec sa `Version` en tant que `--expected-version`.

## Exemples

Répertorier les principaux de service d'un studio, et afficher les octrois d'accès de l'un d'eux :

```bash theme={null}
xbox playfab service-principal list \
  --studio-id 1234567890ABCDEF

xbox playfab service-principal get \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777
```

Remplacer les octrois d'accès du principal de service par ceux de `grants.json`, que vous avez enregistré à partir de
`get` et modifié :

```bash theme={null}
xbox playfab service-principal set \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777 \
  --display-name "Nod Publishers build" \
  --grants-file grants.json \
  --expected-version 3
```

Supprimer le principal de service et ses octrois d'accès du studio :

```bash theme={null}
xbox playfab service-principal revoke \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777 \
  --confirm
```

Après `revoke`, la requête PlayFab suivante du principal de service dans le studio échoue. `revoke`
réussit également lorsque le principal de service n'a déjà aucun accès. Pour restaurer l'accès, exécutez
`set` avec l'ensemble complet des octrois d'accès.


## Related topics

- [Votre premier test de jeu](https://docs.xbox.com/fr/tools/xbox-cli/first-playtest.md)
- [Problèmes connus](https://docs.xbox.com/fr/tools/xbox-cli/known-issues.md)
- [Auth](https://docs.xbox.com/fr/tools/xbox-cli/commands/auth.md)
- [Authentification](https://docs.xbox.com/fr/tools/xbox-cli/authentication.md)
- [Programme de services de certification payants](https://docs.xbox.com/fr/publishing/game-publishing/concepts/certification/certification-paid-services.md)
