Published 2022. 7. 26. 22:57

[Python, API] Cafe24를 통해 알아보는 OAuth 2.0 기반의 API 호출 방법 (Part 1)

카테고리 없음

2022.07.26

[Python, API] Cafe24를 통해 알아보는 OAuth 2.0 기반의 API 호출 방법 (Part 1) (현재 글)

[Python, API] Cafe24를 통해 알아보는 OAuth 2.0 기반의 API 호출 방법 (Part 2)

Cafe24는 국내에서 가장 많은 사람들이 이용하는 전자상거래 플랫폼입니다.

그래서 API 호출 방법에 대한 안내가 굉장히 자세하게 나와있는데요.

오늘은 Cafe24에서 직접 데이터를 가져와보며 OAuth 2.0 기반의 API 호출 방법에 대해 알아보도록 하겠습니다.

Cafe24 개발자센터 (API)

https://developers.cafe24.com/

카페24 개발자센터

카페24 오픈 API를 활용해 쇼핑몰 운영자를 대상으로 앱 비즈니스 기회를 창출할 수 있습니다.

developers.cafe24.com

OAuth 2.0 (Open Authorization 2.0, OAuth2)

OAuth 2.0은 인증을 위한 개방형 표준 프로토콜로, 웹 서비스나 응용 프로그램에 접근할 수 있는 권한을 다른 사용자에게 위임할 수 있도록 설계된 표준 프레임워크입니다.

OAuth 2.0은 다양한 클라이언트 환경에 적합하도록 4가지 종류로 구분하여 권한 부여 방식에 따른 프로토콜을 제공하고 있습니다.

(Authorization Code Grant, Implicit Grant, Resource Owner Password Credentials Grant, Client Credentials Grant)

Cafe24는 이 중 Authorization Code Grant를 이용하고 있으며, 이는 권한 부여 승인을 위해 자체 생성한 인증 코드를 전달하는 방식입니다.

많은 간편 로그인 기능에서도 사용되는 방식으로, 이를 통해 최대한 간단히 설명해보겠습니다.

어떤 기업에서 사용자에게 로그인이 필요한 서비스를 제공하려고 할 때, 원래대로라면 회원가입 서비스를 만들어 사용자로부터 개인정보를 받아서 관리해야 합니다.

그러나 서드파티 애플리케이션에서 제공하는 간편 로그인 기능을 이용한다면, 사용자는 기업에게 직접 개인정보를 제공할 필요 없이 간편 로그인 기능을 통해 서비스를 이용할 수 있습니다.

대표적인 서드파티 애플리케이션으로는 구글, 페이스북, 네이버, 카카오 등이 있으며, 우리가 어떤 쇼핑몰에서 네이버 간편 로그인으로 로그인해 서비스를 이용할 때도 이 기능을 사용하여 인증한 것이라고 볼 수 있습니다.

요약하자면, 우리의 개인정보에 대한 관리 책임을 서드파티 애플리케이션에게 위임하여 서비스를 이용하는 것입니다.

OAuth 2.0에 대한 추가적인 내용은 아래 링크를 참조하여 확인하실 수 있습니다.

OAuth 2.0

https://oauth.net/2/

OAuth 2.0 — OAuth

OAuth 2.0 OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices. This

oauth.net

OAuth 2.0 기반의 인증 프로세스

출처:JongHwan Kim 유튜브 (https://www.youtube.com/channel/UCs-qwWszxIIHeSD5GITqaFg)

Cafe24에서 사용하는 OAuth 2.0 기반의 인증 프로세스를 단계별로 살펴보면 다음과 같습니다.

앱이 인증 서버에 인증 코드를 요청합니다.
인증 서버는 쇼핑몰 운영자에게 해당 앱의 리소스 접근에 대해 동의하는지를 물어봅니다.
운영자가 동의하게 되면 인증 서버는 요청을 했던 앱에게 인증 코드를 발급해줍니다.
앱은 인증 서버가 발급해준 1분간 유효한 인증 코드를 가지고 API 호출에 필요한 액세스 토큰의 발급을 요청합니다.
인증 서버는 인증 코드가 유효한지를 확인한 후 액세스 토큰을 발급해줍니다.
앱은 발급받은 액세스 토큰을 통해 리소스 서버에 API 호출을 합니다.
리소스 서버에서는 API 호출이 적절한지를 판단하여 API 호출에 대한 데이터를 반환해줍니다.

처음 접하게 되면 아마 인증 코드랑 액세스 토큰의 개념이 헷갈릴 수 있습니다. (제가 그랬거든요..ㅎㅎ)

위의 인증 프로세스에서의 역할과 용어를 표로 정리하면 다음과 같습니다.

역할 정의

역할	대응개념	설명
리소스 소유자 (Resource Owner)	쇼핑몰 운영자	리소스 서버에 계정(쇼핑몰 ID)을 가지고 있음. 클라이언트에게 접근 권한을 위임함.
클라이언트 (Client)	앱	리소스 소유자의 권한을 위임받아 리소스 서버의 데이터를 사용하고자 하는 응용 프로그램
리소스 서버 (Resource Server)	Cafe24	데이터를 제공하는 서버
인증 서버 (Authorization Server)	Cafe24	권한 인증을 진행하는 서버

용어 정의

용어	설명
인증 코드 (Authorization Code)	액세스 토큰을 발급하기 위해 필요한 코드
액세스 토큰 (Access Token)	리소스 서버에 접근할 수 있는 권한을 가지고 있는 토큰
클라이언트 ID & 시크릿 키 (Client ID & Secret Key)	클라이언트의 계정 정보. 개발자 admin에서 신규 앱 생성 시 획득할 수 있음.
리다이렉트 URI (Redirect URI)	인증 코드를 리다이렉트 받을 URI

이해가 조금 가시나요..?

간단하게 정리하자면 다음과 같습니다.

인증 코드를 발급받음 => 인증 코드를 이용해 액세스 토큰&리프레시 토큰을 발급받음 => 액세스 토큰을 이용해 데이터에 접근 가능
리프레시 토큰을 발급받아 액세스 토큰을 재발급 받을 수 있음 (액세스 토큰은 유효기간이 짧기 때문에 주기적으로 재발급을 받아야 함)

앱 생성하기

가장 먼저 해야 될 일은 클라이언트에게 접근 권한을 위임하기 위해 앱을 생성하는 일입니다.

앱을 생성하기 위해 일단 'Cafe24 개발자' 페이지에서 '앱 관리'에 들어갑니다.

Cafe24 개발자센터 (API)

https://developers.cafe24.com/

카페24 개발자센터

카페24 오픈 API를 활용해 쇼핑몰 운영자를 대상으로 앱 비즈니스 기회를 창출할 수 있습니다.

developers.cafe24.com

앱 등록 유형을 'Web'으로 선택한 후 '저장'을 누르면 아래와 같은 화면이 뜨는 것을 확인할 수 있습니다.

기본 정보
- App URL: 앱의 시작점이 되는 부분으로, 쇼핑몰 운영자가 앱스토어에서 앱을 설치하게 되었을 때 가장 먼저 호출되는 경로입니다. 이 URL을 통해 인증 코드를 요청할 수 있습니다.
- Redirect URI(s): 인증 과정에서 쇼핑몰 운영자가 정보 제공 동의를 했을 때 인증 코드를 반환받는 경로입니다. 이 인증 코드를 사용하여 액세스 토큰을 발급받을 수 있습니다.
API 정보
- 권한 선택: 앱이 어떠한 권한을 가지고 쇼핑몰에 접근할 수 있는지를 설정할 수 있습니다. '권한 적용범위 안내'를 참고하여 추후 scope에 적용할 부분을 입력할 수 있습니다.
인증 정보
- 클라이언트 ID & 시크릿 키: Cafe24에서는 하나의 앱을 클라이언트라 부르고, 각 앱은 각각 고유의 클라이언트 ID를 가집니다. 그리고 클라이언트 ID에는 그에 상응하는 시크릿 키가 있습니다.

각각의 값을 채워준 후 '테스트 실행'을 클릭해주면 앱이 생성됩니다.

인증 코드 Request

이제 앱을 생성하며 얻은 정보들을 이용하여 인증 코드를 발급받아 보도록 하겠습니다.

인증 코드 Request 형식은 다음과 같습니다.

https://{mall_id}.cafe24api.com/api/v2/oauth/authorize?response_type=code
&client_id={client_id}
&state={encode_csrf_token}
&redirect_uri={encode_redirect_uri}
&scope={scope}

파라미터	필수여부	설명
response_type	필수	인증 형식으로, ‘code’라고 입력하면 됨.
client_id	필수	앱 생성시 발급받은 클라이언트 ID를 입력하면 됨.
state	권장	CSRF(사이트 간 요청 위조) 공격을 방지하기 위한 값. Client-side에서 임의의 문자열을 생성하여 입력함. 사용자 정의의 데이터를 입력하여 그대로 응답받는 목적으로 사용할 수도 있음.
redirect_uri	필수	인증 코드를 전달받는 주소로, 앱 생성시 등록하였던 Redirect URI를 입력하면 됨.
scope	필수	앱 생성시 등록하였던 권한 한에서 입력하면 됨.

임의 값을 넣어 Request를 작성해보면 다음과 같습니다.

https://samplemall.cafe24api.com/api/v2/oauth/authorize?response_type=code
&client_id=sample7eBNEqSfkd7I8hoA
&state=state_t
&redirect_uri=https://sampleapp.com/oauth/redirect
&scope=mall.read_application,mall.write_application

변환한 URL을 주소창에 입력하면 로그인을 하라는 창이 뜹니다.

로그인을 하면 리소스에 대한 접근 권한을 허용할 수 있는 창이 뜨고,

접근을 허용하면 redirect_uri로 이에 대한 Response를 받을 수 있습니다.

인증 코드 Response

인증 코드 Request를 보내면 그에 대한 Response 형식은 다음과 같습니다.

HTTP/1.1 302 Found
Location: {redirect_uri}?code={authorization_code}&state={encode_csrf_token}

파라미터	설명
code	Request에 성공하면 반환받는 인증 코드
state	Request 시 전송한 state 값과 동일한 값이 반환됨. 이 값과 최초 생성되었던 Client-side의 값을 비교하여 CSRF 공격에 대한 무결성을 검증할 수 있음. 사용자 정의의 데이터를 입력하여 그대로 응답받는 목적으로 사용할 수도 있음.

제가 직접 받은 Response입니다.

위의 Response에서 제가 받은 인증 코드는 '4RbDzOO8FJMtNM74wXjwJD'가 됩니다.

이 인증 코드를 이용하여 API를 호출할 수 있는 액세스 토큰을 발급받을 수 있습니다.

에러 코드 Response

만약 인증 코드 Response를 받는 과정에서 실패하게 되면 에러 코드를 반환하게 됩니다.

에러 코드 Response 형식은 다음과 같습니다.

https://{mall_id}.cafe24api.com/api/v2/oauth/authorize?response_type=code&client_id={client_id}&state={encode_csrf_token}
&redirect_uri={encode_redirect_uri}&scope={scope}

파라미터	설명
error	OAuth 2.0 Framework Standard 4.1에 정의된 에러 코드값
trace_id	오류를 추적하기 위한 고유 번호

에러코드 별 대응 방법은 다음과 같습니다.

에러 코드	설명	대응 방법
invalid_request (1)	client_id / redirect_uri / scope 값을 누락한 경우	누락된 값을 확인하여 입력
invalid_request (2)	client_id / redirect_uri / scope 값이 잘못된 경우	요청한 값이 등록한 앱 기본정보의 각 항목과 일치하는지 확인
access_denied	권한이 없는 관리자 계정으로 요청한 경우	앱 사용자가 대표 운영자 계정으로 로그인할 수 있도록 함.
unsupported_response_type	response_type 값이 누락되거나 "code"가 아닐 경우	"response_type=code"로 되어있는지 확인
invalid_scope	scope가 일치하지 않거나, 잘못된 형식인 경우	요청한 scope가 앱에 등록한 scope 내에 있는지 확인

쓰다보니 엄청 길어졌네요!

이후의 과정은 Part2에 나눠서 쓰도록 하겠습니다!