콘텐츠로 이동

Google 로그인 구현하기

레시피 코드로 Google 로그인을 구현하려면 아래 절차를 순서대로 완료하세요.

시작하기 전에 공통 사전 준비를 마치세요.

전체 흐름

각 단계에서 무엇을 설정하고 무엇을 호출하는지는 아래와 같습니다. Android에서는 Credential Manager 방식을, iOS·macOS·Windows에서는 브라우저 방식을 사용합니다.

순서 구분 하는 일 대상 방식
1 외부 콘솔 Google OAuth 클라이언트 준비 전체
2 Hive 콘솔 Google 로그인 활성화와 인증 정보 등록 전체
3 Hive Axyl SDK 인증 모듈과 로그인 Add-on 설치 전체
4 Hive Axyl SDK SDK 초기화와 모듈 등록 전체
5 레시피 코드 공통·방식별 레시피 폴더 복사 전체
6 앱 코드 Hive Axyl ClientId와 DeviceKey 준비 전체
7 레시피 코드 Google 자격 증명 소스 준비 전체
8 레시피 코드 Google 로그인 호출 전체
9 앱 코드 로그인 결과 처리 전체
10 앱 코드 동작 확인 전체
세 종류의 클라이언트 ID를 구분하세요

Google Cloud Console의 웹 애플리케이션 유형 OAuth 클라이언트 ID, 브라우저용 Google OAuth 클라이언트 ID, Hive 콘솔의 Client ID는 서로 다른 값일 수 있습니다. Android Credential Manager에는 웹 애플리케이션 유형 ID를, 브라우저의 WebAuthOptions.ClientId에는 해당 리다이렉트 URI를 등록한 Google OAuth 클라이언트 ID를, ProviderLoginRecipe 생성자에는 Hive Axyl Client ID를 넣으세요.

1. Google 외부 콘솔 설정

Google Cloud Console에서 Google 로그인에 사용할 OAuth 클라이언트를 준비하세요.

Android와 브라우저 방식에 필요한 외부 콘솔 설정이 다릅니다.

방식 준비할 값 용도
Android Credential Manager 웹 애플리케이션 유형 OAuth 클라이언트 ID, Android 유형 OAuth 클라이언트 웹 클라이언트 ID는 레시피에 전달하고, Android 클라이언트는 패키지 이름과 서명으로 앱을 확인합니다.
브라우저 웹 로그인 세션 Google OAuth 클라이언트 ID, 인가 엔드포인트, 리다이렉트 URI, Scope WebAuthOptions를 만들 때 사용합니다. 리다이렉트 URI는 Google Cloud Console의 승인된 리디렉션 URI에도 등록해야 합니다.

브라우저 방식에서 tokenEndpoint를 지정하지 않으면 레시피가 Hive Axyl SDK의 ExchangeProviderTokenAsync()를 호출해 Hive Axyl 인증 서버가 Google과 인가 코드를 교환합니다. 이 경로를 사용하려면 Google 웹 애플리케이션 클라이언트의 ID와 Secret을 Hive 콘솔에 등록하고, 인가 URL에도 같은 클라이언트에 해당하는 ID를 사용하세요. Hive 콘솔의 Web Client Secret 입력란은 프로젝트에 Windows App ID가 있을 때 프로젝트 기본 설정에, 선택한 App ID의 실행 환경이 Windows일 때 App ID 설정에 나타납니다. 해당 입력 조건을 사용할 수 없는 App ID는 tokenEndpoint를 지정하는 공개 클라이언트 경로를 사용하세요.

2. Hive 콘솔 설정

Google 로그인 인증 정보를 등록하고 로그인 수단을 활성화하세요. 설정이 비어 있거나 로그인 수단이 비활성화되어 있으면 레시피의 Hive Axyl 로그인 단계가 거절됩니다.

아래 항목을 설정합니다.

설정 항목 필수 여부 확인할 곳
Google Web Client ID 등록 필수 Google 로그인 인증 정보
Google Web Client Secret 등록 서버 교환 방식을 사용할 때 필수 Google 로그인 인증 정보
Google 로그인 활성화 필수 로그인 수단 종류
App ID별 로그인 설정 선택 App ID별 로그인 설정

Google Cloud Console의 Web Client ID와 Secret은 Hive 콘솔에 등록합니다. 이 값과 앱 코드의 WebAuthOptions.ClientId, Hive Axyl ClientId를 혼동하지 마세요. Client Secret은 앱 코드와 빌드 결과물에 포함하지 않습니다.

3. SDK 모듈과 Add-on 설치

Google 로그인에 필요한 Hive Axyl SDK 모듈과 방식을 선택해 사용할 Add-on을 Unity 프로젝트에 설치하세요.

패키지 필요 여부 역할
com.com2usplatform.hiveaxyl.core 필수 SDK 초기화와 공통 오류 처리
com.com2usplatform.hiveaxyl.auth 필수 Google 자격 증명으로 로그인하고 토큰 발급
com.com2usplatform.hiveaxyl.storage 권장 DeviceKey와 세션 토큰의 암호화 저장
com.com2usplatform.hiveaxyl.auth.addon.credentialmanager Android Credential Manager 방식에 필수 Android 계정 선택 화면 표시
com.com2usplatform.hiveaxyl.auth.addon.webauth 브라우저 방식에 필수 브라우저 웹 로그인 세션 제공
com.unity.nuget.newtonsoft-json 브라우저 레시피에 필수 ProviderLogin.WebAuth/의 JSON 처리

Android Credential Manager 방식만 사용하면 WebAuth Add-on과 브라우저 레시피를 설치하지 않아도 됩니다. 두 방식을 모두 제공하면 두 Add-on을 모두 설치하세요. 패키지 설치 후에는 모듈 초기화에서 등록 메서드도 함께 추가해야 합니다.

4. SDK 초기화

  • Hive Axyl SDK  Hive Axyl SDK를 앱에서 호출합니다.


    상세 절차: 모듈 초기화

앱 시작 지점에서 인증, 토큰, 보안 저장소와 사용할 로그인 Add-on을 한 번 등록하세요. 레시피는 SDK를 초기화하지 않습니다.

아래 예제는 Android Credential Manager와 브라우저 방식을 모두 지원하는 초기화입니다.

using Hive.Axyl.Auth;
using Hive.Axyl.Auth.Addon.CredentialManager;
using Hive.Axyl.Auth.Addon.WebAuth;
using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;
using Hive.Axyl.Storage;

var config = CoreConfig.CreateBuilder("{appId}").Build();

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

{appId}에는 Hive 콘솔에서 만든 App ID를 입력하세요. 한 방식만 지원하면 사용하지 않는 Add-on의 using 구문과 등록 메서드를 함께 제거하세요.

AddCredentialManager()는 Android에서만 실제 모듈을 등록하고, AddWebAuth()는 Android·iOS·macOS·Windows에서 모듈을 등록합니다. 두 메서드 모두 Unity 에디터에서는 모듈을 등록하지 않으며, 지원하지 않는 OS에서 호출해도 오류가 발생하지 않습니다.

5. 레시피 코드 설치

  • 레시피 코드  레시피 코드를 프로젝트에 복사합니다.

레시피는 패키지가 아니라 프로젝트에 복사해서 사용하는 소스 코드입니다. axyl-samples-unity 저장소에서 아래 항목을 Unity 프로젝트의 Assets/Recipes/ 아래로 복사하세요.

복사할 항목과 역할은 아래와 같습니다.

앱에서 두 방식을 모두 지원한다면 앱 어셈블리 정의의 references에 아래 어셈블리를 추가하세요.

{
  "name": "MyApp",
  "references": [
    "Hive.Axyl.Core",
    "Hive.Axyl.Auth",
    "Hive.Axyl.Auth.Addon.CredentialManager",
    "Hive.Axyl.Auth.Addon.WebAuth",
    "Hive.Axyl.Storage",
    "Hive.Axyl.Samples.Recipes",
    "Hive.Axyl.Samples.Recipes.ProviderLogin",
    "Hive.Axyl.Samples.Recipes.ProviderLogin.CredentialManager",
    "Hive.Axyl.Samples.Recipes.ProviderLogin.WebAuth"
  ]
}

MyApp은 앱에서 사용하는 어셈블리 이름으로 바꾸고 기존 설정과 참조는 유지하세요. 한 방식만 사용하면 사용하지 않는 Add-on과 레시피 어셈블리 참조를 빼도 됩니다. ProviderLogin.WebAuth/를 사용할 때는 com.unity.nuget.newtonsoft-json 패키지도 설치해야 합니다.

공통 레시피 폴더를 함께 복사하세요

ProviderLogin.CredentialManager/와 ProviderLogin.WebAuth/는 ProviderLogin/의 자격 증명 소스 계약을 구현하고, ProviderLoginRecipe는 Helper/의 공통 코드를 사용합니다. Helper/, Recipes.asmdef, AssemblyInfo.cs, ProviderLogin/을 방식별 폴더와 함께 복사하세요.

6. ClientId와 DeviceKey 준비

ProviderLoginRecipe의 생성자는 ClientId와 DeviceKey를 받습니다. ClientId는 공통 사전 준비에서 확인한 값으로, Hive 콘솔이 프로젝트마다 발급합니다. DeviceKey는 Hive Axyl 인증 서버가 로그인 세션을 기기 단위로 구분하는 값이며, 앱이 직접 만들어 보관합니다.

값 넣는 곳 준비 방법
Hive Axyl ClientId new ProviderLoginRecipe(clientId, deviceKey) Hive 콘솔의 보안 키에서 확인
DeviceKey new ProviderLoginRecipe(clientId, deviceKey) 앱이 생성해 보관
Google 웹 애플리케이션 유형 Client ID GoogleCredentialManagerCredentialSource(webClientId) Google Cloud Console에서 확인
Google OAuth Client ID WebAuthOptions.Create()의 clientId 리다이렉트 URI를 등록한 Google OAuth 클라이언트에서 확인

레시피는 DeviceKey를 만들거나 저장하지 않으므로, 아래 조건에 맞게 만들고 관리하세요.

  • 기기마다 다른 값. UUID 같은 난수 권장
  • 최초 실행 때 한 번 만들어 저장하고, 이후 모든 로그인에서 재사용하는 값
  • 22자 이상 64자 이하의 길이
  • 공백과 제어 문자를 제외한 ASCII 문자로만 이루어진 값
저장소를 읽지 못했다고 새 DeviceKey로 덮어쓰지 마세요

값이 사라진 것이 아니라 읽기에만 실패했을 수 있습니다. 먼저 저장소 접근 문제를 해결하거나 다시 읽기를 시도하세요.

ClientId나 DeviceKey가 비어 있으면 레시피 생성자에서 ArgumentException이 발생합니다. Android Credential Manager의 웹 클라이언트 ID와 브라우저 WebAuthOptions.ClientId도 비어 있지 않아야 합니다.

PKCE와 nonce는 준비하지 않아도 됩니다. Google 자격 증명 소스가 로그인 시도마다 필요한 값을 만들고 검증합니다. 브라우저 방식에서는 Google용 PKCE와 Hive Axyl 인증 서버용 PKCE를 각각 별도로 사용하므로, 앱에서 직접 만든 값을 레시피에 전달하지 마세요.

7. Google 자격 증명 소스 준비

  • 레시피 코드  레시피 코드를 앱에서 호출합니다.

로그인할 방식을 선택해 자격 증명 소스를 만든 뒤 레시피에 전달하세요. 자격 증명 소스의 생성자와 내부 호출은 Google 자격 증명 획득을 참조하세요.

7.1. Android Credential Manager 방식

GoogleCredentialManagerCredentialSource에 Google Cloud Console의 웹 애플리케이션 유형 OAuth 클라이언트 ID를 전달하세요. 레시피가 nonce를 만들고 Credential Manager의 계정 선택 화면에서 받은 id_token과 UniqueId를 로그인 자격 증명으로 사용합니다.

using Hive.Axyl.Samples.Recipes;

IProviderCredentialSource source =
    new GoogleCredentialManagerCredentialSource("{googleWebClientId}");

{googleWebClientId}에는 Android 유형 OAuth 클라이언트 ID가 아니라 웹 애플리케이션 유형 OAuth 클라이언트 ID를 넣으세요. 이메일 주소인 Id가 아니라 UniqueId가 사용자 식별자로 사용됩니다.

7.2. 브라우저 방식

WebAuthOptions.Create()에 Google OAuth 클라이언트와 등록한 리다이렉트 URI를 지정하세요. 아래 예제처럼 tokenEndpoint를 생략하면 레시피가 ExchangeProviderTokenAsync()를 통해 Hive Axyl 인증 서버에서 인가 코드를 교환합니다.

using Hive.Axyl.Samples.Recipes;

var googleOptions = WebAuthOptions.Create(
    "https://accounts.google.com/o/oauth2/v2/auth",
    "{googleProviderClientId}",
    "{googleRedirectUri}",
    "openid email profile");

IProviderCredentialSource source = new GoogleCredentialSource(googleOptions);

공개 클라이언트가 인가 코드를 직접 교환하도록 구성할 때만 tokenEndpoint를 지정하세요. Google 토큰 엔드포인트를 지정하면 레시피가 PKCE로 Google과 직접 통신하고, 응답의 id_token에서 사용자 식별자를 얻습니다.

var googleOptions = WebAuthOptions.Create(
    "https://accounts.google.com/o/oauth2/v2/auth",
    "{googleProviderClientId}",
    "{googleRedirectUri}",
    "openid email profile",
    tokenEndpoint: "https://oauth2.googleapis.com/token");

IProviderCredentialSource source = new GoogleCredentialSource(googleOptions);

Windows에서는 WebAuth Add-on이 실행할 때마다 포트가 달라지는 로컬 주소로 콜백을 받습니다. Google OAuth 클라이언트가 가변 포트의 로컬 주소 리다이렉트를 허용하면 WebAuthOptions.Create() 대신 WebAuthOptions.WithLoopbackRedirect()에 /hive-auth/callback 같은 경로를 지정하세요. 레시피가 로그인할 때마다 로컬 주소를 예약해 인가 요청에 넣습니다. Google Cloud Console에 등록할 주소는 허용 목록에 등록할 주소를 참조하세요. WithLoopbackRedirect()로 만든 설정은 로컬 주소를 예약할 수 있는 Windows에서만 동작합니다.

Android에서 브라우저 방식도 함께 지원한다면 앱이 등록된 Add-on을 확인해 소스를 선택할 수 있습니다.

using Hive.Axyl.Auth.Addon.CredentialManager;
using Hive.Axyl.Core;
using Hive.Axyl.Samples.Recipes;

IProviderCredentialSource source;
if (HiveCore.TryResolve<IAndroidCredentialManagerPlugin>(out _))
{
    source = new GoogleCredentialManagerCredentialSource("{googleWebClientId}");
}
else
{
    source = new GoogleCredentialSource(googleOptions);
}

한 방식만 제공하면 OS별 소스 선택 없이 해당 생성자만 호출하세요. WebAuth Add-on의 리다이렉트 URI와 브라우저 콜백 처리 방법은 웹 로그인 세션을 참조하세요.

8. Google 로그인 호출

  • 레시피 코드  레시피 코드를 앱에서 호출합니다.

준비한 자격 증명 소스를 LoginWithProviderAsync()에 전달하세요. 레시피가 Google 자격 증명을 획득하고 Hive Axyl 로그인, 토큰 발급, 세션 활성화까지 이어서 수행합니다.

using System.Threading;
using Hive.Axyl.Samples.Recipes;

var recipe = new ProviderLoginRecipe(clientId, deviceKey);

var cancellation = new CancellationTokenSource();
CancellationToken token = cancellation.Token;

LoginWithProviderOutcome outcome = await recipe.LoginWithProviderAsync(source, token);

로그인 화면을 닫는 것처럼 앱이 대기를 중단해야 할 때 cancellation.Cancel()을 호출하고, 호출이 끝나면 cancellation.Dispose()로 정리하세요. Android, iOS, macOS에서 사용자가 Google 화면을 닫은 경우에는 취소 토큰을 호출하지 말고 레시피가 반환하는 UserCanceled를 처리하세요.

Windows에서는 외부 브라우저를 사용하므로 사용자가 브라우저를 닫아도 레시피가 이를 감지하지 못하고 계속 기다립니다. 로그인 화면에 취소 버튼을 두어 cancellation.Cancel()을 호출하거나, new CancellationTokenSource(TimeSpan.FromMinutes(5))처럼 제한 시간을 지정하세요. TimeSpan을 사용하려면 using System;을 추가하세요. 자세한 내용은 웹 로그인 세션 열기의 응답 상태를 참조하세요.

레시피가 내부에서 수행하는 작업은 아래와 같습니다.

구분 호출 확인할 곳
레시피 코드 인증, 토큰, 세션 모듈이 등록되었는지 확인 모듈 초기화
Add-on Android에서 Credential Manager LoginAsync()로 Google id_token 확보 Android Google 자격 증명
Add-on Windows 브라우저 방식에서 AllocateLoopbackRedirectUriAsync()로 콜백을 받을 로컬 주소 예약 리다이렉트 URI 준비
레시피 코드 브라우저 방식의 인가 URL, state, Google PKCE 생성 인가 URL 구성
Add-on 브라우저 방식에서 OpenAsync()로 Google 로그인 페이지를 열고 콜백 수신 웹 로그인 세션 열기
레시피 코드 브라우저 방식의 콜백 state 검증 콜백 확인
Hive Axyl SDK tokenEndpoint를 비워 둔 경우 ExchangeProviderTokenAsync()로 브라우저 인가 코드 교환. RedirectUri에는 인가 요청에 사용한 리다이렉트 URI를, CodeVerifier에는 Google용 PKCE 값을 넣음 외부 인증 코드 교환
레시피 코드 tokenEndpoint를 지정한 경우 Google 토큰 엔드포인트와 직접 교환 브라우저 방식
Hive Axyl SDK LoginProviderAsync()에 준비된 Google 자격 증명 전달 외부 인증 제공자 로그인
Hive Axyl SDK IssueTokenAsync()로 Hive Axyl 토큰 발급, SetSession()으로 세션 활성화 토큰 발급과 세션 활성화

위 표의 SDK 메서드는 레시피가 내부에서 호출합니다. 레시피를 사용하는 앱은 ExchangeProviderTokenAsync(), LoginProviderAsync(), IssueTokenAsync(), SetSession()을 다시 호출하지 마세요. 브라우저 방식에서 레시피가 생성하는 Google용 PKCE와 Hive Axyl용 PKCE는 서로 다른 값입니다.

tokenEndpoint를 지정한 공개 클라이언트 방식의 HTTP 요청은 레시피가 Google에 직접 보냅니다. 이때도 Client Secret을 앱에 넣지 않으며, 앱은 Hive Axyl Server API 엔드포인트를 직접 호출하지 않습니다.

9. 로그인 결과 처리

  • 앱 코드  앱에서 직접 구현합니다.


    상세 절차: HiveError 정보

LoginWithProviderOutcome의 Status를 먼저 확인하고, 나머지 값을 상태에 맞게 읽으세요. FailedStep은 진단용 값이므로 정상 흐름의 분기 기준으로 사용하지 마세요.

Status 확인할 값 앱 처리
Success PlayerId, IsBlocked 이용 제한 상태가 아니면 로그인 후 화면으로 이동합니다.
BusinessOutcome BusinessOutcome, UnknownOutcomeCode 거절 사유에 맞게 분기하고, 모르는 값은 실패로 처리해 기록합니다.
UserCanceled 없음 사용자가 Google 계정 선택 화면이나 브라우저 인증 화면을 닫거나 동의를 거부한 상태이므로 로그인 화면을 유지합니다.
Failure Error.Code, Error.TraceId 기술 문제를 기록하고 재시도 또는 다른 로그인 수단을 제공합니다.

Success의 PlayerId는 같은 Google 계정으로 다시 로그인할 때도 같은 값입니다. IsBlocked가 true이면 로그인은 성공했지만 이용이 제한된 계정이므로 이용 제한을 기준으로 안내하세요.

UserCanceled와 Failure의 Cancelled를 구분하세요. 사용자가 인증 화면을 닫거나 동의를 거부한 경우는 UserCanceled이고, 앱이 CancellationToken으로 대기를 중단한 경우는 Failure와 HiveErrorCode.Cancelled입니다. Windows에서는 사용자가 브라우저를 닫아도 UserCanceled가 반환되지 않으므로 앱의 취소 처리로 대기를 끝내야 합니다.

상황 레시피 결과 앱 처리
Android에서 사용자가 계정 선택 화면을 닫음 UserCanceled 로그인 화면 유지
Android 기기에 요청할 Google 계정이 없음 Failure와 Unavailable Google 계정 추가 또는 다른 로그인 수단 안내
WebAuth 화면에서 사용자가 동의를 거부함 UserCanceled 로그인 화면 유지
Windows 외 OS에서 사용자가 브라우저 인증 화면을 닫음 UserCanceled 로그인 화면 유지
브라우저 콜백의 state가 현재 로그인 요청과 다름 Failure와 PermissionDenied 이번 로그인에서 시작하지 않은 콜백이므로 로그인 화면을 유지하고 다시 시도할 수 있게 함
Add-on 미등록, 잘못된 리다이렉트 URI, 네트워크 문제 Failure FailedStep과 Error.TraceId를 기록하고 설정 또는 네트워크 상태 확인
서버가 Google 자격 증명을 거부함 BusinessOutcome 또는 Failure Google 콘솔과 Hive 콘솔 설정, 인증 만료 여부 확인
앱이 대기를 취소함 Failure와 Cancelled 진행 중인 로그인 화면을 정리하고 로그인 화면 유지

BusinessOutcome에는 ProviderConfigNotFound, ProviderClientInfoNotExists, ProviderTokenError, InvalidAuthorizationCode, ExpiredAuthorizationCode, CodeChallengeMismatch, TemporarilyUnavailable 등이 포함될 수 있습니다. 레시피는 여러 호출의 거절 사유를 하나의 값으로 묶어 돌려주므로 외부 인증 제공자 로그인 응답 상태와 액세스 토큰과 리프레시 토큰 발급을 확인하세요. 서버 교환을 사용하면 외부 인증 코드 교환 응답 상태도 확인하세요. TemporarilyUnavailable만 1초, 3초, 6초처럼 간격을 늘려 가며 재시도하고, 나머지는 설정이나 인증 상태를 먼저 확인하세요.

Google id_token, 액세스 토큰, 인가 코드, WebAuth 콜백 URL은 로그, 크래시 리포트, 분석 이벤트에 남기지 마세요. UnknownOutcomeCode와 RawJson은 사용자에게 표시하지 말고, 앱 오류 기록이 필요한 경우에만 사용하세요.

10. 동작 확인

  • 앱 코드  앱에서 동작을 확인합니다.

Credential Manager와 WebAuth는 Unity 에디터에서 실제 인증 화면을 제공하지 않으므로 지원하는 기기와 빌드에서 확인하세요.

  1. Google Cloud Console과 Hive 콘솔 설정을 저장한 뒤 대상 OS로 앱을 빌드하세요.
  2. Android에서는 Google 계정 선택 화면이 나타나는지 확인하고, iOS·macOS·Windows에서는 Google 로그인 페이지와 콜백이 정상적으로 이어지는지 확인하세요.
  3. Success와 PlayerId를 확인하고 로그인 후 화면으로 이동하는지 확인하세요.
  4. 앱을 완전히 종료한 뒤 같은 Google 계정으로 다시 로그인해 PlayerId가 같은지 확인하세요.
  5. Android, iOS, macOS에서는 인증 화면을 닫아 UserCanceled가 반환되는지 확인하세요. Windows에서는 동의를 거부해 UserCanceled를 확인하고, 취소 버튼이나 제한 시간으로 Failure와 Cancelled가 반환되는지 확인하세요.

다음 단계

로그인한 사용자가 앱을 다시 실행할 때 로그인 화면을 건너뛰도록 하려면 자동 로그인을 참조하세요.

이미 로그인한 계정에 다른 로그인 수단을 연결하려면 외부 인증 제공자 연동을 참조하세요.

로그인한 계정에서 빠져나와 다른 계정으로 로그인하려면 로그아웃을 참조하세요.