L’authentification Entra ID est une alternative aux clés secrètes de développeur pour les appels aux API Admin, Server et à certaines 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é pouvant ê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.
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 durée de vie courte et sont limités à l’utilisateur connecté.
- Responsabilité individuelle : chaque appel d’API est lié à une identité d’utilisateur spécifique, ce qui permet d’auditer facilement qui a fait quoi.
- Accès conditionnel : votre organisation peut appliquer des stratégies Entra ID telles que des restrictions d’adresses IP, l’authentification multifacteur (MFA) et des contrôles de conformité des appareils.
Fonctionnement de l’authentification Entra ID
Si vous n’avez jamais utilisé Microsoft Entra ID, il s’agit du service d’identité cloud de Microsoft, le même système d’identité que celui qui prend en charge Microsoft 365, les comptes développeur XBOX et Azure. Au lieu que PlayFab délivre à votre studio une clé secrète de longue durée, votre outil demande à Entra ID de connecter un développeur et de renvoyer un jeton d’accès de courte durée. PlayFab fait confiance aux jetons émis par Entra ID pour les utilisateurs membres de votre studio. Trois parties sont impliquées :- 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 CLI, 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-ac58cf44d4c1et expose une autorisation déléguée appeléeplugin. Lorsque votre code demande l’étendue448adbda-b8d8-4f33-a1b0-ac58cf44d4c1/plugin, Entra ID émet un jeton que PlayFab accepte.
- Votre code utilise la bibliothèque d’authentification Microsoft (MSAL) pour lancer une connexion, généralement une fenêtre contextuelle de navigateur ou une invite de code d’appareil.
- L’utilisateur se connecte avec son identité Microsoft et consent à ce que votre application appelle PlayFab en son nom.
- MSAL renvoie un jeton d’accès (un JWT) et met en cache un jeton d’actualisation afin que les appels suivants puissent ignorer l’invite.
- Votre code envoie le jeton dans l’en-tête
Authorization: Bearer <token>de chaque requête PlayFab. - PlayFab valide le jeton, l’associe à l’utilisateur de studio correspondant et autorise l’appel en fonction du rôle de cet utilisateur.
Prérequis
- Un compte Microsoft adossé à 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.
- 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 title admin. Pour plus d’informations sur les rôles, consultez Rôles d’utilisateur PlayFab.
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.- Connectez-vous au portail Azure.
- Recherchez et sélectionnez App registrations, puis sélectionnez New registration.
-
Entrez un nom pour votre application (par exemple,
PlayFab API Client). - Sous Supported account types, sélectionnez l’option qui correspond aux exigences de votre organisation. Pour une flexibilité 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.
-
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 utilisant le flux de code d’appareil, sélectionnez Public client/native (mobile & desktop) et entrez
http://localhost.
- Pour une application monopage (SPA), sélectionnez Single-page application (SPA) et entrez votre URI de redirection (par exemple,
- 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.
-
Ajoutez l’autorisation d’API PlayFab à votre inscription d’application :
- Dans le portail Azure, accédez à votre inscription d’application et sélectionnez API permissions.
- Sélectionnez Add a permission > APIs my organization uses.
- Recherchez l’ID d’application PlayFab
448adbda-b8d8-4f33-a1b0-ac58cf44d4c1et sélectionnez-le. - Sélectionnez Delegated permissions, cochez l’autorisation plugin, puis 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 se concentre 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.
Configurer l’accès au studio PlayFab
PlayFab valide les jetons Entra ID par rapport à l’appartenance au studio. L’utilisateur appelant doit être ajouté au studio PlayFab et se voir attribuer le rôle approprié.- Demandez à un administrateur du studio de se connecter à Game Manager.
- Accédez à la section Users du studio.
- Sélectionnez Add User et entrez l’adresse e-mail du compte Microsoft du développeur qui a besoin d’un accès aux API.
- Sélectionnez Microsoft comme fournisseur d’authentification.
- Attribuez à l’utilisateur un rôle qui inclut l’accès aux API Admin ou Server. L’utilisateur doit au minimum être title admin des titres sur lesquels il doit appeler des API.
- Sélectionnez Add user pour envoyer l’invitation.
Obtenir un jeton d’accès
Votre application est chargée de connecter l’utilisateur et d’obtenir un jeton d’accès délégué auprès d’Entra ID. Les exemples suivants présentent 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.Code d’autorisation avec PKCE (recommandé pour les SPA)
Le flux de code d’autorisation avec Proof Key for Code Exchange (PKCE) est l’approche recommandée pour les applications monopages. L’exemple JavaScript suivant utilise la bibliothèque d’authentification Microsoft (MSAL) :Appeler les API PlayFab avec le jeton d’accès
Incluez le jeton d’accès Entra ID dans l’en-têteAuthorization en tant que jeton Bearer dans vos requêtes d’API PlayFab, au lieu d’utiliser l’en-tête X-SecretKey.
Exemple de requête
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’APIServer/GetTime. Remplacez your-client-id par l’Application (client) ID de votre inscription d’application.
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.
Actualisation des jetons
Les jetons d’accès Entra ID ont une durée de vie courte (généralement 60 à 90 minutes). Si vous utilisez MSAL, appelezAcquireTokenSilent (C#) ou vérifiez le cache de jetons avant chaque requête : MSAL gère automatiquement l’actualisation 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 en cours d’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
Exemples de réponses d’erreur
Une réponse401 Unauthorized de PlayFab lorsque le jeton Bearer est manquant, mal formé ou expiré se présente comme suit :
403 Forbidden de PlayFab lorsque l’utilisateur connecté est authentifié mais ne dispose pas des autorisations d’administrateur sur le titre se présente comme suit :
Limitations
Les SDK PlayFab ne prennent actuellement pas en charge l’authentification Entra ID. 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êteAuthorization: Bearer <token>, comme indiqué dans les exemples C# et Node.js. La prise en charge dans les SDK est prévue dans une version ultérieure.
