Passer au contenu principal
Cette rubrique explique comment utiliser l’authentification des services XBOX avec un service de titre personnalisé. Outre les services XBOX, les jetons XSTS peuvent également être utilisés pour l’authentification et l’autorisation des services de titre personnalisés. Les services web personnalisés peuvent utiliser les revendications émises par les services XBOX et contenues dans un jeton XSTS partenaire. Un jeton XSTS partenaire contient un ensemble de revendications définies spécifiquement pour le service cible. Les revendications du jeton sont émises et signées par les services XBOX ; elles sont donc nettement plus inviolables que n’importe quelle donnée du client de jeu. Les services de titre personnalisés doivent utiliser les revendications du jeton XSTS pour valider l’identité et l’autorité de l’utilisateur ou de l’appareil. Parmi les revendications d’un jeton XSTS partenaire figurent par exemple le gamertag, les privilèges du joueur, la tranche d’âge et le Partner XUID (pXUID), unique pour le joueur auprès de l’éditeur de ce titre. Pour obtenir la liste complète des revendications, consultez Revendications des jetons de sécurité des services XBOX. Les services XBOX construisent le jeton XSTS partenaire de façon qu’il ne soit lisible que par un service web personnalisé et opaque pour un client. Pour ce faire, le jeton est un JSON Web Token (JWT) chiffré conforme à la norme RFC 7519. Le jeton est protégé par un chiffrement asymétrique qui utilise des clés de chiffrement privée et publique. Ainsi, seul le service web détenant la clé privée peut déchiffrer et inspecter le jeton XSTS partenaire. Chaque configuration de jeton est effectuée et disponible au niveau de l’éditeur dans Partner Center. Un développeur spécifie le nom du jeton, les revendications disponibles, le certificat de chiffrement (clés) et la durée d’expiration du jeton. Cette configuration concerne une partie de confiance spécifique. L’utilisation des jetons XSTS partenaires est limitée aux connexions HTTPS pour garantir la sécurité et est définie au moyen de la configuration Webservice Endpoint dans Partner Center. Cette configuration spécifie l’association entre le jeton XSTS partenaire et les URI du service web. Contrairement à la configuration de la partie de confiance, les Webservice Endpoints sont configurés par titre dans Partner Center.

​
Configuration de la partie de confiance

Pour utiliser des services web personnalisés, un titre doit d’abord effectuer la configuration de l’authentification unique dans Partner Center. Pour plus d’informations, consultez Configurer une partie de confiance. La partie de confiance est configurée au niveau de l’éditeur et pour tous les sandboxes. La bonne pratique consiste à utiliser, dans la mesure du possible, les mêmes configurations de partie de confiance pour un même service de titre (sur différents titres).

​
Configuration du Webservice Endpoint

En plus de la configuration de la partie de confiance, un point de terminaison de service doit être configuré dans Partner Center pour qu’un service de titre puisse utiliser des jetons XSTS partenaires. Pour plus d’informations, consultez Services web. Les points de terminaison des services web sont configurés au niveau du titre dans la configuration globale DefaultNsal. DefaultNsal est le seul type de configuration pour les titres actuels. Les titres configurés précédemment peuvent utiliser d’autres types de configuration reflétant d’autres environnements, comme CertificationNsal et RetailNsal. Pour simplifier la configuration, ces types de configuration ne sont pas disponibles pour les nouveaux titres.

​
Certificats SSL des services web

Tous les points de terminaison des services web doivent utiliser HTTPS et des certificats SSL émis par des autorités de certification (CA) approuvées. Ces certificats ne doivent pas être spécifiés dans la configuration du point de terminaison du service web. Pour le développement et les tests, les titres peuvent utiliser des certificats SSL auto-signés, mais cela n’est pas recommandé si un certificat racine approuvé peut être utilisé. La communication SSL auto-signée n’est pas approuvée par défaut sur la console XBOX. La connexion HTTPS échoue, sauf si le certificat est ajouté à la définition du Webservice Endpoint dans la page Single Sign-on de votre titre dans Partner Center. Pour obtenir la liste des autorités de certification reconnues, consultez Liste des participants - Programme de certificats racines approuvés Microsoft dans la documentation sur la sécurité. Les services peuvent également obtenir un certificat SSL approuvé gratuit auprès d’organisations comme letsencrypt.org.

​
Récupération du jeton et flux de connexion

Tous les points de terminaison des services de titre doivent exiger un jeton XSTS partenaire pour l’authentification et l’autorisation. Sans ces informations, la communication avec le service doit être rejetée. Pour les services web, le jeton XSTS partenaire et l’identification de l’utilisateur (hachage de l’utilisateur) doivent être inclus dans l’en-tête Authentication de la requête. Pour des informations détaillées sur la structure de ces en-têtes, consultez Jetons de sécurité des services XBOX (jetons XSTS). Pour les services TCP/UDP sécurisés, le jeton XSTS partenaire et l’identification de l’utilisateur (hachage de l’utilisateur) doivent être inclus dans le message initial d’autorisation ou de négociation (handshake). Sans ces informations, la communication avec le service doit être rejetée. Pour ces connexions, un espace réservé reflétant le domaine du service peut être spécifié comme URI du Webservice Endpoint.

​
Obtention d’un jeton XSTS partenaire sur le client et envoi de la requête HTTPS

Les données du jeton XSTS partenaire et de l’en-tête de signature sont obtenues par le client de jeu au moyen de l’API XUserGetTokenAndSignatureUtf16Async, selon le flux suivant.
  1. Appelez XUserGetTokenAndSignatureUtf16Async sur l’utilisateur actuel. Incluez dans l’appel d’API l’URL du service et (le cas échéant) les en-têtes personnalisés ou le corps du message. L’API récupère un jeton XSTS et une signature de message à utiliser avec le point de terminaison cible ou le service XBOX.
  2. Récupérez le jeton XSTS et la signature au moyen de XUserGetTokenAndSignatureUtf16Result à partir du résultat asynchrone. XUserGetTokenAndSignatureUtf16Result renvoie un jeton XSTS chiffré. Les titres doivent traiter le jeton renvoyé comme des données opaques. Les données du jeton ne doivent pas être écrites sur disque ni mises en cache dans l’espace du titre au-delà de l’appel de service suivant. La mise en cache des jetons est gérée pour vous par XUserGetTokenAndSignatureUtf16Async.
  3. Créez une requête HTTPS vers votre point de terminaison cible à l’aide de Microsoft Windows HTTP Services (WinHTTP), du jeton XSTS et des valeurs de signature. Tous les appels HTTPS doivent être effectués au moyen de l’API WinHTTP, en ajoutant la valeur du jeton XSTS à l’en-tête Authentication et la valeur de signature à l’en-tête Signature.
Pour les services TCP/UDP sécurisés, le même flux est utilisé, avec les modifications suivantes.
  • Au lieu de l’URL d’appel du service, le titre spécifie l’URI d’espace réservé du service.
  • Les données d’authentification sont utilisées lors de l’autorisation ou de la négociation initiale de la connexion TCP/UDP.

​
Traitement des jetons XSTS partenaires sur le serveur

Une fois le jeton XSTS partenaire reçu par un service de titre, celui-ci doit analyser et déchiffrer le jeton, puis en valider l’authenticité. Pour plus de détails sur l’analyse et la validation d’un jeton XSTS, consultez Jetons de sécurité des services XBOX (jetons XSTS). Les développeurs de services sont également vivement encouragés à consulter et à tester l’exemple Game Service et la présentation Xfest 2019 XSTS Auth and Server to Server Made Easy. L’exemple comprend une bibliothèque de services complète avec la gestion des jetons.

​
Authentification et autorisation

Une fois qu’un jeton a été analysé, déchiffré et vérifié, le service peut faire confiance à ses revendications. Pour obtenir la liste de toutes les revendications des jetons XSTS, consultez Revendications des jetons de sécurité des services XBOX. Le service doit d’abord utiliser ces revendications pour l’authentification et l’autorisation au niveau du service. Les informations contenues dans un jeton XSTS partenaire doivent toujours être considérées comme faisant autorité. Les appels de service n’ont pas besoin de dupliquer ces informations dans d’autres parties de la requête. Une attention particulière doit être portée à l’identité de l’utilisateur. Elle doit toujours être validée au moyen d’une revendication du jeton XSTS et ne doit pas être utilisée pour la requête de service sans validation provenant d’autres sources. Pour identifier un utilisateur à des fins d’authentification, un service de titre dispose de deux options.
  • La revendication /user/pXUID (ptx). Pour tous les scénarios qui ne nécessitent une identité que pour la liaison de comptes, le Partner XUID (pXUID) doit être utilisé. Cette revendication expose un identificateur unique du compte des services XBOX de l’utilisateur auprès de l’éditeur actuel.
  • La revendication /user/XID. Pour tous les scénarios dans lesquels un service doit renvoyer l’identité de l’utilisateur ou effectuer des appels de service à service aux services XBOX, le XUID de l’utilisateur est nécessaire. Parmi ces services figurent par exemple les services de classement ou de matchmaking personnalisés, ou les services qui valident des achats au moyen d’appels aux services XBOX.
Les services de titre doivent être autorisés à activer le XUID dans le jeton XSTS partenaire et à stocker des informations de XUID. Collaborez avec votre Developer Partner Manager pour suivre ce processus. En revanche, l’utilisation du pXUID ne nécessite ni examen de sécurité ni autorisation supplémentaires. Bien que le gamertag soit disponible dans les revendications du jeton, il ne doit jamais être utilisé comme identificateur unique d’un utilisateur. Le gamertag peut changer ; il ne peut donc être utilisé qu’à des fins d’affichage temporaire ou de mise en cache. À des fins d’autorisation, vous pouvez obtenir les privilèges des services XBOX d’un utilisateur au moyen de la revendication /user/privileges. Ces privilèges sont identiques à ceux exposés sur les services XBOX et doivent être vérifiés pour l’accès au service. Si un utilisateur ne dispose pas de droits d’accès suffisants, le service doit renvoyer un code d’erreur HTTP/401. Après la validation de l’identité et des privilèges de l’utilisateur, les services peuvent utiliser d’autres revendications du jeton partenaire pour obtenir davantage d’informations sur l’utilisateur et l’appareil pour la logique du service.
Les PXUID sont limités au partenaire commercial sélectionné lors de la création de votre partie de confiance dans Partner Center. Si vous utilisez des jetons X pour plusieurs parties de confiance, celles-ci doivent partager le même partenaire commercial pour que les valeurs PXUID correspondent. Pour plus d’informations sur la configuration du partenaire commercial et de la partie de confiance, consultez Configuration des services web dans Partner Center.

​
Expiration et actualisation des jetons

Un jeton XSTS est valide pendant une durée spécifique configurée dans la partie de confiance correspondante dans Partner Center. Le délai d’expiration par défaut d’un jeton XSTS est de quatre heures. Chaque jeton contient un horodatage que le service doit vérifier avant d’accepter les revendications du jeton. Si un jeton expiré est présenté au service personnalisé, celui-ci doit renvoyer une erreur HTTP/401. Comme XUserGetTokenAndSignatureUtf16Async gère côté client l’expiration et la mise en cache des jetons XSTS, il doit être appelé avant chaque envoi d’une requête à vos services de jeu. L’API garantit que le titre reçoit toujours un jeton valide. Un titre ne doit pas mettre les jetons en cache par un autre moyen.
Dernière modification le 8 octobre 2026