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.

Note
For details on the client types, see The OAuth 2.0 Authorization Framework. When working with Login API:
  • The confidential client requires the use of the client ID and secret key when calling the Generate JWT call to get and update the access token.
  • The public client only requires the use of client ID.
  • The JWT auth by username and password call is only available for the public client.

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

Note
For OAuth 2.0 implementation on your application side, it is recommended to use well-debugged code provided by client libraries. It will help you protect yourself and your users.

Integration on application side

These are the following possible ways to integrate:

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 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.

Copy
Full screen
Small screen
<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.

Copy
Full screen
Small screen
<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 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 Xsolla SDKs

Xsolla SDKs support the OAuth 2.0 protocol-based authentication. For setting up the OAuth 2.0 client, choose the game engine and follow the instructions:

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.

Copy
Full screen
Small screen
http
  • http
  • curl
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.

Copy
Full screen
Small screen
http
  • http
  • curl
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

Was this article helpful?
Thank you!
Is there anything we can improve? Message
We’re sorry to hear that
Please explain why this article wasn’t helpful to you. Message
Thank you for your feedback!
We’ll review your message and use it to help us improve your experience.
Rate this page
Rate this page
Is there anything we can improve?

Don’t want to answer

Thank you for your feedback!
Last updated: June 17, 2021

Found a typo or other text error? Select the text and press Ctrl+Enter.

Report a problem
We always review our content. Your feedback helps us improve it.
Provide an email so we can follow up
Thank you for your feedback!