How to set up custom storage

How it works

You can use a custom storage to save user data. The user data is stored at Xsolla’s side too, but passwords are validated by a custom storage only.

If you use a custom storage, you have access to the following features:

• user registration
• authentication via username and password
• passwordless authentication via phone number
• authentication via social networks
• user password reset

You can use the login widget or your application, that uses Login API methods, as a client. The interaction flow between the client and the Xsolla Login server is the following:

1. The client sends requests to the Xsolla Login server. The requests format is described in JWT and General method groups.
2. The Xsolla Login server sends requests to your server. Follow the instruction to validate the requests.
3. The Xsolla Login server processes a response from your server and returns the result to the client.
4. The client processes the response.

User registration

1. The client sends the Register a new user 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 /registration HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer {JWT}

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

3. User data is written to the Xsolla database while the email is flagged as unconfirmed. The user will receive an account confirmation email.
4. 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 via the Username and Password

1. The 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 /authentication HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer {JWT}

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

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

Passwordless authentication via a phone number

1. The client opens an authentication form so the user can enter their phone number.
2. The user enters their phone number.
3. The client sends the Start auth by phone number request to the Xsolla Login server.
4. The client shows a field so the user can fill in the verification code.
5. The user enters the received verification code.
6. The client sends the Complete auth by phone number request to the Xsolla Login server.
7. If it is the first user authorization, the Xsolla Login server sends a request to the Passwordless login with phone URL. The response must be in the format described in this instruction.

Request example:

POST /authentication/phone HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer {JWT}

{
  "login": "+12025550140",
  "type": "phone"
}

Authentication via social networks

To get user data while authenticating via social networks, specify Social Auth Webhook URL. The request with data, received from a social network, will be sent to it. Send your Social Auth Webhook URL to the Account Manager to get access to this feature.

Authentication flow:

1. The client sends the Auth via social network request to the Xsolla Login server.
2. The user logs in to a social network.
3. The Xsolla Login server processes the user data received from a social network and sends a request to Social Auth Webhook URL. The response must be in the format described in this instruction.

The request contains data in the temporary token in the Authorization: Bearer <JWT> header. The user JWT passed in the request contains the following data:

Example of a token payload:

{
  "exp": 1573635020,
  "iat": 1573634600,
  "iss": "https://login.xsolla.com",
  "request_type": "gateway_request",
  "xsolla_login_project_id": "00000000-0000-0000-0000-000000000000",
  "sub": "00000000-0000-0000-0000-000000000000",
  "email": "example@test.com",
  "username": "Smith707",
  "provider": "google",
  "id": "123",
}

Request example:

POST /social/authentication HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer {JWT}

{}

User password reset

1. The client sends the Reset password request to the Xsolla Login Server.
2. The Xsolla Login server sends the user a password reset confirmation email.
3. After confirming password reset in the email, the user is redirected to the page where they can enter a new password.
4. The user enters a new password.
5. The Xsolla Login server sends a request to the Password reset URL. The response must have the format described in this instruction.

Request example:

POST /reset HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer {JWT}

{
  "username": "john@gmail.com",
  "fields": {
    "password": "NewPa$$word1"
  }
}

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 the client:

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

Connect custom storage

1. In Publisher Account go to your Login project > General settings section.
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
   • Passwordless login with phone 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 in the response body, if needed. Passed data is written to a JWT > partner_data parameter.
   • Other HTTP status codes for unsuccessful requests.

Set up processing of requests from the Xsolla Login server

Xsolla Login server requests are sent to your URLs with the Authorization: Bearer <JWT> header. 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.

Example of a token payload:

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