Xsolla-logo

Visão geral

Esta seção descreve as chamadas de API para trabalhar com Login. Configure seu projeto Login na Conta de Distribuidor antes de enviar solicitações.

Baixar definição de API

Você pode baixar a definição de API em dois formatos:

Glossário

Você tem acesso aos seguintes tipos de projeto Login na Conta de Distribuidor:

  • Projeto Login padrão
  • Projeto Shadow Login

Para obter mais informações sobre ele, consulte o recurso Conta multiplataforma.

Projeto Login padrão

É um projeto Login usado para armazenar contas principais.

Projeto Shadow Login

É um projeto Login usado para armazenar contas de plataforma.

Conta principal

É um tipo de conta criado em um projeto Login padrão e vinculado a contas de plataforma. A conta principal é usada para identificar o jogador em diferentes plataformas.

Conta da plataforma

É um tipo de conta criado em um projeto de Login sombra e conectado a uma plataforma de distribuição definida. A conta da plataforma não pode ser vinculada a outra conta da plataforma. Além disso, não é possível desvincular as contas de uma conta principal.

Plataforma de publicação

É uma plataforma de jogos que é usada para a distribuição de jogos (por exemplo, Steam, PlayStation, Xbox, etc.).

Autenticação

A Login API oferece suporte aos seguintes tipos de token:

Obtenção de um token de usuário

Para obter o token, envie uma das seguintes solicitações:

Após a autenticação JWT, o usuário é redirecionado para o URL de retorno de chamada com um token em um parâmetro de consulta: <Callback URL>?token=<User token (JWT)>.

Após a autenticação baseada no protocolo OAuth 2.0, envie a solicitação Generate JWT ao servidor do Xsolla Login para trocar o parâmetro code recebido por um token de usuário (access_token).

Obtenção de um token de servidor

Para obter um token de servidor:

  1. Configure o cliente OAuth 2.0 do servidor.
  2. Gere o JWT do servidor.

Configure o cliente OAuth 2.0 do servidor

  1. Abra seu projeto na Conta de Distribuidor e vá para a seção Login.
  2. Clique em Configure no painel de um projeto Login.
  3. Vá para o bloco Security e selecione a seção OAuth 2.0.
  4. Click Add OAuth 2.0 Client.
  5. Marque a caixa Server (server-to-server connection).
  6. Especifique o Tempo de vida do token.
  7. Clique em Connect.
  8. Copie e salve o ID do cliente e a chave secreta.

Geração do JWT do servidor

No back-end do seu aplicativo, implemente um método para obter o JWT do servidor usando a chamada Generate JWT API. A solicitação deve conter os seguintes parâmetros:

  • grant_type is the type of getting JWT, pass the client_credentials value.
  • client_secret is the secret key that is received when you set up the server OAuth 2.0 client.
  • client_id is the client ID received when you set up the server OAuth 2.0 client.

Estrutura JWT

Cada token tem um formato JWT e contém uma informação definida em uma carga.

JWT do usuário

O JWT do usuário é um token recebido como resultado da autenticação ou cadastro. Uma carga de token contém informações sobre o usuário e a chamada de autenticação.

Para obter um token de usuário por meio do protocolo OAuth 2.0, você precisa de um cliente OAuth 2.0. O token de usuário é passado no cabeçalho Authorization: Bearer <JWT>.

Principais reivindicações

Um token conterá as principais declarações após a autenticação ou confirmação do endereço de e-mail. A presença dessas declarações não depende do banco de dados do usuário e da chamada de autenticação.

 
Reivindicar Tipo Obrigatório Descrição
exp Carimbo de data/hora Unix Sim Data e hora da expiração do token. O tempo de expiração padrão é de 24 horas. Você pode alterar o tempo de expiração para cada projeto Login.
iss cadeia de caracteres Sim Serviço que assinou o token: https://login.xsolla.com.
iat Carimbo de data/hora Unix Sim Data e hora de entrega do token.
sub cadeia de caracteres (UUID) Sim ID do usuário escrito no lado do servidor Xsolla Login.
groups matriz Sim

A lista de grupos em que o usuário está. Cada grupo é escrito no seguinte formato:

  • id — ID do grupo
  • name — nome do grupo
  • is_default — exibe se o grupo é padrão ou não (true ou valores false).

Só pode haver um grupo padrão. Esse grupo inicialmente inclui todos os usuários antes que eles sejam distribuídos em grupos diferentes.

xsolla_login_project_id cadeia de caracteres (UUID) Sim ID do projeto Login.
type cadeia de caracteres

Opção de autenticação:

  • xsolla_login — login via nome de usuário/e-mail e senha.
  • social — login social.
  • email — login sem senha por meio de um código único recebido por e-mail.
  • phone — login sem senha por meio de um código único recebido por SMS.
  • firebase — login via nome de usuário/e-mail e senha quando o sistema de armazenamento de dados do usuário for o Firebase.
  • playfab — login via nome de usuário/e-mail e senha quando o sistema de armazenamento de dados do usuário for o PlayFab.
  • proxy — login via nome de usuário/e-mail e senha quando o armazenamento de dados do usuário for personalizado.
  • device — login com o ID do dispositivo.
  • server_custom_id — login com ID personalizado.

Só pode haver um grupo padrão. Esse grupo inicialmente inclui todos os usuários antes que eles sejam distribuídos em grupos diferentes.

avatar cadeia de caracteres URL do avatar do usuário.
username cadeia de caracteres Nome de usuário.
publisher_id número inteiro ID de um comerciante que possui um projeto de login.
email cadeia de caracteres Endereço de e-mail do usuário.
payload cadeia de caracteres Informações adicionais que são passadas no parâmetro de carga durante a autenticação.
promo_email_agreement valor booleano

Pode ter um dos seguintes valores:

  • true se o usuário concordar em receber uma newsletter.
  • false caso contrário.
Tem o valor true por padrão.

Para adicionar o recurso ao formulário de registro do Login widget:

  • Contate seu Gerente da Conta se você utiliza o Widget 2.0.
  • Adicione o parâmetro fields com o valor promo_email_agreement ao código de inicialização se você utiliza a versão anterior do widget.

connection_information cadeia de caracteres Mostra se o usuário confirmou a data de nascimento ou não. A confirmação é feita através do serviço okname.

Armazenamento PlayFab

Declarações contidas no token após a autenticação se você usar o armazenamento PlayFab.

Reivindicar Tipo Obrigatório Descrição
external_account_id cadeia de caracteres Sim ID do usuário PlayFab.
session_ticket cadeia de caracteres Sim

Um parâmetro SessionTicket recebido durante uma solicitação de autenticação ou solicitações para a PlayFab API.

Um token conterá a declaração se você autenticar usuários por meio do protocolo OAuth 2.0 e passar o valor playfab para o parâmetro scope.

entity_token cadeia de caracteres Sim Um parâmetro EntityToken.EntityToken.
entity_type cadeia de caracteres Sim Um parâmetro EntityToken.Entity.Type. Só aceita o valor title_player_account.
entity_id cadeia de caracteres Sim Um parâmetro EntityToken.Entity.Id.

Armazenamento personalizado

Declarações contidas no token após a autenticação se você usar armazenamento personalizado.

Reivindicar Tipo Obrigatório Descrição
provider cadeia de caracteres Sim Nome de uma rede social usada para autenticação. Se o usuário autenticar via nome de usuário e senha, a declaração terá o valor xsolla.
external_account_id cadeia de caracteres ID do usuário no lado do servidor.
partner_data Dados de qualquer tipo retornados pelo servidor no corpo da resposta durante a autenticação.

Autenticação social

Declarações que estão contidas no token após a autenticação por meio de uma rede social. A presença dessas declarações não depende do banco de dados do usuário.

Reivindicar Tipo Obrigatório Descrição
provider cadeia de caracteres Sim Nome de uma rede social usada para autenticação.
id cadeia de caracteres Sim ID de usuário em uma rede social.
is_cross_auth valor booleano Mostra que a solicitação de autenticação silenciosa está em andamento.
social_access_token cadeia de caracteres Parâmetro access_token de conta de rede social usado para autenticação. Entre em contato com seu Gerente de Conta para configurar o recurso.
picture cadeia de caracteres (URL) Link para a foto de perfil do usuário em uma rede social.
birthday data (RFC3339) Data de nascimento do usuário em uma rede social.
gender cadeia de caracteres Gênero do usuário em uma rede social.
name cadeia de caracteres Apelido do usuário em uma rede social.

Autenticação através do protocolo OAuth 2.0

Declarações contidas no token após a autenticação do OAuth 2.0.

Reivindicar Tipo Obrigatório Descrição
jti cadeia de caracteres Sim ID de token exclusivo.

Autenticação através de um número de telefone

Reivindicação que está contida no token após a autenticação por meio de um número de telefone.

Reivindicar Tipo Obrigatório Descrição
phone_number cadeia de caracteres Sim Número de telefone do usuário usado para autenticação. O formato de número de telefone com base no código do país, código de área e número de linha sem divisórias.

Servidor JWT

O token do servidor é passado no cabeçalho X-SERVER-AUTHORIZATION.

A carga do token contém informações sobre recursos pertencentes ao cliente OAuth 2.0. O token tem acesso a chamadas com autenticação baseada em servidor para esses recursos.

Reivindicar Tipo Obrigatório Descrição
xsolla_login_project_id cadeia de caracteres (UUID) Sim ID de um projeto Login que possui o cliente OAuth 2.0.
resources matriz Sim

Lista de recursos pertencentes a um cliente OAuth 2.0. Tipos possíveis de recursos:

  • publisher_id — recursos de um comerciante proprietário do projeto Login
  • publisher_project_id — ecursos de um projeto na Conta de Distribuidor.

Cada grupo é escrito no seguinte formato:

  • name — tipo de recurso
  • value — ID do recurso

jti cadeia de caracteres Sim ID de token exclusivo.

Validação JWT

Após a autenticação bem-sucedida, cada usuário recebe um JWT gerado para ele. O JWT gerado é assinado por uma chave secreta. Para certificar-se de que um JWT é relevante e pertence ao usuário do seu projeto Login, você deve validar seu valor.

Para validar um JWT:

  1. Abra seu projeto na Conta de Distribuidor e vá para a seção Login.
  2. Clique em Configure no painel de uma opção Login.
  3. Na página de navegação, vá para o bloco Security e selecione a seção JWT Signature.
  4. Selecione seu método de criptografia e copie o valor do campo Secret key ou New public JSON Web Key, dependendo do método selecionado.
  5. Escolha a biblioteca e conecte-a no lado do servidor do seu aplicativo.
  6. Passe o valor, copiado no passo 4, para a entrada da função de validação.

Aviso

Não revele sua chave secreta a ninguém. Se ela foi comprometida, atualize-a.

Erros

Em caso de respostas de erro, o servidor do Xsolla Login retorna um objeto JSON com os seguintes campos:

Campo Tipo Descrição
código cadeia de caracteres Código de erro do servidor Xsolla Login.
descrição cadeia de caracteres Descrição do erro. O texto está sempre em inglês. Não use este texto em caso de erro, pois o valor pode mudar no futuro.
{
  "error": {
    "code": "000-000",
    "description": "description"
  }
}

400 Solicitação incorreta

Código Descrição
0 A solicitação tem parâmetros inválidos.
010-019 Falha na autenticação do cliente (por exemplo: cliente desconhecido, nenhuma autenticação de cliente incluída, ou método de autenticação não suportado).
010-022 Estado do parâmetro ausente ou muito fraco, pois tem menos de 8 caracteres.
010-023 O token de concessão ou atualização de autorização é inválido, expirou, foi revogado, não corresponde ao URL de redirecionamento usado na solicitação de autorização, ou foi emitido para outro cliente.

401 Não autorizado

Código Descrição
002-016 Token inválido.
002-040 Não foi possível autorizar o usuário banido.
003-001 Nome de usuário ou senha errados.
003-007 Conta de usuário não confirmada.
003-025 Ocorreu um erro ao obter o token de acesso OAuth 2.0.
003-040 Usuário não autorizado.
010-026 Solicitação negada ao servidor Xsolla Login ou proprietário do recurso.

403 Proibido

Código Descrição
1901-0001 Token inválido.

404 Não encontrado

Código Descrição
003-002 Usuário não encontrado.
003-019 Projeto não encontrado.
003-061 Objeto não encontrado.

418 Eu sou um bule

Código Descrição
004-001 Ocorreu um erro.

422 Entidade não processável

Código Descrição
0 Apelido perdido na consulta.
002-050 As configurações de autenticação de dois fatores do usuário não foram alteradas.
003-003 Já existe um usuário com esse nome de usuário especificado.
003-020 Chamada indisponível para este projeto Login.
003-022 Este projeto Login foi configurado incorretamente. Altere as configurações deste projeto Login na Conta de Distribuidor Xsolla ou entre em contato com seu Gerente de Conta.
003-033 Tipo de projeto incompatível.
006-003 Clientes OAuth 2.0 com o tipo de concessão client_credentials somente podem ter listas de acesso.
010-015 Falha na autenticação de rede social: SERVICE_NAME.
010-016 Essa conta social já está vinculada a outro usuário.
010-032 Autenticação através desta rede social não habilitada para este projeto Login. Habilite-o em sua Conta de Distribuidor Xsolla > Login > Seu projeto Login > Conexões sociais.
030-024 Redefinição de senha desabilitada para este projeto Login.
2002-0001 Atributos duplicados.

429 Pedidos Demais

Código Descrição
002-054 O número permitido de tentativas de pesquisa excedeu. Aguarde um segundo antes da próxima solicitação.
010-005 Número permitido de solicitações excedido.
1900-0001 Número permitido de solicitações excedido.