DOCUMENTS

Documents of the BORA project.

Authorization APIs

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

OAuth2.0 for BORA Platform Client

콘텐츠 제공자가 유저에게 BORA Shell를 지급하기 위해서는 콘텐츠 제공자의 주소, 유저의 주소를 알고 있어야 합니다. 이를 위해, 주소를 가져온다거나, BORA 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)을 이용합니다.예를 들어, 콘텐츠 제공자와 유저 간 게임이 진행되었고, 유저가 승리하여 콘텐츠 제공자의 주소에서 유저의 주소로 BORA Shell이 흘러갈 경우, Client Access Token을 사용합니다. 반대로, 콘텐츠 제공자가 승리하여 유저의 주소로부터 Point를 가져와야 하는 경우는 User Access Token을 사용합니다. 같은 원리로 콘텐츠 이용 유저 간 거래가 일어날 경우 지불을 해야 하는 유저의 User Access Token이 사용됩니다.모든 인증 요청은 클라이언트 Basic 인증 정보를 필요로 합니다. 인증 정보에는 client_id, client_secret 정보가 담겨있으며, 이는 로그인을 위한 아이디, 패스워드와 같은 역할을 합니다. 따라서 절대 외부로 노출되면 안되며, 노출을 방지하기 위해 가급적 서버 사이드에서 호출 할 것을 권장하고 있습니다. 추가로 BORA 플랫폼은 인증 요청 URI에 대해 CORS를 지원하지 않기 때문에 사용자 브라우저 환경에서는 인증 요청을 하실 수 없습니다.

Client Credentials Grant Flow

Client Credentials Grant Flow에 대한 이해를 위해 도식을 참고하십시오.

1Access the Request Authentication Code page

POST /member/oauth/token
Authorization: Basic {client_basic_auth}
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
HOST: accounts.boraecosystem.com

// 참고: {client_basic_auth}는 client_id:client_secret을 Base64 encoding 한 값입니다.
// 예제:
curl -d "grant_type=client_credentials" -H "Authorization: Basic dGVzdDp0ZXN0MTIzNA" -X POST https://accounts.boraecosystem.com/member/oauth/token

Parameters

ParameterRequiredValuesDescriptionParameter TypeData Type
Authorization*클라이언트 Basic 인증 정보headerstring
grant_type*client_credentials응답 유형 (반드시 client_credentials이어야 함)formDatastring

Response

{
"access_token": "d4c0eecb-4c01-4ef1-94fd-669d227aa625",
"token_type": "bearer",
"expires_in": 79684,
"scope": "user email gauction",
"app_no": 100004
}

Authorization Code Grant Flow

Authorization Code Grant flow와 아래 API를 어떻게 사용하는지에 대한 이해를 돕기 위해 아래 도식을 참고하십시오.

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

GET /member/oauth/authorize?response_type=code&client_id={client_id}&state={state}&redirect_uri={redirect_uri}
HOST: accounts.boraecosystem.com

// 예제:
페이지 이동: https://accounts.boraecosystem.com/member/oauth/authorize?response_type=code&client_id=X0yT6nI69Q&state=hLiDdL2uhPtsftcU&redirect_uri=https://localhost/code
사용자에게 인증을 받고자 할 경우, 컨텐츠 제공자의 페이지에서 BORA에서 제공 하는 인증 페이지(위 예제 URL)로 이동 시키면, 사용자는 BORA의 ID, Password를 입력하고 승인 과정을 거칩니다. 승인이 완료된 경우 지정한 redirect_uri로 code와 state 값을 전송합니다. redirect_uri는 code와 state를 받아 처리할 컨텐츠 제공자의 서버 uri이며 client_id를 발급 받는 과정에서 허용한 uri만 사용할 수 있습니다. CSRF 공격 방지를 위해 state 값 활용을 권고합니다. scope에 email이 있을 경우에 username 항목을 받을 수 있습니다.

Parameters

ParameterRequiredValuesDescriptionParameter TypeData Type
response_type*code응답 유형 (반드시 code이어야 함)querystring
client_id*클라이언트 아이디querystring
stateCSRF 방지 토큰querystring
redirect_uri*리다이렉트 URIquerystring

Response

"GET /{redirect_uri}?code=xxxx" 형식으로 Authorization code 전송

// 예제:
redirect_uri이 "http://localhost/code"인 경우 "http://localhost/code?code=HBua25&state=hLiDdL2uhPtsftcU" 형식으로 컨텐츠 제공자의 페이지로 code 및 state 값을 전송

2액세스 토큰 요청

POST /member/oauth/token
Authorization: Basic {client_basic_auth}
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code={code}&redirect_uri={redirect_uri}
HOST: accounts.boraecosystem.com

// 예제:
// 위에서 전달 받은 code를 사용하여, access token을 발급하는 API를 호출한다. 이 때, 발급된 Access Token을 받아 처리할 redirect_uri을 전송함.
curl -d "grant_type=authorization_code&code=HBua25&redirect_uri=http://localhost/token" -H "Authorization: Basic dGVzdDp0ZXN0MTIzNA" -X POST https://accounts.boraecosystem.com/member/oauth/token

Parameters

ParameterRequiredValuesDescriptionParameter TypeData Type
Authorization*클라이언트 Basic 인증 정보headerstring
grant_type*authorization_code인증 유형 (반드시 authorization_code이어야 함)formDatastring
code*전달받은 액세스 토큰 요청 코드(Authorization Code) formDataformDatastring
redirect_uri*리다이렉트 URIformDatastring

Response

{
"access_token": "b409ebbf-6077-4f60-b961-3d5962ff1e26",
"token_type": "bearer",
"refresh_token": "275c574b-4e41-4053-9e83-fca53dccaxxx",
"expires_in": 86399,
"scope": "user email gauction",
"app_no": 100004,
"member_no": 1
"username": "test@boraecosystem.com"
}

액세스 토큰 유효성 검사

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

유효성 검사 요청

GET /member/oauth/check_token?token={access_token}
Authorization: Basic {client_basic_auth}
HOST: accounts.boraecosystem.com

// 예제:
curl -H "Authorization: Basic dGVzdDp0ZXN0MTIzNA" -X POST https://accounts.boraecosystem.com/member/oauth/check_token?token=b409ebbf-6077-4f60-b961-3d5962ff1e26

Parameters

ParameterRequiredValuesDescriptionParameter TypeData Type
Authorization*클라이언트 Basic 인증 정보headerstring
token*액세스 토큰querystring

Response

{
"member_no": 1,
"scope": "user email gauction",
"active": true,
"app_no": 100004,
"exp": 1539665602,
"client_id": "X0yT6nI69Q",
"username": "test@boraecosystem.com"
}

액세스 토큰 재발급

Access Token은 Refresh Token으로 재발급 받을 수 있습니다.

재발급 요청

POST /member/oauth/token
Authorization: Basic {client_basic_auth}
grant_type=refresh_token&refresh_token={refresh_token}
HOST: accounts.boraecosystem.com

// 예제:
// 앞서 발급 받은 refresh_token을 사용하여, 새로운 access_token으로 재발급 받는 API를 호출한다.
curl -d "grant_type=refresh_token&refresh_token=275c574b-4e41-4053-9e83-fca53dccaxxx" -H "Authorization: Basic dGVzdDp0ZXN0MTIzNA" -X POST https://accounts.boraecosystem.com/member/oauth/token

Parameters

ParameterRequiredValuesDescriptionParameter TypeData Type
Authorization*클라이언트 Basic 인증 정보headerstring
grant_type*refresh_token인증 유형 (반드시 refresh_token이어야 함)formDatastring
refresh_token*리프레쉬 토큰formDatastring

Response

{
"access_token": "37f07130-19ce-47db-a7a5-d635476958a6",
"token_type": "bearer",
"refresh_token": "275c574b-4e41-4053-9e83-fca53dccaxxx",
"expires_in": 86399,
"scope": "user email gauction",
"app_no": 100004,
"member_no": 1,
"username": "test@boraecosystem.com"
}

에러 응답

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

Response

// 400 Error 일 경우
{
"error": "invalid_token",
"error_description": "Token was not recognised"
}
다음과 같은 에러가 발생 할 수 있습니다.

에러 코드

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

에러 코드

HTTP CodeDescription
401Unauthorized: 권한이 없어 인증이 실패했습니다.
403Fobbiden: 접근할 수 없는 URI 입니다.
404Not Found: 없는 URL 또는 결과가 없습니다.
500Internal Server Error: 인증서버의 오류입니다. BORA팀에 문의하십시오.
"