Custom account login practical guide
Custom account login is a way to log users in with accounts from a membership system that the app already operates. Because the app authenticates users directly without going through an external authentication provider such as Google or Apple, not only the app client but also the app server takes part in the login process.
To implement it, you must combine Hive Console settings, Hive Axyl Server API calls, Hive Axyl SDK initialization, recipe code calls, and the app server and app client implementations. With the recipe code, a single recipe method replaces the three Hive Axyl SDK calls needed for login.
Implementation scope
The work required to implement custom account login starts with checking the security key in the Hive Console and ends with displaying the screen that matches the login result.
The work in each step falls into one of the following six 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. |
| Recipe code | App developer | Recipe methods the app calls. |
| App code | App developer | Parts the app implements directly without going through Hive Axyl. |
| App server | App server developer | Parts the app server handles with its own logic. |
| Hive Axyl Server API | App server developer | Hive Axyl Server APIs the app server calls. |
Custom account login involves no Add-on calls. Add-ons are Hive Axyl SDK extension packages that display the authentication screen of an external authentication provider, and custom account login does not need them because the app authenticates users directly.
For the meaning of parameters and response fields, see the detailed procedure linked in each step.
Why the app server is involved
In custom account login, the app client does not send the user's ID or password to the Hive Axyl authentication server. Instead, the app server authenticates the user, gets a grant key from the Hive Axyl server, and passes it to the app client, and the app client logs in with only that grant key.
A grant key is a pre-authentication key that proves "the app server approved this user's login." Because the user's credentials do not pass through the app client, the risk of exposure is reduced accordingly.
A grant key is valid for only 60 seconds after issuance and can be used only once. The app server must issue one and pass it at the moment the user tries to log in. For the full sequence of operations, see the custom account login flow.
Recipe
The Hive Axyl SDK provides the login feature as fine-grained methods. There are separate methods to log in with a grant key, issue tokens, and activate the session. Even to log in a single user, the app must combine the call order and the handling of intermediate failures itself.
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 packages com.com2usplatform.hiveaxyl.* | You install and use it. It provides authentication features as fine-grained methods. |
| Recipe | Assets/Recipes/CustomLogin/ | You copy and use it. It is plain C# code that groups SDK calls by purpose. |
| Usage example | Assets/RecipeExamples/Authentication/CustomLoginExample.cs | Code to read for reference. Its comments explain the recipe call order and what 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.
What the app implements
The recipe handles only the part from receiving the grant key until the session is ready. The app implements the following items outside the recipe.
- User authentication and user identifier management on the app server
- The grant key issuance call on the app server and delivery to the app client
- The login screen and the screen transition after login
- Creating and keeping the
DeviceKey - The retry policy on failure and the guidance messages for users
Common prerequisites
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 |
The App ID is a value you enter when you initialize the SDK, so you must create it first. You must connect the SDK before you can install the authentication module in the following steps.
The app server must also have two things in place. It must have its own authentication system that can authenticate users, and it must be able to pass an identifier that distinguishes each authenticated user to Hive Axyl. This identifier must be a fixed value, one per user, so that the next login continues with the same account.
Next steps
When you finish the prerequisites, start Implement custom account login.