Skip to content

Get started

The way you implement external authentication provider login differs slightly for each method. However, the login flow and the values the app client must prepare are the same for all login methods. Check the common parts on this page first, and then implement each login method.

Login flow

The Hive Axyl SDK does not handle the entire login procedure for you; it provides the features needed for login. The app client itself implements OS branching, PKCE value generation, nonce generation, deviceKey generation and storage, and the login screen UI, and completes login by calling the following features in order.

  • Add-on for each login method: Gets credentials by opening the native authentication screen of the OS
  • Web login session: Gets credentials by opening the external authentication provider's login page, for combinations without a native Add-on
  • IAuthService: Sends credentials to the Hive Axyl authentication server for login processing and receives an authorization code
  • ITokenService: Exchanges the authorization code for an access token and a refresh token
  • ISessionManager: Completes login by registering the issued tokens in the session

The login flow is divided into the 'Direct Token flow' and the 'Authorization Code flow', depending on what the building block that gets credentials returns. Which flow applies is determined by the combination of the external authentication provider and the OS the app runs on. For the detailed combinations, see Login approach by OS.

Direct Token flow

In this flow, the credential step returns a value that the Hive Axyl authentication server can validate directly. There is no intermediate exchange step, so you use the obtained value as is in the login request.

  1. Call the Add-on for the login method or the web login session to get the user identifier (providerUserId) and the authentication result (providerToken).
  2. Call LoginProviderAsync() of Log in with an external authentication provider to receive an authorization code.
  3. Perform Issue tokens and activate the session to complete login.

Authorization Code flow

In this flow, the credential step returns only the external authentication provider's authorization code (providerCode). The Hive Axyl authentication server cannot validate this authorization code directly, so you go through one more exchange step before login.

  1. Call the Add-on for the login method or the web login session to get the external authentication provider's authorization code.
  2. Call ExchangeProviderTokenAsync() of Exchange external authorization codes to exchange the authorization code for providerUserId and providerToken.
  3. Call LoginProviderAsync() of Log in with an external authentication provider to receive an authorization code.
  4. Perform Issue tokens and activate the session to complete login.
Note

In both flows, the authorization code received in step 2 or step 3 is a value issued by the Hive Axyl authentication server. It is different from the external authentication provider's authorization code received in step 1 of the Authorization Code flow.

Login approach by OS

Even for the same external authentication provider, the way to get credentials differs depending on the OS the app runs on. In the table below, check the approach for each OS your app will support, and install the matching Add-on.

External authentication provider Android iOS macOS Windows
Google account Google login Add-on Web login session Web login session Web login session
Apple Web login session Apple login Add-on Apple login Add-on Web login session
Google Play Games Google Play Games login Add-on Not supported Not supported Not supported
Steam Web login session Web login session Steam login Add-on Steam login Add-on
X Web login session Web login session Web login session Web login session
Google accounts and Google Play Games are different login methods

Sign in with Google uses the user's regular Google account identity, and Google Play Games login for mobile apps uses the Play Games gamer profile. The Hive Axyl authentication server also distinguishes the two login methods as Provider.Google and Provider.GooglePlayGames and handles them as different accounts. To offer both login methods, install and initialize both Add-ons.

The Add-on for each login method receives credentials by opening the native authentication screen of the OS. The web login session is a shared approach for combinations without a native Add-on: it opens the external authentication provider's login page in an authentication-only browser session that the OS provides. Apple login on Android and Windows and Steam login on Android and iOS receive the authentication result through the relay URL that Hive Axyl operates.

Flow by combination

Each combination follows the flow below.

Custom account login

Logging in with a custom account does not go through an external authentication provider. It logs in with a pre-authentication key that the app server obtained. Therefore, it does not need an Add-on, does not fall under either of the two flows above, and works the same way regardless of the OS. For how to implement it, see Log in with a custom account.

Values the app client prepares

The Hive Axyl SDK does not generate the following values, so the app client creates them itself and passes them in the login request.

Client ID

The Client ID of the security key that the Hive Console issues for each project. To check it, see Hive Console security key.

deviceKey

deviceKey is a device identification value that the app creates itself and puts in the login request. The Hive Axyl authentication server manages refresh tokens by the combination of player and device, so login requests for guest, username, external authentication provider, and custom accounts all require deviceKey, regardless of the account type. Put the same value in requests that create guest accounts and username accounts as well.

The Hive Axyl authentication server does not issue or interpret this value; it validates only the following conditions. If you send a value that does not meet the conditions, the login request fails. For failure handling, see Common error handling.

  • Length: 22 to 64 characters
  • Characters: ASCII characters, excluding spaces and control characters. Korean characters and emoji are not allowed
  • Format: Not validated

Conditions the app must meet

The server uses this value as the basis for distinguishing login sessions, but it does not check whether the value actually corresponds to a single device. Therefore, the app itself must meet the following conditions.

  • A different value for each device. A random value such as a UUID is recommended
  • A value saved on the device and reused continuously

Create it only once when the app first launches, keep it in secure storage, and reuse the same value in every later request that includes deviceKey. For how to store it, see Save credentials.

When it is created incorrectly or lost

The following problems occur when deviceKey is created in a way that does not meet the conditions or when the saved value is lost.

  • Created anew for every call: The server recognizes the same device as a different device every time.
  • A fixed value in the app code: A fixed value passes server validation as long as it meets the validation conditions, but every device of every user of that app sends the same value. If a user logs in on two devices, the server sees them as the same device, and the device that logs in later overwrites the login session of the earlier device. The user must log in again every time they switch between devices, and logging out on one device also ends the login on the other device. Because the server responses contain no errors, this symptom surfaces only after user inquiries pile up.
  • The saved value is lost: The existing refresh token no longer matches, so the session on that device becomes invalid, and the user must log in again with a new deviceKey. For a guest account, requesting Log in as a guest again with the saved GuestPlayerId and GuestToken and a new deviceKey recovers the same Player ID, and the device-level session history starts anew.

Creation example

The app decides the format. Use any scheme you like as is, such as UUID, hexadecimal strings, or base64. UUID v4 is recommended.

The following example creates a 32-character string by removing the hyphens from a UUID v4.

using System;

// deviceKey: Create it only once on first launch, save the value on the device, and keep reusing it.
static string NewDeviceKey() => Guid.NewGuid().ToString("N");

PKCE codeVerifier and codeChallenge

A pair of single-use values that protect the authorization code received in the login response from being misused for token issuance, even if it is stolen. Generate them right before calling the login method, put codeChallenge in the login request, and keep codeVerifier in the app until the token issuance step. For a generation example, see CreatePkce() in Create a guest account.

Warning

When you log in with X, and when you log in with a Google account while using PKCE in the authorization URL, you need an additional PKCE value for the external authentication provider. This value is used only for external authorization code exchange and is separate from the PKCE values for the Hive Axyl authentication server. For details, see Sign in with Google and Log in with X.

nonce

A single-use random value that lets the server verify that the authentication result was issued for this login request. It is used in the native Add-ons for Google account login and Apple login, and the format passed to each Add-on differs. 'Step 2. Log in' for each login method explains how to generate it.

Compose the login screen

The app does not decide on its own which buttons to show on the login screen; it follows the list that the Hive Axyl authentication server provides. This is because the list reflects both the login methods enabled in the Hive Console and the service country policy.

When you compose the login screen, call GetProviderListAsync() of Get supported login methods, and show only the login methods in the returned list.

Next steps