Passer au contenu principal
Cet article explique comment appeler les services XBOX depuis un service de titre personnalisé à l’aide d’un jeton de sécurité XBOX (XSTS) : Cet article couvre les sections suivantes : Les services XBOX sont accessibles depuis les services de titre au moyen d’un accès de service à service (S2S), également appelé accès back-end à back-end. Cela permet de nouveaux scénarios de gameplay et d’interaction, comme des services de matchmaking personnalisés. Ces services peuvent utiliser des appels S2S pour créer et lire des informations de session multijoueur et des données de joueurs. Le modèle de requête RESTful pour appeler les points de terminaison des services XBOX est identique pour les clients et les services de titre. Toutefois, le chemin d’authentification est différent. Les services de titre nécessitent davantage d’étapes d’authentification avant de pouvoir appeler les services XBOX. Les sections suivantes décrivent le flux de ce chemin d’authentification permettant d’activer l’accès S2S pour votre service.

Configuration S2S

Cette section fournit une vue d’ensemble de l’accès des titres aux services XBOX par appels S2S. L’accès S2S n’est pas activé par défaut pour chaque titre. L’accès doit d’abord être configuré au niveau de l’éditeur et du titre dans Partner Center.

Configuration du certificat de partenaire commercial

Pour accéder aux services XBOX, un service de titre doit disposer d’informations d’identification enregistrées auprès des services XBOX. Un certificat de partenaire commercial (Business Partner Certificate) est utilisé pour cet accès. Ce certificat est un certificat X509 émis par l’autorité de certification (CA) des services XBOX. Le certificat de partenaire commercial est configuré au niveau de l’éditeur et pour tous les sandboxes au moyen de la page Web Services des services XBOX dans Partner Center. Pour connaître les étapes de configuration détaillées, consultez Configuration de l’authentification unique dans Partner Center.

Expiration du certificat de partenaire commercial

Comme les autres certificats, les certificats de partenaire commercial expirent. Ils doivent être mis à jour avant leur expiration. Actuellement, les certificats de partenaire commercial sont générés avec une durée de vie d’environ 18 mois à compter de leur date de création. À l’avenir, cette durée de vie pourra changer. Les certificats de partenaire commercial expirés ne fonctionnent plus après leur date d’expiration. Des erreurs se produisent lorsque vous tentez d’obtenir des jetons de service (jetons S) ou des jetons XSTS liés à ces certificats. Les développeurs doivent suivre la date d’expiration de tous les certificats de partenaire commercial utilisés et les renouveler au moyen de Partner Center avant leur expiration. Il est recommandé de définir un rappel dans le calendrier une semaine avant la date d’expiration d’un certificat de partenaire commercial afin d’en renouveler et d’en déployer un nouveau.

Configuration de l’accès aux services XBOX avec des certificats de partenaire commercial

Pour qu’un serveur disposant d’un certificat de partenaire commercial puisse accéder aux services XBOX, chaque titre doit accorder des droits d’accès au service web pour lequel le certificat a été généré. Cette configuration s’effectue par titre dans Partner Center. Pour plus d’informations, consultez Vue d’ensemble des stratégies d’accès.

Configuration S2S déléguée

Pour effectuer des appels S2S aux services XBOX pour le compte d’un utilisateur, un service doit déjà être configuré pour l’authentification de service et disposer d’une partie de confiance. Pour plus d’informations, consultez Authentification des services XBOX pour les services de titre. Pour l’accès aux appels S2S délégués, la définition du jeton de la partie de confiance doit également inclure la revendication DelegationToken. Cette revendication contient les informations dont XSTS a besoin pour émettre des jetons pour le compte de l’utilisateur. Le jeton de délégation d’un utilisateur expire 30 jours après son émission. Ce jeton ne doit être utilisé que tant que l’utilisateur est connecté ou que des requêtes pour cet utilisateur sont nécessaires. Les titres doivent supprimer les jetons de délégation dont ils n’ont plus besoin. Retour en haut de cet article.

Flux d’authentification de service

Le diagramme suivant illustre les trois étapes de l’authentification d’un service de titre auprès des services XBOX. Image d'un organigramme d'authentification d'un service de titre auprès des services XBOX.
  1. Le service de titre effectue d’abord une requête POST d’authentification auprès du XBOX Service Authentication Service (XSAS), en indiquant le sandbox, les clés de preuve et le type de jeton dans le corps de la requête. Le certificat de partenaire commercial obtenu précédemment doit être utilisé comme certificat TLS client. En cas de réussite, XSAS retourne un jeton S d’une durée de vie par défaut de deux semaines.
    XSAS : https://service.auth.xboxlive.com/service/authenticate
  2. Le jeton S peut ensuite être échangé contre un jeton d’autorisation appelé jeton X en effectuant une requête POST auprès de XSTS. Les paramètres suivants sont requis comme propriétés de la requête : le jeton S, l’ID du sandbox auquel vous essayez d’accéder et le nom de la partie de confiance cible.
    XSTS : https://xsts.auth.xboxlive.com/xsts/authorize
  3. Vous pouvez éventuellement ajouter la revendication DelegationToken à la requête si l’appel doit être effectué pour le compte de l’utilisateur pour lequel vous avez obtenu cette revendication. Dans ce scénario, le SandboxId fourni doit être accessible à l’utilisateur de la revendication DelegationToken. Grâce aux jetons X obtenus de cette façon, votre service peut effectuer des appels authentifiés à différents services XBOX.
Retour en haut de cet article.

Clés de preuve

L’utilisation de clés de preuve empêche une attaque de l’intercepteur (man-in-the-middle) qui permettrait à un attaquant de capturer des jetons et de rédiger des messages au nom du véritable propriétaire du jeton. Pour un exemple de code complet de génération de clés de preuve et de signatures, consultez l’exemple de console GameService disponible en téléchargement sur XBOX Developer Downloads. Plus précisément, lors de l’obtention d’un jeton de sécurité, l’appelant génère d’abord une paire de clés publique/privée. L’appelant conserve la clé privée et envoie la clé publique avec la demande de jeton de sécurité (comme expliqué plus loin dans la section Obtention d’un jeton de service de cet article). La clé publique est alors incorporée au jeton. Chaque fois que l’appelant envoie une requête à un service, il transmet le jeton au service et signe le message avec la clé privée. Seul l’appelant possède la clé privée. Le service qui reçoit le message vérifie la validité du jeton, puis valide la signature de la requête à l’aide de la clé publique contenue dans le jeton. Si la signature de la requête est validée, cela prouve que l’appelant possède la clé privée. En supposant que l’appelant protège sa clé privée, cela prouve que l’appelant est bien la partie qui a fourni la clé publique au service de jetons de sécurité. La clé elle-même est une JSON Web Key (JWK) telle que définie dans la spécification de l’Internet Engineering Task Force (IETF) disponible à l’adresse https://tools.ietf.org/html/draft-ietf-jose-json-web-key-08. L’URL, le chemin, la chaîne de requête, l’en-tête Authorization et l’horodatage sont toujours signés. Ils font donc implicitement partie de la stratégie de signature à utiliser pour signer la requête. Chaque service qui expose des points de terminaison d’authentification peut également exiger des en-têtes supplémentaires à inclure dans la stratégie de signature. Il peut aussi spécifier la taille maximale (en octets) du corps de la requête qui sera signé. Chaque service définit l’ensemble des algorithmes de signature qu’il prend en charge. La stratégie de signature se présente comme suit au format JSON.
Les clients (ici, votre service de titre) doivent connaître la stratégie de signature requise pour les points de terminaison qu’ils doivent appeler. Ils créent à partir de la requête un flux de données à signer (le processus exact est décrit aux étapes 1 à 7 ci-dessous), hachent ce flux de données à l’aide de l’algorithme Secure Hashing Algorithm 256 (SHA256), puis le chiffrent avec la clé privée pour produire une signature. La signature est transmise dans un en-tête HTTP et se compose des trois parties suivantes.
  1. La version de la stratégie de signature. Elle est exprimée sous la forme d’un entier de 4 octets dans l’ordre des octets réseau (big-endian).
  2. Une heure de fichier Windows de 64 bits dans l’ordre des octets réseau.
  3. Les octets de la signature obtenue.
Ces trois parties sont combinées en un seul flux d’octets et encodées sous forme de chaîne en base 64, envoyée avec la requête dans un en-tête supplémentaire : l’en-tête Signature. Comme la signature est transportée dans un en-tête HTTP, tout message incluant un hachage du corps doit être haché en mémoire avant que des octets du corps soient écrits dans le flux de la requête. La signature est calculée sur les octets réellement transmis. Elle doit être calculée après toute transformation du corps de la requête. Le processus exact de création du flux de données à signer est présenté ci-dessous. Toutes les données de type chaîne, comme les en-têtes et l’URL, sont encodées en ASCII. Le corps est un blob opaque et est signé tel quel. Les valeurs de ces éléments sont expliquées ci-dessous.
  1. La version de la stratégie, sous la forme d’un entier non signé de 4 octets dans l’ordre des octets réseau, suivie d’un octet nul.
  2. L’horodatage (issu de l’en-tête Signature) dans l’ordre des octets réseau, suivi d’un octet nul.
  3. La méthode HTTP, en majuscules (par exemple, GET ou POST), suivie d’un octet nul.
  4. Le chemin absolu et la chaîne de requête, suivis d’un octet nul.
  5. La valeur de l’en-tête Authorization (le cas échéant), suivie d’un octet nul.
  6. Les autres en-têtes spécifiés dans la stratégie de signature, chacun suivi d’un octet nul si vous ajoutez un en-tête. S’il n’y a pas d’en-têtes supplémentaires, aucun octet ne doit être ajouté.
  7. Soit N le nombre maximal d’octets du corps à signer, tel que spécifié par la stratégie de signature du point de terminaison à appeler. Soit M la taille du corps non compressé. Si M \> N, utilisez les N premiers octets du corps non compressé. Si M \<= N, utilisez l’intégralité du corps non compressé (sans remplissage). Un octet nul est ajouté à la fin (il doit être ajouté même en l’absence de corps de requête).
Chacun des éléments précédents est séparé par un octet nul (0x00) afin d’éviter toute ambiguïté liée à une concaténation sans séparateur. L’octet nul est utilisé, car la norme HTTP interdit l’utilisation de caractères non imprimables dans les en-têtes. Par conséquent, toute tentative d’insertion ou d’extension des données devrait inclure l’octet nul, ce qui rendrait la requête HTTP non valide. Le chemin absolu et la chaîne de requête sont obtenus à partir de l’URI de la requête signée. Si l’URI de la requête est « https://service.xbox.com/service1/foo?q0=v0&q1=v1\#frag, », le chemin absolu et la chaîne de requête sont « /service1/foo?q0=v0&q1=v1\#frag ». Le chemin absolu doit commencer par une barre oblique (/). Les en-têtes de la requête spécifiés dans la stratégie doivent être inclus dans la signature dans le même ordre que dans la stratégie de signature. L’en-tête Authorization est toujours signé. Si la stratégie spécifie un en-tête absent de la requête, il n’a pas à figurer dans la signature. Par exemple, si la stratégie spécifie les en-têtes \[ H~1~, H~2~, H~3~ \] et que la requête n’inclut que H~1~ et H~2~, H~3~ peut être omis. Cela est nécessaire si la stratégie globale spécifie des en-têtes comme Range, qui ne s’appliquent pas aux requêtes POST. Toutefois, si un en-tête est manquant, les octets nuls correspondants doivent tout de même être inclus. Cela s’applique également si aucun en-tête n’est spécifié. Le flux de données à signer inclurait deux octets nuls entre les en-têtes H~1~ et H~3~ si H~2~ était manquant. On peut aussi considérer les en-têtes manquants comme des chaînes vides. Retour en haut de cet article.

Obtention d’un jeton de service

Cette section détaille la requête, la réponse et la gestion des erreurs associées à l’obtention d’un jeton de service. Pour un exemple de code complet de demande et de gestion des jetons de service, consultez l’exemple de console GameService disponible en téléchargement sur XBOX Developer Downloads.

Requête de jeton de service

XSAS fournit le point de terminaison REST suivant pour gérer l’authentification de service. https://service.auth.xboxlive.com/service/authenticate Ce point de terminaison nécessite TLS 1.2 (ou version ultérieure) et un certificat de partenaire commercial valide utilisé comme certificat SSL client dans la requête. Si la connexion au point de terminaison est interrompue, cela résulte généralement de l’absence ou d’une mauvaise configuration des éléments précédents dans la requête. Votre service effectue une requête POST dont le corps respecte le contrat de données XSASRequest suivant.
La seule propriété requise dans le PropertyBag de XSASRequest est ProofKey. Il doit s’agir d’une JWK, comme indiqué dans la section Clés de preuve de cet article.
Mettez en cache ou conservez une trace de la clé de preuve associée à ce jeton S. Utilisez cette clé de preuve pour générer la signature des appels aux services XBOX effectués avec des jetons obtenus à l’aide du jeton S.
En outre, les en-têtes du tableau suivant doivent être inclus dans la requête. Voici le code d’un exemple de requête.
Assurez-vous que les points de courbe x et y ont une longueur paire lorsque vous les convertissez de la représentation décimale à la représentation hexadécimale. Sinon, la longueur de conversion risque d’être incorrecte et d’être rejetée par le service. Le format brut est celui dans lequel r et s sont simplement concaténés. Dans ce format, r et s doivent d’abord être représentés sous forme de séquences d’octets, selon une convention donnée (généralement big-endian), éventuellement avec quelques octets de remplissage de valeur 0x00. Cela garantit que les encodages de r et de s ont la même taille. Cette taille identique est importante pour que les vérificateurs sachent où diviser ces données. Le format brut est attendu à la place du format DER. Pour ce format brut, le remplissage 0x00 doit également être appliqué.

Réponse de jeton de service

Le contrat de données de la réponse est le suivant.

Gestion des erreurs du jeton de service

Si la signature de la clé de preuve n’est pas valide, le serveur retourne une erreur 403.
Pour que le canal SSL puisse être établi, la chaîne de certificats de confiance complète du certificat de partenaire commercial doit être installée sur le client. La chaîne de certificats est publiée. Vous pouvez télécharger les certificats appropriés en ouvrant le certificat de partenaire commercial, en sélectionnant l’onglet Chemin d’accès de certification, puis en affichant ou en téléchargeant les certificats individuels dont vous avez besoin.
Retour en haut de cet article.

Obtention d’un jeton XSTS pour les appels S2S

Cette section détaille la requête, la réponse et la gestion des erreurs associées à l’obtention d’un jeton X. Pour un exemple de code complet de demande, de gestion et d’utilisation des jetons XSTS pour les appels S2S, consultez l’exemple de console GameService disponible en téléchargement sur XBOX Developer Downloads. Les deux types de jetons XSTS suivants sont disponibles pour authentifier votre service auprès des services XBOX.
  • Jetons XSTS d’authentification de service : ne contiennent que l’identité de votre service et sont créés à l’aide du jeton de service généré. Ce jeton ne peut être utilisé que pour s’authentifier auprès des services de vérification de chaînes, de multijoueur et de comptes supprimés.
  • Jetons XSTS d’authentification déléguée : incluent une revendication d’utilisateur et sont requis pour s’authentifier auprès de la plupart des services XBOX et des services Microsoft Store.

Requête

Le service XSTS fournit le point de terminaison REST suivant pour gérer l’autorisation. https://xsts.auth.xboxlive.com/xsts/authorize Votre service effectue une requête POST dont le corps respecte le contrat de données XSTSRequest suivant.
[!NOTE] Pour obtenir un jeton XSTS d’authentification de service, vous ne fournissez que le jeton S. Pour un jeton XSTS d’authentification déléguée, vous incluez également la valeur DelegationToken. Elle contient l’identité de l’utilisateur pour le compte duquel vous effectuez les appels.

Propriété RelyingParty

Les jetons sont émis (et chiffrés) pour des parties de confiance spécifiques. Un service configuré pour une partie de confiance donnée ne peut consommer que les jetons émis pour cette partie de confiance. Par conséquent, selon les services XBOX que vous devez appeler, vous devrez peut-être récupérer différents jetons, en spécifiant chaque fois la partie de confiance appropriée pour laquelle vous avez besoin d’un jeton. Le tableau suivant indique la partie de confiance pour laquelle vous devez obtenir un jeton afin d’accéder à chacun des services XBOX. Il est également possible de récupérer un jeton pour une partie de confiance personnalisée spécifiée pour un point de terminaison de titre (par exemple, https://example.com/ ou rp://example.com/). Notez que les noms de parties de confiance personnalisées, contrairement à ceux des services XBOX, se terminent par une barre oblique (/).

Propriété PropertyBag

Le contrat de données PropertyBag de XSTS est le suivant.
La propriété ServiceToken contient la valeur Token de la réponse de XSAS. La propriété SandboxId contient le nom du sandbox auquel vous essayez d’accéder, par exemple « ABCD.1 ». Le sandbox principal de tous les utilisateurs et contenus commerciaux s’appelle « RETAIL ». (Notez que le nom est en majuscules; il respecte la casse.) Vous pouvez toujours le définir dynamiquement en recherchant la revendication de sandbox dans le jeton XSTS côté client utilisé pour authentifier le client auprès de votre service.
Lorsque le certificat de partenaire commercial que vous utilisez a été émis pour un sandbox spécifique, vous devez utiliser la même valeur ici.
La propriété DelegationToken est facultative dans ce scénario et ne doit être utilisée que si vous appelez les services XBOX pour le compte de l’utilisateur. Vous devez alors y inclure la valeur de la revendication DelegationToken extraite d’un jeton X que vous avez précédemment reçu d’une console XBOX One ou d’un autre client. La revendication DelegationToken peut être ajoutée à vos jetons XSTS comme indiqué dans la section Configuration S2S déléguée plus haut dans cet article. La propriété UserTokens ne doit être utilisée que si vous appelez les services XBOX depuis un site web dont les serveurs web sont authentifiés avec un certificat de partenaire commercial, et dont l’utilisateur est authentifié auprès de votre site web à l’aide du flux OAuth du compte Microsoft pour l’authentification des utilisateurs. Dans ce cas, la propriété UserTokens doit être un tableau à un élément contenant le jeton obtenu en échangeant, auprès du service XBOX Authentication Service for Users (XASU), le jeton d’accès de l’utilisateur récupéré depuis le compte Microsoft contre un jeton utilisateur (U).

En-têtes

Exemple de requête de jeton XSTS d’authentification de service

Voici le code d’un exemple de requête.

Exemple de requête de jeton XSTS d’authentification déléguée

Voici le code d’un exemple de requête.

Réponse de jeton XSTS d’authentification déléguée

Le contrat de données de la réponse XSTS est le suivant.
Si aucune propriété DelegationToken ou UserTokens n’a été spécifiée dans la requête, la réponse ne contient aucune revendication d’affichage. Sinon, la propriété DisplayClaims de la réponse contient un ensemble d’informations sur l’utilisateur, telles que définies dans le contrat de données précédent.
  • Agegroup : peut être Child, Teen ou Adult.
  • Gamertag : le gamertag de l’utilisateur.
  • Privileges : l’ensemble des privilèges dont dispose l’utilisateur. (Pour plus d’informations sur les privilèges, consultez Revendications des jetons de sécurité des services XBOX.)
  • Xuid : le XUID de l’utilisateur.
    [!IMPORTANT] Vous ne devez pas stocker le XUID de l’utilisateur dans vos bases de données sans le consentement exprès de Microsoft (obtenu par l’intermédiaire de votre gestionnaire de compte développeur (DAM)).
  • UserHash : l’identificateur unique de l’utilisateur à utiliser lors de la construction des en-têtes Authorization des requêtes adressées aux services XBOX. Pour plus d’informations, consultez Appel des points de terminaison des services XBOX.
Notez que toutes les parties de confiance n’exposent pas toutes les DisplayClaims. Pour recevoir tous les membres de revendication, utilisez le nom de partie de confiance https://xboxlive.com. Voici le code d’un exemple de réponse pour la partie de confiance « https://xboxlive.com ».

Gestion des erreurs de l’authentification déléguée

Si la demande de jeton XSTS est rejetée, la réponse contient parfois des données indiquant la raison du rejet.
Les propriétés Identity et Message peuvent être ignorées. La propriété XErr peut prendre les valeurs suivantes. Retour en haut de cet article.

Appel des points de terminaison des services XBOX

Cette section décrit comment effectuer l’authentification pour appeler les services XBOX. L’obtention de jetons X auprès du service XSTS a pour objectif d’effectuer des appels authentifiés à différents services XBOX. Pour que les appels réussissent, un en-tête Authorization et un en-tête Signature doivent être spécifiés lors de l’appel de ces services. L’en-tête Authorization présente la structure suivante. authorization: XBL3.0 x=<userHash>;<XToken> La partie userHash de cet en-tête doit être définie comme suit.
  • Si une propriété DelegationToken ou UserTokens a été définie dans la requête XSTS, la propriété UserHash de l’élément DisplayClaims de la réponse XSTS doit être utilisée.
    Exemple :
    XBL3.0 x=1077552597660441275;eyJlbmMiO...(truncated)
  • Si seul ServiceToken a été spécifié dans la requête XSTS, la propriété UserHash doit être définie sur un trait d’union (-).
    Exemple :
    XBL3.0 x=-;eyJlbmMiO...(truncated)
La partie XToken de cet en-tête doit être définie sur la valeur de l’élément Token de la réponse XSTS. Notez que les jetons X ont une date et une heure d’expiration, spécifiées dans l’élément NotAfter de la réponse XSTS. Si un jeton expiré est utilisé pour appeler les services XBOX, la requête est refusée avec un état HTTP 401, et l’en-tête www-authenticate de la réponse indique que le jeton a expiré. Les services XBOX exigent également une signature du message calculée conformément à la spécification décrite dans la section Clés de preuve de cet article. Lorsque vous appelez les services XBOX depuis votre service, assurez-vous de réutiliser les jetons X jusqu’à leur expiration au lieu de demander un nouveau jeton à chaque requête. Regroupez également les appels lorsque cela est possible, par exemple les appels sociaux, afin d’augmenter le débit et d’éviter la limitation des requêtes. Pour des informations spécifiques sur les appels S2S aux services multijoueur des services XBOX, consultez Gestion des sessions multijoueur de service à service. Retour en haut de cet article.

Voir aussi

Référence RESTful des services XBOX Gestion des sessions multijoueur de service à service Obtention de la liste des comptes supprimés depuis un service API du service Microsoft Store
Dernière modification le 8 octobre 2026