시작하기

외부 인증 제공자 로그인은 수단마다 구현 방법이 조금씩 다릅니다. 하지만 동작 흐름과 앱 클라이언트가 준비해야 하는 값은 모든 로그인 수단에서 같습니다. 이 페이지에서 공통 부분을 먼저 확인한 뒤 각 로그인 수단을 구현하세요.

Hive Axyl SDK는 전체 로그인 절차를 대신 처리하지 않고 로그인에 필요한 기능을 제공합니다. 앱 클라이언트는 OS 분기, PKCE 값 생성, nonce 생성, deviceKey 생성과 보관, 로그인 화면 UI를 직접 구현하고, 아래 기능을 순서대로 호출해 로그인을 완성합니다.

로그인 수단별 Add-on: 해당 OS의 네이티브 인증 화면을 띄워 자격 증명 획득
웹 로그인 세션: 네이티브 Add-on이 없는 조합에서 외부 인증 제공자의 로그인 페이지를 열어 자격 증명 획득
IAuthService: 자격 증명을 Hive Axyl 인증 서버로 보내 로그인 처리 후 인가 코드 수령
ITokenService: 인가 코드를 액세스 토큰과 리프레시 토큰으로 교환
ISessionManager: 발급받은 토큰을 세션에 등록해 로그인 완료

로그인 동작 흐름은 자격 증명을 획득하는 빌딩 블록이 무엇을 반환하는지에 따라 'Direct Token 흐름'과 'Authorization Code 흐름'으로 나뉩니다. 어느 흐름을 따르는지는 외부 인증 제공자와 앱이 실행되는 OS의 조합으로 정해지며, 자세한 조합은 OS별 로그인 방식에서 확인하세요.

Direct Token 흐름

자격 증명을 획득하는 단계에서 Hive Axyl 인증 서버가 바로 검증할 수 있는 값을 받는 흐름입니다. 중간 교환 단계가 없으므로 획득한 값을 그대로 로그인 요청에 사용합니다.

로그인 수단별 Add-on 또는 웹 로그인 세션을 호출해 사용자 식별자(providerUserId)와 인증 결과(providerToken)를 획득합니다.
외부 인증 제공자 로그인의 LoginProviderAsync()를 호출해 인가 코드를 받습니다.
토큰 발급과 세션 활성화를 수행해 로그인을 완료합니다.

Authorization Code 흐름

자격 증명을 획득하는 단계에서 외부 인증 제공자의 인가 코드(providerCode)만 받는 흐름입니다. 인가 코드는 Hive Axyl 인증 서버가 바로 검증할 수 없으므로, 로그인 전에 교환 단계를 한 번 더 거칩니다.

로그인 수단별 Add-on 또는 웹 로그인 세션을 호출해 외부 인증 제공자의 인가 코드를 획득합니다.
외부 인증 코드 교환의 ExchangeProviderTokenAsync()를 호출해 인가 코드를 providerUserId와 providerToken으로 교환합니다.
외부 인증 제공자 로그인의 LoginProviderAsync()를 호출해 인가 코드를 받습니다.
토큰 발급과 세션 활성화를 수행해 로그인을 완료합니다.

Note

두 흐름 모두 2단계 또는 3단계에서 받는 인가 코드는 Hive Axyl 인증 서버가 발급한 값이며, Authorization Code 흐름 1단계에서 받는 외부 인증 제공자의 인가 코드와는 다른 값입니다.

같은 외부 인증 제공자라도 앱이 실행되는 OS에 따라 자격 증명을 획득하는 방법이 달라집니다. 아래 표에서 앱이 지원할 OS에 해당하는 방법을 확인하고, 그에 맞는 Add-on을 설치하세요.

외부 인증 제공자	Android	iOS	macOS	Windows
Google 계정	Google 로그인 Add-on	웹 로그인 세션	웹 로그인 세션	웹 로그인 세션
Apple	웹 로그인 세션	Apple 로그인 Add-on	Apple 로그인 Add-on	웹 로그인 세션
Google Play Games	Google Play Games 로그인 Add-on	지원하지 않음	지원하지 않음	지원하지 않음
Steam	웹 로그인 세션	웹 로그인 세션	Steam 로그인 Add-on	Steam 로그인 Add-on
X	웹 로그인 세션	웹 로그인 세션	웹 로그인 세션	웹 로그인 세션

Google 계정과 Google Play Games는 서로 다른 로그인 수단입니다

Google 계정으로 로그인은 사용자의 일반 Google 계정 신원을 사용하고, Google Play Games 모바일 앱 로그인은 Play Games의 게이머 프로필을 사용합니다. Hive Axyl 인증 서버도 두 로그인 수단을 각각 Provider.Google과 Provider.GooglePlayGames로 구분해 서로 다른 계정으로 처리합니다. 두 로그인 수단을 모두 제공하려면 각각의 Add-on을 함께 설치하고 초기화하세요.

로그인 수단별 Add-on은 해당 OS의 네이티브 인증 화면을 띄워 자격 증명을 받습니다. 웹 로그인 세션은 네이티브 Add-on이 없는 조합에서 OS가 제공하는 인증 전용 브라우저 세션으로 외부 인증 제공자의 로그인 페이지를 여는 공용 방식입니다. Android와 Windows의 Apple 로그인, Android와 iOS의 Steam 로그인은 Hive Axyl이 운영하는 중계 주소를 거쳐 인증 결과를 받습니다.

조합별 동작 흐름

각 조합이 따르는 동작 흐름은 아래와 같습니다.

Google 계정 / Android: Direct Token 흐름
Google 계정 / Android 외 OS: Authorization Code 흐름
Apple / iOS·macOS: Direct Token 흐름
Apple / iOS·macOS 외 OS: Authorization Code 흐름
Google Play Games / Android: Authorization Code 흐름
Steam / 전 OS: Direct Token 흐름
X / 전 OS: Authorization Code 흐름

커스텀 계정 로그인

커스텀 계정으로 로그인은 외부 인증 제공자를 거치지 않고 앱 서버가 발급받은 사전 인증 키로 로그인합니다. 따라서 Add-on이 필요하지 않고 위 두 흐름에도 해당하지 않으며, OS에 상관없이 같은 방식으로 동작합니다. 구현 방법은 커스텀 계정으로 로그인을 참조하세요.

앱 클라이언트가 준비하는 값

아래 값은 Hive Axyl SDK가 생성하지 않으므로 앱 클라이언트가 직접 만들어 로그인 요청에 전달합니다.

Client ID

Hive 콘솔이 프로젝트마다 발급하는 보안 키의 Client ID입니다. 확인 방법은 Hive 콘솔 보안 키를 참조하세요.

deviceKey

deviceKey는 기기 식별 값으로, 앱이 직접 만들어 로그인 요청에 넣습니다. Hive Axyl 인증 서버는 리프레시 토큰을 플레이어와 기기의 조합으로 관리하므로, 게스트, 유저네임, 외부 인증 제공자, 커스텀 계정의 로그인 요청은 계정 유형과 관계없이 모두 deviceKey를 요구합니다. 게스트 계정과 유저네임 계정을 생성하는 요청에도 같은 값을 넣습니다.

Hive Axyl 인증 서버는 이 값을 발급하거나 해석하지 않고 아래 조건만 검증합니다. 조건을 만족하지 않는 값을 보내면 로그인 요청이 실패합니다. 실패 처리는 공통 오류 처리를 참조하세요.

길이: 22자 이상 64자 이하
문자: 공백과 제어 문자를 제외한 ASCII 문자. 한글과 이모지는 허용하지 않음
형식: 검증하지 않음

앱이 지켜야 할 조건

서버는 이 값을 로그인 세션을 구분하는 기준으로 사용하지만, 값이 실제로 한 기기에 대응하는지는 확인하지 않습니다. 따라서 아래 조건은 앱이 직접 지켜야 합니다.

기기마다 서로 다른 값. UUID 같은 난수 권장
기기에 저장해 두고 계속 재사용하는 값

앱을 처음 실행할 때 한 번만 만들어 보안 저장소에 보관하고, 이후 deviceKey를 넣는 모든 요청에 같은 값을 다시 사용하세요. 보관 방법은 인증 정보 저장을 참조하세요.

잘못 만들거나 잃어버린 경우

아래는 deviceKey를 조건과 다르게 만들거나 저장해 둔 값을 잃어버렸을 때 생기는 문제입니다.

호출할 때마다 새로 만든 경우: 서버가 같은 기기를 매번 다른 기기로 인식합니다.
앱 코드에 고정값을 넣은 경우: 고정값도 검증 조건만 만족하면 서버 검증은 통과하지만, 그 앱을 쓰는 모든 사용자의 모든 기기가 같은 값을 보냅니다. 한 사용자가 기기 두 대에서 로그인하면 서버는 둘을 같은 기기로 보고, 나중에 로그인한 기기가 앞선 기기의 로그인 세션을 덮어씁니다. 사용자는 기기를 번갈아 쓸 때마다 다시 로그인해야 하고, 한 기기에서 로그아웃하면 다른 기기의 로그인도 함께 끊깁니다. 이 증상은 서버 응답에 오류가 없어서 사용자 문의가 쌓인 뒤에야 드러납니다.
저장해 둔 값을 잃어버린 경우: 기존 리프레시 토큰이 더 이상 매칭되지 않아 해당 기기의 세션이 무효가 되므로, 새 deviceKey로 다시 로그인해야 합니다. 게스트 계정은 저장해 둔 GuestPlayerId와 GuestToken, 새 deviceKey로 게스트 로그인을 다시 요청하면 같은 Player ID로 복구되며, 기기 단위의 세션 이력은 새로 시작됩니다.

생성 예시

형식은 앱이 정합니다. UUID, 16진수 문자열, base64 등 원하는 체계를 그대로 사용하세요. UUID v4를 권장합니다.

아래 예시는 UUID v4에서 하이픈을 뺀 32자 문자열을 만듭니다.

Unity

using System;

// deviceKey: 최초 실행 시 한 번만 만들고, 만든 값은 기기에 저장해 계속 재사용합니다.
static string NewDeviceKey() => Guid.NewGuid().ToString("N");

PKCE codeVerifier와 codeChallenge

로그인 응답으로 받은 인가 코드가 탈취되더라도 토큰 발급에 악용되지 않도록 보호하는 일회성 값 한 쌍입니다. 로그인 메서드를 호출하기 직전에 새로 생성해 codeChallenge는 로그인 요청에 담고, codeVerifier는 토큰 발급 단계까지 앱에 보관합니다. 생성 예시는 게스트 계정 생성의 CreatePkce()를 참조하세요.

Warning

X로 로그인할 때, 그리고 Google 계정으로 로그인하면서 인가 URL에 PKCE를 사용할 때는 외부 인증 제공자용 PKCE 값이 추가로 필요합니다. 이 값은 외부 인증 코드 교환에만 쓰이며 Hive Axyl 인증 서버용 PKCE 값과는 별개입니다. 자세한 내용은 Google 계정으로 로그인과 X로 로그인을 참조하세요.

nonce

인증 결과가 이번 로그인 요청에 대해 발급된 것임을 서버가 확인하도록 하는 일회성 난수입니다. Google 계정과 Apple 로그인의 네이티브 Add-on에서 사용하며, Add-on에 전달하는 형식이 서로 다릅니다. 각 로그인 수단의 '2단계. 로그인'에서 생성 방법을 안내합니다.

로그인 화면에 어떤 버튼을 노출할지는 앱이 임의로 정하지 않고 Hive Axyl 인증 서버가 알려 주는 목록을 따릅니다. Hive 콘솔에서 활성화한 로그인 수단과 서비스 국가 정책이 함께 반영되기 때문입니다.

로그인 화면을 구성하는 시점에 지원하는 로그인 수단 조회의 GetProviderListAsync()를 호출하고, 반환된 목록에 있는 로그인 수단만 노출하세요.

다음 단계

모듈 설치 및 초기화