외부 인증 코드 교환

Authorization Code 흐름에서 Add-on이 반환하는 값은 외부 인증 제공자의 인가 코드뿐입니다. 이 인가 코드는 Hive Axyl 인증 서버에서 바로 검증할 수 없습니다. 로그인 요청 전에 검증 가능한 자격 증명으로 교환하세요.

교환은 Hive Axyl 인증 서버가 외부 인증 제공자의 토큰 발급 엔드포인트와 직접 통신해 수행하며, 그 결과로 사용자 식별자(ProviderUserId)와 인증 결과(ProviderToken)를 돌려줍니다. 이 두 값을 외부 인증 제공자 로그인의 호출 파라미터로 사용하세요.

교환 단계가 필요한 로그인 수단은 Google 계정, Apple, Google Play Games, X입니다. Direct Token 흐름을 따르는 조합에는 이 단계가 없습니다.

1. 호출 파라미터값 준비

외부 인증 코드 교환 메서드의 호출 파라미터를 준비합니다.

ProviderCode

Add-on이 반환한 외부 인증 제공자의 인가 코드입니다. 로그인 수단마다 값을 얻는 위치가 다릅니다.

Google 계정: 웹 로그인 세션 콜백의 code 파라미터
Apple: 웹 로그인 세션 콜백의 code 파라미터
Google Play Games: Google Play Games 로그인 Add-on이 반환한 ServerAuthCode
X: 웹 로그인 세션 콜백의 code 파라미터

RedirectUri

인가 요청에 사용한 리다이렉트 URI를 한 글자도 바꾸지 않고 그대로 넣습니다. 값이 조금이라도 다르면 외부 인증 제공자가 교환을 거부합니다. 인가 URL의 redirect_uri에 쿼리 파라미터가 붙어 있었다면 그 파라미터까지 포함한 전체 문자열을 넣으세요.

Google 계정, X: 인가 URL의 redirect_uri에 넣은 값
Apple: 인가 URL의 redirect_uri에 넣은 Hive Axyl 중계 주소. OpenRequest.RedirectUri에 넣은 앱 콜백 주소와는 다른 값
Google Play Games: 앱 서버가 사용하는 웹 애플리케이션 유형 OAuth 클라이언트에 등록한 리디렉션 URI. Google Play Games는 인가 URL을 만들지 않으므로 이 값을 사용

CodeVerifier

외부 인증 제공자가 요구하는 PKCE 값입니다. 인가 URL을 만들기 전에 앱이 생성해 보관해 둔 codeVerifier를 그대로 넣습니다. 이 값은 Hive Axyl 인증 서버용 PKCE 값과는 별개입니다.

X: 필수
Google 계정: 인가 URL에 code_challenge를 넣은 경우에만 필요
Apple, Google Play Games: 지정하지 않음

2. 외부 인증 코드 교환

ExchangeProviderTokenAsync

ExchangeProviderTokenAsync()를 호출해 외부 인증 제공자의 인가 코드를 로그인에 사용할 자격 증명으로 교환합니다. 이 메서드만 호출하면 로그인이 완료되지 않습니다. 교환 결과로 외부 인증 제공자 로그인을 이어서 호출하세요.

호출 파라미터

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

ProviderTokenRequest

필드명	타입	필수 여부	설명
`ProviderId`	`Provider`	Required	교환할 로그인 수단. `Google`, `SigninApple`, `GooglePlayGames`, `X` 중 하나
`ProviderCode`	string	Required	외부 인증 제공자가 발급한 인가 코드
`RedirectUri`	string?	Optional	인가 요청에 사용한 리다이렉트 URI와 한 글자도 다르지 않은 값. `Google`, `GooglePlayGames`, `X`에는 필수입니다. `SigninApple`은 웹 로그인 세션으로 받은 인가 코드를 교환할 때 필수이며, 인가 URL의 `redirect_uri`에 넣은 Hive Axyl 중계 주소를 넣습니다.
`CodeVerifier`	string?	Optional	외부 인증 제공자용 PKCE `codeVerifier`. `X`에는 필수이고, `Google`은 인가 URL에 `code_challenge`를 넣은 경우에만 넣습니다. `SigninApple`과 `GooglePlayGames`에는 넣지 않습니다.

호출 예시

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

Unity

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

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

// providerCode는 Add-on에서 받은 인가 코드,
// codeVerifier는 인가 URL을 만들기 전에 앱이 보관한 PKCE 값입니다.
var result = await auth.ExchangeProviderTokenAsync(new ProviderTokenRequest {
    ProviderId   = Provider.X,
    ProviderCode = providerCode,
    RedirectUri  = redirectUri,
    CodeVerifier = codeVerifier,
});

switch (result)
{
    case AuthExchangeProviderTokenResult.Success success:
        // 교환 성공 → 이 두 값으로 외부 인증 제공자 로그인을 호출합니다.
        string providerUserId = success.Data.ProviderUserId;
        string providerToken  = success.Data.ProviderToken;
        break;

    case AuthExchangeProviderTokenResult.ProviderTokenError:
        // 인가 코드 검증 실패 → 해당 로그인 수단으로 다시 인증하도록 안내
        break;

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

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

Warning

ProviderCode와 ProviderToken은 사용자의 인증 정보입니다. 로그, 크래시 리포트, 분석 이벤트에 남기지 마세요.

응답 데이터

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

필드명	타입	필수 여부	설명
`Data.ProviderUserId`	string	Required	외부 인증 제공자가 발급한 사용자 식별자. 로그인 요청의 `ProviderUserId`로 사용합니다.
`Data.ProviderToken`	string	Required	교환으로 받은 인증 결과. 로그인 요청의 `ProviderToken`으로 사용합니다. Google 계정과 Apple은 `id_token`, Google Play Games와 X는 액세스 토큰이 담깁니다.
`Data.ProviderId`	`Provider`	Required	교환에 사용한 로그인 수단

응답 예시

Unity

// Success 분기에서 success.Data 예시
// success.Data.ProviderUserId = "20394809238"   // 로그인 요청의 ProviderUserId
// success.Data.ProviderToken  = "..."           // 로그인 요청의 ProviderToken
// success.Data.ProviderId     = Provider.X

응답 상태

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

응답 케이스	설명	앱 클라이언트 대응
`Success`	교환 성공. `Data.ProviderUserId`와 `Data.ProviderToken`으로 로그인을 진행합니다.	외부 인증 제공자 로그인 호출
`ProviderNotSupported`	지원하지 않는 로그인 수단인 경우	요청한 `ProviderId` 값 확인
`ProviderTokenExchangeNotSupported`	교환 단계를 지원하지 않는 로그인 수단인 경우	해당 로그인 수단의 동작 흐름 확인
`ProviderTokenError`	인가 코드 검증에 실패한 경우	해당 로그인 수단으로 다시 인증하도록 안내
`ProviderRequestFailed`	Hive Axyl 인증 서버가 외부 인증 제공자와 통신하지 못한 경우	잠시 후 재시도
`ProviderConfigNotFound`	콘솔에 이 로그인 수단의 설정이 없는 경우	콘솔의 로그인 설정 확인
`ProviderClientInfoNotExists`	콘솔에 이 로그인 수단의 클라이언트 정보가 없는 경우	콘솔의 로그인 설정 확인
`AppNotFound`	앱 정보를 찾을 수 없는 경우	콘솔의 앱 등록 상태 확인
`TerminateService`	서비스가 종료된 앱인 경우	서비스 운영 상태 확인
`UnknownOutcome`	이 SDK 버전이 알지 못하는 신규 결과	로깅 후 보수적으로 처리
`Failure`	공통 Failure입니다. 필수 파라미터 누락·형식 오류(`invalid_parameter`), 필수 필드 누락(`missing_field`), `X-App-Id` 헤더 누락(`missing_app_id`)도 여기로 분기하며 원인은 `Failure.Problem.ExternalCode`에 담깁니다. 공통 오류 처리를 참조하세요.	공통 오류 처리 기준에 따라 처리

다음 단계

외부 인증 제공자 로그인