Xsolla-logo

概览

本部分介绍用于登录管理器的API调用。发送请求之前请在发布商帐户设置您的登录管理器项目。

词汇表

您可以在发布商帐户中访问以下登录管理器项目类型:

  • 标准登录管理器项目
  • 影子登录管理器项目

关于它的详细信息请参阅跨平台帐户功能。

标准登录管理器项目

用于存储主帐户的登录管理器项目。

影子登录管理器项目

用于存储平台帐户的登录管理器项目。

主帐户

一种在标准登录管理器项目中创建的且关联了平台帐户的帐户类型。主帐户用于在不同平台上识别玩家。

平台帐户

一种在影子登录管理器项目中创建的且关联了指定发布平台的帐户类型。一个平台帐户不能关联其他平台帐户。另外,不能解除帐户与主帐户的关联。

发布平台

用于分发游戏的游戏平台(例如Steam、PlayStation、Xbox等)。

身份认证

Login API支持以下令牌类型:

获取用户令牌

要获取令牌,请发送以下请求之一:

JWT认证后,用户将重定向到在查询参数中包含令牌的回调URL:<Callback URL>?token=<User token (JWT)>

进行基于OAuth 2.0协议的认证后,请将生成JWT请求发送给艾克索拉登录管理器服务器来用收到的code交换用户令牌(access_token)。

获取服务器令牌

使用服务器令牌需要有一个OAuth 2.0客户端进行服务器认证。我们在发布商帐户中没有此类OAuth 2.0客户端的设置。请联系您的帐户经理来创建客户端。

要获取令牌,请发送包含grant_type=client_credentials参数的生成JWT请求。

JWT结构

每个密钥都一个JWT格式,并在负载中包含固定的信息。

用户JWT

用户JWT是作为身份认证或注册结果收到的一个令牌。令牌负载包含关于用户和认证调用的信息。

通过OAuth 2.0协议获取用户令牌需要OAuth 2.0客户端。用户令牌在Authorization: Bearer <JWT>头中传入。

主要声明

身份认证或邮箱地址确认后,令牌会包含主要声明。这些声明的存在不依赖于用户数据库和认证调用。

 
声明 类型 必需 描述
exp Unix时间戳 令牌过期的日期和时间。默认过期时间是24小时。您可以更改各登录管理器项目的过期时间。
iss 字符串 给令牌签名的服务:https://login.xsolla.com
iat Unix时间戳 授予令牌的日期和时间。
sub 字符串(UUID) 写入在艾克索拉登录管理器服务器侧的用户ID。
groups array

用户所在组的列表。每个组的写入格式如下:

  • id — 组ID
  • name — 组名称
  • is_default — 显示该组是否是默认组(truefalse值)。

只能有一个默认组。该组最初包含将用户分到不同组之前的所有用户。

xsolla_login_project_id 字符串(UUID) 登录管理器项目ID。
username 字符串 用户名。
publisher_id integer 拥有登录管理器项目的商户ID。
email 字符串 用户邮箱地址。
payload 字符串 身份认证过程中在payload参数中传递的附加信息。
promo_email_agreement boolean

可以是以下值之一:

  • true,如果用户同意接收电子简讯。
  • false,不同意接收。
默认为true值。

要向登录管理器小组件的注册表单添加该功能:

  • 如使用小组件2.0,请联系您的帐户经理。
  • 如果使用上一版本的小组件,请在初始代码中添加值为promo_email_agreementfields参数。

connection_information 字符串 显示用户是否确认了其出生日期。确认由okname服务进行。

PlayFab存储

如果使用PlayFab存储,身份认证后包含在令牌中的声明如下。

声明 类型 必需 描述
external_account_id 字符串 用户PlayFab ID。
session_ticket 字符串

认证请求或向PlayFab API发送请求期间收到的SessionTicket参数。

如果通过OAuth 2.0协议来认证用户并向scope参数传入了playfab值,则令牌包含该声明。

entity_token 字符串 一个EntityToken.EntityToken参数。
entity_type 字符串 一个EntityToken.Entity.Type参数。只能有title_player_account值。
entity_id 字符串 一个EntityToken.Entity.Id参数。

自定义存储

如果使用自定义存储,身份认证后包含在令牌中的声明如下。

声明 类型 必需 描述
provider 字符串 认证使用的社交网络的名称。如果用户通过用户名和密码进行认证,则声明的值为xsolla
external_account_id 字符串 您服务器侧的用户ID。
partner_data 认证过程中您服务器在响应正文中返回的任何类型的数据。

社交网络帐户认证

通过社交网络进行认证后包含在令牌中的声明如下。这些声明的存在不依赖于用户数据库。

声明 类型 必需 描述
provider 字符串 认证使用的社交网络的名称。
id 字符串 社交网络中的用户ID。
is_cross_auth boolean 显示静默认证请求正在进行中。
social_access_token 字符串 用于认证的社交网络帐户access_token参数。请联系您的帐户经理设置该功能。
picture 字符串(URL) 社交网络中用户个人资料图片的链接。
birthday 日期(RFC3339) 社交网络中的用户出生日期。
gender 字符串 社交网络中的用户性别。
name 字符串 社交网络中的用户昵称。

通过OAuth 2.0协议进行认证

OAuth 2.0认证后包含在令牌中的声明如下。

声明 类型 必需 描述
jti 字符串 唯一令牌ID。

通过手机号码进行认证

通过手机号码进行认证后包含在令牌中的声明如下。

声明 类型 必需 描述
phone_number 字符串 用于认证的用户手机号码。手机号码格式由国家代码、地区代码和线路号码组成,没有分隔符。

服务器JWT

服务器令牌在X-SERVER-AUTHORIZATION头中传入。

令牌负载包含OAuth 2.0客户端拥有的资源的信息。令牌可以访问对这些资源有基于服务器认证的调用。

声明 类型 必需 描述
xsolla_login_project_id 字符串(UUID) OAuth 2.0客户端所属登录管理器项目的ID。
resources array

OAuth 2.0客户端拥有的资源的列表。可能的资源类型:

  • publisher_id — 拥有该登录管理器项目的商户的资源
  • publisher_project_id发布商帐户中项目的资源。

各组的写入格式如下:

  • name — 资源类型
  • value — 资源ID

jti 字符串 唯一令牌ID。

JWT验证

每个用户在成功认证后都会有一个为其生成的JWT。生成的JWT由一个密钥签名。为确保JWT的相关性 以及属于您登录管理器项目的用户,应验证它的值。

要验证JWT:

  1. 发布商帐户中打开您的项目。
  2. 在侧边栏中单击登录管理器,然后前往登录管理器项目 > 您的登录管理器项目 > 常规设置。
  3. 在验证部分,复制密钥的值。
  4. 选择,然后在应用程序的服务器侧连接该库。
  5. 将密钥值传入验证函数。

注意

请勿将密钥告诉任何人。如果发生密钥泄露,请立即更新。

错误

对于错误响应,艾克索拉登录管理器服务器返回包含以下字段的JSON对象:

字段 类型 描述
code 字符串 艾克索拉登录管理器服务器错误代码。
description 字符串 错误描述。文本始终为英文。发生错误时不要使用此文本,因为文本值将来可能会更改。
{
  "error": {
    "code": "000-000",
    "description": "description"
  }
}

400 错误的请求

代码 描述
0 请求包含无效参数。
010-019 客户端认证失败(例如客户端未知、不包含客户端认证或认证方式不支持)。
010-022 缺少参数状态或状态太弱(少于8个字符)。
010-023 授权或筛选令牌无效、过期、撤回、不匹配授权请求中的重定向URI或已发给另一客户端。

401 未授权

代码 描述
002-016 令牌无效。
002-040 无法授权被封禁的用户。
003-001 用户名或密码错误。
003-007 用户帐户未验证。
003-025 获取OAuth 2.0访问令牌时发生错误。
003-040 未授权的用户。
010-026 艾克索拉登录管理器服务器或资源所有者拒绝了请求。

403 被禁止

代码 描述
1901-0001 令牌无效。

404 未找到

代码 描述
003-002 找不到用户。
003-019 未找到项目。
003-061 未找到对象。

418 我是茶壶

代码 描述
004-001 发生了一些问题。

422 无法处理的实体

代码 描述
0 查询中缺少昵称。
002-050 用户的双因素认证设置未更改。
003-003 已存在该用户名的用户。
003-020 调用对此登录管理器项目不可用。
003-022 此登录管理器项目配置错误。请在艾克索拉发布商帐户中更改此登录管理器项目设置或联系您的帐户经理。
003-033 项目类型不匹配。
006-003 只有授权类型为client_credentials的OAuth 2.0客户端有访问列表。
010-015 社交网络认证失败:SERVICE_NAME。
010-016 此社交网络帐户已关联其他用户。
010-032 此登录管理器项目未启用通过该社交网络进行认证。请在您的艾克索拉发布商帐户 > 登录管理器 > 登录管理器项目 > 社交网络连接中启用。
030-024 此登录管理器项目禁用了密码重置。
2002-0001 属性重复。

429 请求过多

代码 描述
002-054 超过允许的搜索尝试次数。请等待一秒后再进行下次请求。
010-005 超过允许的请求次数。
1900-0001 超过允许的请求次数。