Authorization#

본 문서는 BORA API 에 접근하기 위해 어떻게 OAuth 2.0 인증과 승인을 적용하는지에 대한 예제 및 API에 대해 설명합니다. OAuth2.0에 대한 개념을 알고 싶으시면, https://oauth.net/2/ 을 참고하시기 바랍니다.


OAuth2.0 for BORA Platform Client#


개발사(콘텐츠 제공자)가 사용자에게 SHELL 을 지급하기 위해서는 개발사의 SHELL App 지갑주소, 사용자의 SHELL App 지갑주소를 알고 있어야 합니다. 이를 위해, SHELL App 지갑주소를 조회하거나 SHELL 을 전송하는 부분에 대해 적절한 인증 수단으로 제어할 수 있어야 합니다. 이 부분을 해결하기 위해 BORA 플랫폼은 안정성이 검증되었으며, 보편적으로 이용하는 OAuth2.0 인증 방식을 채택하였습니다.

BORA API 를 사용하기 위해서는 OAuth2.0의 grant type 중 Authorization Code, Client Credential 방식을 사용합니다. 콘텐츠 이용 사용자로부터 발생하는 트랜잭션의 경우 Authorization Code 방식으로 취득한 Access Token(이하 User Access Token), 개발사의 주소로부터 발생하는 트랜잭션의 경우 Client Credential 방식으로 취득한 Access Token(이하 Client Access Token)을 이용합니다.

모든 인증 요청은 클라이언트 Basic 인증 정보를 필요로 합니다. 인증 정보에는 client_id, client_secret 정보가 담겨있으며, 이는 로그인을 위한 아이디, 패스워드와 같은 역할을 합니다. 따라서 절대 외부로 노출되면 안되며, 노출을 방지하기 위해 가급적 서버 사이드에서 호출 할 것을 권장하고 있습니다. 추가로 BORA 플랫폼은 인증 요청 URI에 대해 CORS를 지원하지 않기 때문에 사용자 브라우저 환경에서는 인증 요청을 하실 수 없습니다.

BORA Ecosystem 의 모든 API는 보안을 위해 인증키를 요구하며, 이를 위해 OAuth2 기반의 OAuth API 를 제공합니다. "명시적인 사용자 인증절차 필요" 여부에 따라 두가지 타입의 인증 방식이 사용됩니다.

명시적인 사용자 인증이 필요없는 트랜잭션#

  • 인증타입 : Client Credential, (APP 등록시 Client ID, Client Secret Key 발급 후 제공됨)
  • 구현방법 : Client ID, Client Secret Key 로 인증 요청

e.g. 개발사의 서버 와 BORA API 서버간 트랜잭션

명시적인 사용자 인증이 필요한 트랜잭션#

  • 인증타입 : Authorize Code
  • 구현방법 : BORA Ecosystem 에서 제공하는 인증 화면을 호출

e.g. 사용자의 SHELL 차감을 위해 자산 이용 권한을 획득해야하는 경우


Client Registration#


먼저 개발사의 앱BORA Membership 연동을 위해서는 다음 내용이 BORA 운영팀을 통해서 등록되어야 합니다.

  • Client ID - OAuth 인증을 통해서 BORA API를 호출하기 위한 클라이언트에 대한 식별자
  • Client Secret - 클라이언트에 대한 보안 키 값으로 앱 개발사의 서버에 저장되어 관리되어야 합니다.
  • Redirect URI - OAuth 인증이 끝난후 Authorization Code 또는 Access Token을 발급 받기 위하여 앱 개발사에서 제공하는 URI이다. 이 값은 앱 개발사가 BORA 운영팀에 전달하여 클라이언트 등록시에 같이 시스템에 등록되어야 합니다.

앱 개발사는 클라이언트 등록시 발급받은 Client IDRedirect URIBORA Membership 인증과정에서 사용할 수 있습니다.


Access Token Request#


BORA Ecosystem API 호출에 앞서 필요한 Access Token을 획득하기 위하여 2가지 방식의 인증 방식을 처리하기 위한 API에 대해서 설명합니다.

1. Client Credential Grant Flow#

Client Credential 방식은 클라이언트 등록과정에서 발급 받은 Client ID값과 Client Secret 값을 이용해서 한번에 Access Token을 발급 받는 방식입니다. 이 방법은 주로 인증된 서버에서 Resource Server의 API를 요청하기 위한 방법으로 사용됩니다.

Request

  • HOST:

    auth.boraecosystem.com

  • URI:

    /v1/oauth/token

  • METHOD:

    POST

  • PARAMETERS:
Name Required Values Description Parameter Type Data Type
Authorization * Basic {client_basic_auth} 클라이언트 Basic 인증 정보 header string

* {client_basic_auth} : client_id:client_secret을 base64 encoding 한 값

  • REQUEST BODY:
Name Required Values Description Content Type Data Type
grant_type * client_credentials 인증 유형 application/x-www-form-urlencoded string

Resoponse

  • RESPONSE BODY:
{
  "access_token": string,
  "token_type": string,
  "expires_in": integer,
  "app_no": integer
}

Errors

문서 하단 Error Code 참조

Sample

Sample Request

curl -X POST \
  'https://auth.boraecosystem.com/v1/oauth/token' \
  -H 'Authorization: Basic N1ozN1FhS001SDJpaDVzSDpBejZTQzNqWnBVTTNwbGxmRmhLM1phZkp2VlQ5xxxxxx' \
  -d 'grant_type=client_credentials'

Sample Response

{
    "access_token": "f319ce41-3399-4548-a4f9-f203bc139d36-8bfdf2c0-b9d8-4dbc-9f07-a869785xxxxx",
    "token_type": "bearer",
    "expires_in": 82691,
    "app_no": 1000xx
}


2. Authorization Code Flow#

Authorization Code 방식은 사용자가 클라이언트 앱을 통해서 BORA Membership 로그인을 하고 사용자 Access Token을 발급 받는 방법을 제공합니다.

1) 인증 코드 요청 페이지 접근#

사용자에게 인증을 받고자 할 경우, 컨텐츠 제공자의 페이지에서 사용자를 BORA에서 제공 하는 인증 페이지로 이동 시키면 (아래 예제 참고), 사용자는 BORA의 ID, Password를 입력하고 인증 과정을 거치게 됩니다. 유저 인증이 완료되면 지정한 redirect_uri로 code와 state 값을 쿼리 스트링으로 전달합니다. redirect_uri는 code와 state 값을 받아 처리할 컨텐츠 제공자의 서버 uri이며, client_id발급 받는 과정에서 허용한 uri만 사용할 수 있습니다. CSRF 공격 방지를 위해 state 값 활용을 권고합니다.

Request

  • HOST:

    auth.boraecosystem.com

  • URI:

    /v1/oauth/authorize

  • METHOD:

    GET

  • PARAMETERS:
Name Required Values Description Parameter Type Data Type
response_type * code 응답 유형 query string string
client_id * {client_id} 클라이언트 아이디 query string string
state {csrf_token} CSRF 방지 토큰 query string string
redirect_uri * {redirect_uri} 리다이렉트 URI query string string

Errors

문서 하단 Error Code 참조

Sample#

Sample Request

# ① 인터넷 브라우저를 통해 사용자를 해당 URI 접근하도록 유도
https://auth.boraecosystem.com/v1/oauth/authorize?response_type=code&client_id=X0yTxxxxxx&state=hLiDdL2uhPtsftcU&redirect_uri=https://your.server/your_end_point

Sample Response

# ② 유저가 ①에서 접근한 페이지에서 인증을 완료하면 code 값과 함께 지정된 uri로 Redirect
https://your.server/your_end_point?code=bju8iKZU4wFVclj8kUjPpetra02yNTN2gra98O6Cc91RnNDXlmC9LN2jKTixxxxx&state=123
# ③ 컨탠츠 제공자는 자신의 서버에서 code 값을 획득해야 합니다
# {code}: bju8iKZU4wFVclj8kUjPpetra02yNTN2gra98O6Cc91RnNDXlmC9LN2jKTixxxxx 


2) 사용자 Access Token 요청 및 발급#

인증코드 요청을 통해서 Authorization Code를 발급받았다면 이제 다음 과정을 통해서 Authorization Code를 이용하여 Access Token을 요청할 수 있습니다. 이 때, 발급된 Access Token을 받아 처리할 redirect_uri을 지정합니다.

Request

  • HOST:

    auth.boraecosystem.com

  • URI:

    /v1/oauth/token

  • METHOD:

    POST

  • PARAMETERS:
Name Required Values Description Parameter Type Data Type
Authorization * Basic {client_basic_auth} 클라이언트 Basic 인증 정보 header string

* {client_basic_auth} : client_id:client_secret을 base64 encoding 한 값

  • REQUEST BODY:
Name Required Values Description Content Type Data Type
grant_type * authorization_code 인증 유형 application/x-www-form-urlencoded string
code * {code} 인증 code application/x-www-form-urlencoded string
redirect_uri * {redirect_uri} 리다이렉트 URI application/x-www-form-urlencoded string

Response

  • RESPONSE BODY:
{
  "access_token": string,
  "token_type": string,
  "refresh_token": string,
  "expires_in": integer,
  "scope": string,
  "app_no": integer,
  "member_no": integer,
  "nickname": string,
  "username": string
}

Errors

문서 하단 Error Code 참조

Sample

Sample Request

curl -X POST \
  'https://auth.boraecosystem.com/v1/oauth/token?grant_type=authorization_code&code=bju8iKZU4wFVclj8kUjPpetra02yNTN2gra98O6Cc91RnNDXlmC9LN2jKTixxxxx&redirect_uri=http://localhost/your_end_point' \
  -H 'Authorization: Basic N1ozN1FhS001SDJpaDVzSDpBejZTQzNqWnBVTTNwbGxmRmhLM1phZkp2VlQ5xxxxxx'

Sample Response

{
    "access_token": "ac9e3bb8-be89-4ed0-8e30-32b167e3a83d-b9ce608f-6304-4ca7-960e-8f766fxxxxxx",
    "token_type": "bearer",
    "refresh_token": "e6a57af6-7f60-4261-b4b9-60ef228c5d7a-068813d8-a03c-4ea2-a7a5-f9b5fcxxxxxx",
    "expires_in": 86399,
    "scope": "user email gauction",
    "app_no": 1000xx,
    "member_no": 1,
    "nickname": "tester",
    "username": "test@boraecosystem.com"
}


Access Token Validation and Reissuance#


Access Token 은 발급 후 24시간 뒤 만료가 됩니다. Access Token이 만료되었는지 또는 유효한지 검사가 필요한 경우 본 API를 이용합니다.

1) 유효성 검사 요청#

다음 요청으로 access token의 유효성 검사를 실행할 수 있다. 만약 유효성 검사에서 access token이 유효하지 않다면, refresh token으로 access token을 새로 발급 받을 수 있습니다.

Request

  • HOST:

    auth.boraecosystem.com

  • URI:

    /v1/oauth/check_token

  • METHOD:

    GET

  • PARAMETERS:
Name Required Values Description Parameter Type Data Type
Authorization * Basic {client_basic_auth} 클라이언트 Basic 인증 정보 header string
token * {access_token} 검사 대상 access token query string string

* {client_basic_auth} : client_id:client_secret을 base64 encoding 한 값

Resoponse

  • RESPONSE BODY:
{
  "grant_type": string,
  "member_no": integer,
  "scope": string,
  "nickname": string,
  "active": boolean,
  "app_no": integer,
  "exp": integer,
  "client_id": string,
  "username": string
}

Errors

문서 하단 Error Code 참조

Sample

Sample Request

curl -X GET \
  'https://auth.boraecosystem.com/v1/oauth/check_token?token=ac9e3bb8-be89-4ed0-8e30-32b167e3a83d-b9ce608f-6304-4ca7-960e-8f766fxxxxxx' \
  -H 'Authorization: Basic N1ozN1FhS001SDJpaDVzSDpBejZTQzNqWnBVTTNwbGxmRmhLM1phZkp2VlQ5xxxxxx'

Sample Response

{
    "grant_type": "authorization_code",
    "member_no": 1,
    "scope": "user email gauction",
    "nickname": "tester",
    "active": true,
    "app_no": 1000xx,
    "exp": 1539665602,
    "client_id": "X0yTxxxxxx",
    "username": "test@boraecosystem.com"
}


2) 액세스 토큰 재발급#

Access Token은 Access Token 발급 당시 받은 refresh token을 통해서 재 발급 받을 수 있습니다.

Request

  • HOST:

    auth.boraecosystem.com

  • URI:

    /v1/oauth/token

  • METHOD:

    POST

  • PARAMETERS:
Name Required Values Description Parameter Type Data Type
Authorization * Basic {client_basic_auth} 클라이언트 Basic 인증 정보 header string

* {client_basic_auth} : client_id:client_secret을 base64 encoding 한 값

  • REQUEST BODY:
Name Required Values Description Content Type Data Type
grant_type * refresh_token 인증 유형 application/x-www-form-urlencoded string
refresh_token * {refresh_token} refresh token application/x-www-form-urlencoded string

Response

  • RESPONSE BODY:
{
  "access_token": string,
  "token_type": string,
  "refresh_token": string,
  "expires_in": integer,
  "scope": string,
  "app_no": integer,
  "member_no": integer,
  "nickname": string,
  "username": string
}

Errors

문서 하단 Error Code 참조

Sample

Sample Request

curl -X POST \
  'https://auth.boraecosystem.com/v1/oauth/token' \
  -H 'Authorization: Basic N1ozN1FhS001SDJpaDVzSDpBejZTQzNqWnBVTTNwbGxmRmhLM1phZkp2VlQ5xxxxxx' \
  -d 'grant_type=refresh_token&refresh_token=e6a57af6-7f60-4261-b4b9-60ef228c5d7a-068813d8-a03c-4ea2-a7a5-f9b5fcxxxxxx'

Sample Response

{
    "access_token": "89ab8dd6-327a-4d68-abc2-1135dc2f6a55-25185fc0-4566-449d-98cf-06fe37xxxxxx", // 재발급 된 access_token
    "token_type": "bearer",
    "refresh_token": "e6a57af6-7f60-4261-b4b9-60ef228c5d7a-068813d8-a03c-4ea2-a7a5-f9b5fcxxxxxx",
    "expires_in": 86399,
    "scope": "user email gauction",
    "app_no": 1000xx,
    "member_no": 1,
    "nickname": "tester",
    "username": "test@boraecosystem.com"
}


System Check#


현재 서버 상태 확인#

현재 서버 상태를 확인 할 수 있습니다.

Request

  • HOST:

    auth.boraecosystem.com

  • URI:

    /v1/system/maintenance

  • METHOD:

    GET

  • PARAMETERS:

    N/A

Response

  • RESPONSE BODY:
{
  "status": int,
  "data": {
    "status": string, // READY | ACTIVE | INACTIVE
    "start": string, // "yyyy-MM-dd HH24:mi:ss"
    "end": string, // "yyyy-MM-dd HH24:mi:ss"
    "message": string
  }
}

Sample

Sample Request

curl -X GET \
  'https://auth.boraecosystem.com/v1/system/maintenence'

Sample Response

{
  "status": 200,
  "data": {
    "status": "ACTIVE",
    "start": null,
    "end": null,
    "message": null
  }
}
{
  "status": 200,
  "data": {
    "status": "READY",
    "start": "2019-06-18 11:30:00",
    "end": "2019-06-18 15:30:00",
    "message": "the server will be down for system maintenance.(2019-06-18 11:30:00 ~ 2019-06-18 15:30:00)"
  }
}
{
  "status": 200,
  "data": {
    "status": "INACTIVE",
    "start": "2019-06-18 11:30:00",
    "end": "2019-06-18 15:30:00",
    "message": "the server is currently down for system maintenance.(2019-06-18 11:30:00 ~ 2019-06-18 15:30:00)"
  }
}


Error Code#

HTTP Status 400 에러(Bad Request)가 발생 할 경우 API는 아래와 같은 형식으로 응답합니다.

Response

// 400 Error 일 경우
{
  "status": 400,
  "error": {
    "code": -800400,
    "message": "Invalid authorization code: hqL9o1nOen4l7qRIe4aKF2QCMrfeheHu8fpf8SggQWBjY8SEn0sfq0096xxxxxx",
    "detail": "invalid_grant",
    "data": null,
    "errors": {}
  }
}

다음과 같은 에러가 발생 할 수 있습니다.

Values Description
invalid_request 파라미터가 잘못되었거나 요청문이 잘못되었습니다.
invalid_token Access Token이 만료되었거나 형식 오류 또는 다른 이유로 유효하지 않습니다.
invalid_grant grant 방식 또는 token의 만료 등등의 이유로 인증 과정에서 문제가 발생하였습니다. 상세한 내용은 error_description을 참고합니다.
unauthorized_client 인증받지 않은 인증 코드로 요청했습니다.
unsupported_response_type 정의되지 않은 반환 형식으로 요청했습니다.
redirect_uri_mismatch 허용되지 않은 redirect URI입니다.

기타 다음과 같은 오류가 발생할 수 있습니다.

HTTP Status Description
400 Bad Request: 잘못된 요청입니다.
Invalid Parameter: 올바르지 않은 입력값 입니다.
401 Unauthorized: 권한이 없어 인증이 실패했습니다.
403 Fobbiden: 접근할 수 없는 URI 입니다.
404 Not Found: 없는 URL 또는 결과가 없습니다.
500 Internal Server Error: 인증서버의 오류입니다. BORA팀에 문의하십시오.
503 System Maintenance: 시스템 점검 중 입니다. 잠시 후 시도 하십시오.