Собственное хранилище данных пользователей

Если вы используете собственное хранилище данных пользователей, Xsolla Login выступает как посредник и все данные для идентификации пользователя хранятся на вашей стороне. Xsolla Login передает данные аутентификации в токене в заголовке и теле вебхуков.

Примечание
Email-адреса пользователей, данные социальных сетей и атрибуты пользователей хранятся на стороне Xsolla. Пароли не хранятся на стороне Xsolla.
При использовании собственного хранилища данных пользователей вам доступны:
Примечание
Если вы тестируете интеграцию локально, то 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:

  1. Клиент отправляет запросы на сервер Xsolla Login. Формат запросов описан в группах методов JWT и Password.
  2. Сервер Xsolla Login отправляет вебхуки на ваш сервер. В заголовке передается серверный JWT, с параметром “request_type”: “gateway_token”. Чтобы настроить валидацию токена в запросе, следуйте инструкции. Часть данных для идентификации пользователя передается в теле вебхука.
  3. Чтобы подтвердить получение вебхука, ваш сервер должен вернуть:
    • 200, 201, или 204 HTTP-код в случае успешного ответа.
    • 400 HTTP-код с описанием проблемы, если указанный пользователь не был найден или если передана недействительная подпись. Ваш обработчик вебхуков также может возвращать 5xx HTTP-код при временных проблемах на вашем сервере.
  4. Сервер Xsolla Login обрабатывает ответ от вашего сервера и возвращает токен авторизации клиенту.
  5. Клиент обрабатывает ответ.

Если после идентификации пользователя вы хотите добавить информацию о пользователе в JWT, передайте в теле ответа JSON c любым набором параметров. Этот объект будет сохранен в поле JWT partner_data.

Примечание
Максимальная длина JSON c дополнительными данными о пользователе – 1000 символов.
Следующие данные могут быть добавлены в свойства пользовательского профиля:Вы также можете обновить атрибуты пользователя, для этого передайте массив объектов с атрибутами пользователя. Структура объектов описана ниже. Структура объекта с атрибутом пользователя:
ПараметрТипОписание
attr_type
stringТип атрибута, определяет уровень доступа пользователя к атрибутам сервиса:
  • client — значения для таких атрибутов вводятся пользователем или задаются согласно внутриигровой логике в клиентской части вашего приложения. Значения атрибутов этого типа вводятся пользователем или задаются в соответствии с внутриигровой логикой на стороне клиента. Например: имя и характеристики персонажа, уровень сложности игры и т. д. Используется по умолчанию.
  • server — значения для таких атрибутов задаются и редактируются только на серверной части вашего приложения. Рекомендуется использовать их для настройки характеристик игрового персонажа или пользовательских параметров, которые не должны регулярно меняться. Например: получение бонуса, ключевые параметры игрового персонажа, категории пользователей и т. д.
key
stringНазвание атрибута, которое используется для идентификации атрибута пользователя. Должно быть уникальным для каждого пользователя.
Максимальная длина: 256 символов. Вы можете использовать цифры, латинские буквы, подчеркивания и дефисы.
permission
string or nullТип доступа к атрибутам пользователя, влияет на список атрибутов, которые возвращают методы:
Возможные значения: public, private (по умолчанию).
read_only
stringЗащищен ли атрибут от изменений. По умолчанию false и изменять значения атрибута разрешено.
value
stringЗначение атрибута пользователя.
Максимальная длина: 256 символов.

Регистрация пользователя

  1. Клиент отправляет POST-запрос Register new user на сервер Xsolla Login. Запрос должен содержать заголовок Authorization: Bearer {JWT} и следующие обязательные параметры:
    • query-параметр projectId — ID варианта авторизации в Личном кабинете;
    • body-параметры:
      • username — имя пользователя, допустимая длина: от 3 до 255 символов;
      • password — пароль, допустимая длина: от 6 до 100 символов;
      • email — email-адрес, допустимая длина: от 1 до 255 символов.
  2. Сервер Xsolla Login отправляет вебхук на URL для создания пользователя. Ответ на вебхук должен иметь формат, описанный в сценарии взаимодействия. В ответе вы можете указать список пользовательских атрибутов и/или любой необходимый объект JSON. Объект JSON, переданный вами в ответе, записывается в поле partner_data JWT пользователя.

Пример вебхука:

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"}'

Пример ответа на вебхук с атрибутами пользователей:

Copy
Full screen
Small screen
 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:

Copy
Full screen
Small screen
1{ 
2    "id": 123456,
3    "role": "scout"
4}
  1. Информация о пользователе записывается в базу данных Xsolla. При этом параметр email отмечается как неподтвержденный.
  2. Письмо для подтверждения регистрации отправляется пользователю. Если вы интегрировали виджет авторизации, пользователь перенаправляется на страницу с сообщением: Письмо со ссылкой для подтверждения аккаунта отправлено на {email}.
  3. В случае неуспешной регистрации пользователя вы можете передать сообщение об ошибке, которое будет отображено в виджете авторизации. Для этого в ответе на запрос для создания пользователя передайте объект error, в котором:
    • В параметре code укажите код ошибки, например 011-002.
    • В параметре description укажите текст ошибки.
Пример объекта с сообщением об ошибке:
Copy
Full screen
Small screen
1{
2  "error": {
3    "code": "011-002",
4    "description": "<string>"
5  }
6}

Аутентификация по имени пользователя и паролю

  1. Клиент отправляет POST-запрос Auth by username and password на сервер Xsolla Login. Запрос должен содержать заголовок Authorization: Bearer {JWT} и следующие обязательные параметры: 
    • query-параметр projectId — ID варианта авторизации в Личном кабинете;
    • body-параметры:
      • username — имя пользователя, допустимая длина: от 3 до 255 символов;
      • password — пароль, допустимая длина: от 6 до 100 символов.
  2. Сервер Xsolla Login отправляет вебхук на URL для проверки существования пользователя. Ответ на вебхук должен иметь формат, описанный в сценарии взаимодействия. В ответе вы можете указать список пользовательских атрибутов и/или любой необходимый объект JSON. Объект JSON, переданный вами в ответе, записывается в поле partner_data JWT пользователя.

Пример вебхука на URL для проверки существования пользователя:

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"}'

Пример ответа на вебхук с атрибутами пользователей:

Copy
Full screen
Small screen
 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:

Copy
Full screen
Small screen
1{ 
2    "id": 123456,
3    "role": "scout"
4}
  1. В случае неуспешной аутентификации пользователя вы можете передать сообщение об ошибке, которое будет отображено в виджете авторизации. Для этого в ответе на вебхук для создания пользователя передайте объект error, в котором:
    • В параметре code укажите код ошибки, например 011-002.В параметре description укажите текст ошибки.
  2. Сервер Xsolla Login генерирует JWT пользователя.
  3. Пользователь перенаправляется на login_url с query-параметром token. В параметр token записывается JWT пользователя.
Примечание
Если в базе данных Xsolla нет записи о пользователе, создается новая.

Аутентификация без пароля по номеру телефона

  1. Клиент открывает форму аутентификации и предлагает пользователю ввести номер телефона.
  2. Пользователь вводит свой номер телефона.
  3. Клиент отправляет POST-запрос Start auth by phone number на сервер Xsolla Login. Запрос должен содержать заголовок Authorization: Bearer {JWT} и следующие обязательные параметры: 
    • query-параметр projectId — ID варианта авторизации в Личном кабинете;
    • body-параметр phone_number — номер телефона пользователя.
  4. Клиент предлагает пользователю ввести код подтверждения.
  5. Пользователь вводит полученный код.

  1. Клиент отправляет POST-запрос Complete auth by phone number на сервер Xsolla Login. Запрос должен содержать заголовок Authorization: Bearer {JWT} и следующие обязательные параметры:
    • query-параметр projectId — ID варианта авторизации в Личном кабинете;
    • body-параметры:
      • code — код подтверждения;
      • phone_number — номер телефона пользователя;
      • operation_id — ID кода подтверждения.
  2. Если это первая авторизация пользователя, сервер Xsolla Login отправляет вебхук на URL для входа без пароля. Ответ на вебхук должен иметь формат, описанный в сценарии взаимодействия. В ответе вы можете указать список пользовательских атрибутов и/или любой необходимый объект JSON. Объект JSON, переданный вами в ответе, записывается в поле partner_data JWT пользователя.
  3. В случае неуспешной аутентификации пользователя вы можете передать сообщение об ошибке, которое будет отображено в виджете авторизации. Для этого в ответе на вебхук для создания пользователя передайте объект error, в котором:
    • В параметре code укажите код ошибки, например 011-002.
    • В параметре description укажите текст ошибки.
Пример вебхука:
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"}'

Пример ответа на вебхук с атрибутами пользователей:

Copy
Full screen
Small screen
 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:

Copy
Full screen
Small screen
1{ 
2    "id": 123456,
3    "role": "scout"
4}

Аутентификация без пароля по email

  1. Клиент открывает форму аутентификации и предлагает пользователю ввести email-адрес.
  2. Пользователь вводит свой email-адрес.
  3. Клиент отправляет POST-запрос Start auth by email на сервер Xsolla Login. Запрос должен содержать заголовок Authorization: Bearer {JWT} и следующие обязательные параметры:
    •  query-параметр projectId — ID варианта авторизации в Личном кабинете;
    • body-параметр email — email-адрес пользователя.
  4. Клиент предлагает пользователю ввести код подтверждения.
  5. Пользователь вводит полученный код.

  1. Клиент отправляет POST-запрос Complete auth by email на сервер Xsolla Login. Запрос должен содержать заголовок Authorization: Bearer {JWT} и следующие обязательные параметры: 
    • query-параметр projectId — ID варианта авторизации в Личном кабинете;
    • body-параметры:
    • code — код подтверждения;
    • email — email-адрес пользователя;
    • operation_id — ID кода подтверждения.
  2. Если это первая авторизация пользователя, сервер Xsolla Login отправляет вебхук на URL для входа без пароля по email. Ответ на запрос должен иметь формат, описанный в сценарии взаимодействия. В ответе вы можете указать список пользовательских атрибутов и/или любой необходимый объект JSON. Объект JSON, переданный вами в ответе, записывается в поле partner_data JWT пользователя.
  3. В случае неуспешной аутентификации пользователя вы можете передать сообщение об ошибке, которое будет отображено в виджете авторизации. Для этого в ответе на вебхук для создания пользователя передайте объект error, в котором:
    • В параметре code укажите код ошибки, например 011-002.
    • В параметре description укажите текст ошибки.

Пример вебхука:

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"}'

Пример ответа на вебхук с атрибутами пользователей:

Copy
Full screen
Small screen
 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:

Copy
Full screen
Small screen
1{ 
2    "id": 123456,
3    "role": "scout"
4}

Аутентификация через социальные сети

Для получения информации о пользователе при аутентификации через социальные сети задайте URL для входа через социальные сети в настройках вашего варианта авторизации в Личном кабинете (раздел База пользователей > Хранилище > Собственное хранилище). На него будет отправляться запрос с данными, полученными от социальной сети.

Сценарий аутентификации:

  1. Клиент отправляет 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.
  2. Пользователь выполняет аутентификацию в социальной сети.
  3. Сервер Xsolla Login обрабатывает данные пользователя, полученные от социальной сети, и отправляет вебхук на URL для входа через социальные сети. Ответ на вебхук должен иметь формат, описанный в сценарии взаимодействия. В ответе вы можете указать список пользовательских атрибутов и/или любой необходимый объект JSON. Объект JSON, переданный вами в ответе, записывается в поле partner_data JWT пользователя.

Пользовательские данные передаются в заголовке Authorization в виде временного gateway-токена (серверного токена с параметром “request_type”: “gateway_token”)). Основные поля gateway-токена:

ПолеТипОписание
expUnix TimestampДата и время истечения JWT. Срок жизни JWT — 7 минут. Обязательный.
iatUnix TimestampДата и время выдачи JWT. Обязательный.
issstringСервис, подписавший JWT: https://login.xsolla.com. Обязательный.
request_typestringКонстанта: gateway_request. Обязательный.
xsolla_login_project_idstring (UUID)ID вашего варианта авторизации в Личном кабинете. Обязательный.
emailstringEmail-адрес пользователя.
substring (UUID)ID пользователя, записанный на стороне сервера Xsolla Login. Обязательный.
usernamestringИмя пользователя.
providerstringИмя социальной сети, через которую пользователь авторизовался. Обязательный.
idstringID пользователя в социальной сети. Обязательный.
social_access_tokenstringТокен доступа социальной сети, через которую аутентифицировался пользователь. Чтобы подключить передачу этого поля, обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.
partner_datastringДанные любого типа, возвращаемые вашим сервером в теле ответа во время аутентификации. Чтобы подключить передачу этого поля, обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.
Пример полезных данных токена:
Copy
Full screen
Small screen
 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 для входа через социальные сети:

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'

Пример ответа на вебхук с атрибутами пользователей:

Copy
Full screen
Small screen
 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:

Copy
Full screen
Small screen
1{ 
2    "id": 123456,
3    "role": "scout"
4}
  1. В случае неуспешной аутентификации пользователя вы можете передать сообщение об ошибке, которое будет отображено в виджете авторизации. Для этого в ответе на вебхук для создания пользователя передайте объект error, в котором:
    • В параметре code укажите код ошибки, например 011-002.
    • В параметре description укажите текст ошибки.

Сброс пароля пользователя

  1. Клиент отправляет POST-запрос Reset password на сервер Xsolla Login. Запрос должен содержать заголовок Authorization: Bearer {JWT} и следующие обязательные параметры:
    • query-параметр projectId — ID варианта авторизации в Личном кабинете;
    • body-параметры username — имя пользователя, допустимая длина: от 3 до 255 символов.
  2. Сервер Xsolla Login отправляет письмо пользователю для подтверждения сброса пароля.
  3. Пользователь подтверждает сброс пароля в письме и переходит на страницу ввода нового пароля.
  4. Пользователь вводит новый пароль.
  5. Сервер Xsolla Login отправляет вебхук на URL для сброса пароля.
  6. В случае неуспешного сброса пароля вы можете передать сообщение об ошибке, которое будет отображено в виджете авторизации. Для этого в ответе на вебхук для создания пользователя передайте объект error, в котором:
    • В параметре code укажите код ошибки, например 011-002.
    • В параметре description укажите текст ошибки.

Пример вебхука на URL для сброса пароля:

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"}}'
Была ли статья полезна?
Спасибо!
Что может сделать страницу еще лучше? Сообщение
Жаль, что так произошло
Расскажите, почему статья не была полезна. Сообщение
Спасибо за обратную связь!
Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.

Продолжить чтение

Последнее обновление: 8 мая 2025

Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.

Сообщите о проблеме
Мы постоянно улучшаем качество нашей документации. Ваш отзыв поможет нам в этом.
Укажите email-адрес, чтобы мы могли связаться с вами
Спасибо за обратную связь!
Не получилось отправить ваш комментарий
Попробуйте еще раз позже или напишите нам на doc_feedback@xsolla.com.