외부 인증 제공자 연동 구현하기

레시피 코드로 외부 인증 제공자 연동을 구현하려면 아래 절차를 순서대로 완료하세요.

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

전체 흐름

각 단계에서 무엇을 설정하고 무엇을 호출하는지는 아래와 같습니다.

순서	구분	하는 일
1	Hive 콘솔	연결할 로그인 수단의 인증 정보 등록
2	Hive Axyl SDK	인증 모듈과 로그인 수단별 Add-on 설치
3	Hive Axyl SDK	SDK 초기화와 모듈 등록
4	레시피 코드	레시피 폴더 복사
5	레시피 코드, 앱 코드	자격 증명 소스 준비
6	레시피 코드	연동 호출
7	앱 코드	연동 결과 처리
8	앱 코드	게스트 자격 증명 정리
9	앱 코드	동작 확인

연동을 시작한 뒤에는 다른 계정 작업을 실행하지 마세요

레시피는 인증 화면을 띄우기 전과 연동을 요청하기 직전의 세션 액세스 토큰을 비교합니다. 그 사이에 로그인, 로그아웃, 계정 전환이 일어나 값이 달라지면 연동을 보내지 않고 중단합니다. 연동 버튼을 누른 뒤에는 다른 계정 작업 진입점을 막으세요.

1. Hive 콘솔 설정

• Hive 콘솔 | Hive 콘솔에서 설정하거나 확인합니다.

연결할 로그인 수단의 인증 정보를 Hive 콘솔에 등록하세요. 등록하지 않은 로그인 수단으로 연동을 요청하면 ProviderConfigNotFound 또는 ProviderClientInfoNotExists로 거절됩니다.

각 로그인 수단은 외부 콘솔에서 인증 정보를 먼저 발급받아야 합니다. 발급 절차와 Hive 콘솔 등록 절차는 아래에서 확인하세요.

• Google: Hive 콘솔에 인증 정보 등록
• Apple: Hive 콘솔에 인증 정보 등록
• Google Play Games: Hive 콘솔에 인증 정보 등록
• Steam: Hive 콘솔에 인증 정보 등록
• X: Hive 콘솔에 인증 정보 등록

앱이 이미 그 로그인 수단으로 로그인을 제공하고 있다면 이 단계는 끝난 상태입니다. 연동은 로그인과 같은 설정을 사용합니다.

2. SDK 모듈 설치

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

  ---

  상세 절차: 모듈 설치

인증 모듈과 연결할 로그인 수단의 Add-on을 Unity 프로젝트에 설치하세요. Add-on은 외부 인증 제공자의 인증 화면을 띄우는 Hive Axyl SDK 확장 패키지이고, 5단계에서 준비하는 자격 증명 소스가 이 Add-on을 호출합니다. Add-on 패키지가 없으면 자격 증명 소스가 컴파일 대상에서 빠지므로 앱 코드에서 사용하지 못합니다.

패키지	필요 여부	역할
com.com2usplatform.hiveaxyl.core	필수	SDK 초기화와 로그인 세션 관리
com.com2usplatform.hiveaxyl.auth	필수	로그인 수단 연결

연결할 로그인 수단에 맞는 Add-on을 함께 설치하세요.

• Google, Android 네이티브 계정 선택 화면: com.com2usplatform.hiveaxyl.auth.addon.credentialmanager
• Google, 브라우저 로그인: com.com2usplatform.hiveaxyl.auth.addon.webauth
• Apple, 네이티브 로그인 화면: com.com2usplatform.hiveaxyl.auth.addon.apple
• Apple, 브라우저 로그인: com.com2usplatform.hiveaxyl.auth.addon.webauth
• Google Play Games: com.com2usplatform.hiveaxyl.auth.addon.gpg
• Steam, Steamworks 인증 티켓: com.com2usplatform.hiveaxyl.auth.addon.steam
• Steam, 브라우저 로그인: com.com2usplatform.hiveaxyl.auth.addon.webauth
• X: com.com2usplatform.hiveaxyl.auth.addon.webauth

여러 로그인 수단을 연동 대상으로 제공한다면 해당 Add-on을 모두 설치하세요.

3. SDK 초기화

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

  ---

  상세 절차: 모듈 초기화

앱 시작 지점에서 SDK를 한 번 초기화하고 인증 모듈과 Add-on을 등록하세요. 레시피는 SDK를 초기화하지 않으므로, 초기화하지 않은 상태에서 호출하면 FailedPrecondition 오류로 실패합니다.

아래는 Apple 계정을 연동하는 앱의 초기화 예제 코드입니다.

Unity

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

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

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

{appId}에는 Hive 콘솔에서 만든 App ID를 입력하세요.

연동 자체는 AddAuth()로 등록하는 IAuthService만 사용합니다. AddToken()은 연동보다 앞서 일어나는 로그인에 필요하므로 함께 등록된 상태여야 합니다. 로그인 수단별 Add-on 등록 메서드는 로그인 수단별 Add-on 초기화에서 확인하세요.

4. 레시피 코드 설치

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

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

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

• Recipes.asmdef: 레시피 공통 어셈블리 정의
• AssemblyInfo.cs: 내부 헬퍼를 다른 레시피 어셈블리에 공개하는 설정
• Helper/: 여러 레시피가 함께 사용하는 공통 코드
• ProviderLogin/: IProviderCredentialSource 계약과 자격 증명 처리 코드
• LinkProvider/: LinkProviderRecipe, 결과 유형
• GuestLogin/: 게스트 로그인을 제공해 8단계를 수행할 때 필요한 GuestCredential

연결할 로그인 수단의 자격 증명 소스 폴더도 함께 복사하세요.

• Google, Android 네이티브 계정 선택 화면: ProviderLogin.CredentialManager/
• Google, 브라우저 로그인: ProviderLogin.WebAuth/
• Apple, 네이티브 로그인 화면: ProviderLogin.Apple/
• Apple, 브라우저 로그인: ProviderLogin.WebAuth/
• Google Play Games: ProviderLogin.Gpg/
• Steam, Steamworks 인증 티켓: ProviderLogin.Steam/
• Steam, 브라우저 로그인: ProviderLogin.WebAuth/
• X: ProviderLogin.WebAuth/

ProviderLogin.WebAuth/는 JSON 처리에 Newtonsoft Json을 사용하므로 이 폴더를 복사할 때는 com.unity.nuget.newtonsoft-json 패키지도 설치하세요.

LinkProvider/만 복사하면 컴파일되지 않습니다

LinkProviderRecipe는 ProviderLogin/의 자격 증명 처리 코드와 Helper/의 공통 코드를 사용합니다. Helper/, Recipes.asmdef, AssemblyInfo.cs, ProviderLogin/을 함께 복사하세요.

앱 코드에서 레시피를 호출하려면 앱 쪽 어셈블리 정의의 references에 아래 어셈블리를 추가하세요. 원본 Recipes.asmdef의 autoReferenced 값이 false이므로 앱 어셈블리가 자동으로 참조하지 않습니다.

MyApp.asmdef

{
  "name": "MyApp",
  "references": [
    "Hive.Axyl.Core",
    "Hive.Axyl.Auth",
    "Hive.Axyl.Auth.Addon.Apple",
    "Hive.Axyl.Samples.Recipes",
    "Hive.Axyl.Samples.Recipes.ProviderLogin",
    "Hive.Axyl.Samples.Recipes.LinkProvider",
    "Hive.Axyl.Samples.Recipes.ProviderLogin.Apple"
  ]
}

MyApp은 앱에서 사용하는 어셈블리 이름으로 바꾸고, 기존 설정과 참조는 유지하세요. Unity 어셈블리는 참조를 전이하지 않으므로 앱 코드가 직접 사용하는 어셈블리를 모두 여기에 적어야 합니다. Hive.Axyl.Core에는 CoreConfig와 HiveError가, Hive.Axyl.Auth에는 AddAuth()와 AddToken()이, Hive.Axyl.Auth.Addon.Apple에는 AddAppleSignIn()이 들어 있습니다. 다른 로그인 수단으로 연동한다면 마지막 두 항목을 그 로그인 수단의 Add-on 어셈블리와 자격 증명 소스 어셈블리로 바꾸세요.

5. 자격 증명 소스 준비

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

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

LinkProviderAsync()를 호출하려면 연결할 계정의 인증 결과가 먼저 필요하므로, 인증 화면을 띄워 그 값을 받아오는 IProviderCredentialSource 객체를 준비해야 합니다. 이 객체를 자격 증명 소스라고 부릅니다. 연동은 로그인과 같은 자격 증명 소스를 사용하므로, 앱이 이미 그 로그인 수단으로 로그인을 제공한다면 로그인에서 소스를 만드는 코드를 그대로 사용하세요. 소스 클래스와 생성자 인자는 로그인 수단마다 다르며, 인자에 넣을 값은 아래 표에 연결한 로그인 구현 절차에 따라 준비하세요.

로그인 수단과 인증 방식	소스 클래스	생성자 인자
Google, Android 네이티브 계정 선택 화면	GoogleCredentialManagerCredentialSource	Google Cloud Console에서 만든 웹 애플리케이션 유형 OAuth 클라이언트 ID. Android 유형 OAuth 클라이언트 ID와 다른 값이며, 준비 방법은 Google 로그인의 Android Credential Manager 방식을 참조하세요.
Google, 브라우저 로그인	GoogleCredentialSource	WebAuthOptions. OAuth 클라이언트 ID, 요청 범위, 리다이렉트 URI를 담는 값이며, 넣을 값은 Google 로그인의 브라우저 방식을 참조하세요.
Apple, 네이티브 로그인 화면	AppleCredentialSource	AppleSignInOptions. 이메일과 이름을 요청할 때만 전달하며, 넣을 값은 Apple 로그인의 네이티브 방식을 참조하세요.
Apple, 브라우저 로그인	AppleWebCredentialSource	WebAuthOptions와 앱 콜백 주소 {appId}://oauth-callback. 앱 콜백 주소는 Android에서만 전달합니다. 넣을 값은 Apple 로그인의 브라우저 방식을, 인증 결과가 Hive Axyl 중계 주소를 거쳐 앱으로 돌아오는 방식과 Android 앱 콜백 스킴 등록은 Hive Axyl 중계 주소를 참조하세요.
Google Play Games	GooglePlayGamesCredentialSource	Google Cloud Console에서 만든 웹 애플리케이션 유형 OAuth 클라이언트 ID. 준비 방법은 Google Play Games 로그인의 Play Games 자격 증명 소스 준비를 참조하세요.
Steam, Steamworks 인증 티켓	SteamCredentialSource	인증 티켓 identity 문자열과 Steam ID64. 두 값을 준비하는 방법은 Steam 로그인의 Steam 클라이언트 방식을 참조하세요.
Steam, 브라우저 로그인	SteamOpenIdCredentialSource	Steam이 돌려보낼 주소 returnTo와 앱 콜백 주소 {appId}://oauth-callback. returnTo는 Hive Axyl 중계 주소에 앱 콜백 주소와 난수를 붙인 값이므로 연동을 시도할 때마다 SteamRelayReturnTo.Build()로 새로 만드세요. 만드는 방법과 Android 앱 콜백 스킴 등록은 Steam 로그인의 브라우저 방식을 참조하세요.
X	XCredentialSource	WebAuthOptions. 넣을 값은 X 로그인의 ClientId, DeviceKey와 OAuth 설정 준비를 참조하세요.

아래는 Apple 네이티브 로그인 화면으로 연동할 자격 증명 소스를 만드는 예제 코드입니다. 이메일과 이름을 요청하지 않으므로 AppleSignInOptions를 생략합니다.

Unity

using Hive.Axyl.Samples.Recipes;

IProviderCredentialSource source = new AppleCredentialSource();

6. 연동 호출

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

준비한 자격 증명 소스를 LinkProviderAsync()에 전달하세요. 레시피가 인증 화면을 띄워 자격 증명을 받고, 그 자격 증명을 현재 로그인한 계정에 연결합니다.

사용자가 화면을 닫거나 연동을 취소할 때 기다리기를 멈출 수 있도록 CancellationTokenSource를 함께 준비하세요.

Unity

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

var recipe = new LinkProviderRecipe();

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

LinkProviderOutcome outcome = await recipe.LinkProviderAsync(source, token);

화면을 닫거나 사용자가 취소를 선택할 때 cancellation.Cancel()을 호출하고, 호출이 끝나면 cancellation.Dispose()로 정리하세요.

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

구분	호출	확인할 곳
레시피 코드	로그인 세션 확인과 인증 전후의 세션 액세스 토큰 비교	없음
Add-on	자격 증명 소스로 인증 화면을 띄워 ProviderUserId와 ProviderToken 확보	호출 파라미터값 준비
Hive Axyl SDK	Google Play Games와 Google, Apple, X의 브라우저 로그인에서 받은 인가 코드를 ExchangeProviderTokenAsync()로 ProviderUserId와 ProviderToken으로 교환. 브라우저 로그인에서는 RedirectUri에 인가 요청에 사용한 리다이렉트 URI를 그대로 넣고, Google과 X는 CodeVerifier에 레시피가 만든 PKCE 값을 넣음. tokenEndpoint를 지정한 Google과 X는 이 호출 대신 외부 인증 제공자와 직접 교환	외부 인증 코드 교환
Hive Axyl SDK	LinkProviderAsync()로 로그인 수단을 현재 Player ID에 연결	계정 연동 처리 및 조회

위 표의 상세 절차는 Hive Axyl SDK 메서드를 직접 호출할 때를 기준으로 쓰여 있습니다. 자격 증명을 확보하는 작업처럼 레시피가 대신하는 단계는 앱에서 다시 구현하지 마세요. 각 호출이 무엇을 주고받는지 확인할 때만 참조하세요.

7. 연동 결과 처리

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

  ---

  상세 절차: HiveError 정보

LinkProviderOutcome은 Status로 연동 결과를 알려 줍니다. FailedStep은 진단용 값이므로 앱의 정상 흐름을 분기하는 기준으로 사용하지 마세요.

Status	확인할 값	앱 처리
Success	PlayerId, ProviderUserId	화면의 연동 목록을 갱신하고 8단계를 실행합니다.
BusinessOutcome	IsConflict, BusinessOutcome, UnknownOutcomeCode	충돌과 거절을 구분해 분기하고, 모르는 값은 실패로 처리해 기록합니다.
UserCanceled	없음	사용자가 인증 화면을 닫은 상태이므로 이전 화면으로 돌아갑니다.
Failure	Error.Code, Error.TraceId	Error.Code에 맞게 분기하고 기술 문제를 기록합니다.

연동된 로그인 수단 목록은 로그인 응답에만 담겨 오므로, 연동한 뒤에는 앱이 화면의 목록에 ProviderUserId를 직접 추가해 갱신하세요.

오류를 기록할 때는 FailedStep을 함께 남기세요. 값은 None, Resolve, AcquireCredential, Link 네 가지이며, 어느 단계에서 멈췄는지 알려 줍니다.

7.1. 충돌 처리

충돌은 요청이 잘못된 것이 아니라 계정의 현재 상태와 부딪힌 결과입니다. IsConflict가 true인 세 가지 결과는 다시 시도해도 같은 답이 돌아오므로, 연동 실패로 안내하지 말고 상태에 맞는 화면을 보여 주세요.

BusinessOutcome	의미	앱 처리
ProviderOwnedByOther	연결하려는 계정이 다른 Player ID에 이미 연결된 상태	사용자에게 어느 계정을 사용할지 선택하도록 요청합니다. 처리 방법은 계정 연동 시 충돌 처리를 참조하세요.
ProviderTypeAlreadyExists	현재 계정에 같은 종류의 로그인 수단이 이미 연결된 상태	기존 연결을 해제한 뒤 다시 연동하도록 안내합니다. 해제 방법은 계정 연동 해제를 참조하세요.
ProviderAlreadyConnected	같은 계정이 이미 연결된 상태	요청한 연동이 이미 되어 있으므로 연동 완료 상태로 화면을 갱신합니다.

충돌을 앱이 임의로 해결하지 마세요

ProviderOwnedByOther는 사용자가 계정 두 개를 가진 상태이고, ProviderTypeAlreadyExists는 같은 종류의 로그인 수단 두 개 중 무엇을 남길지 정하지 않은 상태입니다. 앱이 대신 골라 다른 계정으로 로그인하거나 기존 연결을 끊으면 사용자가 한쪽 계정의 진행 상태를 잃습니다.

7.2. 거절 사유 처리

충돌이 아닌 BusinessOutcome 값은 연동이 거절된 사유이며, 값마다 앱이 확인할 설정, 입력, 계정 상태가 다릅니다. 레시피는 연동 호출과 외부 인증 코드 교환 호출에서 나온 거절 사유를 하나의 값으로 묶어 돌려주고, 상세 절차의 이름 가운데 TerminateService만 ServiceTerminated로 바꿉니다. 값별 의미와 대응은 거절 사유가 나온 호출에 따라 아래에서 확인하세요.

• LinkProviderAsync(): 계정 연동 응답 상태
• ExchangeProviderTokenAsync(): 외부 인증 코드 교환 응답 상태. Google Play Games와 Google, Apple, X의 브라우저 로그인에서 호출

레시피가 해석하지 못한 결과를 받으면 BusinessOutcome은 Unrecognized입니다. 외부 인증 코드 교환의 ProviderTokenExchangeNotSupported도 레시피가 이름을 붙이지 않은 결과이므로 Unrecognized로 돌아옵니다. 이때는 UnknownOutcomeCode로 두 경우를 구분하세요. 값이 있으면 서버가 보낸 결과 코드를 이 SDK 버전이 모른다는 뜻이고, 비어 있으면 SDK는 아는 결과지만 레시피가 이름을 붙이지 않았다는 뜻입니다. 어느 쪽이든 위 두 곳에서 찾지 말고 UnknownOutcomeCode와 RawJson을 기록한 뒤 실패로 처리하고, 두 값은 사용자에게 표시하지 마세요.

7.3. 실패와 취소 처리

Failure는 기술 문제로 연동을 끝까지 실행하지 못한 결과이므로, Error.Code로 원인을 구분해 처리하세요.

Error.Code	의미	앱 처리
FailedPrecondition	SDK가 초기화되지 않았거나 로그인 세션이 없는 상태. Android에서 Apple 브라우저 로그인에 앱 콜백 주소를 전달하지 않아도 발생	초기화와 로그인 상태, 5단계의 생성자 인자를 확인한 뒤 연동 버튼을 다시 노출합니다.
Aborted	인증 화면이 열려 있는 동안 세션 액세스 토큰이 바뀐 상태. 계정이 바뀌지 않아도 같은 사용자의 액세스 토큰이 갱신되면 발생하므로, 연동 진입점을 막아도 피할 수 없음	연동을 보내지 않은 상태이므로 실패로 안내하지 않습니다. 현재 로그인한 계정을 확인한 뒤 처음부터 다시 시작합니다.
Cancelled	앱이 취소 토큰으로 기다리기를 멈춘 상태	아래 취소 처리를 따릅니다.

취소는 진행 중인 연동을 되돌리지 않습니다. 요청이 Hive Axyl 인증 서버에 도달한 뒤 취소했다면 이미 연결이 끝났을 수 있으므로, 같은 로그인 수단으로 연동을 다시 실행해 결과를 확인하세요. ProviderAlreadyConnected가 돌아오면 연결된 상태입니다. 이때 게스트 자격 증명 정리는 8단계의 안내를 따르세요.

8. 게스트 자격 증명 정리

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

  ---

  상세 절차: 게스트 자격 증명 저장소 준비

게스트 계정에 첫 연동이 끝나면 Hive Axyl 인증 서버가 그 Player ID의 게스트 토큰을 무효로 만듭니다. 저장해 둔 게스트 자격 증명을 지우지 않으면 다음 실행에서 쓸 수 없는 값으로 로그인을 시도해 InvalidGuestToken으로 거절됩니다.

응답에는 이번이 첫 연동인지 알려 주는 값이 없으므로, 연동에 성공하면 저장된 게스트 자격 증명을 지우세요. 지우기 전에는 LinkProviderOutcome.PlayerId와 저장된 GuestCredential.PlayerId가 같은지 비교하세요. 연동 전에 다른 계정으로 로그인했다면 저장된 자격 증명이 이번에 연동한 계정의 것이 아닐 수 있고, 그 값을 지우면 연동과 관계없는 계정으로 들어가는 길을 없애게 됩니다.

Unity

if (outcome.Status == LinkProviderStatus.Success)
{
    GuestCredential stored = await guestCredentialStore.LoadAsync(token);

    if (stored != null && stored.PlayerId == outcome.PlayerId)
    {
        await guestCredentialStore.DeleteAsync(token);
    }
}

guestCredentialStore는 게스트 자격 증명 저장소 준비에서 만든 저장소입니다. 게스트 로그인을 제공하지 않는 앱에는 지울 값이 없으므로 이 단계를 건너뛰세요.

취소 뒤에 확인한 연동은 위 분기로 정리되지 않습니다

취소 뒤에 다시 실행한 연동이 ProviderAlreadyConnected를 반환하면 Status는 BusinessOutcome이고 PlayerId는 0입니다. 이때는 현재 로그인한 Player ID와 저장된 GuestCredential.PlayerId를 비교해 같을 때만 지우세요.

9. 동작 확인

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

실제 기기에서 연동과 재로그인을 확인하세요. Unity 에디터에서는 Add-on이 등록되지 않아 자격 증명 소스가 Unavailable 오류를 반환하므로 인증 화면부터 검증할 수 없습니다.

1. 게스트로 로그인한 뒤 연동을 실행하세요. Android에서 브라우저 로그인을 마친 뒤 앱으로 돌아오지 않으면 5단계에 연결한 로그인 구현 절차에서 Android 스킴 등록을 확인하세요.
2. Success를 확인하고 저장된 게스트 자격 증명이 지워졌는지 확인하세요.
3. 앱을 완전히 종료한 뒤 다시 실행하고, 연동한 로그인 수단으로 로그인하세요.
4. 연동 결과의 PlayerId와 로그인 결과의 Player ID가 같은지 확인하세요.
5. 같은 계정으로 연동을 한 번 더 실행해 ProviderAlreadyConnected가 반환되는지 확인하세요.

다음 단계

연결한 로그인 수단을 끊는 기능에는 레시피가 없습니다. Hive Axyl SDK 메서드를 직접 호출해 구현하려면 계정 연동 해제를 참조하세요.

연동을 마친 계정에서 빠져나와 다른 계정으로 로그인하도록 하려면 로그아웃 활용 가이드를 참조하세요.