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 calls, as a client. The interaction flow between the client and the Xsolla Login server is the following:
- The client sends requests to the Xsolla Login server. The requests format is described in JWT and General endpoints.
- The Xsolla Login server sends requests to your server. Follow the instruction to validate the requests.
- The Xsolla Login server processes a response from your server and returns the result to the client.
- The client processes the response.
User registration
- The client sends the
Register a new user request to the Xsolla Login server. - 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:
- http
POST /registration HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer {JWT}
{
"email": "john@gmail.com",
"password": "123456"
}
- User data is written to the Xsolla database while the
email is flagged as unconfirmed. The user will receive an account confirmation email. - 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
- The client sends the
Auth by username and password request to the Xsolla Login server. - 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:
- http
POST /authentication HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer {JWT}
{
"email": "john@gmail.com",
"password": "123456"
}
- The Xsolla Login server generates a user JWT.
- 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
- The client opens an authentication form so the user can enter their phone number.
- The user enters their phone number.
- The client sends the
Start auth by phone number request to the Xsolla Login server. - The client shows a field so the user can fill in the verification code.
- The user enters the received verification code.
- The client sends the
Complete auth by phone number request to the Xsolla Login server. - 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:
- http
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:
- The client sends the
Auth via social network request to the Xsolla Login server. - The user logs in to a social network.
- 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
Claim | Type | Description |
---|---|---|
exp | Unix Timestamp | The date and time of the JWT expiry. The JWT lifetime is 7 minutes. Required. |
iat | Unix Timestamp | The date and time JWT is issued. Required. |
iss | string | The service that signed the JWT: https://login.xsolla.com. Required. |
request_type | string | Constant: gateway_request. Required. |
xsolla_login_project_id | string (UUID) | Your Login project ID in Publisher Account. Required. |
string | User email address. | |
sub | string (UUID) | User ID written on the Xsolla Login server side. Required. |
username | string | Username. |
provider | string | Name of a social network used for authentication. Required. |
id | string | User ID in a social network. Required. |
Example of a token payload:
- json
{
"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:
- http
POST /social/authentication HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer {JWT}
{}
User password reset
- The client sends the
Reset password request to the Xsolla Login Server. - The Xsolla Login server sends the user a password reset confirmation email.
- After confirming password reset in the email, the user is redirected to the page where they can enter a new password.
- The user enters a new password.
- The Xsolla Login server sends a request to the Password reset URL. The response must have the format described in this instruction.
Request example:
- http
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:
Connect custom storage
- In Publisher Account go to your Login project > General settings section.
- In the User data storage block, select Custom storage.
- Enter the URLs for sending API requests:
- User verification URL
- New user URL
- Password reset URL
- Email change URL
- Passwordless login with phone URL
- 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:
- Copy the value of the secret key (Publisher Account > your Login project > General settings > Secret key).
- Choose a library and pass the value of the secret key to the validation function.
- 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 | Type | Description |
---|---|---|
exp | Unix Timestamp | The date and time of the JWT expiry. The JWT lifetime is 7 minutes. |
iat | Unix Timestamp | The date and time JWT is issued. |
iss | string | The service that signed the JWT: https://login.xsolla.com. |
request_type | string | Constant: gateway_request. |
xsolla_login_project_id | string (UUID) | Your Login project ID in Publisher Account. |
Example of a token payload:
- json
{
"exp": 1573635020,
"iat": 1573634600,
"iss": "https://login.xsolla.com",
"request_type": "gateway_request",
"xsolla_login_project_id": "00000000-0000-0000-0000-000000000000"
}