Single Sign-on

How it works

If you have several connected services with a common single account for user authentication, you can use Single Sign-on. The game website works as a service. It will allow a user to enter their credentials only once. After that, when opening one of the connected services, the user will already be authenticated.

Interaction flow

1. Unauthenticated user opens one of the services.
2. Your client sends the Check user authentication request to the Xsolla Login server and gets error 401.
3. Your client opens the authentication form (Login Widget or your login UI) for the user.
4. The user authenticates via a username and password or via a social network.

5. Your client authenticates the user in your Login project:
   • The following requests are used when integrating Login via API calls:
     • authentication via username and password (JWT and OAuth 2.0).
     • authentication via social networks (JWT and OAuth 2.0).
   • The OAuth 2.0 protocol is used when integrating Login via the Widget.
   The user session data is saved on the Xsolla Login server. The server sends login_uri that contains redirect_uri with code in the query-parameter.

6. Your client redirects the user to redirect_uri.
7. Your server sends the Generate JWT request to exchange the received code for a JWT. The user is authenticated on the service.
8. The user opens another service.
9. Your client sends the Check user authentication request to the Xsolla Login server and receives login_uri that contains redirect_uri with code in the query-parameter.
10. Your server sends the Generate JWT request to exchange the received code for a JWT. The user is authenticated on the second service.

Differentiating access rights for different services

To differentiate user account access rights for different services, you can use special values of the scope parameter (e.g. scope=playfab) in different OAuth 2.0 clients.

Who can use it

Partners who have already integrated Login and use Xsolla database or PlayFab.

How to get it

To connect Single Sign-on:

1. Connect the OAuth 2.0 protocol.
2. Implement the getting user session request callback.

Connecting OAuth 2.0 protocol

Follow the instruction to connect the OAuth 2.0 protocol. You can use one OAuth 2.0 client for all services or create a separate OAuth 2.0 client for every service.

Calling request for getting user session

Implement the Check user authentication request callback when opening your service. The request should be executed before opening the authentication form for the user. For authentication, use the OAuth 2.0 client parameters of the exact service the user wants to authenticate in.

Example of the request:

GET https://login.xsolla.com/api/oauth2/sso?client_id=<client_id>&redirect_uri=<redirect_uri>&scope=<scope>&state=<state>&response_type=code HTTP/1.1

curl --request GET \
  --url 'https://login.xsolla.com/api/oauth2/sso?redirect_uri=redirect_uri&response_type=code&state=state&scope=scope&client_id=client_id'

Example of the response when the user is authenticated:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "login_url": "<redirect_uri>?code=<code>"
}

To get a user JWT:

1. Your client implements and uses the request that redirects the user to the received redirect_uri.
2. Your server sends the Generate JWT request with received code and grant_type=authorization_code for getting a JWT.

Example of the response when the user is not authenticated:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "code": "003-040",
    "description": "User is unauthorized."
  }
}