> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Authentification Microsoft Entra ID pour les API PlayFab > Authentifiez-vous auprès des API Admin, Server et d'entité de PlayFab avec des jetons délégués Microsoft Entra ID à l'aide de flux OAuth 2.0 comme PKCE, le code d'appareil ou l'octroi implicite. PlayFab prend en charge l'authentification Microsoft Entra ID (anciennement Azure Active Directory) pour appeler les API Admin, Server et d'entité. Avec l'authentification Entra ID, vous vous connectez avec votre identité Microsoft et utilisez un jeton d'accès délégué au lieu d'une clé secrète de développeur. Votre application gère l'expérience de connexion à l'aide de flux de client public OAuth 2.0 standard, comme le code d'autorisation avec PKCE, le code d'appareil ou l'octroi implicite. L'authentification Entra ID est une solution de rechange aux clés secrètes de développeur pour les appels d'API Admin, Server et certains appels d'API d'entité. Les API Client et d'entité destinées aux joueurs continuent d'utiliser les tickets de session et les jetons d'entité obtenus lors de la connexion des joueurs. Seules les API d'entité qui peuvent être appelées avec un jeton d'entité de *titre* peuvent être utilisées avec Entra ID. Pour plus d'informations sur les clés secrètes, consultez [Gestion des clés secrètes](/fr-CA/services/playfab/live-service-management/gamemanager/secret-key-management). ## Pourquoi utiliser l'authentification Entra ID Les clés secrètes de développeur sont simples à utiliser, mais l'authentification Entra ID offre plusieurs avantages : * **Aucun secret partagé** : les flux de client public ne nécessitent pas de secret client. Les jetons ont une courte durée de vie et sont limités à l'utilisateur connecté. * **Responsabilité individuelle** : chaque appel d'API est lié à une identité d'utilisateur précise, ce qui facilite la vérification de qui a fait quoi. * **Accès conditionnel** : votre organisation peut appliquer des stratégies Entra ID comme des restrictions d'adresses IP, l'authentification multifacteur (MFA) et des vérifications de conformité des appareils. ## Fonctionnement de l'authentification Entra ID Si vous n'avez jamais travaillé avec Microsoft Entra ID, il s'agit du service d'identité infonuagique de Microsoft, soit le même système d'identité qui sous-tend Microsoft 365, les comptes de développeur XBOX et Azure. Au lieu que PlayFab remette à votre studio une clé secrète à longue durée de vie, votre outil demande à Entra ID de connecter un développeur et de renvoyer un **jeton d'accès** à courte durée de vie. PlayFab fait confiance aux jetons qu'Entra ID émet pour les utilisateurs qui sont membres de votre studio. Trois parties sont en jeu : * **Le développeur.** Vous, connecté avec un compte Microsoft (personnel) ou un compte professionnel ou scolaire (Entra ID). * **Une inscription d'application dans Entra ID.** Elle représente l'outil qui appelle PlayFab : une interface de ligne de commande, un script de build, un tableau de bord interne, etc. Elle indique à Entra ID que « cette application est autorisée à demander des jetons d'accès PlayFab au nom d'un utilisateur connecté ». * **Le service PlayFab.** PlayFab est inscrit dans Entra ID sous l'ID d'application `448adbda-b8d8-4f33-a1b0-ac58cf44d4c1` et expose une autorisation déléguée appelée `plugin`. Lorsque votre code demande l'étendue `448adbda-b8d8-4f33-a1b0-ac58cf44d4c1/plugin`, Entra ID émet un jeton que PlayFab accepte. Un appel typique se déroule comme suit : 1. Votre code utilise la bibliothèque d'authentification Microsoft (MSAL) pour lancer une connexion, généralement au moyen d'une fenêtre contextuelle de navigateur ou d'une invite de code d'appareil. 2. L'utilisateur se connecte avec son identité Microsoft et consent à ce que votre application appelle PlayFab en son nom. 3. MSAL renvoie un jeton d'accès (un JWT) et met en cache un jeton d'actualisation afin que les appels futurs puissent éviter l'invite. 4. Votre code envoie le jeton dans l'en-tête `Authorization: Bearer ` de chaque requête PlayFab. 5. PlayFab valide le jeton, l'associe à l'utilisateur du studio correspondant et autorise l'appel en fonction du rôle de cet utilisateur. Pour les définitions des termes Entra ID utilisés dans cet article, consultez le [Glossaire](#glossary) à la fin. ## Prérequis * Un compte Microsoft soutenu par Entra ID (un compte professionnel ou scolaire) ou un compte Microsoft personnel (MSA). * Un titre PlayFab. Pour plus d'informations, consultez [Créer un compte PlayFab](/fr-CA/services/playfab/identity/dev-identity/pfab-account). * Des autorisations pour inscrire des applications dans votre locataire Microsoft Entra ID. * L'utilisateur appelant doit être ajouté au studio PlayFab et désigné comme administrateur de titre. Pour plus d'informations sur les rôles, consultez [Rôles d'utilisateur PlayFab](/fr-CA/services/playfab/identity/dev-identity/permissions/playfab-user-roles). ## Inscrire une application cliente publique dans Entra ID Vous devez inscrire une application dans votre locataire Entra ID afin que votre code puisse demander des jetons délégués au nom d'un utilisateur connecté. Pour les flux de client public (SPA, code d'appareil, implicite), aucun secret client n'est nécessaire. 1. Connectez-vous au [portail Azure](https://portal.azure.com). 2. Recherchez et sélectionnez **App registrations**, puis sélectionnez **New registration**. 3. Entrez un nom pour votre application (par exemple, `PlayFab API Client`). 4. Sous **Supported account types**, sélectionnez l'option qui correspond aux exigences de votre organisation. Pour une souplesse maximale, sélectionnez **Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts**. Cette option permet à n'importe quel compte Microsoft de s'authentifier. 5. Configurez le **Redirect URI** en fonction de votre type d'application : * Pour une application monopage (SPA), sélectionnez **Single-page application (SPA)** et entrez votre URI de redirection (par exemple, `http://localhost:3000`). * Pour une application native ou console qui utilise le flux de code d'appareil, sélectionnez **Public client/native (mobile & desktop)** et entrez `http://localhost`. 6. Sélectionnez **Register**. Sur la page de vue d'ensemble, notez l'**Application (client) ID**. Vous aurez besoin de cette valeur pour demander des jetons. 7. Ajoutez l'autorisation de l'API PlayFab à votre inscription d'application : 1. Dans le portail Azure, accédez à votre inscription d'application et sélectionnez **API permissions**. 2. Sélectionnez **Add a permission** > **APIs my organization uses**. 3. Recherchez l'ID d'application PlayFab `448adbda-b8d8-4f33-a1b0-ac58cf44d4c1` et sélectionnez-le. 4. Sélectionnez **Delegated permissions**, cochez l'autorisation **plugin** et sélectionnez **Add permissions**. Si votre scénario nécessite un client confidentiel (application Web), vous devez également créer un secret client sous **Certificates & secrets**. Cet article porte sur les flux de client public, qui ne nécessitent pas de secret. Pour plus d'informations sur les flux de client confidentiel, consultez [Plateforme d'identités Microsoft et flux de code d'autorisation OAuth 2.0](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow). ## Configurer l'accès au studio PlayFab PlayFab valide les jetons Entra ID en fonction de l'appartenance au studio. L'utilisateur appelant doit être ajouté au studio PlayFab et se voir accorder le rôle approprié. 1. Demandez à un administrateur du studio de se connecter à [Game Manager](https://developer.playfab.com). 2. Accédez à la section **Users** du studio. 3. Sélectionnez **Add User** et entrez l'adresse courriel du compte Microsoft du développeur qui a besoin d'un accès aux API. 4. Sélectionnez **Microsoft** comme fournisseur d'authentification. 5. Attribuez à l'utilisateur un rôle qui inclut l'accès aux API Admin ou Server. Au minimum, l'utilisateur doit être **administrateur de titre** pour les titres sur lesquels il doit appeler des API. 6. Sélectionnez **Add user** pour envoyer l'invitation. Pour plus d'informations sur l'ajout d'utilisateurs et l'attribution de rôles, consultez [Authentification des comptes pour PlayFab Game Manager](/fr-CA/services/playfab/identity/dev-identity/authentication/aad-authentication). ## Obtenir un jeton d'accès Votre application est responsable de la connexion de l'utilisateur et de l'obtention d'un jeton d'accès délégué auprès d'Entra ID. Les exemples suivants montrent des flux de client public courants. ### Flux de navigateur interactif (recommandé pour les applications de bureau et console) Le flux de navigateur interactif ouvre une fenêtre du navigateur système pour la connexion. Il s'agit de l'option recommandée pour les applications de bureau et les outils de développement locaux. ```csharp theme={null} using Microsoft.Identity.Client; // Build an MSAL public client app. The client ID identifies your Entra app // registration; "common" lets users sign in from any Entra tenant or with a // personal Microsoft account. var app = PublicClientApplicationBuilder.Create("your-client-id") .WithAuthority("https://login.microsoftonline.com/common") .WithDefaultRedirectUri() .Build(); // The scope identifies the PlayFab API and the delegated permission ("plugin") // your app is requesting on behalf of the signed-in user. string[] scopes = ["448adbda-b8d8-4f33-a1b0-ac58cf44d4c1/plugin"]; AuthenticationResult result; try { // Try to get a token from MSAL's cache without prompting the user. // This succeeds on subsequent runs while the cached refresh token is valid. var accounts = await app.GetAccountsAsync(); result = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault()) .ExecuteAsync(); } catch (MsalUiRequiredException) { // No cached token, or it expired and can't be refreshed silently. // Open the system browser so the user can sign in interactively. result = await app.AcquireTokenInteractive(scopes) .WithUseEmbeddedWebView(false) .ExecuteAsync(); } // The access token is what you send to PlayFab in the Authorization header. string accessToken = result.AccessToken; ``` ### Code d'autorisation avec PKCE (recommandé pour les SPA) Le flux de code d'autorisation avec clé de preuve pour l'échange de code (PKCE) est l'approche recommandée pour les applications monopages. L'exemple JavaScript suivant utilise la bibliothèque d'authentification Microsoft (MSAL) : ```javascript theme={null} import { PublicClientApplication } from "@azure/msal-browser"; // MSAL config. clientId is your Entra app registration's Application (client) ID. // "common" lets users sign in from any tenant or with a personal account. // redirectUri must match a Single-page application redirect URI on the app registration. const msalConfig = { auth: { clientId: "your-client-id", authority: "https://login.microsoftonline.com/common", redirectUri: "http://localhost:3000" } }; const msalInstance = new PublicClientApplication(msalConfig); await msalInstance.initialize(); // loginPopup runs the auth code + PKCE flow in a pop-up window. The scope // asks Entra ID for a delegated token that PlayFab will accept. const loginResponse = await msalInstance.loginPopup({ scopes: ["448adbda-b8d8-4f33-a1b0-ac58cf44d4c1/plugin"] }); // Send this token to PlayFab in the Authorization header. const accessToken = loginResponse.accessToken; ``` ## Appeler les API PlayFab avec le jeton d'accès Incluez le jeton d'accès Entra ID dans l'en-tête `Authorization` comme jeton Bearer dans vos requêtes d'API PlayFab, au lieu d'utiliser l'en-tête `X-SecretKey`. ### Exemple de requête ```http theme={null} POST https://{titleId}.playfabapi.com/Server/GetPlayerProfile Content-Type: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi... { "PlayFabId": "ABCDEF1234567890" } ``` Vous ne pouvez pas utiliser à la fois `X-SecretKey` et `Authorization: Bearer` dans la même requête. Utilisez une seule méthode d'authentification par appel. ### Exemple C\# L'exemple suivant utilise la bibliothèque d'authentification Microsoft (MSAL) pour obtenir un jeton et appelle l'API `Server/GetTime`. Remplacez `your-client-id` par l'**Application (client) ID** de votre inscription d'application. ```csharp theme={null} using Microsoft.Identity.Client; using System.Net.Http.Headers; using System.Text; // PlayFab API endpoint. Every title gets its own subdomain on playfabapi.com. string titleId = "YOUR_TITLE_ID"; string host = $"{titleId}.playfabapi.com"; string url = $"https://{host}/Server/GetTime"; // MSAL configuration. // clientId - your Entra app registration's Application (client) ID. // authority - "common" lets any Entra tenant or personal Microsoft account sign in. // scopes - the PlayFab application ID + the "plugin" delegated permission. string clientId = "your-client-id"; string authority = "https://login.microsoftonline.com/common"; string[] scopes = ["448adbda-b8d8-4f33-a1b0-ac58cf44d4c1/plugin"]; // Build the MSAL public client. Public clients (desktop, CLI, mobile) don't use // a client secret; tokens are bound to the signed-in user instead. var app = PublicClientApplicationBuilder.Create(clientId) .WithAuthority(authority) .WithDefaultRedirectUri() .Build(); AuthenticationResult authResult; try { // Reuse a cached token if MSAL has one. Avoids prompting on every run. var accounts = await app.GetAccountsAsync(); authResult = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault()) .ExecuteAsync(); } catch (MsalUiRequiredException) { // First run, or the cached token expired. Open the system browser to sign in. authResult = await app.AcquireTokenInteractive(scopes) .WithUseEmbeddedWebView(false) .ExecuteAsync(); } // Call PlayFab. Replace X-SecretKey with an Authorization: Bearer header // containing the Entra ID access token. using var httpClient = new HttpClient(); var request = new HttpRequestMessage(HttpMethod.Post, url); request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", authResult.AccessToken); request.Content = new StringContent("{}", Encoding.UTF8, "application/json"); var response = await httpClient.SendAsync(request); var body = await response.Content.ReadAsStringAsync(); Console.WriteLine($"Status: {response.StatusCode}"); Console.WriteLine($"Response: {body}"); ``` ### Exemple Node.js L'exemple suivant utilise la bibliothèque `@azure/msal-node` pour obtenir un jeton et appelle l'API `Server/GetTime`. Remplacez `your-client-id` par l'**Application (client) ID** de votre inscription d'application. ```javascript theme={null} import { PublicClientApplication } from "@azure/msal-node"; import open from "open"; // PlayFab API endpoint for your title. const titleId = "YOUR_TITLE_ID"; const host = `${titleId}.playfabapi.com`; const url = `https://${host}/Server/GetTime`; // MSAL configuration. // clientId - your Entra app registration's Application (client) ID. // authority - "common" accepts any Entra tenant or personal Microsoft account. const msalConfig = { auth: { clientId: "your-client-id", authority: "https://login.microsoftonline.com/common", }, }; const pca = new PublicClientApplication(msalConfig); // Token request: // scopes - PlayFab application ID + the "plugin" delegated permission. // redirectUri - must match a Public client redirect URI on the app registration. // openBrowser - MSAL calls this to launch the user's default browser for sign-in. const tokenRequest = { scopes: ["448adbda-b8d8-4f33-a1b0-ac58cf44d4c1/plugin"], redirectUri: "http://localhost:3000", openBrowser: async (url) => { await open(url); }, successTemplate: "

Authentication complete. You can close this window.

", }; // Sign the user in and obtain a delegated access token. const authResult = await pca.acquireTokenInteractive(tokenRequest); // Call PlayFab with the token in the Authorization header instead of X-SecretKey. const response = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${authResult.accessToken}`, }, body: JSON.stringify({}), }); const body = await response.json(); console.log(`Status: ${response.status}`); console.log("Response:", JSON.stringify(body, null, 2)); ``` ## Actualisation des jetons Les jetons d'accès Entra ID ont une courte durée de vie (généralement de 60 à 90 minutes). Si vous utilisez MSAL, appelez `AcquireTokenSilent` (C#) ou vérifiez le cache de jetons avant chaque requête : MSAL gère l'actualisation automatiquement lorsqu'un jeton d'actualisation mis en cache est disponible. Si vous gérez les jetons manuellement, demandez un nouveau jeton à l'aide du même flux de connexion avant l'expiration du jeton actuel. Si un jeton expire pendant son utilisation, PlayFab renvoie une réponse `401 Unauthorized`. Votre application doit gérer cette erreur en demandant un nouveau jeton et en réessayant l'appel. ## Résolution des problèmes | Problème | Cause | Résolution | | - | - | - | | `401 Unauthorized` | Le jeton est expiré ou non valide | Reconnectez-vous et demandez un nouveau jeton | | `403 Forbidden` | L'utilisateur n'a pas le rôle requis sur le titre | Vérifiez l'appartenance au studio et le rôle d'administrateur de titre dans Game Manager | | `AADSTS50076: Need multifactor authentication` | Une stratégie d'accès conditionnel exige la MFA | Répondez à la demande de MFA et réessayez | | `AADSTS700016: Application not found` | L'ID client est incorrect ou l'application ne se trouve pas dans le locataire prévu | Vérifiez l'ID client et l'ID de locataire | ### Exemples de réponses d'erreur Une réponse `401 Unauthorized` de PlayFab lorsque le jeton Bearer est manquant, mal formé ou expiré ressemble à ceci : ```json theme={null} { "code": 401, "status": "Unauthorized", "error": "NotAuthenticated", "errorCode": 1074, "errorMessage": "Invalid \"Authorization\" header." } ``` Une réponse `403 Forbidden` de PlayFab lorsque l'utilisateur connecté est authentifié, mais ne dispose pas des autorisations d'administrateur sur le titre ressemble à ceci : ```json theme={null} { "code": 403, "status": "Forbidden", "error": "NotAuthorizedByTitle", "errorCode": 1191, "errorMessage": "Developer does not have admin permission for this title." } ``` ## Limites Les SDK PlayFab ne prennent pas en charge l'authentification Entra ID pour le moment. Pour appeler les API PlayFab avec un jeton Entra ID aujourd'hui, utilisez des appels HTTP directs et définissez vous-même l'en-tête `Authorization: Bearer `, comme le montrent les exemples [C#](#c-example) et [Node.js](#nodejs-example). La prise en charge dans les SDK est prévue pour une version ultérieure. ## Glossaire | Terme | Signification | | - | - | | **Locataire** | Un annuaire isolé dans Entra ID. Votre entreprise en a un; les comptes Microsoft personnels utilisent un locataire partagé appelé *consumers*. L'autorité `common` utilisée dans les exemples permet aux utilisateurs de se connecter à partir de n'importe quel locataire. | | **Inscription d'application** | L'enregistrement dans Entra ID qui décrit votre application cliente (son ID client, les URI de redirection autorisés, les autorisations d'API demandées). | | **Autorisation déléguée** | Une autorisation que votre application reçoit *au nom* d'un utilisateur connecté, plutôt que d'agir de son propre chef. | | **Client public** | Un client qui ne peut pas stocker un secret de façon sécuritaire : une application de bureau ou mobile, une interface de ligne de commande ou une application Web monopage. Les clients publics utilisent des flux comme le code d'autorisation avec PKCE ou le code d'appareil au lieu d'un secret client. | | **Étendue** | L'autorisation d'API que votre code demande à Entra ID. Pour PlayFab, l'étendue est `448adbda-b8d8-4f33-a1b0-ac58cf44d4c1/plugin`. | | **MSAL** | Bibliothèque d'authentification Microsoft (Microsoft Authentication Library). La bibliothèque cliente officielle qui implémente tous ces flux pour que vous n'ayez pas à construire manuellement les requêtes OAuth. | ## Voir aussi * [Gestion des clés secrètes](/fr-CA/services/playfab/live-service-management/gamemanager/secret-key-management) * [Authentification des comptes pour PlayFab Game Manager](/fr-CA/services/playfab/identity/dev-identity/authentication/aad-authentication) * [Rôles d'utilisateur PlayFab](/fr-CA/services/playfab/identity/dev-identity/permissions/playfab-user-roles) * [Stratégie d'accès aux API](/fr-CA/services/playfab/api-references/api-access-policy) * [Documentation Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/fundamentals/whatis) ## Related topics - [Authentification par compte Microsoft pour PlayFab](/fr-CA/services/playfab/identity/dev-identity/authentication/aad-authentication.md) - [Connexion de Grafana à Insights](/fr-CA/services/playfab/data-analytics/legacy/connectivity/connecting-grafana-to-insights.md) - [Créer une application Microsoft Entra ID pour PlayFab Insights](/fr-CA/services/playfab/data-analytics/legacy/connectivity/creating-AAD-app-for-insights.md) - [Demander un User Store ID pour l'authentification de service à service](/fr-CA/publishing/xstore-commerce/xstore-requesting-userstoreid.md) - [Intégration de place de marché - Microsoft Store](/fr-CA/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/microsoft.md)