Skip to content

Web login session

A web login session is a shared means of getting credentials for combinations of external authentication providers and OSs that have no dedicated Add-on. It uses an authentication-only browser session provided by the OS to open the authorization URL that the app built, and delivers to the app the redirect callback that comes back after authentication finishes.

A web login session does not interpret the OAuth specification; it returns the callback URL and its query parameters as is. Therefore, the app client handles all of the following itself: building the authorization URL, generating and verifying the PKCE and state values, and extracting the authorization code from the callback.

state is a random value that you create anew for every login attempt. Send this value in the authorization URL and compare it with the state that comes back with the callback. This prevents authentication results that the app did not start from coming in. In particular, Windows receives the callback at a local address, so another program on the same device can send a fake response to that address. Be sure to implement state verification.

To use it, install com.com2usplatform.hiveaxyl.auth.addon.webauth and register it with AddWebAuth() as described in Install and initialize the module.

1. Prepare the redirect URI

The redirect URI is the address to which the external authentication provider sends the user back after authentication. If this address does not lead back to the app exactly, the app does not receive the callback and login fails.

First decide the redirect URI to use in the app, and then register it in the allowlist of the provider's console. For the registration procedure, see Prerequisites; for registering login methods in the Hive Console, see Login settings. How the app receives the callback differs by OS, and combinations where the external authentication provider's response cannot return directly to the app go through the Hive Axyl relay URL.

1.1. Android

Android receives the callback through the app's own URL scheme. The web login session Add-on already contains the screen that receives the callback and its intent filter, and the scheme of the intent filter is set by a Gradle setting value at build time. You cannot change Android's callback scheme with OpenRequest.RedirectUri, so put the scheme through which the app receives the callback in the build settings in advance.

If you turn on Custom Launcher Gradle Template in Project Settings > Player > Android > Publishing Settings > Build in the Unity Editor, the Assets/Plugins/Android/launcherTemplate.gradle file is created. Specify the hiveAxylWebAuthRedirectScheme value in defaultConfig of this file. If you put this value in mainTemplate.gradle, the Android build fails. If you specify com.myapp.oauth as in the following example, use a URL that starts with this scheme, such as com.myapp.oauth://callback, as the redirect URI.

android {
  defaultConfig {
    manifestPlaceholders = [
      hiveAxylWebAuthRedirectScheme: "com.myapp.oauth"
    ]
  }
}

Register the App ID scheme

If you provide login that goes through the Hive Axyl relay URL on Android, you must also register the App ID as a scheme so that the app can receive the callback that the relay URL sends. If the App ID is the only scheme you need, specify the App ID in hiveAxylWebAuthRedirectScheme.

Register multiple schemes

hiveAxylWebAuthRedirectScheme takes only one scheme. If you need two or more schemes, such as the app callback scheme of the Hive Axyl relay URL and the redirect URI scheme of another login method, specify one in hiveAxylWebAuthRedirectScheme and add the others as intent filters on the same callback screen in the manifest of an Android library that the app owns.

The following example adds the App ID scheme to the manifest while hiveAxylWebAuthRedirectScheme is set to com.myapp.oauth, the scheme of another login method. For {appId}, enter the Hive Console App ID that you used to initialize the SDK.

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  <application>
    <activity android:name="com.com2usplatform.hiveaxyl.auth.addon.webauth.HiveAxylWebAuthCallbackActivity"
              android:exported="true">
      <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="{appId}" />
      </intent-filter>
    </activity>
  </application>
</manifest>

1.2. iOS and macOS

No additional settings are required. The OS authentication session uses the scheme of the URL you put in OpenRequest.RedirectUri as is, so the app receives the callback without registering a URL scheme in Info.plist.

1.3. Windows

Windows receives the callback at a local address that the app opens temporarily. This address changes every time the app runs, so call AllocateLoopbackRedirectUriAsync() right before you build the authorization URL to reserve the address, and use that value identically in the authorization URL and OpenRequest.RedirectUri.

using Hive.Axyl.Auth.Addon.WebAuth;
using Hive.Axyl.Core;

// WindowsLoopback has a value only in Windows builds.
if (!HiveCore.TryResolve<IExternalUserAgent>(out var agent)
    || agent is not WebAuthSessionPlugin { WindowsLoopback: { } loopback })
{
    // Not Windows, or the Add-on is not registered
    return;
}

var allocated = await loopback.AllocateLoopbackRedirectUriAsync(
    new AllocateLoopbackRedirectUriRequest { PathPrefix = "/hive-auth/callback" });

if (allocated is not WindowsLoopbackServiceAllocateLoopbackRedirectUriResult.Success success)
{
    // Address reservation failed → keep the login screen
    return;
}

// Example: http://127.0.0.1:54321/hive-auth/callback
string redirectUri = success.Data.RedirectUri;

In PathPrefix, specify the path part of the redirect URI. If you enter a value, it must start with /; if you enter an empty string, the default path is used. If you call AllocateLoopbackRedirectUriAsync() again, the previously reserved address becomes invalid. If you did not call this method first, or if OpenRequest.RedirectUri differs from the most recently reserved address, OpenAsync() ends with Failure, and Failure.Problem.Code contains FailedPrecondition.

Addresses to register in the allowlist

The port number of the reserved address changes every time the app runs, so register a local address without a port in the allowlist of the external authentication provider's console. Apple does not allow local addresses as redirect URIs, so Apple login on Windows receives the callback at the reserved local address through the Hive Axyl relay URL.

1.4. Hive Axyl relay URL

Some external authentication providers do not send users back to an app's own scheme or to a local address. In that case, an HTTPS relay URL that Hive Axyl operates receives the external authentication provider's response and delivers it to the app.

The combinations that go through the relay URL are as follows. For the request composition and callback handling of each combination, see Sign in with Apple and Log in with a Steam account.

  • Apple login on Android and Windows
  • Steam login on Android and iOS

Relay URL and app callback URL

The Hive Axyl relay URL is https://core-api.hiveaxyl.com/auth/v1/provider/callback, and you put it in the request you send to the external authentication provider. For Apple, put this URL in redirect_uri of the authorization URL; for Steam, append query parameters to this URL to build openid.return_to of the login request.

The app callback URL is the app's URL to which the Hive Axyl relay URL delivers the authentication result; put this URL, not the relay URL, in OpenRequest.RedirectUri. On Android and iOS, use the {appId}://oauth-callback format, and for {appId}, enter the Hive Console App ID that you used to initialize the SDK, not the Android package name. On Windows, the local address reserved with AllocateLoopbackRedirectUriAsync() is the app callback URL.

Division of roles

In login that goes through the relay URL, Hive Axyl handles the following.

  • Operating the relay URL
  • Checking the App ID and the delivery target based on the registered app information
  • Delivering the external authentication provider's response to the app callback URL
  • Verifying the authenticity of Steam login results and exchanging Apple authorization codes

The app handles the following. Registering the relay URL with the external authentication provider applies only to Apple login; you do not register the relay URL with Steam.

  • Registering the Service ID's Return URL and domain for Apple login
  • Building the login request that contains the relay URL
  • Registering the App ID scheme on Android
  • Verifying the callback and extracting the login values
  • Stopping login on verification failure, user cancellation, or exchange failure

Callback settings by platform

On Android, you must register the App ID as a callback scheme so that the callback sent by the Hive Axyl relay URL returns to the app. For how to register it, see Register the App ID scheme. On iOS, the OS authentication session uses the scheme of OpenRequest.RedirectUri as is, so no additional settings are required.

2. Open a web login session

Method

OpenAsync

Call OpenAsync() to open the authorization URL in an authentication-only browser session and receive the redirect callback. Only one session can be open at a time; if you call it again while a session is in progress, it returns Failure and keeps the in-progress session.

Call parameters

Field name Type Required Description
request OpenRequest Required Web login session request
ct CancellationToken Optional Cancellation token. The session itself has no default time limit, so set a time limit in the app with CancellationTokenSource(TimeSpan).

OpenRequest

Field name Type Required Description
Url string Required Authorization URL that the app built. It follows the specification set by each external authentication provider.
RedirectUri string Required The URL you decided in Prepare the redirect URI. It must be the same as the value you put in the authorization URL. For combinations that go through the Hive Axyl relay URL, put the app callback URL, not the relay URL that you put in the authorization URL.

If Url or RedirectUri is empty, an ArgumentException is thrown.

Call example

For the result model and handling principles of common failures (Failure) that prevent the request from being performed, see Common error handling.

using Hive.Axyl.Auth.Addon.WebAuth;
using Hive.Axyl.Core;
using UnityEngine;

// The web login session is registered only in builds for supported OSs.
if (!HiveCore.TryResolve<IExternalUserAgent>(out var webAuth))
{
    return;
}

// authorizationUrl and redirectUri are values that the app built and stored.
var result = await webAuth.OpenAsync(new OpenRequest {
    Url         = authorizationUrl,
    RedirectUri = redirectUri,
});

switch (result)
{
    case ExternalUserAgentServiceOpenResult.Success success:
        // Extract the authorization code from the callback query parameters and pass it to the next step.
        string providerCode = success.Data.Parameters["code"];
        break;

    case ExternalUserAgentServiceOpenResult.UserCanceled:
        // The user closed the authentication window → keep the login screen
        break;

    case ExternalUserAgentServiceOpenResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    // Safety net: unhandled results and unknown new results (UnknownOutcome)
    default:
        Debug.LogWarning($"Unhandled result: {result.GetType().Name}");
        break;
}
Warning

The callback parameters contain the authorization code as is. Do not record Data.CallbackUrl and Data.Parameters in logs, crash reports, or analytics events.

Response data

On success, the callback result is in Data (OpenResponse) of ExternalUserAgentServiceOpenResult.Success.

Field name Type Required Description
Data.CallbackUrl string Required Original text of the redirected callback URL
Data.Parameters IReadOnlyDictionary<string, string> Required Parsed values of the callback URL's query parameters

Some external authentication providers report authentication failures through the callback. In that case, the session ends with Success and Data.Parameters contains parameters such as error, so check the parameters before you extract the authorization code.

Response example

// Example of success.Data in the Success branch
// success.Data.CallbackUrl        = "com.myapp.oauth://callback?code=...&state=..."
// success.Data.Parameters["code"]  = "..."   // Used for external authorization code exchange
// success.Data.Parameters["state"] = "..."   // Compare with the state that the app sent

Response status

We recommend handling the response cases of ExternalUserAgentServiceOpenResult with a switch statement.

Response case Description App client handling
Success When the callback is received. Extract the authorization code from Data.Parameters. Pass the authorization code to the next step
UserCanceled When the user closes the authentication window. Windows uses an external browser, so it cannot detect that the user closed the browser. Keep the login screen
UnknownOutcome A new result that this SDK version does not recognize Log it and handle it conservatively
Failure Common Failure. The case where the call is rejected because a session is in progress, the case where the redirect URI was not reserved first on Windows (FailedPrecondition), and the case where the app canceled the session (Cancelled) also branch here, and the cause is in Failure.Problem.Code. See Common error handling. Handle according to the common error handling criteria

On Windows, OpenAsync() does not end and keeps waiting even if the user closes the browser. Put a cancel button on the login screen that calls Cancel an in-progress session, or set a time limit with a cancellation token.

Cancel an in-progress session

Method

CancelCurrentSession

Call CancelCurrentSession() when the app must stop authentication first, such as when the user leaves the login screen. If no session is in progress, it does nothing.

using Hive.Axyl.Auth.Addon.WebAuth;
using Hive.Axyl.Core;

if (HiveCore.TryResolve<IExternalUserAgent>(out var webAuth))
{
    webAuth.CancelCurrentSession();
}

When you cancel, the waiting OpenAsync() ends with Failure, and Failure.Problem.Code contains Cancelled. This is distinct from UserCanceled, which occurs when the user closes the authentication window directly.

Next steps