Apple login Add-on

An Add-on that displays the Apple login screen with Apple's ASAuthorizationController on iOS and macOS and returns the credentials issued by Apple without modification. Pass the returned user identifier and identity token to LoginProviderAsync() of the Auth module to log in with a Hive Axyl account.

Module information

Package: com.com2usplatform.hiveaxyl.auth.addon.apple
Interface: IAppleSignInPlugin
Namespace: Hive.Axyl.Auth.Addon.Apple
Registration method: AddAppleSignIn()
Supported platforms: iOS, macOS
Minimum requirements: iOS 17+, macOS 15+, Unity 6000.0+

Prerequisites

When you install this Add-on, the Sign in with Apple entitlement is automatically added to the Xcode project generated during the build. On macOS, the entitlement is added only when you build so that an Xcode project is generated. However, you must enable the Sign in with Apple capability for the App ID in Apple Developer and issue a matching provisioning profile yourself. The system rejects a build signed without this work when it runs.

For how to set this up, see Prepare the App ID and provisioning profile for iOS and macOS.

Registration and retrieval

Register it in the registration step of HiveBootstrap.Initialize, and then retrieve it with HiveCore.TryResolve<T>().

Unity

using Hive.Axyl.Auth;
using Hive.Axyl.Auth.Addon.Apple;
using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddAuth()
           .AddToken()
           .AddAppleSignIn();
});

if (HiveCore.TryResolve<IAppleSignInPlugin>(out var apple))
{
    // Code that runs only in iOS and macOS builds
}

Not registered in the Unity Editor

This Add-on is registered only in players built for iOS or macOS. It is not registered in the Unity Editor even if the platform matches, so if you use HiveCore.Resolve<T>(), a RegistrationNotFoundException is thrown. Always check with TryResolve<T>() before you use it.

For the package installation and registration procedure, see Install and initialize the module.

Method summary

Asynchronous methods take CancellationToken ct = default as the last parameter. For the calling conventions, see Call context.

LoginAsync(): Display the Apple login screen and receive the credentials issued by Apple
CancelCurrentSession(): Cancel an in-progress login from code

Methods

LoginAsync

Displays the Apple login screen and returns the user identifier, identity token, authorization code, email, name, and real user status that Apple returned, without modification.

Only one login proceeds at a time. If you call it again while a login is in progress, it leaves the in-progress login as is and immediately returns a Failure whose Code is FailedPrecondition.

Unity

Task<AppleSignInServiceLoginResult> LoginAsync(AppleSignInServiceLoginRequest request, CancellationToken ct = default)

Request: AppleSignInServiceLoginRequest
Response: AppleSignInServiceLoginResponse

Result cases — AppleSignInServiceLoginResult

Result case	Wire code	Description
`Success`	—	Login succeeded. `Data` contains the Apple credentials.
`UserCanceled`	`user_canceled`	The app user closed the Apple login screen. You can guide the app user to try again.
`UnknownOutcome`	`UNKNOWN`	A new result that this SDK version does not recognize.
`Failure`	`FAILURE`	The call could not be completed. Check the cause with the HiveError in `Problem`.

UserCanceled implements IUserCanceledOutcome.

User cancellation and code cancellation are different

If the app user closes the Apple login screen, the result is UserCanceled. In contrast, if you cancel from code with CancellationToken or CancelCurrentSession(), the result is a Failure whose Code is Cancelled.

Exceptions

ArgumentNullException: When request is null
ArgumentException: When request.NonceHash is null or empty, or when request.RequestedScopes contains Unspecified

Call example

Unity

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

var request = new AppleSignInServiceLoginRequest
{
    NonceHash = nonceHash,   // SHA256 value of the original nonce created by the app, as a lowercase hexadecimal string
    RequestedScopes = new[] { RequestedScope.Email, RequestedScope.FullName },
};

var result = await apple.LoginAsync(request);

switch (result)
{
    case AppleSignInServiceLoginResult.Success success:
        string providerUserId = success.Data.UserIdentifier;   // ProviderUserId of LoginProviderAsync
        string providerToken = success.Data.IdentityToken;     // ProviderToken of LoginProviderAsync
        break;

    case AppleSignInServiceLoginResult.UserCanceled:
        // The app user closed the Apple login screen.
        break;

    case AppleSignInServiceLoginResult.Failure failure:
        HiveError error = failure.Problem;
        break;

    default:
        // Unhandled results and UnknownOutcome
        break;
}

When login succeeds, call LoginProviderAsync() with UserIdentifier as ProviderUserId and IdentityToken as ProviderToken. For the implementation procedure, see Get Apple credentials on iOS and macOS.

CancelCurrentSession

Cancels an in-progress login from code. The pending LoginAsync() ends with a Failure whose Code is Cancelled. If no login is in progress, it does nothing.

Unity

void CancelCurrentSession()

Data types

AppleSignInServiceLoginRequest

Field	Type	Required	Description
`NonceHash`	`string`	Required	String that represents the SHA256 value of the original nonce created by the app in lowercase hexadecimal. The Add-on only passes this value as is as the nonce of the Apple login request and does not create or validate it, so create a new original nonce for every login.
`RequestedScopes`	`IReadOnlyList<`RequestedScope`>`	Required	Scopes of user information to request from Apple. If you pass an empty list, only the user identifier is returned.

Email and name are returned only at the first login

According to Apple's policy, the email and name are returned only when the user logs in to this app with that Apple account for the first time. In later logins, empty strings are returned even if you request the scopes, so the app must save the values received at the first login itself.

AppleSignInServiceLoginResponse

Credentials issued by Apple.

Field	Type	Required	Description
`UserIdentifier`	`string`	Required	Apple user identifier. It has the same value in all apps that belong to the same Apple Developer team. Use it as `ProviderUserId` in the `LoginProviderAsync()` request.
`IdentityToken`	`string`	Required	Apple identity token in JSON Web Token (JWT) format. Use it as `ProviderToken` in the `LoginProviderAsync()` request.
`AuthorizationCode`	`string`	Required	Authorization code valid for about 5 minutes. Empty string if Apple does not provide a value. When you log in with this Add-on, you log in directly with `IdentityToken`, so this value is not used.
`Email`	`string`	Required	Email address of the app user. It contains a value only at the first login and is an empty string afterward. If the app user selected Hide My Email, it can be Apple's private relay address that ends with `@privaterelay.appleid.com`.
`UserName`	AppleUserName	Required	Name of the app user. It contains values only at the first login; afterward, all its fields are empty strings.
`RealUserStatus`	RealUserStatus	Required	Value that Apple provides for fraud prevention, indicating whether the logged-in account belongs to a real person.

AppleUserName

Some of the components of Apple's PersonNameComponents. Rarely used components, such as the name prefix, suffix, and nickname, are not included.

Field	Type	Required	Description
`GivenName`	`string`	Required	Given name, which is the `PersonNameComponents.givenName` value. Empty string if Apple does not provide a value.
`FamilyName`	`string`	Required	Family name, which is the `PersonNameComponents.familyName` value. Empty string if Apple does not provide a value.
`MiddleName`	`string`	Required	Middle name, which is the `PersonNameComponents.middleName` value. Empty string if Apple does not provide a value.

Enums

Specify Add-on enums by their C# member names. The 'Value' in the tables is the integer used for serialization.

RealUserStatus

Apple's assessment of how likely the account is to belong to a real person. Corresponds to Apple's ASUserDetectionStatus.

C# member	Value	Description
`Unspecified`	0	Apple did not provide an assessment.
`LikelyReal`	1	Apple assessed that the account likely belongs to a real person.
`Unknown`	2	Apple could not determine whether the account belongs to a real person.
`Unsupported`	3	Real user status is not supported on this OS version or platform.

RequestedScope

Scope of user information to request from Apple. Regardless of the requested scopes, Apple returns that information only at the first login.

C# member	Value	Description
`Unspecified`	0	Default value with no scope specified. If you put it in `RequestedScopes`, an `ArgumentException` is thrown.
`Email`	1	Requests the email address. It is contained in `Email` of the response.
`FullName`	2	Requests the name. It is contained in `UserName` of the response.