自定义用户数据存储
如果使用自定义用户数据存储，艾克索拉登录管理器将作为中介，所有用户身份认证数据将存储在您自己的系统中。艾克索拉登录管理器通过Webhook请求头和请求正文中的令牌传递身份认证数据。
注：
用户邮箱地址、社交媒体数据和用户属性存储在艾克索拉侧。密码不在艾克索拉侧存储。
注：
如果您在本地测试集成，艾克索拉的
POST请求将无法访问类似http://localhost:3000/my-webhook-endpoint的URL。Ngrok可以创建外部访问的通道，使您能够在本地接收来自艾克索拉的请求。您可以在ngrok文档中了解更多信息。交互过程
您可以使用登录管理器小组件或调用Login API的应用程序作为客户端。客户端与艾克索拉登录管理器服务器之间的交互过程如下：
- 客户端向艾克索拉登录管理器服务器发送请求。请求格式在身份认证方式中有详细说明。
- 艾克索拉登录管理器服务器向您的服务器发送Webhook。请求头包含带有
“request_type”: “gateway_token”参数的服务器JWT。请按照说明设置令牌验证。部分用户身份认证数据将在Webhook请求正文中传递。 - 要确认收到Webhook，您的服务器必须返回以下响应：
- 如响应成功，返回
200、201或204HTTP代码。 - 如未找到指定用户或传递了无效签名，则返回
400HTTP代码和问题描述。如服务器出现临时问题，您的Webhook处理程序也可返回5xxHTTP代码。
- 如响应成功，返回
- 艾克索拉登录管理器服务器处理您服务器的响应，并将授权令牌返回给客户端。
- 客户端处理响应。
如果您想在用户身份认证后将用户信息添加到JWT中，请在响应正文中返回包含任意参数集的JSON对象。该对象将保存在用户JWT的partner_data字段中。
您可以使用登录管理器小组件或调用Login API的应用程序作为客户端。客户端与艾克索拉登录管理器服务器之间的交互过程如下：
- 客户端向艾克索拉登录管理器服务器发送请求。请求格式在身份认证方式中有详细说明。
- 艾克索拉登录管理器服务器向您的服务器发送Webhook。请求头包含带有
“request_type”: “gateway_token”参数的服务器JWT。请按照说明设置令牌验证。部分用户身份认证数据将在Webhook请求正文中传递。 - 要确认收到Webhook，您的服务器必须返回以下响应：
- 如响应成功，返回
200、201或204HTTP代码。 - 如未找到指定用户或传递了无效签名，则返回
400HTTP代码和问题描述。如服务器出现临时问题，您的Webhook处理程序也可返回5xxHTTP代码。
- 如响应成功，返回
- 艾克索拉登录管理器服务器处理来自你服务器的响应，并将授权令牌返回给客户端。
- 客户端向艾克索拉登录管理器服务器发送生成JWT
POST请求。请求正文必须包含以下必需参数：grant_type— JWT发放类型，传递authorization_code值。client_id— OAuth 2.0客户端ID。client_secret— OAuth 2.0客户端密钥ID。机密认证类型需要此参数。code— 授权代码。
- 艾克索拉登录管理器服务器向客户端返回一对JWT：访问令牌和刷新令牌。
- 客户端处理响应。
- 当访问令牌过期时，客户端向艾克索拉登录管理器服务器发送生成JWT
POST请求。请求正文必须包含以下必需参数：grant_type— JWT发放类型，传递refresh_token值。client_id— OAuth 2.0客户端ID。refresh_token— 在用户授权请求响应中收到的刷新令牌。
在识别用户和/或刷新令牌时，您可以向JWT添加用户信息，请在响应正文中返回包含任意参数集的JSON对象。该对象将保存在用户JWT的partner_data字段中。
注：
包含附加用户数据的JSON最大长度为1000个字符。
- 昵称
- 出生日期
- 名字
- 姓氏
- 用户在您服务器上的ID
您还可以通过传递用户属性对象数组来更新用户属性。用户属性对象的结构如下所述。
用户属性对象的结构：
| 参数 | 类型 | 描述 |
|---|---|---|
attr_type | string | 定义用户对服务属性的访问级别：
|
key | string | 用于识别用户属性的属性名称。对每个用户必须唯一。 最大长度：256个字符。可使用数字、英文字母、连字符和下划线。 |
permission | string or null | 对用户属性的访问权限类型影响方法返回的属性列表： 可能的值： public、private（默认）。 |
read_only | string | 该属性是否不可修改。默认为false，允许更改属性值。 |
value | string | 用户属性的值。 最大长度：256个字符。 |
用户注册
- 客户端向艾克索拉登录管理器服务器发送
Register new user POST请求。请求必须包含以下必需参数：projectId查询参数 — 发布商帐户中登录管理器项目的ID。- 正文参数：
username— 用户名。允许长度：3至255个字符。password— 用户密码。允许长度：6至100个字符。email— 用户邮箱地址。允许长度：1至255个字符。
- 艾克索拉登录管理器服务器向新用户URL发送Webhook。响应必须符合此交互过程中描述的格式。在响应中，您可以指定用户属性列表和/或任何必要的JSON对象。您在响应中提供的JSON对象将记录在用户JWT的
partner_data字段中。
注：
要将JSON字段映射到艾克索拉中的用户资料属性，并在您的服务器上配置按用户ID进行帐户关联，请按照说明操作。
Webhook示例：
Copy
Full screen
Small screen
http
- http
- curl
1POST https://your.hostname/your_registration_uri HTTP/1.1
2Authorization: Bearer {JWT}
3Content-Type: application/json
4
5{
6 "email":"j.smith@email.com",
7 "password":"123456",
8 "username":"j.smith@email.com"
9}
1curl --request POST \
2 --url 'https://your.hostname/your_registration_uri' \
3 --header 'authorization: bearer_JWT' \
4 --header 'content-type: application/json' \
5 --data '{"email":"j.smith@email.com","password":"123456","username":"j.smith@email.com"}'
包含用户属性的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "attributes": [
3 {
4 "attr_type": "server",
5 "key": "company",
6 "permission": "private",
7 "value": "facebook-promo"
8 },
9 {
10 "attr_type": "server",
11 "key": "custom-id",
12 "permission": "private",
13 "value": 48582
14 }
15 ]
16}
包含JSON对象的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "user": {
3 "player_id": "12345678",
4 "email": "user@example.com"
5 },
6 "user_info": {
7 "username": "gamer123",
8 "user_first_name": "John",
9 "user_last_name": "Doe",
10 "gender": "male",
11 "birthday": "1990-05-15",
12 "country": "US",
13 "language": "en"
14 },
15 "subscription_status": "active",
16 "loyalty_level": "gold"
17
18}
- 用户数据写入艾克索拉数据库，并且
email标记为未确认。用户将收到一封帐户验证邮件。 - 如果集成了登录管理器小组件，则用户将重定向到包含以下消息的页面：请按照发送至{email}的说明验证您的帐户。
- 如果用户注册不成功，可提供一条显示在认证小组件中的错误消息。方法是在用户创建请求的响应中，传入包含以下详细信息的
error对象：- 在
code参数中，指定错误代码，例如011-002。 - 在
description参数中，提供错误消息的文本。
- 在
包含错误消息的对象示例：
Copy
Full screen
Small screen
- json
1{
2 "error": {
3 "code": "011-002",
4 "description": "<string>"
5 }
6}
- 客户端向艾克索拉登录管理器服务器发送
Register new user POST请求。该请求必须包含以下必需参数：- 查询参数：
response_type— JWT发放类型，传递code值。client_id— OAuth 2.0客户端ID。state— 用于额外用户身份认证的值。用于防止CSRF攻击。在响应中返回。允许长度：1到8个字符。
- 正文参数：
username— 用户名。允许长度：3到255个字符。password— 用户密码。允许长度：6到100个字符。email— 用户邮箱地址。允许长度：1到255个字符。
- 查询参数：
- 艾克索拉登录管理器服务器向新用户URL发送Webhook。响应必须采用此交互过程中描述的格式。在响应中，您可以指定用户属性列表和/或任何必要的JSON对象。在响应中提供的JSON对象会记录在用户JWT的
partner_data字段中。
注：
要将JSON字段映射到艾克索拉中的用户资料属性，并在您的服务器上配置按用户ID进行帐户关联，请按照说明操作。
Webhook示例：
Copy
Full screen
Small screen
http
- http
- curl
1POST https://your.hostname/your_registration_uri HTTP/1.1
2Authorization: Bearer {JWT}
3Content-Type: application/json
4
5{
6 "email":"j.smith@email.com",
7 "password":"123456",
8 "username":"j.smith@email.com"
9}
1curl --request POST \
2 --url 'https://your.hostname/your_registration_uri' \
3 --header 'authorization: bearer_JWT' \
4 --header 'content-type: application/json' \
5 --data '{"email":"j.smith@email.com","password":"123456","username":"j.smith@email.com"}'
包含用户属性的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "attributes": [
3 {
4 "attr_type": "server",
5 "key": "company",
6 "permission": "private",
7 "value": "facebook-promo"
8 },
9 {
10 "attr_type": "server",
11 "key": "custom-id",
12 "permission": "private",
13 "value": 48582
14 }
15 ]
16}
包含JSON对象的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "user": {
3 "player_id": "12345678",
4 "email": "user@example.com"
5 },
6 "user_info": {
7 "username": "gamer123",
8 "user_first_name": "John",
9 "user_last_name": "Doe",
10 "gender": "male",
11 "birthday": "1990-05-15",
12 "country": "US",
13 "language": "en"
14 },
15 "subscription_status": "active",
16 "loyalty_level": "gold"
17
18}
- 用户数据写入艾克索拉数据库，并且
email标记为未确认。用户将收到一封帐户验证邮件。 - 如果集成了登录管理器小组件，则用户将重定向到包含以下消息的页面：请按照发送至{email}的说明验证您的帐户。
- 如果用户注册不成功，可提供一条显示在认证小组件中的错误消息。方法是在用户创建请求的响应中，传入包含以下详细信息的
error对象：- 在
code参数中，指定错误代码，例如011-002。 - 在
description参数中，提供错误消息的文本。
- 在
包含错误消息的对象示例：
Copy
Full screen
Small screen
- json
1{
2 "error": {
3 "code": "011-002",
4 "description": "<string>"
5 }
6}
通过用户名和密码进行认证
- 客户端向艾克索拉登录管理器服务器发送
Auth by username and password POST请求。该请求必须包含以下必需参数：projectId查询参数 — 发布商帐户中登录管理器项目的ID。- 正文参数：
username— 用户名。允许长度：3到255个字符。password— 用户密码。允许长度：6到100个字符。
- 艾克索拉登录管理器服务器向用户验证URL发送Webhook。响应必须采用此交互过程中描述的格式。在响应中，您可以指定用户属性列表和/或任何必要的JSON对象。在响应中提供的JSON对象会记录在用户JWT的
partner_data字段中。
注：
要将JSON字段映射到艾克索拉中的用户资料属性，并在您的服务器上配置按用户ID进行帐户关联，请按照说明操作。
用户验证URL Webhook示例：
Copy
Full screen
Small screen
http
- http
- curl
1POST https://your.hostname/your_authentication_uri HTTP/1.1
2Authorization: Bearer {JWT}
3Content-Type: application/json
4
5{
6 "email":"j.smith@email.com",
7 "password":"123456",
8 "username":"j.smith@email.com"
9}
1curl --request POST \
2 --url 'https://your.hostname/your_authentication_uri' \
3 --header 'authorization: bearer_JWT' \
4 --header 'content-type: application/json' \
5 --data '{"email":"j.smith@email.com","password":"123456","username":"j.smith@email.com"}'
包含用户属性的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "attributes": [
3 {
4 "attr_type": "server",
5 "key": "company",
6 "permission": "private",
7 "value": "facebook-promo"
8 },
9 {
10 "attr_type": "server",
11 "key": "custom-id",
12 "permission": "private",
13 "value": 48582
14 }
15 ]
16}
包含JSON对象的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "user": {
3 "player_id": "12345678",
4 "email": "user@example.com"
5 },
6 "user_info": {
7 "username": "gamer123",
8 "user_first_name": "John",
9 "user_last_name": "Doe",
10 "gender": "male",
11 "birthday": "1990-05-15",
12 "country": "US",
13 "language": "en"
14 },
15 "subscription_status": "active",
16 "loyalty_level": "gold"
17
18}
- 如果用户身份认证失败，您可以提供将在身份认证小组件中显示的错误消息。为此，请在用户创建请求的响应中传入包含以下详细信息的
error对象：- 在
code参数中，指定错误代码，例如011-002。 - 在
description参数中，提供错误消息文本。
- 在
- 艾克索拉登录管理器服务器生成用户JWT。
- 用户被重定向到包含
token查询参数的login_url。token参数包含用户JWT。
注：
如果艾克索拉数据库中没有该用户数据，将创建新用户。
- 客户端向艾克索拉登录管理器服务器发送
Auth by username and password POST请求。该请求必须包含以下必需参数：- 查询参数：
response_type— JWT发放类型，传递code值。client_id— OAuth 2.0客户端ID。state— 用于额外用户身份认证的值。用于防止CSRF攻击。在响应中返回。允许长度：1到8个字符。
- 正文参数：
username— 用户名。允许长度：3到255个字符。password— 用户密码。允许长度：6到100个字符。
- 查询参数：
- 艾克索拉登录管理器服务器向用户验证URL发送Webhook。响应必须采用此交互过程中描述的格式。在响应中，您可以指定用户属性列表和/或任何必要的JSON对象。在响应中提供的JSON对象会记录在用户JWT的
partner_data字段中。
注：
要将JSON字段映射到艾克索拉中的用户资料属性，并在您的服务器上配置按用户ID进行帐户关联，请按照说明操作。
用户验证URL Webhook示例：
Copy
Full screen
Small screen
http
- http
- curl
1POST https://your.hostname/your_authentication_uri HTTP/1.1
2Authorization: Bearer {JWT}
3Content-Type: application/json
4
5{
6 "email":"j.smith@email.com",
7 "password":"123456",
8 "username":"j.smith@email.com"
9}
1curl --request POST \
2 --url 'https://your.hostname/your_authentication_uri' \
3 --header 'authorization: bearer_JWT' \
4 --header 'content-type: application/json' \
5 --data '{"email":"j.smith@email.com","password":"123456","username":"j.smith@email.com"}'
包含用户属性的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "attributes": [
3 {
4 "attr_type": "server",
5 "key": "company",
6 "permission": "private",
7 "value": "facebook-promo"
8 },
9 {
10 "attr_type": "server",
11 "key": "custom-id",
12 "permission": "private",
13 "value": 48582
14 }
15 ]
16}
包含JSON对象的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "user": {
3 "player_id": "12345678",
4 "email": "user@example.com"
5 },
6 "user_info": {
7 "username": "gamer123",
8 "user_first_name": "John",
9 "user_last_name": "Doe",
10 "gender": "male",
11 "birthday": "1990-05-15",
12 "country": "US",
13 "language": "en"
14 },
15 "subscription_status": "active",
16 "loyalty_level": "gold"
17
18}
- 如果用户身份认证失败，您可以提供将在身份认证小组件中显示的错误消息。为此，请在用户创建请求的响应中传入包含以下详细信息的
error对象：- 在
code参数中，指定错误代码，例如011-002。 - 在
description参数中，提供错误消息文本。
- 在
- 艾克索拉登录管理器服务器生成用户JWT。
- 用户被重定向到包含
token查询参数的login_url。token参数包含用户JWT。
注：
如果艾克索拉数据库中没有该用户数据，将创建新用户。
通过手机号进行免密认证
- 客户端打开身份认证表单供用户输入手机号码。
- 用户输入手机号码。
- 客户端向艾克索拉登录管理器服务器发送
Start auth by phone number POST请求。请求必须包含以下必需参数：projectId查询参数 — 发布商帐户中登录管理器项目的ID。phone_number正文参数 — 用户手机号码。
- 客户端显示验证码输入字段。
- 用户输入收到的验证码。
- 客户端向艾克索拉登录管理器服务器发送
Complete auth by phone number POST请求。请求必须包含以下必需参数：projectId查询参数 — 发布商帐户中登录管理器项目的ID。- 正文参数：
code— 验证码。phone_number— 用户手机号码。operation_id— 验证码ID。
- 如果这是用户的首次授权，艾克索拉登录管理器服务器将向免密登录URL发送Webhook。响应必须符合交互过程中描述的格式。在响应中，您可以指定用户属性列表和/或任何必要的JSON对象。您在响应中提供的JSON对象将记录在用户JWT的
partner_data字段中。 - 如果用户身份认证失败，您可以提供将在身份认证小组件中显示的错误消息。为此，请在用户创建请求的响应中传入包含以下详细信息的
error对象：- 在
code参数中，指定错误代码，例如011-002。 - 在
description参数中，提供错误消息文本。
- 在
注：
要将JSON字段映射到艾克索拉中的用户资料属性，并在您的服务器上配置按用户ID进行帐户关联，请按照说明操作。
Webhook示例：
Copy
Full screen
Small screen
http
- http
- curl
1POST https://your.hostname/your_phone_authentication_uri HTTP/1.1
2Authorization: Bearer {JWT}
3Content-Type: application/json
4
5{
6 "login": "+12025550140",
7 "type": "phone"
8}
1curl --request POST \
2 --url 'https://your.hostname/your_phone_authentication_uri' \
3 --header 'authorization: bearer_JWT' \
4 --header 'content-type: application/json' \
5 --data '{"login":"+12025550140","type":"phone"}'
包含用户属性的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "attributes": [
3 {
4 "attr_type": "server",
5 "key": "company",
6 "permission": "private",
7 "value": "facebook-promo"
8 },
9 {
10 "attr_type": "server",
11 "key": "custom-id",
12 "permission": "private",
13 "value": 48582
14 }
15 ]
16}
包含JSON对象的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "user": {
3 "player_id": "12345678",
4 "email": "user@example.com"
5 },
6 "user_info": {
7 "username": "gamer123",
8 "user_first_name": "John",
9 "user_last_name": "Doe",
10 "gender": "male",
11 "birthday": "1990-05-15",
12 "country": "US",
13 "language": "en"
14 },
15 "subscription_status": "active",
16 "loyalty_level": "gold"
17
18}
- 客户端打开身份认证表单，用户可以输入手机号码。
- 用户输入手机号码。
- 客户端向艾克索拉登录管理器服务器发送
Start auth by phone number POST请求。该请求必须包含以下必需参数：- 查询参数：
response_type— JWT发放类型，传递code值。client_id— OAuth 2.0客户端ID。state— 用于额外用户身份认证的值。防止 CSRF攻击所必需。在响应中返回。允许长度：1到8个字符。
phone_number正文参数 — 用户手机号码。
- 查询参数：
- 客户端显示字段，用户可以填入验证码。
- 用户输入收到的验证码。
- 客户端向艾克索拉登录管理器服务器发送
Complete auth by phone number POST请求。请求必须包含以下必需参数：- 查询参数
client_id— OAuth 2.0客户端ID。 - 正文参数：
code— 验证码。phone_number— 用户手机号码。operation_id— 验证码ID。
- 查询参数
- 如果这是用户的首次授权，艾克索拉登录管理器服务器将向免密登录URL发送Webhook。响应必须符合交互过程中描述的格式。在响应中，您可以指定用户属性列表和/或任何必要的JSON对象。您在响应中提供的JSON对象将记录在用户JWT的
partner_data字段中。 - 如果用户身份认证失败，您可以提供将在身份认证小组件中显示的错误消息。为此，请在用户创建请求的响应中传入包含以下详细信息的
error对象：- 在
code参数中，指定错误代码，例如011-002。 - 在
description参数中，提供错误消息文本。
- 在
注：
要将JSON字段映射到艾克索拉中的用户资料属性，并在您的服务器上配置按用户ID进行帐户关联，请按照说明操作。
Webhook示例：
Copy
Full screen
Small screen
http
- http
- curl
1POST https://your.hostname/your_phone_authentication_uri HTTP/1.1
2Authorization: Bearer {JWT}
3Content-Type: application/json
4
5{
6 "login": "+12025550140",
7 "type": "phone"
8}
1curl --request POST \
2 --url 'https://your.hostname/your_phone_authentication_uri' \
3 --header 'authorization: bearer_JWT' \
4 --header 'content-type: application/json' \
5 --data '{"login":"+12025550140","type":"phone"}'
包含用户属性的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "attributes": [
3 {
4 "attr_type": "server",
5 "key": "company",
6 "permission": "private",
7 "value": "facebook-promo"
8 },
9 {
10 "attr_type": "server",
11 "key": "custom-id",
12 "permission": "private",
13 "value": 48582
14 }
15 ]
16}
包含JSON对象的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "user": {
3 "player_id": "12345678",
4 "email": "user@example.com"
5 },
6 "user_info": {
7 "username": "gamer123",
8 "user_first_name": "John",
9 "user_last_name": "Doe",
10 "gender": "male",
11 "birthday": "1990-05-15",
12 "country": "US",
13 "language": "en"
14 },
15 "subscription_status": "active",
16 "loyalty_level": "gold"
17
18}
通过邮箱进行免密认证
- 客户端打开身份认证表单供用户输入邮箱地址。
- 用户输入邮箱地址。
- 客户端向艾克索拉登录管理器服务器发送
Start auth by email POST请求。请求必须包含以下必需参数：projectId查询参数 — 发布商帐户中登录管理器项目的ID。email正文参数 — 用户邮箱地址。
- 客户端显示验证码输入字段。
- 用户输入收到的验证码。
- 客户端向艾克索拉登录管理器服务器发送
Complete auth by email POST请求。请求必须包含以下必需参数：projectId查询参数 — 发布商帐户中登录管理器项目的ID。- 正文参数：
code— 验证码。email— 用户邮箱地址。operation_id— 验证码ID。
- 如果这是用户的首次授权，艾克索拉登录管理器服务器将向免密登录URL发送Webhook。响应必须符合交互过程中描述的格式。在响应中，您可以指定用户属性列表和/或任何必要的JSON对象。您在响应中提供的JSON对象将记录在用户JWT的
partner_data字段中。 - 如果用户身份认证失败，您可以提供将在身份认证小组件中显示的错误消息。为此，请在用户创建请求的响应中传入包含以下详细信息的
error对象：- 在
code参数中，指定错误代码，例如011-002。 - 在
description参数中，提供错误消息文本。
- 在
注：
要将JSON字段映射到艾克索拉中的用户资料属性，并在您的服务器上配置按用户ID进行帐户关联，请按照说明操作。
Webhook示例：
Copy
Full screen
Small screen
http
- http
- curl
1POST https://your.hostname/your_email_authentication_uri HTTP/1.1
2Authorization: Bearer {JWT}
3Content-Type: application/json
4
5{
6 "email": "user@mail.com",
7 "type": "email"
8}
1curl --request POST \
2 --url 'https://your.hostname/your_email_authentication_uri' \
3 --header 'authorization: bearer_JWT' \
4 --header 'content-type: application/json' \
5 --data '{"email": "user@mail.com","type": "email"}'
包含用户属性的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "attributes": [
3 {
4 "attr_type": "server",
5 "key": "company",
6 "permission": "private",
7 "value": "facebook-promo"
8 },
9 {
10 "attr_type": "server",
11 "key": "custom-id",
12 "permission": "private",
13 "value": 48582
14 }
15 ]
16}
包含JSON对象的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "user": {
3 "player_id": "12345678",
4 "email": "user@example.com"
5 },
6 "user_info": {
7 "username": "gamer123",
8 "user_first_name": "John",
9 "user_last_name": "Doe",
10 "gender": "male",
11 "birthday": "1990-05-15",
12 "country": "US",
13 "language": "en"
14 },
15 "subscription_status": "active",
16 "loyalty_level": "gold"
17
18}
- 客户端打开身份认证表单，用户可以输入邮箱。
- 用户输入邮箱地址。
- 客户端向艾克索拉登录管理器服务器发送
Start auth by email POST请求。该请求必须包含以下必需参数：- 查询参数：
response_type— JWT发放类型，传递code值。client_id— OAuth 2.0客户端ID。state— 用于额外用户身份认证的值。防止 CSRF攻击所必需。在响应中返回。允许长度：1到8个字符。
email正文参数 — 用户邮箱地址。
- 查询参数：
- 客户端显示字段，用户可以填入验证码。
- 用户输入收到的验证码。
- 客户端向艾克索拉登录管理器服务器发送
Complete auth by email POST请求。请求必须包含以下必需参数：client_id查询参数 — OAuth 2.0客户端ID。- 正文参数：
code— 验证码。email— 用户邮箱。operation_id— 验证码ID。
- 如果这是用户的首次授权，艾克索拉登录管理器服务器将向免密登录URL发送Webhook。响应必须符合交互过程中描述的格式。在响应中，您可以指定用户属性列表和/或任何必要的JSON对象。您在响应中提供的JSON对象将记录在用户JWT的
partner_data字段中。 - 如果用户身份认证失败，您可以提供将在身份认证小组件中显示的错误消息。为此，请在用户创建请求的响应中传入包含以下详细信息的
error对象：- 在
code参数中，指定错误代码，例如011-002。 - 在
description参数中，提供错误消息文本。
- 在
Webhook示例：
注：
要将JSON字段映射到艾克索拉中的用户资料属性，并在您的服务器上配置按用户ID进行帐户关联，请按照说明操作。
Copy
Full screen
Small screen
http
- http
- curl
1POST https://your.hostname/your_email_authentication_uri HTTP/1.1
2Authorization: Bearer {JWT}
3Content-Type: application/json
4
5{
6 "email": "user@mail.com",
7 "type": "email"
8}
1curl --request POST \
2 --url 'https://your.hostname/your_email_authentication_uri' \
3 --header 'authorization: bearer_JWT' \
4 --header 'content-type: application/json' \
5 --data '{"email": "user@mail.com","type": "email"}'
包含用户属性的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "attributes": [
3 {
4 "attr_type": "server",
5 "key": "company",
6 "permission": "private",
7 "value": "facebook-promo"
8 },
9 {
10 "attr_type": "server",
11 "key": "custom-id",
12 "permission": "private",
13 "value": 48582
14 }
15 ]
16}
包含JSON对象的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "user": {
3 "player_id": "12345678",
4 "email": "user@example.com"
5 },
6 "user_info": {
7 "username": "gamer123",
8 "user_first_name": "John",
9 "user_last_name": "Doe",
10 "gender": "male",
11 "birthday": "1990-05-15",
12 "country": "US",
13 "language": "en"
14 },
15 "subscription_status": "active",
16 "loyalty_level": "gold"
17
18}
通过社交网络进行身份验证
要在通过社交网络进行认证时获取用户数据，请在发布商帐户的登录管理器项目设置中指定社交帐户登录URL（在用户数据库 > 存储 > 自定义存储部分）。包含从社交网络获取的数据的请求将发送到该URL。
身份认证流程：
- 客户端向艾克索拉登录管理器服务器发送
Auth via social network POST请求。请求必须包含以下必需参数：projectId查询参数 — 发布商帐户中登录管理器项目的ID。provider_name路径参数 — 在发布商帐户中连接到登录管理器的社交网络名称。可以是：amazon、apple、xsolla、baidu、battlenet、discord、epicgames、facebook、github、google、kakao、linkedin、mailru、microsoft、msn、naver、ok、paypal、qq、reddit、steam、twitch、twitter、vimeo、vk、wechat、weibo、xbox、yahoo、yandex、youtube。
- 用户登录社交网络。
- 艾克索拉登录管理器服务器会处理从社交网络获取的用户数据，并向社交帐户登录URL发送Webhook。响应必须符合交互过程中描述的格式。在响应中，您可以指定用户属性列表和/或任何必要的JSON对象。您在响应中提供的JSON对象将记录在用户JWT的
partner_data字段中。
注：
要将JSON字段映射到艾克索拉中的用户资料属性，并在您的服务器上配置按用户ID进行帐户关联，请按照说明操作。
用户数据将在Authorization请求头中以临时网关令牌（包含“request_type”: “gateway_token”的服务器令牌）的形式传递。
网关令牌的主要字段：
| 声明 | 类型 | 描述 |
|---|---|---|
| exp | Unix Timestamp | JWT的过期日期和时间。JWT寿命为7分钟。 必需。 |
| iat | Unix Timestamp | 使用该JWT时的日期和时间。 必需。 |
| iss | string | 签名JWT的服务，例如https://login.xsolla.com。 必需。 |
| request_type | string | 常量：gateway_request。 必需。 |
| xsolla_login_project_id | string (UUID) | 您发布商帐户的登录管理器项目ID。 必需。 |
| string | 用户邮箱地址。 | |
| sub | string (UUID) | 写入在艾克索拉登录管理器服务器侧的用户ID。 必需。 |
| username | string | 用户名。 |
| provider | string | 认证使用的社交网络的名称。 必需。 |
| id | string | 社交网络中的用户ID。 必需。 |
| social_access_token | string | 用户通过其进行身份认证的社交网络的访问令牌。要启用此声明的传输，请联系您的客户成功经理或发送邮件至csm@xsolla.com。 |
| partner_data | string | 您的服务器在用户认证期间在响应正文中返回的任何类型的数据。要启用此声明的传输，请联系您的客户成功经理或发送邮件至csm@xsolla.com。 |
令牌负载示例：
Copy
Full screen
Small screen
- json
1{
2 "exp": 1573635020,
3 "iat": 1573634600,
4 "iss": "https://login.xsolla.com",
5 "request_type": "gateway_request",
6 "xsolla_login_project_id": "00000000-0000-0000-0000-000000000000",
7 "sub": "00000000-0000-0000-0000-000000000000",
8 "email": "example@test.com",
9 "username": "Smith707",
10 "provider": "google",
11 "id": "123",
12}
社交帐户登录URL Webhook示例：
Copy
Full screen
Small screen
http
- http
- curl
1POST https://your.hostname/your_social_authentication_uri HTTP/1.1
2Authorization: Bearer {JWT}
3Content-Type: application/json
4
5{}
1curl --request POST \
2 --url 'https://your.hostname/your_social_authentication_uri' \
3 --header 'authorization: bearer_JWT' \
4 --header 'content-type: application/json'
包含用户属性的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "attributes": [
3 {
4 "attr_type": "server",
5 "key": "company",
6 "permission": "private",
7 "value": "facebook-promo"
8 },
9 {
10 "attr_type": "server",
11 "key": "custom-id",
12 "permission": "private",
13 "value": 48582
14 }
15 ]
16}
包含JSON对象的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "user": {
3 "player_id": "12345678",
4 "email": "user@example.com"
5 },
6 "user_info": {
7 "username": "gamer123",
8 "user_first_name": "John",
9 "user_last_name": "Doe",
10 "gender": "male",
11 "birthday": "1990-05-15",
12 "country": "US",
13 "language": "en"
14 },
15 "subscription_status": "active",
16 "loyalty_level": "gold"
17
18}
- 如果用户身份认证失败，您可以提供将在身份认证小组件中显示的错误消息。为此，请在用户创建请求的响应中传入包含以下详细信息的
error对象：- 在
code参数中，指定错误代码，例如011-002。 - 在
description参数中，提供错误消息文本。
- 在
要在通过社交网络进行认证时获取用户数据，请在发布商帐户的登录管理器项目设置中指定社交帐户登录URL（在用户数据库 > 存储 > 自定义存储部分）。包含从社交网络获取的数据的请求将发送到该URL。
身份认证流程：
- 客户端向艾克索拉登录管理器服务器发送
Auth via social network POST请求。请求必须包含以下必需参数：- 查询参数：
response_type— JWT发放类型，传递code值。client_id— OAuth 2.0 客户端ID。state— 用于额外用户身份认证的值。用于防止CSRF攻击。在响应中返回。允许长度：1到8个字符。
provider_name路径参数 — 在发布商帐户中连接到登录管理器的社交网络名称。可以是：amazon、apple、xsolla、baidu、battlenet、discord、epicgames、facebook、github、google、kakao、linkedin、mailru、microsoft、msn、naver、ok、paypal、qq、reddit、steam、twitch、twitter、vimeo、vk、wechat、weibo、xbox、yahoo、yandex、youtube。
- 查询参数：
- 用户登录社交网络。
- 艾克索拉登录管理器服务器会处理从社交网络获取的用户数据，并向社交帐户登录URL发送Webhook。响应必须符合交互过程中描述的格式。在响应中，您可以指定用户属性列表和/或任何必要的JSON对象。您在响应中提供的JSON对象将记录在用户JWT的
partner_data字段中。
注：
要将JSON字段映射到艾克索拉中的用户资料属性，并在您的服务器上配置按用户ID进行帐户关联，请按照说明操作。
用户数据将在Authorization请求头中以临时网关令牌（包含“request_type”: “gateway_token”的服务器令牌）的形式传递。
网关令牌的主要字段：
| 声明 | 类型 | 描述 |
|---|---|---|
| exp | Unix Timestamp | JWT的过期日期和时间。JWT寿命为7分钟。 必需。 |
| iat | Unix Timestamp | 使用该JWT时的日期和时间。 必需。 |
| iss | string | 签名JWT的服务，例如https://login.xsolla.com。 必需。 |
| request_type | string | 常量：gateway_request。 必需。 |
| xsolla_login_project_id | string (UUID) | 您发布商帐户的登录管理器项目ID。 必需。 |
| string | 用户邮箱地址。 | |
| sub | string (UUID) | 写入在艾克索拉登录管理器服务器侧的用户ID。 必需。 |
| username | string | 用户名。 |
| provider | string | 认证使用的社交网络的名称。 必需。 |
| id | string | 社交网络中的用户ID。 必需。 |
| social_access_token | string | 用户通过其进行身份认证的社交网络的访问令牌。要启用此声明的传输，请联系您的客户成功经理或发送邮件至csm@xsolla.com。 |
| partner_data | string | 您的服务器在用户认证期间在响应正文中返回的任何类型的数据。要启用此声明的传输，请联系您的客户成功经理或发送邮件至csm@xsolla.com。 |
令牌负载示例：
Copy
Full screen
Small screen
- json
1{
2 "exp": 1573635020,
3 "iat": 1573634600,
4 "iss": "https://login.xsolla.com",
5 "request_type": "gateway_request",
6 "xsolla_login_project_id": "00000000-0000-0000-0000-000000000000",
7 "sub": "00000000-0000-0000-0000-000000000000",
8 "email": "example@test.com",
9 "username": "Smith707",
10 "provider": "google",
11 "id": "123",
12}
社交帐户登录URL Webhook示例：
Copy
Full screen
Small screen
http
- http
- curl
1POST https://your.hostname/your_social_authentication_uri HTTP/1.1
2Authorization: Bearer {JWT}
3Content-Type: application/json
4
5{}
1curl --request POST \
2 --url 'https://your.hostname/your_social_authentication_uri' \
3 --header 'authorization: bearer_JWT' \
4 --header 'content-type: application/json'
包含用户属性的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "attributes": [
3 {
4 "attr_type": "server",
5 "key": "company",
6 "permission": "private",
7 "value": "facebook-promo"
8 },
9 {
10 "attr_type": "server",
11 "key": "custom-id",
12 "permission": "private",
13 "value": 48582
14 }
15 ]
16}
包含JSON对象的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "user": {
3 "player_id": "12345678",
4 "email": "user@example.com"
5 },
6 "user_info": {
7 "username": "gamer123",
8 "user_first_name": "John",
9 "user_last_name": "Doe",
10 "gender": "male",
11 "birthday": "1990-05-15",
12 "country": "US",
13 "language": "en"
14 },
15 "subscription_status": "active",
16 "loyalty_level": "gold"
17
18}
- 如果用户身份认证失败，您可以提供将在身份认证小组件中显示的错误消息。为此，请在用户创建请求的响应中传入包含以下详细信息的
error对象：- 在
code参数中，指定错误代码，例如011-002。 - 在
description参数中，提供错误消息文本。
- 在
用户密码重置
- 客户端向艾克索拉登录管理器服务器发送
Reset password POST请求。请求必须包含以下必需参数：projectId查询参数 — 发布商帐户中登录管理器项目的ID。username请求正文参数 — 用户名。允许长度：3至255个字符。
- 艾克索拉登录管理器服务器向用户发送密码重置确认邮件。
- 用户在邮件中确认重置密码后，将被重定向到可输入新密码的页面。
- 用户输入新密码。
- 艾克索拉登录管理器服务器向密码重置URL发送Webhook。
- 如果密码重置失败，您可以提供将在身份认证小组件中显示的错误消息。为此，请在用户创建请求的响应中传入包含以下详细信息的
error对象：- 在
code参数中，指定错误代码，例如011-002。 - 在
description参数中，提供错误消息文本。
- 在
密码重置URL的Webhook示例：
Copy
Full screen
Small screen
http
- http
- curl
1POST https://your.hostname/your_reset_uri HTTP/1.1
2Authorization: Bearer {JWT}
3Content-Type: application/json
4
5{
6 "username": "john@gmail.com",
7 "fields": {
8 "password": "NewPa$$word1"
9 }
10}
1curl --request POST \
2 --url 'https://your.hostname/your_reset_uri' \
3 --header 'authorization: bearer_JWT' \
4 --header 'content-type: application/json' \
5 --data '{"email":"john@gmail.com","fields":{"password":"NewPa$$word1"}}'
令牌刷新
注：
令牌刷新仅在使用OAuth 2.0身份认证协议时可用。
- 当访问令牌过期时，客户端向艾克索拉登录管理器服务器发送生成JWT
POST请求端点。请求正文必须包含以下参数：grant_type— JWT发放类型，传递refresh_token值。client_id— OAuth 2.0客户端ID。refresh_token— 在用户授权请求响应中收到的刷新令牌。
- 艾克索拉登录管理器服务器处理从社交网络接收的用户数据，并向刷新令牌URL发送Webhook。响应必须采用 交互过程中描述的格式。在响应中，可以指定用户属性列表和/或任何必要的JSON对象。在响应中提供的JSON对象会记录在用户JWT的
partner_data字段中。
注：
要将JSON字段映射到艾克索拉中的用户资料属性，并在您的服务器上配置按用户ID进行帐户关联，请按照说明操作。
Copy
Full screen
Small screen
- http
1POST https://your.hostname/your_refrsh_token_uri HTTP/1.1
2Authorization: Bearer {JWT}
3Content-Type: application/json
4
5{}
包含用户属性的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "attributes": [
3 {
4 "attr_type": "server",
5 "key": "company",
6 "permission": "private",
7 "value": "facebook-promo"
8 },
9 {
10 "attr_type": "server",
11 "key": "custom-id",
12 "permission": "private",
13 "value": 48582
14 }
15 ]
16}
包含JSON对象的Webhook响应示例：
Copy
Full screen
Small screen
- json
1{
2 "user": {
3 "player_id": "12345678",
4 "email": "user@example.com"
5 },
6 "user_info": {
7 "username": "gamer123",
8 "user_first_name": "John",
9 "user_last_name": "Doe",
10 "gender": "male",
11 "birthday": "1990-05-15",
12 "country": "US",
13 "language": "en"
14 },
15 "subscription_status": "active",
16 "loyalty_level": "gold"
17
18}
本文对您的有帮助吗？
感谢您的反馈！
我们会查看您的留言并运用它改进用户体验。继续阅读
上次更新时间: 2025年11月21日发现了错别字或其他内容错误？ 请选择文本，然后按Ctrl+Enter。
