OAuth 2.0 protocol

Overview

Xsolla Login supports the OAuth 2.0 standard protocol for user registration and authentication. OAuth 2.0 separates the client role from the resource owner. The resources are controlled by the owner and hosted by the server. To access protected resources, the client gets an access token — a string defining access attributes, and doesn’t use the resource owner’s credentials. With the approval of the resource owner, the server gives access tokens to third-party clients for usage. Detailed info on the OAuth 2.0 protocol is available on its official website. The user JWT is an access_token.

The interaction flow between the client and the Xsolla Login server is the following:

To set up the OAuth 2.0 protocol:

1. Connect the Login product.
2. Set up Xsolla storage or PlayFab.
3. Connect OAuth 2.0 client.

Connecting OAuth 2.0 client

1. Go to Publisher Account and open your Login project > General settings > Authorization > OAuth 2.0 authentication.
2. Click Connect.
3. Specify in the modal window:
   1. Client name.
   2. OAuth 2.0 redirect URIs. Parameter redirect_uri for the Login API calls.
   3. Authentication type: public or confidential.

4. Click Connect.

Getting OAuth 2.0 client settings

To get the client ID and secret key:

1. Go to Publisher Account and open your Login project > General settings > Authorization > OAuth 2.0 authentication.
2. In the client block, click Connect/Edit.

A window with these settings opens automatically after connecting the OAuth 2.0 client. Client ID and secret key match the client_id and client_secret parameters for the Login API calls. Use these settings when working with OAuth 2.0 clients.

Integration on the application side

These are the following possible ways to integrate:

• via the Login widget
• via the Login API
• via the Login SDK

When working with Login API, you can also use the scope parameter. Possible parameter values:

• offline for updating the access token. Passing scope=offline to the registration or authentication call is required.
• email for the additional user email request when authenticating the user via a social network. Set this value if you have integrated the product Login via the previous version of the Login widget. See Collecting emails during social authentication instruction.

Integration via the Login widget

If you integrate Login via the widget:

• For widget 2.0: Add the client_id, response_type, state and redirect_uri to the initialization code. Also, you can add the scope parameter. You should specify the HTTP/HTTPS scheme in the redirect_uri parameter, as in https://example.com.

<script>
const xl = new XsollaLogin.Widget({
  projectId: 'LOGIN_PROJECT_ID',
  preferredLocale: 'en_US',
  clientId: 'CLIENT_ID',
  responseType: 'code',
  state: 'CUSTOM_STATE',
  redirectUri: 'REDIRECT_URI',
  scope: 'SCOPE'
});
</script>

• For the previous version of widget: Add the redirect_uri and client_id parameters to the initialization code. Also, you can add the scope parameter. You should specify the HTTP/HTTPS scheme in the redirect_uri parameter.

<script type="text/javascript">
XL.init({
  projectId: 'LOGIN_PROJECT_ID',
  locale: 'en_US',
  redirectUri: 'REDIRECT_URI',
  clientId: 'CLIENT_ID',
  state: 'CUSTOM_STATE',
  scope: 'SCOPE'
});
</script>

Integration via the Login API

For user registration and authentication, use the API requests for the OAuth 2.0 protocol. If you have already integrated requests for the JWT standard, replace them by calling the OAuth 2.0 requests.

When calling API authentication requests, exchange the code parameter for an access token.

Integration via the Login SDK

Login SDK supports the OAuth 2.0 protocol-based authentication. For setting up the OAuth 2.0 client, choose the game engine and follow the instructions:

• Unity
• Unreal Engine
• Android

Getting access token

Use the Generate JWT call with the grant_type=authorization_code parameter to get the access token. The code parameter required for getting the token is passed to redirect_uri after user authentication or registration.

POST https://login.xsolla.com/api/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=11&client_secret=vGbXcsQ0CEW233m2qldYkd5IxbnRKoWt2YiBOgHYJGRGQwtIAdtxgxT64ik&code=ldYkd5IxbnRKoWt2YiBOgHYJGRGQwtIAdtxgxT64ik&grant_type=authorization_code&redirect_uri=https://my-website.com/callback

curl --request POST \
  --url https://login.xsolla.com/api/oauth2/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data client_secret=vGbXcsQ0CEW233m2qldYkd5IxbnRKoWt2YiBOgHYJGRGQwtIAdtxgxT64ik \
  --data client_id=11 \
  --data redirect_uri=https://my-website.com/callback \
  --data code=ldYkd5IxbnRKoWt2YiBOgHYJGRGQwtIAdtxgxT64ik

Updating access token

The Xsolla Login server generates an access token and creates a new session for each successfully authenticated user. By default, the token has an expiration time of 1 hour.

To update the token, use the Generate JWT call:

• For the first call, use the grant_type=authorization_code parameter and the code parameter that was received after user authentication.
• For the subsequent calls after the token expires, use the grant_type=refresh_token parameter and the latest refresh_token value.

POST https://login.xsolla.com/api/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=11&client_secret=vGbXcsQ0CEW233m2qldYkd5IxbnRKoWt2YiBOgHYJGRGQwtIAdtxgxT64ik&grant_type=refresh_token&refresh_token=111dfgdfgdf&redirect_uri=https://my-website.com/callback

curl --request POST \
  --url https://login.xsolla.com/api/oauth2/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=refresh_token \
  --data client_secret=vGbXcsQ0CEW233m2qldYkd5IxbnRKoWt2YiBOgHYJGRGQwtIAdtxgxT64ik \
  --data client_id=11 \
  --data redirect_uri=https://my-website.com/callback \
  --data refresh_token=111dfgdfgdf