Custom Storage

How It Works

  1. Your application (client) sends requests to the Xsolla Login server. The requests format is described in the JWT and General methods groups.
  2. The Xsolla Login server sends requests to your server. Use the instruction to validate requests.
  3. The Xsolla Login server processes the response from your server and returns the result to your client.
  4. Your client processes this response.

Info: User information is stored both in your database and Xsolla. The passwords are kept in your database only.

Registration

  1. Your client sends the Register request to the Xsolla Login server.
  2. The Xsolla Login server sends a request to the New user URL. The response must be in the format described in this instruction.

Request example:

POST https://example.registration.com

Headers:
Content-Type: application/json
Authorization: Bearer {JWT}

Body:
{
  "email": "john@gmail.com",
  "password": "123456"
}

  1. User information is written to the Xsolla database, while:
    • The email parameter is flagged as unconfirmed. The user will receive an account confirmation email.
    • The password is not written.
  2. If you have integrated the Login Widget, the user will be redirected to the page with the following message: Please confirm your account following the instructions we sent to {email}.

Authentication by the Username and Password

  1. Your client sends the Auth by Username and Password request to the Xsolla Login server.
  2. The Xsolla Login server sends a request to the User verification URL. The response must be in the format described in this instruction.

Request example:

POST https://example.authentication.com

Headers:
Content-Type: application/json
Authorization: Bearer {JWT}

Body:
{
  "email": "john@gmail.com",
  "password": "123456"
}

  1. The Xsolla Login server generates a user JWT.
  2. The user is redirected to the login_url with a token query parameter. The token parameter contains the user JWT.

If there is no information about this user in the Xsolla database, a new entry is created, but the password is not written.

Password Reset

  1. Your client sends the Reset Password request to the Xsolla Login server.
  2. The Xsolla Login server sends a request to the Password reset URL. The response must be in the format described in this instruction. The user receives a password change verification email.

Request example:

POST https://example.reset.com

Headers:
Content-Type: application/json
Authorization: Bearer {JWT}

Body:
{
  "email": "john@gmail.com"
}

  1. A new password is written to your database.

Who Can Use It

Partners who have already integrated Login and implemented the JWT standard-based authentication.

How to Get It

To set up the connection between the Xsolla Login server and your application (client):

  1. Connect the custom storage.
  2. Set up the validation of requests from the Xsolla Login Server.

Connection of the Custom Storage

  1. Go to Publisher Account > your Login project > General settings.
  2. In the User data storage block, select Custom storage.
  3. Enter the URLs for sending API requests:
    • User verification URL,
    • New user URL,
    • Password reset URL,
    • Email change URL.
  4. Implement an API, which will respond in the following way:
    • HTTP 200/HTTP 204 for successful requests. A JSON containing additional user data can be placed to the response body, if needed. Passed data is written to a JWT > partner_data parameter.
    • Other HTTP status codes for unsuccessful requests.

Info: If you want a JWT to contain the user ID from your database, please contact your Account Manager.

Validation of Requests from the Xsolla Login Server

Xsolla Login server requests are sent to your URLs with the Authorization: Bearer <JWT> title. The JWT is signed with the secret key of your project.

To validate the JWT:

  1. Copy the value of the secret key (Publisher Account > your Login project > General settings > Secret key).
  2. Choose a library and pass the value of the secret key to the validation function.
  3. If the validation is successful, decode the JWT and make sure it includes the claims from the table below. Find and use a library for decoding.

Claim Description
exp The date and time of the JWT expiry in the Unix Timestamp format. The JWT lifetime is 7 minutes.
iat The date and time JWT is issued in the Unix Timestamp format.
iss The service that signed the JWT: https://login.xsolla.com.
request_type Constant: gateway_request.
xsolla_login_project_id Your Login project ID in Publisher Account.

Example:

{
  "exp": 1573635020,
  "iat": 1573634600,
  "iss": "https://login.xsolla.com",
  "request_type": "gateway_request",
  "xsolla_login_project_id": "00000000-0000-0000-0000-000000000000"
}