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.
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-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 au moyen d’une fenêtre contextuelle de navigateur ou d’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 futurs puissent éviter 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 du studio correspondant et autorise l’appel en fonction du rôle de cet utilisateur.
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.
- 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.
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 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.
-
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.
- 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 de l’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 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.
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é.- 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 courriel 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. Au minimum, l’utilisateur doit être administrateur de titre pour les 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 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.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) :Appeler les API PlayFab avec le jeton d’accès
Incluez le jeton d’accès Entra ID dans l’en-têteAuthorization comme 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 courte durée de vie (généralement de 60 à 90 minutes). Si vous utilisez MSAL, appelezAcquireTokenSilent (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
Exemples de réponses d’erreur
Une réponse401 Unauthorized de PlayFab lorsque le jeton Bearer est manquant, mal formé ou expiré ressemble à ceci :
403 Forbidden de PlayFab lorsque l’utilisateur connecté est authentifié, mais ne dispose pas des autorisations d’administrateur sur le titre ressemble à ceci :
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êteAuthorization: Bearer <token>, comme le montrent les exemples C# et Node.js. La prise en charge dans les SDK est prévue pour une version ultérieure.
