API 인증가이드 – ESM Trading API

API 인증가이드

Description
ESM Trading API를 사용하기 위해서는 Header에 아래 내용을 참고한 인증값을 설정합니다(모든API 동일)
ESM Trading API 인증은 정상적으로 발급된 키의 사용자 인지, 허용된 서버(IP address)에서 전달된 요청인지, 요청이 전달되는 과정에서 악의적으로 요청이 오염되었는지를 체크합니다
권한은, 인증된 사용자라 해도 특정 리소스(api)에 접근이 허용된 사용자인지를 판단합니다. 따라서, API를 사용할 때는 인증 및 권한도 부여 받아야 합니다


API 인증방식

: public/private key를 이용한 JWT 인증 방식(JWT 참고)

  • 청인증 방식은 HMAC 해싱 방식으로 생성된 비밀키(Secret Key)를 사용자에게 발행하며 Secret Key로 header와 payload를 해싱한 signature를 생성해서 JWT(JSON Web Token)을 만들어 이를 Http 헤더를 통해 API 인증 서버로 전송하는 방식으로 처리 됩니다.
  • 클라이언트는 ESM+를 통해 관리자에게 사용할 key pair(Access Key/Secret Key) 발급 및 권한을 요청합니다.(현재는 ESM+ 메뉴를 오픈하지 않아 메일로 직접 판매자마스터ID와 Secret Key 요청필요 / 문의메일:et_api@ebay.co.kr) ESM+의 API 인증 담당 관리자는 요청을 검토하고 키를 발급한 후에, 사용할 api에 대한 접근 권한을 부여합니다. ESM+ API 인증 관리자를 통해 발급 받은 인증 key pair는 분실 또는 유효기간 만료 등의 이유로 재발급이 가능하며 재 발급 전에는 한번 발급 받은 key pair를 계속 사용하면 됩니다.
  • 이런 과정을 통해 획득한 key pair를 사용해서 클라이언트는 서API 인증 서버가 요구하는 값을 Base64로 인코딩하고 Signature를 생성해 API 호출 시 Header를 통해 전달합니다. Selling API는 호출 직전에 인증 및 권한을 체크하기 위해 인증 시스템이 요청을 확인하고 API의 사용 가능여부를 판단합니다. 인증/권한 체크에서 실패가 떨어지면 인증 시스템은 요청을 중간에 차단하고 바로 UnAuthorization 오류를 클라이언트에 전달합니다. 하지만 인증/권한 체크가 통과하면 클라이언트의 요청은 호출한 API로 전달되고 그 결과가 클라이언트에 리턴됩니다.
How does a JSON Web Token works
[인증 도식화]

API 인증 토큰 구성 및 Sample Code

인증 토큰은 아래와 같이, Header와 Payload, Signature를 “.” 으로 연결하는 형태로 구성됩니다.

Header는 해싱(hashing) 알고리즘을 정의하는 정보와 사용자의 Identity를 나타내는 값으로 구성되며, 아래와 같이 json 포맷으로 표현하고 base64로 인코딩 합니다.
{
“alg”: “HS256”, // 인증 알고리즘
“typ”: “JWT”,
// 인증방식
“kid”: “{master id}” // Key Id. MasterId를 사용
}

Payload는 사용자에 관한 정보와 몇 가지 api에 대한 메타 데이터를 포함하는 json 포맷의 구조로 Header와 마찬가지로 base64로 인코딩 됩니다.
{
“iss”: “{token issuer}”, // 토큰 발행자. 보통 클라이언트의 도메인이나 주소가 사용 됨. ex)www.lotte.com, www.shinsegaemall.ssg.com, www.playauto.com
“sub”: “{domain}”, // Sell API는 “sell”
“aud”: “sa.esmplus.com”, // JWT 토큰 수신처
“iat”: “{issued timestamp(long type)}”, // JWT 발행 시간
“ssi”: “{site Id}:{site seller id}” // Site Id는 sell 도메인의경우 옥션은 “A”, 지마켓은 “G” 입력. “,”를 구분자로 복수개 입력 가능.
}

Signature는 위에서 정의한 Header와 Payload 값을 사용해서 해싱하여 고유의 기호를 만들어 내는 작업입니다. 마찬가지로 base64로 인코딩된 Header와 Payload 값을 사용해서 HmacSHA256으로 값을 해싱 합니다.
HS256(
base64UrlEncode(header) + “.” +
base64UrlEncode(payload),
secret key)

Sample Code
예를 들어, sell 도메인의 특정 api를 호출하려는 사용자가 있는데, 이 사용자의 ESM+의 masterId는 “test_masterId_1” 이며 Selling API를 사용하기 위해 발급 받은 Access Key는 “MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBALBHY2s60yx24OM/QoGEK4PtTroO8goHpJRFsxPCMco9uO01hSyAKFnH848HGvsD2mpiXk+OixlkTuS/TmILh3ECAwEAAQ==” 입니다. 그리고, 이 요청을 보내는 시점을 “2017-08-21 14:40:00(KST 기준)”라고 했을 때 이 값을 timestamp로 변환하면 “1503294000”가 됩니다. (timestamp 변환은 https://www.epochconverter.com / 참조)
그럼 이 상황 대로 토큰을 발행하기 위해 Header와 Payload 값을 구성해 보면 아래와 같습니다.

  • 호스팅사의 경우, kid는 무조건 호스팅사의 마스터ID를 넣어주셔야 합니다.

Header
{
“alg”: “HS256”,
“typ”: “JWT”,
“kid”: “your_master_id”
}

Payload
{
“iss”: “www.cafe24.com”,
“sub”: “sell”,
“aud”: “sa.esmplus.com”,
“iat”: “1503294000”,
“ssi”: “A:auction_seller_id,G:gmarket_seller_id” // “,”를 구분자로 옥션/지마켓 모두 입력 가능.
}

그리고, 이 Header와 Payload를 base64로 인코딩한 후 Secret Key로 해싱을 해서 각각 아래와 같은 값들을 얻었다고 가정해 보면,
Base64 encoded Header: “4eadf432lkjavnasdfkje32lkadjsf09”
Base64 encoded Payload: “zxcvlkjq234i8jl/+02jkldq341lkjzxdfckj”,
Signature: “MIIBVgIBADANBgkqhkiG9w0BAQEFAASCAUAwggE8AgEAAkEAsEdjazrTLHbg4z9CgYQrg+1O”

이 요청의 토큰은 아래와 같이 됩니다. (“.”으로 구분된 형태 확인)
“Authorization” : “Bearer 4eadf432lkjavnasdfkje32lkadjsf09.zxcvlkjq234i8jl/+02jkldq341lkjzxdfckj.MIIBVgIBADANBgkqhkiG9w0BAQEFAASCAUAwggE8AgEAAkEAsEdjazrTLHbg4z9CgYQrg+1O”

API 요청 보내기/결과

토큰을 생성했다면, 이제 API를 호출하면 됩니다. API를 호출할 때는 인증 과정을 통과하기 위해서 Http Request의 Header에 인증 토큰을 실어 보내야 합니다. 토큰을 실어 보낼 Http Header의 키는 “Authorization”이며, 스키마는 Bearer입니다. 그래서, 요청을 보낼 때는 Http Header에 아래의 키/값을 추가해야 합니다. (참고로, Authorization 헤더 값의 포맷은 “{Schema} {Token}” 입니다.)
// http header
“Authorization” : “Bearer 4eadf432lkjavnasdfkje32lkadjsf09.zxcvlkjq234i8jl/+02jkldq341lkjzxdfckj.MIIBVgIBADANBgkqhkiG9w0BAQEFAASCAUAwggE8AgEAAkEAsEdjazrTLHbg4z9CgYQrg+1O”

Http Header에 Authorization 키로 토큰을 실어 보냈고 Selling API 인증 시스템에서 전달된 토큰으로 문제 없이 인증과 권한을 모두 통과 했다면 API 호출은 정상적으로 API 서버에 전달 될 것입니다. 그리고, 처리 결과는 클라이언트에 리턴 됩니다.
하지만, 인증 또는 권한에서 요구하는 조건을 만족시키지 못했다면 요청은 API 서버로 전달되지 않고 곧바로 Selling API 인증 시스템에서 클라이언트로 오류를 리턴하게 되며 리턴 결과는 상황에 맞는 Http Status Code가 전달됩니다.


예를 들면, 접근 권한이 없는 API에 요청을 보내면 아래와 같은 결과가 클라이언트로 리턴 됩니다.

{
“status”:
{
“message”: “The user does not have right access to the api”,
“status_code”: 401
}
}

JWT를 소개하고 있는, jwt.io 웹사이트에서는 다양한 플랫폼 별로 사용할 수 있는 jwt 라이브러리들 역시 소개하고 있습니다.
https://jwt.io 웹사이트에 접근 후, 상단의 “Libraries” 메뉴를 보면 다양한 플랫폼 별로 여러 개의 라이브러리들이 제공되고 있는 것을 쉽게 알 수 있습니다. 따라서, 개발 플랫폼에 맞는 라이브러리들을 선택해서 쉽게 인증 코드를 구현할 수 있습니다