이 문서는 OAuth2.0 프로젝트 인증서버의 API 명세서임.

제공하는 API는 아래와 같음.

• AgreementAPI /oauth2/api/agreement - 정보 제공 동의 API
• LoginAPI /oauth2/api/login - 로그인 API
• LogoutAPI /oauth2/api/logout - 로그아웃 API
• RevokeAPI /oauth2/api/revoke - 연동 해제 API
• UserInfoAPI/oauth2/api/userinfo - 사용자 정보 API

로그인 API

/oauth2/api/login

API_KEY, SECRET_KEY, CALLBACK_URL을 통해 플랫폼 로그인 URL을 반환한다.

플랫폼 로그인 결과에 따라 정상일 경우 code를, 비정상일 경우 error를 URL 파라미터로 담아 CALLBACK_URL로 리다이렉션한다.

GET https://api.itcode.dev/oauth2/api/login/{:platform}

{
	"flag": true,
	"title": "success",
	"message": "naver authrorization url response success",
	"body": "https://nid.naver.com/oauth2.0/authorize?response_type=code&client_id=czCaqAOB1aAjNRk6N_Oq&redirect_uri=https%3A%2F%2Fproject.itcode.dev%2Foauth2%2Fcallback%3Fplatform%3Dnaver&state=b73ed0eb-abcc-4f95-b1d9-d52623e90946"
}

위 응답은 https://api.itcode.dev/oauth2/api/login/naver의 예시다.

정보 제공 동의를 재선택할 수 있는 URL을 생성하여 반환하는 API.

재동의가 이루어진 후 다시 한 번 로그인 과정을 거쳐 갱신된 내용이 반영된 인증 정보를 다시 생성한다.

지원하는 플랫폼은 아래 두 플랫폼이다.

• NAVER - 필수, 추가 정보에 관계없이 임의로 허가/거부가 가능함
• KAKAO - 추가에 해당하는 정보만 허가/거부가 가능하며, 이미 허가한 정보는 거부 불가

Google의 경우, 요청하는 정보가 프로필 정보를 벗어나지 않으므로 별도의 동의 과정이 없어서 의미가 없다.

GitHub의 경우, OAuth 앱은 프로필 정보만을 가져오므로 별도의 동의항목이 없다.

PUT https://api.itcode.dev/oauth2/api/login/put
Cookie: access={:access};

{
	"flag": true,
	"title": "success",
	"message": "naver reauthrorization url response success",
	"body": "https://nid.naver.com/oauth2.0/authorize?auth_type=reprompt&state=08199e0e-ef61-444a-8d4f-f3c048b771f0&response_type=code&client_id=czCaqAOB1aAjNRk6N_Oq&redirect_uri=https%3A%2F%2Fproject.itcode.dev%2Foauth2%2Fcallback%3Fplatform%3Dnaver"
}

위 응답은 https://api.itcode.dev/oauth2/api/login/put의 예시다.

플랫폼 로그인 결과로 발급받은 code를 Access Token으로 교환하여 서비스 인증 토큰을 생성하는 API.

생성한 인증 토큰을 쿠키에 저장하여 로그인 처리를 수행한다.

Access Token과 Refresh Token을 JWT로 변환하여 제공하며, 인증이 필요한 각종 요청에 해당 쿠키를 사용한다.

POST https://api.itcode.dev/oauth2/api/login/{:platform}

{
    "code": {:code},
    "state": {:state}
}

{
	"flag": true,
	"title": "success",
	"message": "authorized success",
	"body": null
}

# Header
Set-Cookie: access={access JWT}
Set-Cookie: refresh={refresh JWT}

Set-Cookie 헤더를 통해 인증 쿠키를 생성한다.

access, refresh 쿠키를 검증하여 유효할 경우 자동로그인을 진행하는 API.

쿠키의 보관 여부에 따라 매커니즘이 달라진다.

access 쿠키를 보유하고 있을 경우, 이미 인증 정보를 보유하고있는 셈이므로 별다른 동작을 수행하지 않으며 즉시 홈으로 리다이렉션 시킨다. 이 때 refresh 토큰의 유무는 신경쓰지 않는다.

refresh 쿠키만 보유하고 있을 경우, Access Token을 갱신하여 로그인 절차를 수행한다. 이 때 Set-Cookie 헤더를 통해 새로운 인증 정보를 생성한다.

POST https://api.itcode.dev/oauth2/api/login/auto
Cookie: access={:access}; refresh={:refresh};

{
	"flag": true,
	"title": "success",
	"message": "auto authorized success",
	"body": null
}

# Header
Set-Cookie: access={access JWT}
Set-Cookie: refresh={refresh JWT}

refresh 쿠키만을 보유하고 있어서 Access Token을 갱신한 경우에만 Set-Cookie가 포함된다.

로그아웃 API

/oauth2/api/logout

로그아웃을 수행하는 API.

access, refresh 쿠키를 삭제한다.

POST https://api.itcode.dev/oauth2/api/logout

{
	"flag": true,
	"title": "success",
	"message": "logout success",
	"body": null
}

# Header
Set-Cookie: access={access JWT}
Set-Cookie: refresh={refresh JWT}

Max-Age 0인 쿠키로 만들어 Set-Cookie로 덮어씌워 삭제한다.

연동 해제 API

/oauth2/api/revoke

플랫폼 연동을 해제하여 관련 정보와 정보 제공 동의 내역을 전부 삭제하는 API.

추후 다시 서비스에 로그인을 수행하면, 이전 정보들이 모두 파기됐기 때문에 약관 및 정보 제공 동의를 다시 수행해야한다.

플랫폼 연동 해제 후 로그아웃을 진행하며, 표면적인 동작은 로그아웃 동작과 완전히 동일하다.

DELETE https://api.itcode.dev/oauth2/api/revoke
Cookie: access={:access};

{
	"flag": true,
	"title": "success",
	"message": "logout success",
	"body": null
}

# Header
Set-Cookie: access={access JWT}
Set-Cookie: refresh={refresh JWT}

사용자 정보 API

/oauth2/api/userinfo

Access Token을 통해 사용자 정보를 전달받는 API.

이 때 전달받는 정보는 첫 로그인 시 제공 동의한 정보만을 가져온다.

플랫폼마다 전달해주는 데이터의 스키마와 형식이 다르기 때문에, 인증 서버에서 이를 적절히 가공하여 일괄된 형태의 응답으로 반환한다.

GET https://api.itcode.dev/oauth2/api/userinfo
Cookie: access={:access};

{
	"flag": true,
	"title": "success",
	"message": "user info response success",
	"body": {
		"email": "[email protected]",
		"name": "name",
		"profile": "https://phinf.pstatic.net/contact/PROFILE.png",
		"platform": "naver"
	}
}

위 응답은 네이버 사용자 정보 응답의 예시다.