OAuth 로그인 구현

왁타버스 게임즈 로그인은 OAuth 2.0 PKCE 방식을 사용합니다.
OAuth 2.0에 대하여 자세히 알아보기 → (영상)

절차 개요

사전 설정
사용자 로그인 의사 표시
콜백 서버 시작
인증 페이지 열기
사용자 인증 및 콜백 처리
토큰 요청
토큰 저장 및 프로필 조회

연동 절차

1. 사전 설정

연동에 필요한 작업을 위해 왁타버스 게임즈의 개발자 포탈에서 Client ID를 확인하고 Callback URL를 수정해야합니다. (자세한 내용은 OAuth 연동 설정 을 참고해 주세요.)

개발자 포탈의 게임 연동 탭에 접속합니다. (로그인 필요)
작업할 게임을 클릭하고 "OAuth 연동 정보" 영역에서 Client ID를 우선 확인하고 수정 버튼을 클릭합니다.

게임이 나오지 않는다면 해당 그룹 관리자나 Partners 서버에 게임 그룹 가입을 요청해주세요.

Callback URL를 입력하고 저장합니다.

http://localhost:포트/callback

포트는 사용자 환경의 다른 프로그램과 충돌이 생기지 않을만한 것으로 정해주세요.

2. 사용자 로그인 의사 표시

사용자가 게임에서 왁타버스 게임즈로 로그인하겠다는 의사를 표시합니다. (예: 로그인 버튼 클릭)

3. 콜백 서버 시작

게임은 OAuth 인가 토큰을 전달 받기 위해 Callback URL와 연결되는 자체 HTTP 서버(이하 콜백 서버)를 시작해야 합니다.

웹 게임의 경우, 따로 콜백 서버를 시작하지 않고, 기존에 게임에서 이용하던 API 서버에 Callback 라우트를 추가하여 이용할 수 있습니다.

예시: 사전 설정 단계에서 Callback URL을 http://localhost:27610/callback 로 설정했다면,
localhost:27610에서 HTTP 요청을 대기하는 서버를 시작해야 합니다.

4. 인증 페이지 열기

콜백 서버가 준비되면 왁타버스 게임즈의 https://waktaverse.games/oauth/authorize 페이지를 아래 필요 인자와 함께 웹 브라우저로 엽니다.

OAuth 2.0 표준과 다르게, 모든 파라미터 이름은 camelCase로 전송되어야 합니다.
예) response_type (X) / responseType (O)

파라미터 예시: ?responseType=code&clientId=wakgames_demo&callbackUri=http://localhost:27610/callback&state=Gye8y5p8zwl8qLWw&challengeMethod=S256&challenge=26d1b0e86092fc7f50af99d0e09b385bfae4aa4020c470b49a54ee6c0802d674

파라미터	설명
responseType	인증 후, 인가 토큰을 발급하기 위해 `code` 로 고정
clientId	사전 설정 단계에서 확인한 Client ID
callbackUri	사전 설정 단계에서 설정한 Callback URL (URL Escape 처리)
state	8~16자 정도의 CSRF 방지를 위한 랜덤 코드. 따로 저장하는 것을 추천 (nanoid 등 이용하여 생성, 예: JgHy6c5q4aEEU...)
challengeMethod	`codeChallenge`의 암호화 방식으로, SHA256 해시를 뜻하는 `S256` 으로 고정.
challenge	128자의 랜덤 Code Verifier(따로 저장)에 대한 SHA256 해시 (nanoid 등 이용하여 생성, 예: 6qIIZX6KIaUe...)

5. 사용자 인증 및 콜백 처리

사용자가 왁타버스 게임즈에서 로그인 후 연동을 허용하면, 아래 테이블의 파라미터가 Callback URL로 전송됩니다. (쿼리 파라미터로 GET 요청 발생)

연동 오류가 발생하였으나 디버깅이 어려운 경우, 혹은 상세한 오류 로그 확인이 필요하신 경우,
Partners 서버로 문의해 주세요.

파라미터	설명
`code`	왁타버스 게임즈에서 발급한 1회성 인가 토큰. 이 값을 이용해 실제 Access Token 발급 진행
`state`	인증 페이지 오픈 시 전달 한 CSRF 방지 코드. 인증 페이지 오픈 전 저장한 값과 비교 검증 추천

게임의 콜백 서버는 해당 요청을 받아 처리하고 적절한 페이지로 응답해야 합니다:

error가 있거나 state가 다를 경우: 오류 페이지로 응답, 로그인 절차 실패
code(인가 토큰)가 있을 경우: 성공 페이지로 응답, 다음 단계로 진행

별도 성공 페이지를 만들기 번거로운 경우, 왁타버스 게임즈에서 제공하는 성공 페이지로 리디렉션 하셔도 됩니다.
(단, 웹 게임의 경우 필히 콜백을 받을 수 있는 라우트로 Callback URL을 설정하셔야 합니다.)

성공 페이지: https://waktaverse.games/oauth/authorize?success=1

이 시점에서 콜백 서버는 닫으셔도 됩니다.

6. 토큰 요청

왁타버스 게임즈의 /api/oauth/token API로 POST 요청을 아래 필요 인자와 함께 전송합니다.

웹 브라우저를 통해 오픈하는 것이 아니라, 게임 (혹은 웹게임 API 서버)에서 POST 요청을 보내야 합니다.
모든 파라미터는 Query Parameter로 전송해야 합니다만, 꼭 POST 요청으로 진행해야 합니다.
(GET 요청과 혼동하지 않도록 유의 바랍니다.)

OAuth 2.0 표준과 다르게, 모든 파라미터 이름은 camelCase로 전송되어야 합니다.
예) grant_type (X) / grantType (O)

API 요청 예시: ?grantType=authorization_code&clientId=wakgames_demo&code=Gye8y5p8zwl8qLWw&verifier=e42e64ba998a60415f1bb444d6bc998c95e92eeeb23a4e936a2cd79d1acb4c22550ae9dd683f48babe958fa9ccd4a5ea5feb39f75239e24b9ec62b4ab010645f&callbackUri=http://localhost:27610/callback

파라미터	설명
grantType	인증 진행 타입. 인가 토큰 (`code`) 방식을 통하여 인증하므로, `authorization_code` 로 고정
clientId	사전 설정 단계에서 확인한 Client ID
code	콜백 서버가 받은 1회성 인가토큰(`code`)
codeVerifier	인증 페이지 오픈시에 발급한 Code Verifier. (Code Challenge의 SHA256 해시 이전 값)
callbackUri	사전 설정 단계에서 설정한 Callback URL (URL Escape 처리)

7. 토큰 저장 및 프로필 조회

JWT 형태의 접근 토큰(accessToken)과 갱신 토큰(refreshToken), 사용자 고유 ID가 JSON 형태로 응답됩니다. 이 단계에서, 사용자에게 로그인이 되었음을 알리는 것이 좋습니다.

{
  "accessToken": "g0sE123...",
  "refreshToken": "j1nGb32...",
  "idToken": 1
}

게임을 종료해도 사라지지 않도록 저장해두시는 것을 권장드립니다.

자동 로그인 연동

자동 로그인

게임이 재실행될 때 사용자 경험을 개선하기 위해 자동 로그인 기능을 구현할 수 있습니다. 다음은 자동 로그인 프로세스입니다:

게임 재실행 시 이전에 저장한 토큰 확인
- 토큰이 없으면 → 로그아웃 상태로 판단 (로그인 진행)
- 토큰이 있으면 → 다음 단계로 진행
저장된 접근 토큰으로 GET /api/game-link/user/profile 호출
- 프로필 정보 수신 성공 → 로그인 상태로 판단
- 401 응답 수신 → 다음 단계로 진행
토큰 갱신 절차에 따라 갱신 토큰으로 GET /api/oauth/refresh API 호출
새 토큰 정보 처리
- 새 토큰 수신 성공 → 토큰 저장 후 로그인 상태로 판단
- 401 응답 수신 → 최종적으로 로그아웃 상태로 판단

토큰 갱신

접근 토큰은 보안상 빠른 시간 안에 만료됩니다. 만료 시 갱신 토큰을 사용하여 새로운 접근 토큰과 갱신 토큰을 발급받아 계속 사용할 수 있습니다.

프로필 조회, 도전과제 API 등을 사용하다 HTTP 401 응답을 받은 경우에 수행하는 것이 좋습니다.
토큰 갱신은 재사용 가능한 함수로 구현하는 것이 좋습니다.

토큰 갱신 절차

GET /api/oauth/refresh API 호출
- 메서드: GET
- 헤더: Authorization: Bearer {refreshToken}
응답 처리 성공 시, 7. 토큰 저장 및 프로필 조회 와 동일한 형태의 JSON 응답이 돌아옵니다.
이 값을 기존 토큰 정보 대신 저장하면 갱신이 완료되며, 호출하려던 API에 다시 호출하면 됩니다.

{
  "accessToken": "g0sE123...",
  "refreshToken": "j1nGb32...",
  "idToken": 1
}

OAuth 로그인 구현

On this page