회원 인증

1.개요

Windows 앱을 EXE 유형으로 서비스 하는 경우 웹 결제 규격을 연동해야 합니다. 웹 결제 규격 연동 시 회원 인증(로그인)이 필요하므로 이 규격서를 제공합니다.

  • 결제 서버 API는 회원 인증(로그인) 시 제공되는 OAuth Token(이하 User Access Token)을 이용합니다.

  • 결제 시마다 회원 인증(로그인)을 수행하지 않도록 OAuth 인증을 지원합니다.

2.주의사항

Embedded Browser(웹뷰)에서 구글 SDK를 적용하지 않고, 구글 Oauth 로그인을 시도하는 경우 403 에러가 발생합니다. 아래의 방법을 통해 403 에러를 방지할 수 있습니다.

  • Embedded Browser가 아닌 새 창으로 로그인을 시도합니다.

  • UserAgent 정보를 수정하여 Embedded Browser가 아닌 웹으로 인식하도록 처리합니다.

3.회원 인증 플로우

3.1 Conceptual View

3.2 논리 API ↔ 물리 API 규격 매핑

Conceptual View'에 표기된 논리 API들이 매핑되는 물리 API 규격은 다음과 같습니다.

No
Flow
논리 API
물리 API (연동 규격)

1

회원인증

  1. Loging UI 요청

4.2 ONE store 로그인 인증 요청

2

회원인증

  1. ONEstore UserAccessToken 발급

4.3 ONE store User Access Token 발급 요청

4. ONE store 회원인증

4.1 ONE store 로그인 API 개요

ONE store 로그인 API는 아래와 같이 구성되어 있습니다.

  • ONE store 로그인 인증 요청 API

  • 접근 토큰(User Access Token) 발급/삭제 요청 API

ONE store 로그인 인증 요청 API는 개발자 서비스 Web에 ONE store 로그인 화면을 띄우는 API입니다. 사용자가 ONE store 회원 인증에 성공하면 API로부터 받은 임시코드(code) 값을 이용해서 접근 토큰(User Access Token) 발급 요청 API를 호출합니다.

접근 토큰 발급 요청 API를 통해 받은 접근 토큰은 여러가지 Server API들을 호출하는데 사용합니다.

접근 토큰(User Access Token)은 갱신 토큰(Refresh Token)에 비하여 만료기한이 짧으며, 접근 토큰 만료 시 갱신 토큰을 이용하여 새로운 접근 토큰을 발급 받아야 합니다.

토큰 발급 상세 규칙은 '4.1.4 User Access Token 및 Refresh Token 발급 기준'에 명시 되어 있습니다.

4.1.1 표준 응답코드

Code

message_ko

message_en

HTTP Status Code

대상API

비고

Success

정상처리 되었습니다.

The request has been successfully completed.

200 - Success

4.4 ONE store User Access Token 삭제 요청

RequiredValueNotExist

필수값이 존재하지 않습니다. [ field1, field2, ... ]

Request parameters are required. [ field1, field2, ... ]

400 - Bad Request

공통

NoSuchData

조회된 결과값이 존재하지 않습니다.

The requested data could not be found.

404 - Not Found

단건 조회 API

ResourceNotFound

요청한 자원이 존재하지 않습니다.

The requested resource could not be found.

404 - Not Found

공통

요청한 URL 자원이 없는 경우

InternalError

정의되지 않은 오류가 발생하였습니다.

An undefined error has occurred.

500 - Internal Server Error

공통

InvalidRequest

입력값이 유효하지 않습니다. [ field1, field2, ... ]

Request parameters are invalid. [ field1, field2, ... ]

400 - Bad Request

공통

UserAccessTokenExpired

Access 토큰이 만료되었습니다.

User Access Token has expired.

401 - Unauthorized

공통

code 및 UserAccessToken 만료 처리

  • 만료 기한 초과 시

  • 회원 상태 변동 시 (휴면/탈퇴/통합)

  • TStore ID 회원 패스워드 변경 시

  • 소셜 인증 실패 시 (소셜 연동 정보 변동 - 연결 취소 등)

InvalidRefreshToken

잘못된 Refresh Token 입니다.

Invalid refresh token

400 - Bad Request

공통

grant_type : refresh_token 경우

ExpiredRefreshToken

만료된 Refresh Token 입니다.

Invalid refresh token (expired)

401 - Unauthorized

공통

grant_type : refresh_token 경우

UnauthorizedAccess

해당 API에 접근권한이 없습니다.

Not authorized to this API.

403 - Fobidden

공통

InvalidUserAccessToken

Access 토큰이 유효하지 않습니다.

User Access Token is invalid.

401 - Unauthorized

공통

InvalidAuthorizationParam

Authorization Param의 값이 유효하지 않습니다.

Authorization param is invalid.

400 - Bad Request

공통

  • code

  • 올바르지 않은 code

MethodNotAllowed

지원하지 않는 HTTP Method 입니다.

HTTP method not supported.

405 - Method Not Allowed

공통

InvalidContentType

잘못된 Content Type 입니다.

The request content-type is invalid.

415 - Unsupported Media Type

공통

UserNotExist

회원 정보가 존재하지 않습니다.

User does not exist.

404 - Not Found

공통

InvalidUser

회원 정보가 유효하지 않습니다.

User information is not valid.

409 - Conflict

공통

UnsupportedResponseType

Unsupported response types: [field1]

400 - Bad Request

공통

WrongApproach

The wrong approach.

403 - Forbidden

공통

4.1.2 표준 오류응답

오류응답인 경우 표준 응답코드에 정의된 코드 및 메시지를 전달합니다.

Example

HTTP/1.1 400 Bad Request Content-type: application/json;charset=UTF-8 { "error" : { "code" : "NoSuchData", "message" : "The requested data could not be found." } }

4.1.3 client_id와 client_secret

client_id와 client_secret 값은 "개발자센터 > 상품현황 > 앱 상세 > 공통정보 > 라이선스 관리" 메뉴를 통해 확인할 수 있습니다.

4.1.4 User Access Token 및 Refresh Token 발급 기준

ONE store User Access Token은 Client ID(=게임/앱)와 원스토어 사용자의 회원 ID 기준으로 발급됩니다.

  • grant_type : authorization_code

    • 사용자의 명시적 로그인이기 때문에 기존 token이 유효하지 않아도 신규 발급

    • user_access_token, refresh_token

      • 기존 유효한 (user_access, refresh) token이 있는 경우 기존 value 응답

      • 기존 유효한 (user_access, refresh) token이 없는 경우 신규 발급

  • grant_type : refresh_token

    • refresh_token

      • 유효한 refresh_token이 없는 경우 오류 응답

      • 유효한 refresh_token이 있는 경우 만료기한 연장(초기화: 기본 35일)

    • user_access_token

      • 기존 유효한 user_access_token이 있는 경우 기존 value 응답

      • 기존 유효한 user_access_token이 없는 경우 신규 발급

  • 토큰 삭제 시 refresh_token, user_access_token 함께 삭제 됨

4.2 ONE store 로그인 인증 요청

[ API Spec. ]

Protocol

HTTPS

Content-Type

application/x-www-form-urlencoded

Method

GET/POST

응답 포맷

URL Redirect

Path

상용

- https://accounts.onestore.net/oauth2.0/authorize

개발

- https://qa-accounts.onestore.co.net/oauth2.0/authorize

Description

ONE store OAuth 이용 시 로그인 페이지

오류 코드 참고 : 표준 응답코드

[ Request ]

Parameter

Parameter Name

Type

Description

Required

Remarks

response_type

String

인증 과정에 대한 내부 구분값으로 'code'로 전송해야 함

Y

  • code

client_id

String

OAuth Client Id

Y

Android OS Application의 Package Name을 사용

redirect_uri

String

등록 시 입력한 Callback URL 값으로 URL 인코딩을 적용한 값

Y

URL 인코딩

state

String

사이트 간 요청 위조(cross-site request forgery) 공격을 방지하기 위해 개발자 측에서 생성한 상태 토큰값으로 URL 인코딩을 적용한 값을 사용

Y

  • URL 인코딩

  • 개발자 측에서 생성/전달. ONE store 측은 넘겨받은 값을 그대로 리턴

scope

String

접근 허용 범위를 처리하기 위한 내부 구분값

Y

  • user_payment

Header

Parameter Name

Type

Description

Required

x-market-code

String

마켓 구분 코드

  • MKT_ONE: 원스토어(대한민국)

  • MKT_GLB: 원스토어(대한민국 외)

Y

Example

https://accounts.onestore.net/oauth2.0/authorize?response_type=code&client_id=client_id_example&redirect_uri=http%3A%2F%2Fservice.redirect.url%2Fsubpath&state=hLiDdL2uhPtsftcU&scope=user_payment

[ Response ]

  • ONE store 로그인 인증 요청 API를 호출 했을 때 사용자가 로그인되지 않은 상태이면 로그인 화면으로 이동합니다.

  • 사용자 로그인 완료 후 약관 및 정보 제공 동의 등이 필요한 경우 해당 화면으로 이동합니다.

  • 로그인과 동의 과정이 완료되면 콜백 URL에 code값과 state 값이 URL 문자열로 전송됩니다.

  • code 값은 접근 토큰(User Access Token) 발급 요청에 사용됩니다.

Element Name

Type

Description

Remarks

code

String

- 로그인 인증에 성공하면 반환받는 인증 코드

- 접근 토큰(User Access Token) 발급에 사용

  • length : 50

  • 영문 대소문자 및 숫자로 구성

  • 만료기한 5분

state

String

사이트 간 요청 위조 공격을 방지하기 위해 개발자 측에서 생성한 상태 토큰

  • URL 인코딩

  • 요청 시 넘겨준 값을 그대로 리턴

error_code

String

로그인 인증에 실패하면 반환받는 에러 코드

오류 코드 참고 : 표준 응답코드

error_message

String

로그인 인증에 실패하면 반환받는 에러 메시지

Example

인증 절차 완료 후

  • API 요청 성공시 : http://콜백URL?code={code값}&state={state값}

  • API 요청 실패시 : http://콜백URL?state={state값}&error_code={에러코드값}&error_message={에러메시지}

오류 유형 정리

코드

응답 방식

발생 조건

전문 (메세지 및 화면내용)

기타 설명

RequiredValueNotExist

PAGE

필수값 누락 - response_type - client_id - state - scope - redirect_uri

Request parameters are required. [ {누락 파라미터} ]

UnsupportedResponseType

REDIRECTION

파라미터 유효성 - response_type ≠ code

{redirect_uri}?error_code=UnsupportedResponseType&error_message=Unsupported response types: [{response_type}]

InvalidRequest

PAGE

파라미터 유효성 - 미발급 client_id

Request parameters are invalid. [ client_id ]

InvalidRedirect

PAGE

파라미터 유효성 - 미등록 redirect_uri

Invalid redirect

InvalidScope

REDIRECTION

파라미터 유효성 - scope ≠ user_payment

{redirect_uri}?error_code=InvalidScope&error_message=Invalid scope

접속 후 인증 요청 시 발생

WrongApproach

PAGE

로그인 URI 직접 접근

The wrong approach.

/oauth2.0/login 직접 접근

4.3 ONE store User Access Token 발급 요청

[ API Spec. ]

Protocol

HTTPS

Content-Type

application/x-www-form-urlencoded

Method

POST

응답 포맷

application/json

Path

상용

- https://accounts.onestore.net/oauth2.0/token

개발

- https://qa-accounts.onestore.net/oauth2.0/token

Description

  • ONE store User Access Token 발급

[ Request ]

Parameter

Parameter Name

Type

Description

Required

Remarks

grant_type

String

접근 토큰 발급 방식에 대한 구분값

Y

  • 'authorization_code'

  • 'refresh_token'

  • 그 외 발급 방식 현재 미정

client_id

String

OAuth Client Id

Y

Android OS Application의 Package Name을 사용

client_secret

String

OAuth Client Secret

Y

ONE store 개발자센터에서 발급한 Client secret 값을 사용

code

String

로그인 인증 요청 API 호출에 성공하고 응답 받은 인증코드값 (code)

N

grant_type : authorization_code 경우 필수값

refresh_token

String

User Access Token 발급 시 함께 발급받은 refresh_token 값

N

grant_type : refresh_token 경우 필수값

state

String

사이트 간 요청 위조(cross-site request forgery) 공격을 방지하기 위해 개발자 측에서 생성한 상태 토큰값으로 URL 인코딩을 적용한 값을 사용

Y

  • URL 인코딩

  • 개발자 측에서 생성/전달, ONE store 측은 넘겨받은 값을 그대로 리턴 함

Header

Parameter Name

Type

Description

Required

x-market-code

String

마켓 구분 코드

  • MKT_ONE: 원스토어(대한민국)

  • MKT_GLB: 원스토어(대한민국 외)

Y

Example

POST /oauth2.0/token HTTP/1.1 Host: accounts.onestore.net Content-Type: application/x-www-form-urlencoded x-market-code:MKT_ONE

grant_type : authorization_code의 경우 grant_type=authorization_code& code=EIc5bFrl4RibFls1& client_id=client_id_example& client_secret=hDBmMRhz7eJRsM9Z2q1oFBSe& state=9kgsGTfH4j7IyAkg

grant_type : refresh_token의 경우 grant_type=refresh_token& refresh_token=EIc5bFrl4RibFls1& client_id=client_id_example& client_secret=hDBmMRhz7eJRsM9Z2q1oFBSe& state=9kgsGTfH4j7IyAkg

[ Response ]

Element Name

Type

Description

Remarks

user_access_token

String

ONE store 접근 토큰(User Access Token)

  • max length : 255

  • 만료기한 10분

refresh_token

String

User Access Token에 대한 Refresh 토큰

  • max length : 255

  • 기본 만료기한 35일, 사용 시 만료기한 연장(초기화)

token_type

String

Bearer

expires_in

integer

접근 토큰의 유효 기간(초 단위)

state

String

사이트 간 요청 위조 공격을 방지하기 위해 개발자 측에서 생성한 상태 토큰

  • URL 인코딩

  • 요청 시 넘겨준 값을 그대로 리턴

  • 성공 시에만 포함됨

error {

Object

error 발생 시에만 포함

오류 코드 참고 : 표준 응답코드

code

String

에러 코드

message

String

에러 메세지

}

Example

// 성공 시

{

  "user_access_token" : "f27d2c49-231d-4848-9e8c-ec9a1fef9c35",
  "refresh_token" : "1fe54c5f-60d1-4fbb-a412-929c84adab43",
  "token_type" : "Bearer",
  "expires_in" : 603389,
  "state" : "hLiDdL2uhPtsftcU"
}

// 실패 시

{ "error" : { "code" : "InvalidAuthorizationParam", "message" : "Authorization param is invalid." } }

오류 유형 정리

코드

발생 조건

전문 (json)

기타 설명

RequiredValueNotExist

필수값 누락 - grant_type - client_id - client_secret - code (선택적 필수값) - refresh_token (선택적 필수값) - state

{ "error": { "code": "RequiredValueNotExist", "message": "Request parameters are required. ({누락파라미터})" } }

- code : grant_type : authorization_code 경우 필수값 - refresh_token : grant_type : refresh_token 경우 필수값

InvalidRequest

파라미터 유효성 - grant_type ≠ (authorization_code or refresh_token)

{ "error": { "code": "InvalidRequest", "message": "Request parameters are invalid. [ grant_type ]" } }

InvalidAuthorizationParam

파라미터 유효성 - 미발급 code

{ "error": { "code": "InvalidAuthorizationParam", "message": "Authorization param is invalid." } }

InvalidRequest

파라미터 유효성 - 미발급 client_id

{ "error": { "code": "InvalidRequest", "message": "Request parameters are invalid. [ client_id or client_secret ]" } }

InvalidRequest

파라미터 유효성 - 미발급 client_secret

{ "error": { "code": "InvalidRequest", "message": "Request parameters are invalid. [ client_id or client_secret ]" } }

InvalidRefreshToken

파라미터 유효성 - 미발급 refresh_token

{ "error": { "code": "InvalidRefreshToken", "message": "Invalid refresh token" } }

grant_type : refresh_token 경우

ExpiredRefreshToken

파라미터 유효성 - 만료 refresh_token

{ "error": { "code": "ExpiredRefreshToken", "message": "Invalid refresh token (expired)" } }

grant_type : refresh_token 경우

Last updated