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 pane of a Login option.
3. Go to the Security block and select the OAuth 2.0 section.

4. Click Add OAuth 2.0 client.

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

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

7. 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 pane of a Login option.
3. 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.

Integration on application side

The following integration options are available:

• via the Login widget
• via the Login API
• via Xsolla SDKs

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:

<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

• Unity
• Unreal Engine
• Android
• iOS
• Cocos Creator

Getting access token

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

• authorization_code for the grant_type parameter;
• offline for the scope parameter (required for subsequent renewal of the access token);
• client_id — OAuth 2.0 client setting value;
• client_secret — OAuth 2.0 client setting value (not required for public OAuth 2.0 client);
• redirect_uri — the value that was set when connecting the OAuth 2.0 client in the Publisher Account;
• code received after successful user authentication or registration in the application.

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:

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:

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