Android Credential Manager 로그인 Add-on

Android에서 AndroidX Credential Manager로 자격 증명 선택 화면을 띄우고, 앱 사용자가 고른 자격 증명을 반환하는 Add-on입니다. 앱이 요청한 여러 선택지를 하나의 시스템 선택 화면으로 묶어 보여 줍니다. 반환된 Google ID 토큰과 계정 식별자를 Auth 모듈의 LoginProviderAsync()에 넘겨 Google 계정으로 로그인합니다.

모듈 정보

• 패키지: com.com2usplatform.hiveaxyl.auth.addon.credentialmanager
• 인터페이스: IAndroidCredentialManagerPlugin
• 네임스페이스: Hive.Axyl.Auth.Addon.CredentialManager
• 등록 메서드: AddCredentialManager()
• 지원 플랫폼: Android
• 최소 사양: Android API 29+, Unity 6000.0+

등록과 획득

HiveBootstrap.Initialize의 등록 단계에서 등록한 뒤 HiveCore.TryResolve<T>()로 가져옵니다.

Unity

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

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

if (HiveCore.TryResolve<IAndroidCredentialManagerPlugin>(out var credential))
{
    // Android 빌드에서만 실행되는 코드
}

Unity 에디터에서는 등록되지 않습니다

이 Add-on은 Android로 빌드한 플레이어에서만 등록됩니다. Unity 에디터에서는 플랫폼을 Android로 바꿔도 등록되지 않으므로, HiveCore.Resolve<T>()를 쓰면 RegistrationNotFoundException이 발생합니다. 반드시 TryResolve<T>()로 확인한 뒤 사용하세요.

패키지 설치와 등록 절차는 모듈 설치 및 초기화를 참조하세요.

메서드 요약

비동기 메서드는 마지막 파라미터로 CancellationToken ct = default를 받습니다. 호출 규약은 호출 컨텍스트를 참조하세요.

• LoginAsync(): 자격 증명 선택 화면 표시와 앱 사용자가 고른 자격 증명 수신
• CancelCurrentSession(): 코드에서 진행 중인 로그인 취소

메서드

LoginAsync

요청에 담은 CredentialOption을 선택지로 삼아 자격 증명 선택 화면을 띄웁니다. 선택지 하나는 GetCredentialRequest.Builder().addCredentialOption() 호출 하나에 대응하며, 앱 사용자는 모든 선택지를 합친 하나의 화면에서 자격 증명을 고릅니다.

한 번에 하나의 로그인만 진행합니다. 로그인이 진행 중일 때 다시 호출하면 진행 중인 로그인은 그대로 두고 Code가 FailedPrecondition인 Failure를 바로 반환합니다.

Unity

Task<AndroidCredentialManagerServiceLoginResult> LoginAsync(LoginRequest request, CancellationToken ct = default)

• 요청: LoginRequest
• 응답: LoginResponse

결과 케이스 — AndroidCredentialManagerServiceLoginResult

결과 케이스	와이어 코드	설명
Success	—	앱 사용자가 자격 증명을 선택했습니다. Data.Selected에 선택한 자격 증명이 담깁니다.
UserCanceled	user_canceled	앱 사용자가 자격 증명 선택 화면을 닫았습니다.
NoCredentials	no_credentials	요청한 선택지에 맞는 자격 증명이 기기에 없습니다. 선택지를 여러 개 요청했다면 어느 선택지에도 맞는 자격 증명이 없을 때만 이 결과가 반환됩니다. FilterByAuthorizedAccounts를 true로 요청해 이 결과를 받았다면, false로 바꿔 다시 요청해 기기의 모든 Google 계정을 보여 주세요.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. Problem의 HiveError로 원인을 확인합니다.

UserCanceled는 IUserCanceledOutcome을 구현합니다.

UserCanceled와 NoCredentials는 Failure가 아닌 정상 결과이므로 오류 처리와 구분해 처리하세요. 반면 CancellationToken이나 CancelCurrentSession()으로 코드에서 취소하면 Code가 Cancelled인 Failure가 됩니다.

결과의 원본 응답을 로그에 남기지 마세요

네이티브 응답을 받은 결과는 Success를 포함해 모두 RawResponse에 응답 본문을 그대로 담습니다. Success라면 이 본문에 ID 토큰과 계정 이메일 주소를 포함한 자격 증명 전체가 들어 있으므로, 로그, 크래시 리포트, 분석 이벤트에 기록하지 마세요.

발생 예외

• ArgumentNullException: request가 null인 경우
• ArgumentException: 아래 중 하나에 해당하는 경우
  • request.Options가 null이거나 비어 있는 경우
  • Options에 null 항목이 있는 경우
  • 선택지 하나에 GoogleId와 SignInWithGoogle을 모두 지정했거나 둘 다 지정하지 않은 경우
  • 같은 종류의 선택지를 두 개 이상 넣은 경우
  • 선택지의 WebClientId나 Nonce가 null이거나 비어 있는 경우

호출 예시

Unity

using Hive.Axyl.Auth.Addon.CredentialManager;

var request = new LoginRequest
{
    Options = new[]
    {
        new CredentialOption
        {
            GoogleId = new GoogleIdOption
            {
                WebClientId = "{webClientId}",
                Nonce = nonce,                      // 로그인할 때마다 새로 만든 원본 nonce
                FilterByAuthorizedAccounts = true,  // 이 앱에 권한을 준 Google 계정만 후보로 표시
            },
        },
    },
};

var result = await credential.LoginAsync(request);

if (result is AndroidCredentialManagerServiceLoginResult.Success success
    && success.Data.Selected.GoogleIdToken is { } google)
{
    string providerUserId = google.UniqueId;   // LoginProviderAsync의 ProviderUserId
    string providerToken = google.IdToken;     // LoginProviderAsync의 ProviderToken
}

로그인에 성공하면 UniqueId를 ProviderUserId로, IdToken을 ProviderToken으로 넣어 LoginProviderAsync()를 호출합니다.

ProviderUserId에는 Id가 아니라 UniqueId를 넣으세요

Id에는 사용자 식별자가 아니라 계정의 이메일 주소가 담깁니다. Hive Axyl 인증 서버는 ProviderUserId를 검증한 ID 토큰의 sub 값과 비교하므로, Id를 넘기면 값이 달라 로그인이 거부됩니다.

구현 절차는 Android에서 Google 자격 증명 획득을 참조하세요.

CancelCurrentSession

진행 중인 로그인을 코드에서 취소합니다. 대기 중이던 LoginAsync()는 Code가 Cancelled인 Failure로 끝납니다. 진행 중인 로그인이 없으면 아무 동작도 하지 않습니다.

Unity

void CancelCurrentSession()

데이터 타입

Credential

앱 사용자가 선택한 자격 증명입니다. 자격 증명 종류별 프로퍼티 중 값이 담긴 프로퍼티를 확인해 사용하세요.

필드	타입	필수 여부	설명
GoogleIdToken	GoogleIdTokenCredential?	Optional	Google ID 토큰 자격 증명입니다.

CredentialOption

선택 화면에 제시할 선택지 하나입니다. GoogleId와 SignInWithGoogle 중 정확히 하나만 지정하세요. 둘 다 지정하거나 둘 다 지정하지 않으면 ArgumentException이 발생합니다.

필드	타입	필수 여부	설명
GoogleId	GoogleIdOption?	Optional	계정 선택 시트로 Google 계정을 고르게 하는 선택지입니다.
SignInWithGoogle	SignInWithGoogleOption?	Optional	Google 계정으로 로그인 버튼 흐름으로 제시하는 선택지입니다.

GoogleIdOption

계정 선택 시트로 Google 계정을 고르게 하는 선택지입니다. GetGoogleIdOption.Builder에 대응합니다.

필드	타입	필수 여부	설명
WebClientId	string	Required	웹 애플리케이션 유형 OAuth 2.0 클라이언트 ID입니다. 발급되는 ID 토큰의 aud 클레임 값이 되며, Android 유형 클라이언트 ID와는 다른 값입니다. 발급 방법은 Google 로그인 인증 정보 확인을 참조하세요.
Nonce	string	Required	앱이 암호학적으로 안전한 난수 생성기로 만든 원본 nonce입니다. 패딩을 뺀 URL-safe Base64 문자열을 권장합니다. Add-on은 이 값을 그대로 전달하며, Google은 같은 문자열을 ID 토큰의 nonce 클레임에 담습니다. Apple 로그인 Add-on과 달리 SHA256 해시를 적용하지 않습니다.
FilterByAuthorizedAccounts	bool	Required	true이면 앱 사용자가 이 앱에 이전에 권한을 준 Google 계정만 후보로 보여 주며, 첫 시도에 권장합니다. false이면 기기의 모든 Google 계정을 보여 줍니다.
AutoSelectEnabled	bool	Required	권한을 준 계정이 하나뿐일 때 선택 화면 없이 바로 반환할지 여부입니다. FilterByAuthorizedAccounts가 true일 때만 적용됩니다.
RequestVerifiedPhoneNumber	bool	Required	검증된 전화번호를 GoogleIdTokenCredential.PhoneNumber로 함께 받을지 여부입니다. FilterByAuthorizedAccounts가 false인 가입 흐름에서만 반환되며, Google Cloud Console에서 범위 승인을 받아야 합니다. 검증된 전화번호가 없는 계정은 오류 없이 빈 문자열을 반환합니다.
HostedDomainFilter	string	Required	후보 계정을 특정 Google Workspace 호스팅 도메인으로 제한합니다. 빈 문자열이면 제한하지 않습니다.

GoogleIdTokenCredential

Google이 발급한 자격 증명의 원본 필드입니다. Add-on은 ID 토큰의 서명, aud, iss, nonce를 검증하지 않습니다. 모든 필드가 사용자를 식별하는 정보이므로 SDK 로그에 평문으로 기록되지 않습니다.

필드	타입	필수 여부	설명
Id	string	Required	계정의 이메일 주소이며 사용자 식별자가 아닙니다. Google이 지원을 중단한 필드이므로 ProviderUserId에는 UniqueId를, 이메일 주소에는 Email을 사용하세요.
IdToken	string	Required	JSON Web Token(JWT) 형식의 OpenID Connect ID 토큰입니다. LoginProviderAsync() 요청의 ProviderToken으로 사용합니다.
DisplayName	string	Required	표시 이름입니다. 범위가 허용되지 않았으면 빈 문자열입니다.
GivenName	string	Required	이름입니다. 범위가 허용되지 않았으면 빈 문자열입니다.
FamilyName	string	Required	성입니다. 범위가 허용되지 않았으면 빈 문자열입니다.
ProfilePictureUri	string	Required	프로필 사진 URL입니다. 값이 없으면 빈 문자열입니다.
PhoneNumber	string	Required	검증된 전화번호입니다. RequestVerifiedPhoneNumber가 true일 때만 의미가 있으며, 요청하지 않았거나 계정이 지원하지 않으면 빈 문자열입니다. Google이 대체 필드 없이 지원을 중단한 필드입니다.
UniqueId	string	Required	Google Identity SDK가 ID 토큰의 sub 값에서 읽은 Google 계정의 고유 식별자입니다. LoginProviderAsync() 요청의 ProviderUserId로 사용하며, 성공한 자격 증명에는 항상 값이 있습니다.
Email	string	Required	ID 토큰에서 읽은 계정의 이메일 주소입니다. 화면 표시나 계정 힌트에만 사용하고 식별자로 사용하지 마세요. 자격 증명에 이메일 주소가 없으면 빈 문자열입니다.

LoginRequest

필드	타입	필수 여부	설명
Options	IReadOnlyList<CredentialOption>	Required	선택 화면에 제시할 선택지 목록입니다. 선택지가 하나 이상 있어야 하며, 같은 종류의 선택지는 하나만 넣으세요.

LoginResponse

필드	타입	필수 여부	설명
Selected	Credential	Required	앱 사용자가 선택 화면에서 고른 자격 증명입니다. AutoSelectEnabled로 선택 화면 없이 자동 선택된 자격 증명도 여기에 담깁니다.

SignInWithGoogleOption

Google 계정으로 로그인 버튼 흐름으로 제시하는 선택지입니다. GetSignInWithGoogleOption.Builder에 대응합니다.

필드	타입	필수 여부	설명
WebClientId	string	Required	GoogleIdOption.WebClientId와 같은 값입니다.
Nonce	string	Required	GoogleIdOption.Nonce와 같은 규칙을 따릅니다.
HostedDomainFilter	string	Required	후보 계정을 특정 Google Workspace 호스팅 도메인으로 제한합니다. 빈 문자열이면 제한하지 않습니다.