콘텐츠로 이동

커스텀 계정으로 로그인

커스텀 계정은 앱이 직접 운영하는 인증 시스템의 계정을 Hive Axyl 계정과 연결해 사용하는 로그인 수단입니다. Hive Axyl이 공식 지원하는 외부 인증 제공자 외의 인증 수단을 쓰거나, 이미 운영 중인 회원 시스템을 그대로 사용해야 할 때 선택합니다.

다른 로그인 수단과 달리 앱 클라이언트는 인증 결과를 Hive Axyl 인증 서버로 직접 보내지 않습니다. 앱 서버가 사용자를 인증한 뒤 Hive Axyl 서버에서 사전 인증 키인 grant key를 발급받아 앱 클라이언트에 전달합니다. 앱 클라이언트는 이 grant key로 로그인합니다. 사용자의 인증 정보가 앱 클라이언트를 거치지 않으므로 노출 위험이 줄어듭니다.

1. 커스텀 계정 로그인 흐름

커스텀 계정 로그인은 앱 서버와 앱 클라이언트가 나누어 처리합니다.

  1. 앱 클라이언트가 사용자를 앱 서버 또는 앱이 사용하는 인증 시스템으로 인증합니다.
  2. 앱 서버가 사전 인가 키 발급으로 Hive Axyl 서버에 grant key 발급을 요청합니다. 이때 커스텀 인증 제공자 식별자와 그 제공자의 사용자 식별자를 함께 전달합니다.
  3. 앱 서버가 발급받은 grant key를 앱 클라이언트에 전달합니다.
  4. 앱 클라이언트가 grant key로 LoginCustomProviderAsync()를 호출합니다.
  5. Hive Axyl 인증 서버가 grant key를 검증하고, 연결된 Player ID와 토큰 발급용 인가 코드를 반환합니다.

grant key는 발급 후 60초 동안만 유효하고 한 번만 사용할 수 있습니다. 따라서 앱 서버는 앱 클라이언트가 로그인을 시도하는 시점에 맞춰 발급해야 합니다.

grant key의 개념과 앱 서버가 처리할 내용은 추가 보안 적용을 참조하세요.

Note

처음 로그인하는 커스텀 계정에는 Player ID가 새로 발급됩니다. 이미 사용 중인 Player ID에 커스텀 계정을 연결하려면 커스텀 계정 연동을 사용하세요.

2. 호출 파라미터값 준비

커스텀 계정 로그인 메서드의 호출 파라미터를 준비합니다.

GrantKey

앱 서버가 발급받아 앱 클라이언트에 전달한 사전 인증 키입니다.

DeviceKey, ClientId, PKCE

DeviceKey, ClientId, PKCE codeChallenge는 다른 로그인 수단과 같은 방식으로 준비합니다. 각 값의 의미와 준비 방법은 앱 클라이언트가 준비하는 값을 참조하세요.

codeChallenge와 짝이 되는 codeVerifier는 토큰 발급 단계에서 사용하므로 앱에 보관해 두세요.

3. 커스텀 계정 로그인

Method

LoginCustomProviderAsync

LoginCustomProviderAsync()를 호출해 커스텀 계정으로 로그인합니다. Hive Axyl 인증 서버가 grant key를 검증하고, 처음 로그인하는 계정이면 가입을, 이미 있는 계정이면 로그인을 처리합니다.

호출 파라미터

필드명 타입 필수 여부 설명
request CustomLoginRequest Required 커스텀 계정 로그인 요청
context ApiCallContext Optional 호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

CustomLoginRequest

필드명 타입 필수 여부 설명
GrantKey string Required 앱 서버가 발급받아 전달한 사전 인증 키
DeviceKey string Required 기기 식별 값. 22자 이상 64자 이하
ClientId string Required 콘솔 보안 키의 Client ID
CodeChallenge string Required PKCE 코드 챌린지
CodeChallengeMethod CodeChallengeMethod Required PKCE 방식. S256

호출 예시

요청 수행이 불가능한 공통 실패(Failure)의 결과 모델과 처리 원칙은 공통 오류 처리를 참조하세요.

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

IAuthService auth = HiveCore.Resolve<IAuthService>();

var (codeVerifier, codeChallenge) = CreatePkce();

var result = await auth.LoginCustomProviderAsync(new CustomLoginRequest {
    GrantKey            = customLoginGrantKey,
    DeviceKey           = deviceKey,
    ClientId            = "{clientId}",
    CodeChallenge       = codeChallenge,
    CodeChallengeMethod = CodeChallengeMethod.S256,
});

switch (result)
{
    case AuthLoginCustomProviderResult.Success success:
        // 로그인 성공 → 토큰을 발급하고 세션을 활성화합니다.
        await StartSessionAsync(success.Data.AuthorizationCode, codeVerifier, success.Data.PlayerId);
        break;

    case AuthLoginCustomProviderResult.InvalidGrantKey:
        // grant key가 만료되었거나 이미 사용됨 → 앱 서버에서 새로 발급받아 재시도
        break;

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

    // 안전망: 처리하지 않은 결과 및 알 수 없는 신규 결과(UnknownOutcome)
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

CreatePkce()는 게스트 계정 생성에서 정의한 헬퍼이고, StartSessionAsync()의 정의와 세션 활성화 절차는 토큰 발급과 세션 활성화를 참조하세요.

응답 데이터

성공 시 AuthLoginCustomProviderResult.Success의 Data(LoginResponseData)에 결과가 담깁니다. 응답 데이터 구조는 외부 인증 제공자 로그인의 응답 데이터와 같습니다.

필드명 타입 필수 여부 설명
Data.PlayerId long Required 로그인한 Player ID. 연결된 계정이 없으면 새로 발급됩니다.
Data.AuthorizationCode string Required 액세스 토큰과 리프레시 토큰 발급에 사용하는 인가 코드. 발급 후 180초가 지나면 만료됩니다.
Data.ProviderList IReadOnlyList<ProviderInfo> Required 이 Player ID에 연동된 로그인 수단 목록
Data.IsBlock bool Required 이용 제한 여부
Data.CreatedAt DateTimeOffset Required 계정 최초 생성 시각(UTC)

응답 예시

// Success 분기에서 success.Data 예시
// success.Data.PlayerId          = 10000021454
// success.Data.AuthorizationCode = "ac_..."   // 토큰 발급에 사용
// success.Data.IsBlock           = false

응답 상태

AuthLoginCustomProviderResult의 응답 케이스는 switch 구문으로 처리하는 것을 권장합니다.

응답 케이스 설명 앱 클라이언트 대응
Success 로그인 성공. Data.AuthorizationCode로 토큰을 발급한 뒤 세션을 활성화합니다. 토큰 발급 후 세션 활성화
InvalidGrantKey grant key가 만료되었거나 이미 사용되었거나 요청 정보와 맞지 않는 경우 앱 서버에서 grant key를 새로 발급받아 재시도
ProviderNotSupported 커스텀 계정 로그인이 지원되지 않는 경우 콘솔의 로그인 설정 확인
ProviderConfigNotFound 콘솔에 커스텀 계정 설정이 없는 경우 콘솔의 로그인 설정 확인
InvalidClientId Client ID가 올바르지 않은 경우 콘솔 보안 키 확인
IpBlocked 접속 IP가 차단된 경우 정책 안내
AppNotFound 앱 정보를 찾을 수 없는 경우 콘솔의 앱 등록 상태 확인
TerminateService 서비스가 종료된 앱인 경우 서비스 운영 상태 확인
UnknownOutcome 이 SDK 버전이 알지 못하는 신규 결과 로깅 후 보수적으로 처리
Failure 공통 Failure입니다. 필수 파라미터 누락·형식 오류(invalid_parameter), 필수 필드 누락(missing_field), X-App-Id 헤더 누락(missing_app_id)도 여기로 분기하며 원인은 Failure.Problem.ExternalCode에 담깁니다. 공통 오류 처리를 참조하세요. 공통 오류 처리 기준에 따라 처리

다음 단계