Game User Access Token 유효성 검증

Game User Access Token 검증 흐름 소개

* Game Server에서 유저의 게임 접속 검증을 처리하기 위해서는 
      1) Game Client에서 SDK를 통해서 Game User Access Token 획득 
      2) Stove Server를 통해 Game User Access Token 유효성 검증 
      3) User 확인 
  과정을 거치게 됩니다.

Game User Access Token 검증 시퀀스 다이어그램

---

Access Token 토큰 종류

---

Token Type	발급	역할(Role)	유효(Valid)
Game User Access Token	Client	사용자를 인증을 합니다.	6시간(21600000ms)
API Access Token	Server	스토브 API 서버와 통신을 하기 위해, 서버 인증을 합니다.	720시간(30일)

Game User Access Token 소개

* Client에서 PC_SDK에 StoveSDK_GetToken() 함수를 통해 얻은 토큰(이하 Game User Access Token)을 지칭합니다.
* StoveSDK_GetToken() 함수를 통해 얻은 토큰은 두 가지입니다.
  * 게임 유저 엑세스 토큰(Game User Access Token) : 보안상의 이유로 권한 증명 역할을 하는 액세스 토큰으로 비교적 짧은 유효 기간(6시간)을 갖습니다.
    * Game User Access Token 유효 기간은 6시간(21600000ms)이며, 만료 시간 이후에는 재발급이 필요합니다.

API Access Token 소개

* 발급된 `API Access Token`은 요청(request)에 사용됩니다.
* 발급된 토큰은 `authorization` header에 포함해 전달해야 합니다.
* `API Access Token`의 유효 기간은 30일 입니다.
* 유효 기간은 client_id 별로 변경 가능합니다.
* 주기적으로 "API Access Token 발급 API"를 호출하여 토큰을 갱신 하거나, "expires_in"을 저장해 만료 전 발급 API를 호출하여 토큰을 갱신 받을 것을 권장합니다.
* API Access Token 발급 API 호출 시, 기존에 발급 토큰의 유효 기간이 남은 경우 기존 토큰을 전달하고, 30% 미만이 남았을 시, 신규 토큰을 발급해줍니다.
* 여러 대의 서버에서 같은 서버 토큰을 사용할 수 있으며, 각 서버 별로 API 호출 주기가 다를 것으로 예상하여 신규 토큰 발급 후에도 기존 토큰은 기존 유효 기간까지 사용 가능하도록 하였습니다.

주의사항

• 게임서버가 스토브 API 서버와 통신을 하기 위해서 인증(Authentication)이 필요하며 이때 API Access Token이 필요합니다.
• API Access Token 유효 기간은 30일이며, 유효 기간 이후에는 재발급을 받아야 합니다.

API Access Token 발급

사전체크사항

• API Access Token을 발급 받기 위한 Key 발급
  • API Access Token 을 받기 위해서는 "client_id", "client_secret" 값이 필요합니다.
  • "client_id", "client_secret" 값은 "Live", "Sandbox" 등 서비스 환경에 맞춰 발급이 필요하며, STOVE 기술PM에게 문의하시면 됩니다.

소개

* API 액세스 토큰 발급 및 조회 합니다.
    * 토큰 유효시간 설정 가능 (default : 30일)
* 기존 발급된 토큰의 유효시간의 70 퍼센트가 지난 경우는 신규 발급 처리합니다.
    ex) 유효시간 설정 60초 인 경우 토큰 유효시간 20초 까지는 기존 토큰 조회, 이 후 신규 토큰 발급합니다.
    * 현재 발급된 모든 토큰은 유효시간까지 사용 가능합니다.

---

기본정보

POST /auth/v5/server_token
Host:
   https://api.onstove.com (LIVE)    
   https://api.gate8.com (SB)
Content-Type: application/json

Request

Header

Name	Type	Required	Default Value	Example	Description
Content-Type	application/json

Parameters

Name	Type	Required	Default Value	Example	Description
client_id	String	Y	com.stove.test.server	담당 기술PM 에게 요청
client_secret	String	Y	alkjsdf8jsf9n3onf78s9dhfjlk398f9hlksdfuihaoisdhf	담당 기술PM 에게 요청
service_id	String	Y	SGP_EVENT	파트너스에서 등록한 Game ID

Response

Body

Name	Type	Required	Default Value	Example	Description
code	int	Y		0	응답 코드
message	String	Y		success	응답 메시지
response_data	Object	N			응답 값

response_data

Name	Type	Required	Default Value	Example	Description
access_token	String	Y		sljdflksjd239ofmosdg98yfgoudfgfljsfoj3498klfbsdfgs98dfug;lkj==	API Access Token AES256로 암호화된 스트링 200byte 정도
token_type	String			bearer
expires_in	Integer	Y		2591999	초 단위의 만료 시간

Sample

Request

curl --location --request POST 'https://api.onstove.com/auth/v5/server_token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "client_id": "com.sgp.event.server",
    "client_secret": "4tqFNG5ysyBUa6rk-dS4CQ",
    "service_id": "SGP_EVENT"
}'

Response

Content-Type : application/json

{
    "code": 0,
    "message": "success",
    "response_data": {
        "access_token": "-LEn5c7a9L-PaLuOYh8qiyBZOLhTJ6U3oesa1USdf9zhYLwrM6gVEPoedM-QqkT8tskTm0u9-1QhoEdrznCHC_nWHBQ46oVnwBdV9I69bihX8Rzntm3Gv-qTVQrYJG5trLAdcgVInhPGJRYy_t944APpkXtaXWzvfd2tvMsFT08",
        "token_type": "bearer",
        "expires_in": 2591999
    }
} 

응답 실패 예제

{
    "code": 40105,
    "message": "invalid client"
}

Return Code

HTTP Status code	Code	Message	Description
200	0	success	성공
401	40105	No client found	invalid client

Game User Access Token 유효성 검증

Game User Access Token 검증 소개

* Client가 Game Server에 "Game User Access Token"을 전달하면 Game Server는 이를 다시 STOVE Platform(Auth Server)에 전달해 유효한 Token인지 확인하는 인증 과정을 거칩니다.
* 본 인증과정에서 API Access Token을 Header에 포함시켜야 하며, API Access Token이 없는 경우, API Access Token 발급 API 를 통해 발급받아야 합니다.

기본정보

POST /member/v3.0/{game_id}/token/verify
Host:
   https://api.onstove.com (LIVE)    
   https://api.gate8.com (SB)
Content-Type: application/json

Request

Header

Name	Type	Required	Default Value	Example	Description
Authorization	String	Y	-	Bearer {{api_access_token}	API Access Token
Content - Type	application/json

Body

Name	Type	Required	Default Value	Example	Description
access_token	String	Y	-	{Access Token}	사용자의 인증을 통해 발급 되는 user access token

Response

Body

Name	Type	Required	Default Value	Example	Description
code	int	Y		0	응답 코드
message	String	Y		success	응답 메시지
value	Object	N			응답 값

value

Name	Type	Required	Default Value	Example	Description
member_no	Long	Y		20005061986	STOVE 정회원 번호
guid	Long	N		200000000397	게임별로 사용하는 고유 회원 번호 게임약관 동의 시 생성 됩니다.

Sample

Request

curl -L -X POST 'https://api.onstove.com/member/v3.0/MVP_SDK_QA/token/verify' \
-H 'Authorization: Bearer Es_ulMUjO7OHmk8WfiPE0-zQAppdPEyye6rRRmrZKkw3sdN38bTYANAsco_0kOHc4EPNPGQHKzV4B080JLd1smLs7YkFwpDOwEKi0aqX_qOa7_LVTl-9jvrWfiYQ-XqiUu7HGScjAWth0_K_CXwsdnvogSf3yE3oRSUvD66obgg' \
-H 'Content-Type: application/json' \
--data-raw '{
    "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHBpcmVfdGltZSI6MTY2MzkyNDQwNzQxNywibWVtYmVyX25vIjoyMDAwNTA2MTk4NiwiYXBwbGljYXRpb25fbm8iOjEwMDAyfQ.lVXx2gL-7keAs42wFDZLS-coqkSUFIAli3Opq4Is34K7ZgnpnneHJx15ofczp3Ep0ogEggRm5WNOungptQqdZy3WbNcMg-0-6MDv2x1QG-MseSAxS1hNZ5TLeDx6emSdSkAsqcp1f6kqnqRX1Hp8oTqPB-UKMQOzx91ox5cbF5KnmaKcf6VZ7tUtaDvCSxS1Ec3xda7iQCBrtgT8wmbppdkcSV2Z7AQbpP8gVnX9-I0_ZHpXroz6nzujdK8DUCJqD7cW5R5nTwMedW5pndqzzQ"
}'

Response

Content-Type : application/json

{
    "code": 0,
    "message": "success",
    "value": {
        "member_no": 20005061986,
        "guid": 200000000397
    }
}

응답 실패 예제

{
    "code": 40000,
    "message": "bad request"
}

Return Code

HTTP Status code	Code	Message	Description
200	0	Success	성공
200	40000	bad request	잘못된 파라미터 - 토큰 전달 누락 - authorization 해더에 user_access_token을 사용한 경우
401	40101	invalid token	server access token 오류
200	41002	Invalid game id	잘못된 game_id - 토큰 내 게임id와 요청 게임id가 다른 경우