OAuth 2.0 protocol

Overview

The Login product supports the OAuth 2.0 standard protocol for user registration and authentication. The OAuth 2.0 standard authorization protocol focuses on the ease of client application development and allows you to renew access tokens without user participation. Detailed info on the OAuth 2.0 protocol is available on its official website. The user JWT is used as the access token.

The interaction between your OAuth 2.0 client and the Xsolla Login server is illustrated below:

To set up the OAuth 2.0 protocol:

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

Connecting OAuth 2.0 client

  1. Open your project in Publisher Account and go to the Login section.
  2. Click Configure in the panel of a Login option.
  3. On the navigation page, go to the Security block and select the OAuth 2.0 section.

  1. Click Add OAuth 2.0 client.

  1. In the modal window, specify:
    • Client name.
    • URI(s) where users are redirected after account verification, successful authentication, or password reset confirmation.
    • Authentication type: public, confidential, or server.

Note
For information on the authentication types (client types), see The OAuth 2.0 Authorization Framework and Confidential and Public Applications. The server and confidential authentication types use a confidential client, but differ in how they grant access to the application (see Application Grant Types for more details):
  • for server authentication: grant_type=client_credentials;
  • for confidential and public authentication: grant_type=authorization_code or grant_type=refresh_token.
If you use integration via the Login API, the following features should be taken into account when choosing the type of authentication:
  • The confidential client requires the use of the client ID and secret key when calling the Generate JWT method to get or update an access token.
  • The public client requires the use of the client ID only.
  • The JWT auth by username and password method call is only available for public authentication.

  1. Click Connect.

  1. A client ID and secret key will be generated that are required to set up OAuth 2.0 authentication in your application.

  1. In the dialog window, copy the Client ID and Secret key using the copy buttons.

Getting OAuth 2.0 client settings

If you did not copy the client ID and secret key when connecting the OAuth 2.0 client, you need to do the following to access this data:

  1. Open your project in Publisher Account and go to the Login section.
  2. Click Configure in the panel of a Login option.
  3. On the navigation page, go to the Security block and select the OAuth 2.0 section.
  4. In the line of the required OAuth 2.0 client:
    • Copy the contents of the Client ID field.
    • Click Client key to copy the secret key.

The client ID and secret key correspond to the client_id and client_secret parameters in the Login API methods. Use these values when working with OAuth 2.0 clients.

Note
When you implement OAuth 2.0 authentication in your application, we recommend that you use the code from the client libraries. This will help you protect your information and your users’ data.

Integration on application side

The following integration options are available:

When working with the Login API and the Login widget, the scope parameter is used. It can take the following values:

  • offline to refresh the access token. Pass scope=offline to the registration or authentication method.
  • email to request the user’s email address when authenticating through a social network. If you have integrated the Login product via the Login API, pass scope=email to the registration or authentication method. When integrating via the Login widget, configure the collection of user email addresses using the Collecting email addresses and phone numbers instruction.

Integration via Login widget

If you have configured integration via the Login widget, add the client_id, response_type, state, and redirect_uri parameters to the initialization code. In the redirect_uri parameter, you must specify the value that was set when connecting the OAuth 2.0 client in the Publisher Account. You can also add the scope parameter.

Example of the request:

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>

Integration via Login API

Use the API methods for the OAuth 2.0 protocol to register and authenticate users. If you have already integrated methods for the JWT standard, replace them with OAuth 2.0 method calls.

When calling authentication methods, exchange the received 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 or platform and follow the instructions:

Getting access token

To get a user access token, use the Generate JWT method with the following parameter values:

The API method response will return the following tokens:

  • access_token — an access token. The default validity period is 1 hour.
  • refresh_token — a refresh token. The validity period is not limited.

Example of the request:

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

Refreshing access token

When the access token expires, use the Generate JWT method to refresh it with the grant_type parameter equal to refresh_token and the last value of the refresh token (refresh_token) received.

The API method response will return a new pair of tokens: the access_token access token and the refresh_token refresh token, which can then be refreshed again.

Example of the request:

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

Note
The Login product supports a maximum of five simultaneous user sessions by default. With each new user authentication, the access_token and refresh_token token pair received by that user earlier than the last five token pairs becomes invalid. To change the limit on the number of simultaneous user sessions, contact your Account Manager.
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: August 31, 2022

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!