유저네임 로그인

유저네임 계정으로 로그인합니다.

유저네임 계정으로 로그인할 때는 Username, Password, DeviceKey, ClientId, PKCE를 사용합니다.

1. 호출 파라미터 준비

유저네임 로그인에 필요한 파라미터를 준비합니다.

Username, DeviceKey

사용자가 로그인 시점에 입력한 Username과 앱이 이 기기에 저장해 둔 DeviceKey를 사용합니다. DeviceKey는 로그인 요청에서도 같은 길이·문자 검증을 거치므로, DeviceKey의 조건을 만족하는 값을 그대로 넣으세요.

Note

com.com2usplatform.hiveaxyl.storage 모듈을 사용하면 위 값을 사용자 기기에 저장해 두었다가 불러와 사용할 수 있습니다. 자동 로그인을 참조하세요.

Password

Password에는 현재 입력한 비밀번호를 SHA256으로 해시한 64자리 16진수 문자열을 입력합니다. 이 값은 유저네임 계정을 생성할 때 보낸 비밀번호 해시값과 일치해야 합니다. 앱에서 직접 생성해야 합니다.

Unity

using System.Security.Cryptography;
using System.Text;

// 비밀번호는 평문을 보내지 않고 SHA256(raw)의 16진수 문자열로 변환해 전달합니다.
static string Sha256Hex(string raw)
{
    using var sha = SHA256.Create();
    byte[] hash = sha.ComputeHash(Encoding.UTF8.GetBytes(raw));
    var sb = new StringBuilder(hash.Length * 2);
    foreach (byte b in hash) sb.Append(b.ToString("x2"));
    return sb.ToString();
}

ClientId

Hive 콘솔이 프로젝트 단위로 발급하는 Client ID입니다. 같은 프로젝트에 속한 모든 App ID가 같은 값을 사용합니다. 값은 보안 키 획득에서 확인하세요.

PKCE: codeChallenge와 codeVerifier

PKCE(codeVerifier·codeChallenge)는 발급되는 인가 코드가 중간에 탈취되어도 악용되지 않도록 보호하는 일회성 값 한 쌍입니다. 앱에서 직접 생성해야 합니다.

Unity

using System;
using System.Security.Cryptography;
using System.Text;

// PKCE(RFC 7636): codeVerifier 생성 + codeChallenge = BASE64URL(SHA256(codeVerifier))
static (string verifier, string challenge) CreatePkce()
{
    var bytes = new byte[32];
    using (var rng = RandomNumberGenerator.Create()) rng.GetBytes(bytes);
    string verifier = Base64Url(bytes);
    using var sha = SHA256.Create();
    string challenge = Base64Url(sha.ComputeHash(Encoding.ASCII.GetBytes(verifier)));
    return (verifier, challenge);
}
static string Base64Url(byte[] b) =>
    Convert.ToBase64String(b).TrimEnd('=').Replace('+', '-').Replace('/', '_');

2. 유저네임 로그인

LoginUsernameAsync

LoginUsernameAsync()를 호출해 유저네임 계정으로 로그인합니다. 사용자가 로그인 시점에 입력한 유저네임과 비밀번호를 사용하고, 비밀번호는 앱에서 SHA256으로 해시해 전달합니다.

호출 파라미터

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

UsernameLoginRequest

필드명	타입	필수 여부	설명
Username	string	Required	사용자가 입력한 유저네임
Password	string	Required	로그인 시점에 사용자가 입력한 비밀번호의 SHA256 해시 값(평문 금지). 계정 생성 때 보낸 값과 같아야 합니다.
ClientId	string	Required	프로젝트 단위로 발급되는 콘솔 보안 키의 Client ID
CodeChallenge	string	Required	PKCE 코드 챌린지
CodeChallengeMethod	CodeChallengeMethod	Required	PKCE 방식. S256
DeviceKey	string	Required	로그인 세션을 기기 단위로 구분하는 기기 식별 값. 22자 이상 64자 이하

호출 예시

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

Unity

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

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

var (codeVerifier, codeChallenge) = CreatePkce();

// 비밀번호는 로그인 시점의 사용자 입력을 SHA256 해시 후 전달합니다.
// DeviceKey에는 앱이 이 기기에 저장해 둔 값을 넣습니다.
// AuthLoginUsernameResult 객체를 반환
var result = await auth.LoginUsernameAsync(new UsernameLoginRequest {
    Username            = inputUsername,
    Password            = Sha256Hex(rawPassword),
    ClientId            = "{clientId}",
    CodeChallenge       = codeChallenge,
    CodeChallengeMethod = CodeChallengeMethod.S256,
    DeviceKey           = deviceKey,
});

Note

실제 서비스에서 사용자가 로그인 수단을 선택하는 UI는 앱 클라이언트에서 직접 구현해야 합니다.

응답 데이터

성공 시 AuthLoginUsernameResult.Success의 Data(LoginResponseData)에 로그인 결과가 담깁니다.

필드명	타입	필수 여부	설명
Data.PlayerId	long	Required	Player ID
Data.AuthorizationCode	string	Required	액세스 토큰과 리프레시 토큰 발급에 사용하는 인가 코드(토큰 발급에서 사용)
Data.ProviderList	IReadOnlyList<ProviderInfo>	Required	이 계정에 연동된 인증 제공자 목록
Data.IsBlock	bool	Required	이용 제한 여부
Data.CreatedAt	DateTimeOffset	Required	계정 생성 시각(UTC)

응답 예시

Unity

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

응답 상태

AuthLoginUsernameResult의 응답 케이스는 switch 구문으로 처리하는 것을 권장합니다. 분기 코드 예시는 세션 활성화하기의 통합 예시를 참조하세요.

응답 케이스	설명	앱 클라이언트 대응
Success	로그인 성공. Data.AuthorizationCode를 사용해 토큰을 발급한 뒤 세션을 시작합니다.	토큰 발급 후 세션 시작
UsernameVerifyFailed	유저네임 또는 비밀번호가 일치하지 않는 경우	재입력 안내
InvalidClientId	Client ID가 올바르지 않은 경우	콘솔 보안 키 확인
IpBlocked	접속 IP가 차단된 경우	정책 안내
ProviderConfigNotFound	앱에 설정된 로그인 수단(Provider 구성)이 없는 경우	콘솔 로그인 설정 확인
AppNotFound	앱 정보를 찾을 수 없는 경우	콘솔의 앱 등록 상태 확인
TerminateService	서비스가 종료된 앱인 경우	서비스 운영 상태 확인
UnknownOutcome	이 SDK 버전이 알지 못하는 신규 결과	로깅 후 보수적으로 처리
Failure	공통 Failure입니다. 필수 파라미터 누락 또는 형식 오류(invalid_parameter), 필수 필드 누락(missing_field), X-App-Id 헤더 누락(missing_app_id)도 이 경우에 해당합니다. 원인은 Failure.Problem.ExternalCode에 담깁니다. 공통 오류 처리를 참조하세요.	공통 오류 처리 기준에 따라 처리

다음 단계

• 토큰 발급하기