OAuth 2.0协议

概览

艾克索拉登录管理器支持用于用户注册与认证的OAuth 2.0标准协议。OAuth 2.0将客户端角色与资源所有者分离。资源由所有者控制并由服务器托管。要访问受保护的资源，客户端需获取访问令牌（一个定义了访问属性的字符串）而不使用资源所有者的凭证。获得资源所有者的批准后，服务器将访问令牌授予第三方服务器进行使用。关于OAuth 2.0协议的详细信息请访问其官方网站。用户JWT是一个access_token。

客户端与艾克索拉登录管理器之间的交互过程如下：

要设置OAuth 2.0协议：

1. 连接登录管理器产品。
2. 设置艾克索拉存储或PlayFab。
3. 连接OAuth 2.0客户端。

连接OAuth 2.0客户端

1. 前往发布商帐户并打开登录管理器项目 > 常规设置 > 授权 > OAuth 2.0认证。
2. 单击连接。
3. 在模态窗口中指定：
   1. 客户端名称。
   2. OAuth 2.0重定向URI。用于Login API调用的redirect_uri参数。
   3. 认证类型：公开或机密。

4. 单击连接。

获取OAuth 2.0客户端设置

要获取客户端ID和密钥：

1. 前往发布商帐户，然后打开登录管理器项目 > 常规设置 > 授权 > OAuth 2.0认证。
2. 在客户端部分，单击连接/编辑。

连接OAuth 2.0客户端后将自动打开一个包含这些设置的窗口。客户端ID和密钥与Login API调用的client_id和client_secret参数一致。与OAuth 2.0客户端交互时需用到这些设置。

在应用程序侧进行集成

可使用以下集成方式：

• 通过登录管理器小组件
• 通过Login API
• 通过Login SDK

与Login API交互时，也可使用scope参数。可能的参数值有：

• offline，用于更新访问令牌。需要将scope=offline传入注册或认证调用。
• email，用于通过社交网络认证用户时额外请求用户的邮箱地址。如果集成产品时使用的是登录管理器小组件的上一个版本，请设置该值。请参阅在使用社交帐户认证时收集邮箱地址的说明。

通过登录管理器小组件集成

如果是通过小组件集成登录管理器：

• 对于小组件2.0：请在初始化代码中添加client_id、response_type、state和redirect_uri。此外，您还可以添加scope参数。redirect_uri参数中需指定HTTP/HTTPS协议，如https://example.com。

<script>
const xl = new XsollaLogin.Widget({
  projectId: 'LOGIN_PROJECT_ID',
  preferredLocale: 'en_US',
  clientId: 'CLIENT_ID',
  responseType: 'code',
  state: 'CUSTOM_STATE',
  redirectUri: 'REDIRECT_URI',
  scope: 'SCOPE'
});
</script>

• 对于更早版本的小组件：请在初始化代码中添加redirect_uri和client_id参数。此外，还可以添加scope参数。redirect_uri参数中需指定HTTP/HTTPS协议。

<script type="text/javascript">
XL.init({
  projectId: 'LOGIN_PROJECT_ID',
  locale: 'en_US',
  redirectUri: 'REDIRECT_URI',
  clientId: 'CLIENT_ID',
  state: 'CUSTOM_STATE',
  scope: 'SCOPE'
});
</script>

通过Login API集成

对于用户注册和认证，请使用用于OAuth 2.0协议的API请求。如果已集成了用于JWT标准的请求，请通过调用OAuth 2.0请求来替代。

调用API认证请求时，用code参数换取访问令牌。

通过Login SDK集成

Login SDK支持基于OAuth 2.0协议的用户认证。要设置OAuth 2.0客户端，请选择游戏引擎并按照相应说明进行操作：

• Unity
• 虚幻引擎
• Android

获取访问令牌

使用包含grant_type=authorization_code参数的Generate JWT调用获取访问令牌。获取令牌所必需的code参数会在用户认证或注册后传入redirect_uri。

POST https://login.xsolla.com/api/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=11&client_secret=vGbXcsQ0CEW233m2qldYkd5IxbnRKoWt2YiBOgHYJGRGQwtIAdtxgxT64ik&code=ldYkd5IxbnRKoWt2YiBOgHYJGRGQwtIAdtxgxT64ik&grant_type=authorization_code&redirect_uri=https://my-website.com/callback

curl --request POST \
  --url https://login.xsolla.com/api/oauth2/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data client_secret=vGbXcsQ0CEW233m2qldYkd5IxbnRKoWt2YiBOgHYJGRGQwtIAdtxgxT64ik \
  --data client_id=11 \
  --data redirect_uri=https://my-website.com/callback \
  --data code=ldYkd5IxbnRKoWt2YiBOgHYJGRGQwtIAdtxgxT64ik

更新访问令牌

艾克索拉登录管理器服务器会为每个成功认证的用户生成一个访问令牌并创建一个新会话。默认情况下，令牌的到期时间为1小时。

要更新令牌，请使用Generate JWT调用：

• 对于首次调用，请使用grant_type=authorization_code参数以及用户通过认证后收到的code参数。
• 对于令牌到期后的调用，请使用grant_type=refresh_token以及最新的refresh_token值。

POST https://login.xsolla.com/api/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=11&client_secret=vGbXcsQ0CEW233m2qldYkd5IxbnRKoWt2YiBOgHYJGRGQwtIAdtxgxT64ik&code=ldYkd5IxbnRKoWt2YiBOgHYJGRGQwtIAdtxgxT64ik&grant_type=refresh_token&refresh_token=111dfgdfgdf&redirect_uri=https://my-website.com/callback

curl --request POST \
  --url https://login.xsolla.com/api/oauth2/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data client_secret=vGbXcsQ0CEW233m2qldYkd5IxbnRKoWt2YiBOgHYJGRGQwtIAdtxgxT64ik \
  --data client_id=11 \
  --data redirect_uri=https://my-website.com/callback \
  --data code=ldYkd5IxbnRKoWt2YiBOgHYJGRGQwtIAdtxgxT64ik \
  --data refresh_token=111dfgdfgdf