ITokenService

OAuth 2.0 기반으로 JWT 토큰을 발급하는 서비스입니다. IAuthService의 로그인 메서드가 반환한 인가 코드를 액세스 토큰과 리프레시 토큰으로 교환하거나, 리프레시 토큰으로 새 토큰을 발급받을 때 사용합니다.

인터페이스: ITokenService
네임스페이스: Hive.Axyl.Auth
패키지: com.com2usplatform.hiveaxyl.auth

토큰 유효성 검증은 서버 API입니다

앱 서버가 액세스 토큰의 유효성을 확인하는 introspection은 Hive Axyl SDK가 제공하지 않습니다. 액세스 토큰 유효성 확인을 참조하세요.

등록과 획득

Unity

using Hive.Axyl.Auth;
using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap

var config = CoreConfig.CreateBuilder("{appId}").Build();

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddToken();
});

ITokenService token = HiveCore.Resolve<ITokenService>();

메서드 요약

메서드	인증	설명
IssueTokenAsync	불필요	인가 코드, 리프레시 토큰, 클라이언트 자격 증명 중 하나로 토큰을 발급합니다.

메서드

IssueTokenAsync

토큰을 발급합니다. 요청 본문으로 어떤 타입을 넘기느냐에 따라 발급 방식이 결정됩니다.

Unity

Task<TokenIssueTokenResult> IssueTokenAsync(TokenRequest request, ApiCallContext? context = null);

App ID는 SDK가 X-App-Id 헤더로 자동 전달하므로 요청 본문에 넣지 않습니다.

파라미터

파라미터	타입	필수 여부	설명
`request`	TokenRequest	Required	발급 방식에 맞는 하위 타입 인스턴스입니다.
`context`	`ApiCallContext?`	Optional	호출 단위 설정입니다. 생략하면 기본값이 적용됩니다. 호출 컨텍스트를 참조하세요.

결과

반환 객체 TokenIssueTokenResult는 아래 케이스 중 하나로 분기합니다. Success의 Data에는 TokenResponseData가 담기며, 그 밖의 케이스에는 추가 데이터가 없습니다.

결과 케이스	와이어 코드	설명
`Success`	—	토큰 발급에 성공했습니다.
`InvalidClient`	`invalid_client`	클라이언트 자격 증명이 올바르지 않습니다.
`UnsupportedGrantType`	`unsupported_grant_type`	지원하지 않는 `GrantType`입니다.
`InvalidGrant`	`invalid_grant`	인가 코드가 유효하지 않거나 만료됐습니다.
`InvalidGrantExpired`	`invalid_grant_expired`	인가 코드가 만료됐습니다. 로그인부터 다시 진행해야 합니다.
`InvalidGrantCodeChallenge`	`invalid_grant_code_challenge`	PKCE `CodeVerifier`가 로그인 시 보낸 `CodeChallenge`와 일치하지 않습니다.
`InvalidGrantRefreshToken`	`invalid_grant_refresh_token`	리프레시 토큰이 만료, 변조, 재사용 등의 이유로 유효하지 않습니다. 이유와 관계없이 다시 로그인해야 합니다.
`AppNotFound`	`app_not_found`	앱 정보를 찾을 수 없습니다.
`TemporarilyUnavailable`	`temporarily_unavailable`	서버가 일시적으로 요청을 처리하지 못했습니다. 바로 재시도하지 말고 간격을 두고 같은 요청을 다시 보내세요.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기하며 원인은 `Failure.Problem.ExternalCode`에 담깁니다.

서버가 코드로 응답한 결과 중 다시 시도해 결과가 달라질 수 있는 것은 TemporarilyUnavailable뿐입니다. 나머지는 같은 요청을 다시 보내도 결과가 같습니다. 이름이 InvalidGrant로 시작하는 결과는 인가 코드나 리프레시 토큰을 더 이상 쓸 수 없다는 뜻이므로, 사용자가 다시 로그인하도록 안내하세요.

호출 예시

Unity

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

ITokenService token = HiveCore.Resolve<ITokenService>();

var request = new AuthorizationCodeTokenRequest
{
    ClientId          = "{clientId}",
    AuthorizationCode = authorizationCode,   // 로그인 메서드가 반환한 값
    CodeVerifier      = codeVerifier,        // 로그인 요청에 사용한 codeChallenge의 원본
};

TokenIssueTokenResult result = await token.IssueTokenAsync(request);

switch (result)
{
    case TokenIssueTokenResult.Success success:
        string accessToken = success.Data.AccessToken;
        string? refreshToken = success.Data.RefreshToken;
        break;

    case TokenIssueTokenResult.InvalidGrantExpired:
        // 인가 코드가 만료됐습니다. 로그인부터 다시 진행합니다.
        break;

    case TokenIssueTokenResult.Failure failure:
        HiveError err = failure.Problem;
        break;

    default:
        // 처리하지 않은 결과와 UnknownOutcome
        break;
}

리프레시 토큰은 1회용입니다

RefreshTokenTokenRequest로 발급하면 사용한 리프레시 토큰은 즉시 무효가 되고 새 리프레시 토큰이 함께 발급됩니다. 응답의 RefreshToken으로 저장값을 교체하지 않으면 다음 갱신이 실패합니다.

데이터 타입

TokenRequest

abstract class — 토큰 발급 요청 본문입니다. 직접 인스턴스를 만들 수 없으며, 아래 세 하위 타입 중 하나를 사용합니다. 발급 방식은 각 하위 타입이 고정해 둔 GrantType 값으로 구분됩니다.

하위 타입	`GrantType`	용도
AuthorizationCodeTokenRequest	`authorization_code`	로그인으로 받은 인가 코드를 토큰으로 교환
RefreshTokenTokenRequest	`refresh_token`	리프레시 토큰으로 토큰 재발급
ClientCredentialsTokenRequest	`client_credentials`	서버 간 통신용 토큰 발급

AuthorizationCodeTokenRequest

PKCE 기반으로 사용자 토큰을 발급합니다. 로그인 메서드가 반환한 인가 코드를 교환할 때 사용합니다.

필드	타입	필수 여부	설명
`GrantType`	`string`	Required	`authorization_code`로 고정되어 있습니다. 값을 바꾸지 마세요.
`ClientId`	`string`	Required	OAuth 클라이언트 식별자입니다.
`AuthorizationCode`	`string`	Required	로그인 메서드의 응답에서 받은 인가 코드입니다. AES-256-CBC로 암호화된 값입니다.
`CodeVerifier`	`string`	Required	로그인 요청에 보낸 `CodeChallenge`의 원본 문자열입니다. RFC 7636 §4.1의 unreserved 문자만 사용합니다.

RefreshTokenTokenRequest

리프레시 토큰으로 액세스 토큰과 리프레시 토큰을 다시 발급합니다.

필드	타입	필수 여부	설명
`GrantType`	`string`	Required	`refresh_token`으로 고정되어 있습니다. 값을 바꾸지 마세요.
`ClientId`	`string`	Required	OAuth 클라이언트 식별자입니다.
`RefreshToken`	`string`	Required	RS256 JWT 형식의 리프레시 토큰입니다. 가장 최근에 발급받은 값이어야 하며, 이전 값은 이미 무효입니다.

ClientCredentialsTokenRequest

서버 간 통신에 사용할 토큰을 발급합니다. 액세스 토큰만 발급되며 리프레시 토큰은 발급되지 않습니다.

필드	타입	필수 여부	설명
`GrantType`	`string`	Required	`client_credentials`로 고정되어 있습니다. 값을 바꾸지 마세요.
`ClientId`	`string`	Required	OAuth 클라이언트 식별자입니다.
`ClientSecret`	`string`	Required	클라이언트 시크릿입니다.

클라이언트 시크릿은 앱 클라이언트에 포함하지 마세요

이 방식은 앱 서버가 Hive Axyl Server API를 호출할 때 사용합니다. 앱 서버에서 발급받는 절차는 토큰 발급을 참조하세요.

TokenResponseData

발급 성공 시 Success.Data에 담기는 응답입니다.

필드	타입	필수 여부	설명
`AccessToken`	`string`	Required	발급된 액세스 토큰입니다.
`RefreshToken`	`string?`	Optional	발급된 리프레시 토큰입니다. `client_credentials` 방식에서는 발급되지 않습니다.
`ExpiresIn`	`long`	Required	액세스 토큰의 남은 유효 시간(초)입니다.
`Meta`	`string?`	Optional	서버가 함께 전달한 부가 정보입니다. 가공되지 않은 원본 JSON 문자열로 담깁니다.