Собственное хранилище данных пользователей
Если вы используете собственное хранилище данных пользователей, Xsolla Login выступает как посредник и все данные для идентификации пользователя хранятся на вашей стороне. Xsolla Login передает данные аутентификации в токене в заголовке и теле вебхуков.
- регистрация пользователей;
- аутентификация по имени пользователя и паролю;
- аутентификация без пароля по номеру телефона;
- аутентификация без пароля по email;
- аутентификация через социальные сети;
- cброс пароля пользователя.
POST
-запросы от Xsolla не доходят до URL-адресов вида http://localhost:3000/my-webhook-endpoint
. Сервис ngrok позволяет создать туннель для внешнего доступа, благодаря чему вы сможете локально получать запросы от Xsolla. Подробнее вы можете прочитать в документации ngrok.
Если вы тестируете интеграцию локально, то POST
-запросы от Xsolla не доходят до URL-адресов вида http://localhost:3000/my-webhook-endpoint
. Сервис ngrok позволяет создать туннель для внешнего доступа, благодаря чему вы сможете локально получать запросы от Xsolla. Подробнее вы можете прочитать в документации ngrok.Сценарий взаимодействия
В качестве клиента может выступать виджет авторизации Xsolla или ваше приложение, которое использует методы Login API. Сценарий взаимодействия клиента и сервера Xsolla Login:
- Клиент отправляет запросы на сервер Xsolla Login. Формат запросов описан в группах методов JWT и Password.
- Сервер Xsolla Login отправляет вебхуки на ваш сервер. В заголовке передается серверный JWT, с параметром
“request_type”: “gateway_token”
. Чтобы настроить валидацию токена в запросе, следуйте инструкции. Часть данных для идентификации пользователя передается в теле вебхука. - Чтобы подтвердить получение вебхука, ваш сервер должен вернуть:
200
,201
, или204
HTTP-код в случае успешного ответа.400
HTTP-код с описанием проблемы, если указанный пользователь не был найден или если передана недействительная подпись. Ваш обработчик вебхуков также может возвращать5xx
HTTP-код при временных проблемах на вашем сервере.
- Сервер Xsolla Login обрабатывает ответ от вашего сервера и возвращает токен авторизации клиенту.
- Клиент обрабатывает ответ.
Если после идентификации пользователя вы хотите добавить информацию о пользователе в JWT, передайте в теле ответа JSON c любым набором параметров. Этот объект будет сохранен в поле JWT partner_data.
- email-адрес;никнейм;
- дата рождения;
- имя;фамилия;
- ID пользователя на вашем сервере.
Параметр | Тип | Описание |
---|---|---|
attr_type | string | Тип атрибута, определяет уровень доступа пользователя к атрибутам сервиса:
|
key | string | Название атрибута, которое используется для идентификации атрибута пользователя. Должно быть уникальным для каждого пользователя. Максимальная длина: 256 символов. Вы можете использовать цифры, латинские буквы, подчеркивания и дефисы. |
permission | string or null | Тип доступа к атрибутам пользователя, влияет на список атрибутов, которые возвращают методы:
Возможные значения: public , private (по умолчанию). |
read_only | string | Защищен ли атрибут от изменений. По умолчанию false и изменять значения атрибута разрешено. |
value | string | Значение атрибута пользователя. Максимальная длина: 256 символов. |
Регистрация пользователя
- Клиент отправляет
POST
-запросRegister new user на сервер Xsolla Login. Запрос должен содержать заголовокAuthorization: Bearer {JWT}
и следующие обязательные параметры:- query-параметр
projectId
— ID варианта авторизации в Личном кабинете; - body-параметры:
username
— имя пользователя, допустимая длина: от 3 до 255 символов;password
— пароль, допустимая длина: от 6 до 100 символов;email
— email-адрес, допустимая длина: от 1 до 255 символов.
- query-параметр
- Сервер Xsolla Login отправляет вебхук на URL для создания пользователя. Ответ на вебхук должен иметь формат, описанный в сценарии взаимодействия. В ответе вы можете указать список пользовательских атрибутов и/или любой необходимый объект JSON. Объект JSON, переданный вами в ответе, записывается в поле
partner_data
JWT пользователя.
Пример вебхука:
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"}'
Пример ответа на вебхук с атрибутами пользователей:
- 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:
- json
1{
2 "id": 123456,
3 "role": "scout"
4}
- Информация о пользователе записывается в базу данных Xsolla. При этом параметр
email
отмечается как неподтвержденный. - Письмо для подтверждения регистрации отправляется пользователю. Если вы интегрировали виджет авторизации, пользователь перенаправляется на страницу с сообщением: Письмо со ссылкой для подтверждения аккаунта отправлено на {email}.
- В случае неуспешной регистрации пользователя вы можете передать сообщение об ошибке, которое будет отображено в виджете авторизации. Для этого в ответе на запрос для создания пользователя передайте объект
error
, в котором:- В параметре
code
укажите код ошибки, например011-002
. - В параметре
description
укажите текст ошибки.
- В параметре
- json
1{
2 "error": {
3 "code": "011-002",
4 "description": "<string>"
5 }
6}
Аутентификация по имени пользователя и паролю
- Клиент отправляет POST-запрос
Auth by username and password на сервер Xsolla Login. Запрос должен содержать заголовокAuthorization: Bearer {JWT}
и следующие обязательные параметры:- query-параметр
projectId
— ID варианта авторизации в Личном кабинете; - body-параметры:
username
— имя пользователя, допустимая длина: от 3 до 255 символов;password
— пароль, допустимая длина: от 6 до 100 символов.
- query-параметр
- Сервер Xsolla Login отправляет вебхук на URL для проверки существования пользователя. Ответ на вебхук должен иметь формат, описанный в сценарии взаимодействия. В ответе вы можете указать список пользовательских атрибутов и/или любой необходимый объект JSON. Объект JSON, переданный вами в ответе, записывается в поле
partner_data
JWT пользователя.
Пример вебхука на URL для проверки существования пользователя:
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"}'
Пример ответа на вебхук с атрибутами пользователей:
- 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:
- json
1{
2 "id": 123456,
3 "role": "scout"
4}
- В случае неуспешной аутентификации пользователя вы можете передать сообщение об ошибке, которое будет отображено в виджете авторизации. Для этого в ответе на вебхук для создания пользователя передайте объект
error
, в котором:- В параметре
code
укажите код ошибки, например011-002
.В параметреdescription
укажите текст ошибки.
- В параметре
- Сервер Xsolla Login генерирует JWT пользователя.
- Пользователь перенаправляется на
login_url
с query-параметромtoken
. В параметрtoken
записывается JWT пользователя.
Аутентификация без пароля по номеру телефона
- Клиент открывает форму аутентификации и предлагает пользователю ввести номер телефона.
- Пользователь вводит свой номер телефона.
- Клиент отправляет
POST
-запросStart auth by phone number на сервер Xsolla Login. Запрос должен содержать заголовокAuthorization: Bearer {JWT}
и следующие обязательные параметры:- query-параметр
projectId
— ID варианта авторизации в Личном кабинете; - body-параметр
phone_number
— номер телефона пользователя.
- query-параметр
- Клиент предлагает пользователю ввести код подтверждения.
- Пользователь вводит полученный код.
- Клиент отправляет
POST
-запросComplete auth by phone number на сервер Xsolla Login. Запрос должен содержать заголовокAuthorization: Bearer {JWT}
и следующие обязательные параметры:- query-параметр
projectId
— ID варианта авторизации в Личном кабинете; - body-параметры:
code
— код подтверждения;phone_number
— номер телефона пользователя;operation_id
— ID кода подтверждения.
- query-параметр
- Если это первая авторизация пользователя, сервер Xsolla Login отправляет вебхук на URL для входа без пароля. Ответ на вебхук должен иметь формат, описанный в сценарии взаимодействия. В ответе вы можете указать список пользовательских атрибутов и/или любой необходимый объект JSON. Объект JSON, переданный вами в ответе, записывается в поле
partner_data
JWT пользователя. - В случае неуспешной аутентификации пользователя вы можете передать сообщение об ошибке, которое будет отображено в виджете авторизации. Для этого в ответе на вебхук для создания пользователя передайте объект
error
, в котором:- В параметре
code
укажите код ошибки, например011-002
. - В параметре
description
укажите текст ошибки.
- В параметре
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"}'
Пример ответа на вебхук с атрибутами пользователей:
- 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:
- json
1{
2 "id": 123456,
3 "role": "scout"
4}
Аутентификация без пароля по email
- Клиент открывает форму аутентификации и предлагает пользователю ввести email-адрес.
- Пользователь вводит свой email-адрес.
- Клиент отправляет
POST
-запросStart auth by email на сервер Xsolla Login. Запрос должен содержать заголовокAuthorization: Bearer {JWT}
и следующие обязательные параметры:- query-параметр
projectId
— ID варианта авторизации в Личном кабинете; - body-параметр
email
— email-адрес пользователя.
- query-параметр
- Клиент предлагает пользователю ввести код подтверждения.
- Пользователь вводит полученный код.
- Клиент отправляет
POST
-запросComplete auth by email на сервер Xsolla Login. Запрос должен содержать заголовокAuthorization: Bearer {JWT}
и следующие обязательные параметры:- query-параметр
projectId
— ID варианта авторизации в Личном кабинете; - body-параметры:
code
— код подтверждения;email
— email-адрес пользователя;operation_id
— ID кода подтверждения.
- query-параметр
- Если это первая авторизация пользователя, сервер Xsolla Login отправляет вебхук на URL для входа без пароля по email. Ответ на запрос должен иметь формат, описанный в сценарии взаимодействия. В ответе вы можете указать список пользовательских атрибутов и/или любой необходимый объект JSON. Объект JSON, переданный вами в ответе, записывается в поле
partner_data
JWT пользователя. - В случае неуспешной аутентификации пользователя вы можете передать сообщение об ошибке, которое будет отображено в виджете авторизации. Для этого в ответе на вебхук для создания пользователя передайте объект
error
, в котором:- В параметре
code
укажите код ошибки, например011-002
. - В параметре
description
укажите текст ошибки.
- В параметре
Пример вебхука:
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"}'
Пример ответа на вебхук с атрибутами пользователей:
- 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:
- json
1{
2 "id": 123456,
3 "role": "scout"
4}
Аутентификация через социальные сети
Для получения информации о пользователе при аутентификации через социальные сети задайте URL для входа через социальные сети в настройках вашего варианта авторизации в Личном кабинете (раздел База пользователей > Хранилище > Собственное хранилище). На него будет отправляться запрос с данными, полученными от социальной сети.
Сценарий аутентификации:
- Клиент отправляет
POST
-запросAuth via social network на сервер Xsolla Login. Запрос должен содержать заголовокAuthorization: Bearer {JWT}
и следующие обязательные параметры:- query-параметр
projectId
— ID варианта авторизации в Личном кабинете; - path-параметр
provider_name
— название социальной сети, подключенной в Личном кабинете. Возможные варианты:amazon
,apple
,babka
,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
.
- query-параметр
- Пользователь выполняет аутентификацию в социальной сети.
- Сервер Xsolla Login обрабатывает данные пользователя, полученные от социальной сети, и отправляет вебхук на URL для входа через социальные сети. Ответ на вебхук должен иметь формат, описанный в сценарии взаимодействия. В ответе вы можете указать список пользовательских атрибутов и/или любой необходимый объект JSON. Объект JSON, переданный вами в ответе, записывается в поле
partner_data
JWT пользователя.
Пользовательские данные передаются в заголовке Authorization
в виде временного gateway-токена (серверного токена с параметром “request_type”: “gateway_token”)
).
Основные поля gateway-токена:
Поле | Тип | Описание |
---|---|---|
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 | Email-адрес пользователя. | |
sub | string (UUID) | ID пользователя, записанный на стороне сервера Xsolla Login. Обязательный. |
username | string | Имя пользователя. |
provider | string | Имя социальной сети, через которую пользователь авторизовался. Обязательный. |
id | string | ID пользователя в социальной сети. Обязательный. |
social_access_token | string | Токен доступа социальной сети, через которую аутентифицировался пользователь. Чтобы подключить передачу этого поля, обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com. |
partner_data | string | Данные любого типа, возвращаемые вашим сервером в теле ответа во время аутентификации. Чтобы подключить передачу этого поля, обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com. |
- 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 для входа через социальные сети:
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'
Пример ответа на вебхук с атрибутами пользователей:
- 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:
- json
1{
2 "id": 123456,
3 "role": "scout"
4}
- В случае неуспешной аутентификации пользователя вы можете передать сообщение об ошибке, которое будет отображено в виджете авторизации. Для этого в ответе на вебхук для создания пользователя передайте объект
error
, в котором:- В параметре
code
укажите код ошибки, например011-002
. - В параметре
description
укажите текст ошибки.
- В параметре
Сброс пароля пользователя
- Клиент отправляет
POST
-запросReset password на сервер Xsolla Login. Запрос должен содержать заголовокAuthorization: Bearer {JWT}
и следующие обязательные параметры:- query-параметр
projectId
— ID варианта авторизации в Личном кабинете; - body-параметры
username
— имя пользователя, допустимая длина: от 3 до 255 символов.
- query-параметр
- Сервер Xsolla Login отправляет письмо пользователю для подтверждения сброса пароля.
- Пользователь подтверждает сброс пароля в письме и переходит на страницу ввода нового пароля.
- Пользователь вводит новый пароль.
- Сервер Xsolla Login отправляет вебхук на URL для сброса пароля.
- В случае неуспешного сброса пароля вы можете передать сообщение об ошибке, которое будет отображено в виджете авторизации. Для этого в ответе на вебхук для создания пользователя передайте объект
error
, в котором:- В параметре
code
укажите код ошибки, например011-002
. - В параметре
description
укажите текст ошибки.
- В параметре
Пример вебхука на URL для сброса пароля:
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"}}'
Продолжить чтение
Полезные ссылки
Как подключить собственное хранилищеНашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.