Skip to content

External authentication provider linking practical guide

External authentication provider linking is the task of connecting an additional login method to the account of a user who has already logged in. An external authentication provider is a service, such as Google or Apple, that authenticates users on the app's behalf, and users use it as a login method. Once linking is complete, whichever linked login method users log in with, they log in with the same Player ID and keep using the same play data.

To implement it, you must combine Hive Console settings, Hive Axyl SDK calls, recipe code calls, and app code. With the recipe code, the authentication of the account to link and the linking call come down to a single method.

The work required to implement external authentication provider linking starts with registering the login method to link in the Hive Console and ends with displaying the screen that matches the linking result.

The work in each step falls into one of the following five categories.

Category Owner Description
Hive Console App operator Settings you configure in the Hive Console.
Hive Axyl SDK App developer Hive Axyl SDK methods the app calls.
Add-on App developer Hive Axyl SDK extension packages that display the authentication screen of an external authentication provider.
Recipe code App developer Recipe methods the app calls.
App code App developer Parts the app implements directly without going through Hive Axyl.

External authentication provider linking has no Hive Axyl Server API calls. The app does not call the Add-on directly; the recipe calls it on the app's behalf, so the Add-on appears in the list of tasks the recipe performs internally rather than as a step category. For the meaning of the parameters and the response fields, see the detailed procedure linked in each step.

A guest account can be restored only with the credentials stored on the device, so users lose the account when they delete the app or change devices. When you link a login method to a guest account, users log in to the same Player ID with that login method on any device.

Once the first linking is complete, the Hive Axyl authentication server invalidates the guest token of that Player ID. After linking, the way into that account is the linked login method, not the guest credentials. The app must delete the values in the store created in Prepare the guest credential store, and Clean up guest credentials explains how to handle this.

The Hive Axyl SDK provides a single linking method, LinkProviderAsync(), but before calling it, the app must first obtain the user identifier and the authentication result of the account to link. How to receive those values differs for each login method, and the app must also check by itself that the login session did not change while the authentication screen was displayed.

A recipe is source code that completes that combination in advance. Instead of installing it as a package, you copy it into your project.

Category Location Characteristics
Hive Axyl SDK Unity package com.com2usplatform.hiveaxyl.* You install and use it. It provides authentication features as fine-grained methods.
Recipe Assets/Recipes/LinkProvider/ You copy and use it. Plain C# code that groups SDK calls by purpose.
Usage example Assets/RecipeExamples/Authentication/LinkProviderExample.cs Code you read for reference. Its comments explain the recipe call order and the parts the app must implement for each result.
Recipes are code you copy and use

Recipes are copied into your app and become your app's code. You can use them as is or modify them to fit your app's policies.

The linking recipe reuses, as is, the code that performs authentication when logging in with an external authentication provider. Login methods the app already provides become linking targets without additional implementation.

There is no recipe for unlinking. To disconnect a linked login method, you must call the Hive Axyl SDK methods directly, so see Unlink accounts.

The recipe links five login methods: Google, Apple, Google Play Games, Steam, and X. Google, Apple, and Steam each have two authentication methods, so choose the one that fits the OSs your app supports. Only one login method of the same kind is linked to a single Player ID.

Login method Authentication method OS used
Google Android native account selection screen Android
Google Browser login Android, iOS, macOS, Windows
Apple Apple native login screen iOS, macOS
Apple Browser login Android, Windows
Google Play Games Google Play Games login Android
Steam Steamworks authentication ticket Windows, macOS
Steam Browser login Android, iOS
X Browser login Android, iOS, macOS, Windows

You do not link username accounts with this recipe. To link a username, you must call the Hive Axyl SDK methods directly, so see Link accounts and get linked login methods. Custom accounts are linked with a grant key issued to the app server. A grant key is a pre-authentication key that proves the app server has authenticated the user. For how to use it, see Link a custom account. Guests are not linking targets.

The recipe handles only the authentication of the account to link and the linking call on the app's behalf. The app implements the following items outside the recipe.

  • The link button and the screen that lists linked login methods
  • Control that prevents other account operations from overlapping during linking
  • The screen that asks users to choose when a conflict occurs
  • Deleting the saved guest credentials
  • The retry policy and user-facing messages when a failure occurs

The recipe does not choose an account on the user's behalf. The app logs in with another account or disconnects an already linked login method only after the user chooses to.

Before you start implementing, prepare the following items.

Item to prepare Required Category Where to check
Create a project Required Hive Console Create a project
Create an App ID Required Hive Console Create an App ID
Connect the SDK to your Unity project Required Hive Axyl SDK Connect the SDK to your Unity project
Logged-in user Required Recipe code Guest login practical guide, Username login practical guide, Custom account login practical guide

The recipe works only when there is an active session. An active session means the state in which login is complete and the Hive Axyl SDK identifies the user. If you call it without logging in, it fails with a FailedPrecondition error, so display the link button only to logged-in users.

Once you have completed the prerequisites, start Implement external authentication provider linking.