외부 인증 제공자 로그인

외부 인증 제공자 로그인은 Google 계정, Apple, Google Play Games, Steam, X 로그인에서 공통으로 거치는 단계입니다. Hive Axyl 인증 서버는 Add-on으로 획득하거나 외부 인증 코드 교환으로 받은 자격 증명을 검증합니다. 처음 인증한 계정이면 가입을, 이미 있는 계정이면 로그인을 처리합니다.

이 단계는 세션을 바로 만들지 않고 인가 코드만 반환합니다. 인가 코드를 토큰으로 교환하고 세션에 등록해야 로그인이 끝나므로, 토큰 발급과 세션 활성화까지 이어서 진행하세요.

1. 호출 파라미터값 준비

외부 인증 제공자 로그인 메서드의 호출 파라미터를 준비합니다.

ProviderUserId, ProviderToken

로그인할 사용자의 자격 증명입니다. 동작 흐름에 따라 값을 얻는 위치가 다릅니다.

• Direct Token 흐름: 로그인 수단별 Add-on의 응답 데이터
• Authorization Code 흐름: 외부 인증 코드 교환 응답의 Data.ProviderUserId와 Data.ProviderToken

Add-on의 어떤 응답 필드를 사용하는지는 각 로그인 수단의 '2단계. 로그인'에서 안내합니다.

DeviceKey, ClientId, PKCE

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

codeChallenge와 짝이 되는 codeVerifier는 토큰 발급과 세션 활성화에서 사용하므로 앱에 보관해 두세요.

2. 외부 인증 제공자 로그인

LoginProviderAsync

LoginProviderAsync()를 호출해 외부 인증 제공자의 자격 증명으로 로그인합니다. Hive Axyl 인증 서버가 자격 증명을 검증하고, 해당 계정에 연결된 Player ID와 토큰 발급용 인가 코드를 반환합니다.

호출 파라미터

필드명	타입	필수 여부	설명
request	ProviderLoginRequest	Required	외부 인증 제공자 로그인 요청
context	ApiCallContext	Optional	호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

ProviderLoginRequest

필드명	타입	필수 여부	설명
ProviderId	Provider	Required	로그인할 로그인 수단. Google, SigninApple, GooglePlayGames, Steam, X 중 하나
ProviderUserId	string	Required	외부 인증 제공자가 발급한 사용자 식별자. Steam은 Steam ID64
ProviderToken	string	Required	외부 인증 제공자가 발급한 인증 결과. Google 계정과 Apple은 id_token, Google Play Games와 X는 access_token, Steam은 Windows·macOS에서 받은 인증 티켓 또는 Android·iOS에서 Steam이 돌려준 쿼리 문자열 전체
DeviceKey	string	Required	기기 식별 값. 22자 이상 64자 이하
ClientId	string	Required	콘솔 보안 키의 Client ID
CodeChallenge	string	Required	PKCE 코드 챌린지
CodeChallengeMethod	CodeChallengeMethod	Required	PKCE 방식. S256

Note

게스트 로그인, 유저네임 로그인, 커스텀 계정 로그인은 이 메서드로 처리하지 않습니다. 각각 게스트 로그인, 유저네임 로그인, 커스텀 계정으로 로그인을 참조하세요.

호출 예시

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

Unity

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

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

var (codeVerifier, codeChallenge) = CreatePkce();

// providerUserId·providerToken은 Add-on 또는 외부 인증 코드 교환으로 받은 값,
// deviceKey는 앱이 보관 중인 기기 식별 값입니다.
var result = await auth.LoginProviderAsync(new ProviderLoginRequest {
    ProviderId          = Provider.Steam,
    ProviderUserId      = providerUserId,
    ProviderToken       = providerToken,
    DeviceKey           = deviceKey,
    ClientId            = "{clientId}",
    CodeChallenge       = codeChallenge,
    CodeChallengeMethod = CodeChallengeMethod.S256,
});

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

    case AuthLoginProviderResult.ProviderTokenError:
        // 자격 증명 검증 실패 → 해당 로그인 수단으로 다시 인증하도록 안내
        break;

    case AuthLoginProviderResult.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()는 토큰 발급과 세션 활성화에서 정의합니다.

Note

사용자가 로그인 수단을 선택하는 로그인 화면 UI는 앱 클라이언트에서 직접 구현해야 합니다. 화면에 노출할 로그인 수단 목록을 얻는 방법은 로그인 화면 구성을 참조하세요.

응답 데이터

성공 시 AuthLoginProviderResult.Success의 Data(LoginResponseData)에 결과가 담깁니다.

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

ProviderInfo

필드명	타입	필수 여부	설명
ProviderId	Provider	Required	연동된 로그인 수단
ProviderUserId	string	Required	연동된 로그인 수단의 사용자 식별자
ProviderIndex	int	Required	로그인 수단의 숫자 식별자

Data.IsBlock이 true이면 이용이 제한된 사용자입니다. 제한 사유와 기간을 확인하고 앱 진입을 차단하는 방법은 이용 제한을 참조하세요.

응답 예시

Unity

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

응답 상태

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

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

3. 토큰 발급과 세션 활성화

로그인 응답으로 받은 인가 코드만으로는 로그인 상태가 만들어지지 않습니다. 인가 코드를 액세스 토큰과 리프레시 토큰으로 교환하고, 토큰을 세션에 등록해야 인증이 필요한 다른 메서드를 호출할 수 있습니다.

이 두 단계는 모든 로그인 수단이 동일하며, 게스트 로그인이나 유저네임 로그인과도 같습니다. 각 메서드의 전체 파라미터와 응답 상태는 토큰 발급하기와 세션 활성화하기를 참조하세요.

1. ITokenService.IssueTokenAsync()에 인가 코드와 codeVerifier를 전달해 액세스 토큰과 리프레시 토큰을 발급받습니다.
2. ISessionManager.SetSession()에 발급받은 토큰과 Player ID, 액세스 토큰 만료 시각을 전달해 세션을 등록합니다.

인가 코드는 발급 후 180초가 지나면 만료되므로 로그인 직후에 이어서 호출하세요.

아래는 두 단계를 하나의 헬퍼로 묶은 예시입니다. 각 로그인 수단의 구현 예시에서 이 헬퍼를 StartSessionAsync()로 호출합니다.

Unity

using System;
using System.Threading.Tasks;
using Hive.Axyl.Auth;
using Hive.Axyl.Core;

// 인가 코드로 토큰을 발급하고 세션을 활성화합니다.
static async Task StartSessionAsync(string authorizationCode, string codeVerifier, long playerId)
{
    ITokenService   token   = HiveCore.Resolve<ITokenService>();
    ISessionManager session = HiveCore.Resolve<ISessionManager>();

    var issueResult = await token.IssueTokenAsync(new AuthorizationCodeTokenRequest {
        GrantType         = "authorization_code",
        ClientId          = "{clientId}",
        AuthorizationCode = authorizationCode,
        CodeVerifier      = codeVerifier,   // 로그인 호출에 보낸 codeChallenge와 짝
    });
    if (issueResult is not TokenIssueTokenResult.Success issued)
    {
        // 토큰 발급 실패 처리 (InvalidGrant, InvalidGrantCodeChallenge 등)
        return;
    }

    // SDK는 로그인 시 세션을 자동으로 설정하지 않습니다. 직접 등록합니다.
    session.SetSession(
        issued.Data.AccessToken,
        issued.Data.RefreshToken ?? string.Empty,   // SetSession은 null을 허용하지 않습니다
        playerId,
        DateTimeOffset.UtcNow.ToUnixTimeSeconds() + issued.Data.ExpiresIn);
}

Note

세션을 활성화한 뒤 액세스 토큰이 만료되면 자동으로 갱신하도록 설정할 수 있습니다. 자세한 내용은 자동 로그인을 참조하세요.

다음 단계

• Google 계정으로 로그인: 2단계. 로그인
• Apple로 로그인: 2단계. 로그인
• Google Play Games 모바일 앱 로그인: 2단계. 로그인
• Steam 계정으로 로그인: 2단계. 로그인
• X(Twitter) 계정으로 로그인: 2단계. 로그인