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.

  %%{init: {'themeVariables': { 'noteBkgColor': 'transparent', 'noteBorderColor': 'transparent' }}}%%
sequenceDiagram
  participant U as User
  participant CS1 as Connected service 1
  participant XL as Xsolla Login server
  participant LW as Login widget
  participant CS2 as Connected service 2
  U->>CS1: Opens service
  CS1->>XL: Sends request to check user authentication
  activate XL
  XL-->>CS1: Sends “Unauthorized” error (401)
  deactivate XL
  CS1->>LW: Opens authentication form
  U->>LW: Enters credentials
  activate LW
  LW->>XL: Authenticates user
  deactivate LW
  activate XL
  XL-->>LW: Returns link with authorization code
  deactivate XL
  activate LW
  LW-->>CS1: Redirects user to received link
  deactivate LW
  activate CS1
  CS1->>XL: Sends request to generate user’s JWT
  deactivate CS1
  activate XL
  XL-->>CS1: Returns user’s JWT
  deactivate XL
  U->>CS2: Opens another service
  activate CS2
  CS2->>XL: Sends request to check user authentication
  deactivate CS2
  activate XL
  XL-->>CS2: Redirects user to received link
  deactivate XL
  activate CS2
  CS2->>XL: Sends request to generate user’s JWT
  deactivate CS2
  activate XL
  XL-->>CS2: Returns user’s JWT
  deactivate XL

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, Firebase, or PlayFab database.

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:

1GET 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

1curl --request GET \
2  --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:

1HTTP/1.1 200 OK
2Content-Type: application/json
3
4{
5  "login_url": "<redirect_uri>?code=<code>"
6}

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:

1HTTP/1.1 401 Unauthorized
2Content-Type: application/json
3
4{
5  "error": {
6    "code": "003-040",
7    "description": "User is unauthorized."
8  }
9}