Solicitar uma ID da Store do Usuário com X-tokens ou OAuth 2.0

Este artigo descreve como seu serviço pode gerar IDs da Store do Usuário diretamente, sem trocar tokens de acesso e chaves pelo cliente do jogo. Essa abordagem é útil para:

Experiências em que não há um cliente do jogo no fluxo
Vincular a conta XBOX do usuário à conta do usuário no seu próprio serviço
Jogos e serviços que já usam autenticação com Tokens de Segurança do XBOX (XSTS ou X-tokens) para chamadas de cliente para serviço e de serviço para serviço

Para obter informações sobre IDs da Store do Usuário em geral, consulte Solicitando uma ID da Store do Usuário para autenticação de serviço para serviço.

Requisito de X-token

Esse processo requer o uso de um X-Token de Autenticação Delegada para identificar o usuário que a ID da Store do Usuário representa. Para obter mais informações sobre X-Tokens de Autenticação Delegada e como criá-los, consulte a documentação “Chamadas de serviço do título para os XBOX services”.

Requisitos do OAuth 2.0 para gerar as IDs da Store do Usuário

Se o seu serviço usa OAuth para que o usuário entre com a conta Microsoft (MSA), os seguintes itens são necessários:

O usuário deve ter uma identidade XBOX vinculada à conta Microsoft, pois as credenciais OAuth precisam ser trocadas por um X-token.
O escopo OAuth que você solicita deve incluir xboxlive.signin e xboxlive.offline_access para garantir o consentimento adequado do usuário para esse fluxo e a capacidade de recuperar o X-token necessário.

Para obter mais informações sobre como usar a entrada nos XBOX services com OAuth no seu serviço, consulte a documentação “Entrada nos XBOX services para sites de títulos”.

Etapas ao usar credenciais OAuth 2.0

Com o OAuth, você obtém o consentimento do usuário e troca as credenciais OAuth por um X-token na sua terceira parte confiável. Depois disso, continue com o mesmo fluxo em Etapas ao usar X-Tokens. Resumo do fluxo para trocar credenciais OAuth por um X-token:

Obtenha o código de autorização OAuth 2.0
Troque o código de autorização por um token RPS (também chamado de token de acesso da conta Microsoft)
Troque o token RPS por um Token de Usuário do XBOX
Troque o Token de Usuário do XBOX por um X-Token na sua própria Terceira Parte Confiável
Use o X-token em Etapas ao usar X-Tokens.

Para obter os detalhes completos da implementação, consulte a documentação “Entrada nos XBOX services para sites de títulos”.

Etapas ao usar X-Tokens

Depois de ter um X-token que identifica o usuário para a sua terceira parte confiável, use a declaração DelegationToken dele para criar um X-token de Autenticação Delegada. O X-token inicial pode vir do cliente do jogo ou do fluxo OAuth 2.0. Resumo do fluxo para criar um X-token de Autenticação Delegada:

Extraia a declaração DelegationToken (dlt) do X-token do usuário.
Obtenha um Token de Serviço do serviço XSAS usando seu certificado de Parceiro Comercial.
Troque o DelegationToken, o Token de Serviço e a Terceira Parte Confiável de destino (consulte a tabela) por um X-token de Autenticação Delegada.

Para obter os detalhes completos da implementação de como criar X-tokens de Autenticação Delegada, consulte a documentação “Chamadas de serviço do título para os XBOX services”. Na etapa 3, a Terceira Parte Confiável que você usa depende de você estar gerando uma ID de Coleções do Usuário ou uma ID de Compra do Usuário para o usuário:

Tipo de ID da Store do Usuário	Terceira Parte Confiável do X-token de Autenticação Delegada	URI para criar a ID da Store do Usuário
ID de Coleções do Usuário (`UserCollectionsId`)	`http://licensing.xboxlive.com`	`https://collections.mp.microsoft.com/v7.0/beneficiaries/me/keys`
ID de Compra do Usuário (`UserPurchaseId`)	`http://mp.microsoft.com/`	`https://purchase.mp.microsoft.com/v7.0/users/me/keys`

Solicitação

Depois de obter o X-token de Autenticação Delegada, solicite a ID da Store do Usuário usando o URI correspondente ao serviço que você está chamando.

Sintaxe da solicitação

Método	URI da solicitação
`POST`	`collections.mp.microsoft.com/v7.0/beneficiaries/me/keys`
`POST`	`purchase.mp.microsoft.com/v7.0/users/me/keys`

Cabeçalho da solicitação

Cabeçalho	Tipo	Descrição
`Authorization`	`string`	Obrigatório. X-token de Autenticação Delegada no formato `XBL3.0 x=[User Hash];[Token]`
`Host`	`string`	Deve corresponder ao host do URI que está sendo chamado
`Content-Length`	`number`	O comprimento do corpo da solicitação.
`Content-Type`	`string`	Especifica o tipo de solicitação e resposta. Atualmente, o único valor com suporte é `application/json`.

Corpo da solicitação

Parâmetro	Tipo	Descrição	Obrigatório
`serviceTicket`	`string`	O Token de Acesso de Coleções ou o Token de Acesso de Compra do seu serviço, de acordo com o URI que você está chamando. Para obter informações sobre como criar esses tokens de acesso, consulte Entendendo os diferentes tokens e URIs de público.	Sim
`publisherUserId`	`string`	Valor opcional carimbado na ID da Store do Usuário para seu próprio acompanhamento.	Não

Exemplo de solicitação

POST https://collections.mp.microsoft.com/v7.0/beneficiaries/me/keys HTTP/1.1
Authorization: XBL3.0 x=13178812777611882182;eyJ...
Content-Length: 1352
Content-Type: application/json;
Host: collections.mp.microsoft.com
 
{
    "serviceTicket": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn...",
    "publisherUserId": "CustomPublisherUserId"
}

Resposta

Corpo da resposta

Parâmetro	Tipo	Descrição	Obrigatório
`key`	`string`	ID da Store do Usuário que pode ser usada para autenticação de serviço para serviço com os serviços da Microsoft Store.	Sim

Exemplo de resposta

HTTP/1.1 200 OK
Date: Wed, 23 Mar 2022 23:06:25 GMT
Content-Type: application/json; 
Content-Length: 1716
MS-CorrelationId: dd5be303-f9a0-408a-bd01-e8c63afa721a
MS-RequestId: 0b9c8e5e-dfdd-4cf8-bfbe-93a5be3a7f48
MS-CV: rqFUH3gA+UOmTyXe.0

{"key":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjY..."}

Confira também

Gerenciar produtos a partir dos seus serviços Autenticando seu serviço com as APIs da Microsoft Store Chamadas de serviço do título para os XBOX services Entrada nos XBOX services para sites de títulos Renovando uma chave de ID da Store do Usuário Biblioteca Microsoft.StoreServices Exemplo do Microsoft.StoreServices

Porting

Build Paths

Solicitar uma ID da Store do Usuário com X-tokens ou OAuth 2.0

Requisito de X-token

Requisitos do OAuth 2.0 para gerar as IDs da Store do Usuário

Etapas ao usar credenciais OAuth 2.0

Etapas ao usar X-Tokens

Solicitação

Sintaxe da solicitação

Cabeçalho da solicitação

Corpo da solicitação

Exemplo de solicitação

Resposta

Corpo da resposta

Exemplo de resposta

Confira também

​Requisito de X-token

​Requisitos do OAuth 2.0 para gerar as IDs da Store do Usuário

​Etapas ao usar credenciais OAuth 2.0

​Etapas ao usar X-Tokens

​Solicitação

​Sintaxe da solicitação

​Cabeçalho da solicitação

​Corpo da solicitação

​Exemplo de solicitação

​Resposta

​Corpo da resposta

​Exemplo de resposta

​Confira também

Requisito de X-token

Requisitos do OAuth 2.0 para gerar as IDs da Store do Usuário

Etapas ao usar credenciais OAuth 2.0

Etapas ao usar X-Tokens

Solicitação

Sintaxe da solicitação

Cabeçalho da solicitação

Corpo da solicitação

Exemplo de solicitação

Resposta

Corpo da resposta

Exemplo de resposta

Confira também