공개 API의 인증을 위해서 OAuth 2.0 프로토콜 사용을 권장하고 있습니다.
- client_id(회원계정)와 발급받은 client_Secret를 사용하여 서버로 요청하시면, Access_Token을 발급받으실 수 있습니다.
- 발급받은 Access_Token은 API 호출 시, HTTP 헤더에 포함되어야 합니다.
- 만약 제 3자가 고객님의 client_id와 보안키를 획득하면 보안문제가 발생할 수 있습니다. 따라서 Access_Token은 반드시 서버에서 이뤄져야합니다.
1 유효기간
- Access_Token은 1시간, Refresh_Token은 24시간 유효합니다.
- Access_Token이 만료되면, Refresh_Token을 사용하여 재발급이 필요합니다.
- client_id, client_secret 정보로 재발급시 기존 Token은 사용할 수 없습니다.
- API 호출시마다, Access_Token을 새로발급받는 것은 너무 많은 리소스가 사용될 우려가 있습니다.
2 OAuth 2.0의 표준 권한 승인 방법
- (a) 서버(Server)와 클라이언트(Client)사이에 인증을 완료하면 권한 부여의 기능을 수행하는 엑세스 토큰*(Access_Token)을 증표로 전달
- (b) 클라이언트(Clinet)는 이 엑세스 토큰으로 보호된 자원(Protected Resource)에 접근하거나 서비스를 요청할 수 있음
- (c) 자원 서버(Resource Server)는 엑세스 토큰(Access_Token)을 기반으로 권한을 확인 후, 결과를 클라이언트에게 다시 보냄
- * 엑세스 토큰(Access Token)
-
보호된 자원에 접근하거나 서비스를 요청할 때, 클라이언트의 권한을 대표하여 확인용으로 사용함.
엑세스 토큰 하나로 계정 인증에 필요한 모든 것들을 확인할 수 있음
3 API기본정보
- POST방식을 지원합니다.
- 시스템 설정에 따라 GET방식이 가능하나, 보안에 취약하여 권장하지 않습니다.
| 메서드 |
인증 |
요청URL |
출력 포맷 |
설명 |
|
POST
|
OAuth 2.0
|
http://api.goodapi.co.kr:8888/Rest/oauth20/token?type=json
|
json
|
접근 토큰발급/갱신/삭제 요청
|
|
POST
|
OAuth 2.0
|
http://api.goodapi.co.kr:8888/Rest/oauth20/token?type=xml
|
xml
|
접근 토큰발급/갱신/삭제 요청
|
4 요청변수
| 요청 변수명 |
타입 |
필수 여부 |
기본값 |
설명 |
|
grant_type
|
string
|
Y
|
code
|
인증 과정에 대한 구분값
1. 발급:'client_credentials'
2. 갱신:'refresh_token'
3. 삭제: 'delete'
|
|
client_id
|
string
|
Y
|
-
|
애플리케이션 등록 시 발급받은 Client ID 값
|
|
client_secret
|
string
|
Y
|
-
|
애플리케이션 등록 시 발급받은 Client secret 값
|
|
refresh_token
|
string
|
갱신 때 필수
|
-
|
사용자 인증에 성공하고 발급받은 갱신 토큰(refresh token)
|
|
access_token
|
string
|
삭제 때 필수
|
-
|
발급받은 접근 토큰으로 URL 인코딩을 적용한 값을 사용
|
|
service_provider
|
string
|
|
GSCMS
|
인증 제공자 이름으로 'GSCMS'로 세팅해 전송
|
5 출력결과
접근 토근 발급 요청
| 필드 |
타입 |
설명 |
|
access_token
|
string
|
접근 토큰, 발급 후 expires_in 파라미터에 설정된 시간(초)이 지나면 만료됨
|
|
refresh_token
|
string
|
접근 토큰의 타입으로 Bearer 지원
|
|
expires_in
|
integer
|
접근 토큰의 유효 기간(초 단위)
|
|
R_CODE
|
string
|
결과 코드
|
|
R_MSG
|
string
|
결과 메시지
|
접근 토근 갱신 요청
| 필드 |
타입 |
설명 |
|
access_token
|
string
|
접근 토큰, 발급 후 expires_in 파라미터에 설정된 시간(초)이 지나면 만료됨
|
|
token_type
|
string
|
접근 토큰의 타입으로 Bearer 지원
|
|
expires_in
|
integer
|
접근 토큰의 유효 기간(초 단위)
|
|
R_CODE
|
string
|
결과 코드
|
|
R_MSG
|
string
|
결과 메시지
|
접근 토근 삭제 요청
| 필드 |
타입 |
설명 |
|
access_token
|
string
|
삭제 처리된 접근 토큰 값
|
|
result
|
string
|
처리 결과가 성공이면 'success'가 리턴
|
|
expires_in
|
integer
|
접근 토큰의 유효 기간(초 단위)
|
|
R_CODE
|
string
|
결과 코드
|
|
R_MSG
|
string
|
결과 메시지
|
6 OAuth응답코드
OAuth관련 응답코드입니다.
| HTTP 코드 |
결과 코드 |
결과 메시지 |
조치 방안 |
|
200 |
0000 |
정상처리 |
요청에 대한 정상처리 |
|
401 |
@024 |
Authentication failed / 인증에 실패했습니다. |
|
|
401 |
@028 |
Authentication header not exists / OAuth 인증 헤더(authorization header)가 없습니다. |
|
|
403 |
@403 |
Forbidden / 호출 권한이 없습니다. |
API 요청 헤더에 클라이언트 ID와 Secret 값을 정확히 전송했는지 확인해보시길 바랍니다 |
|
404 |
@404 |
Not Found / 검색 결과가 없습니다 |
- |
|
405 |
@405 |
HTTP 메서드를 잘못 호출한 경우. POST 방식으로 호출해야 하는데 GET 방식으로 호출한 경우 등입니다 |
허용하는 HTTP 메서드를 확인합니다. |
|
500 |
@500 |
Internal Server Error / 데이터베이스 오류입니다. |
서버 내부 에러가 발생하였습니다. 포럼에 올려주시면 신속히 조치하겠습니다. |
7 예시
요청 예시
[POST]http://api.goodapi.co.kr:8888/Rest/oauth20/token?type=json
접근 토큰 발급 요청
{
"grant_type":"client_credentials"
"client_id":"jyvqXeaVOVmV"
"client_secret":"527300A0COq1XV33cf"
"service_provider":"GSCMS"
}
접근 토큰 갱신 요청
{
"grant_type":"refresh_token"
"client_id":"jyvqXeaVOVmV"
"refresh_token":"vnxzP22RgbQgbNeEMDdD5dSPKGM"
"service_provider":"GSCMS"
}
접근 토큰 삭제 요청
{
"grant_type":"delete"
"client_id":"jyvqXeaVOVmV"
"access_token":"d30C9mWef2g5H1Y4QjVQzFWzG8vMsQwIaC1fmYxHyI"
"service_provider":"GSCMS"
}
응답 예시
접근 토큰 발급 요청
{
"access_token":"d30C9mWef2g5H1Y4QjVQzFWzG8vMsQwIaC1fmYxHyI",
"refresh_token":"vnxzP22RgbQgbNeEMDdD5dSPKGM",
"token_type":"bearer",
"expires_in":"3600"
}
접근 토큰 갱신 요청
{
"access_token":"wGijpi0NkhQfoR8CB46xkUxAUtcpACQEtfQROn3QTx4",
"token_type":"bearer",
"expires_in":"3600"
}
접근 토큰 삭제 요청
{
"access_token":"d30C9mWef2g5H1Y4QjVQzFWzG8vMsQwIaC1fmYxHyI",
"result":"success"
}
