diff --git a/doc/OAuth2Guide_kr.md b/doc/OAuth2Guide_kr.md index a445fe6..c231de0 100644 --- a/doc/OAuth2Guide_kr.md +++ b/doc/OAuth2Guide_kr.md @@ -1,59 +1,270 @@ # Thing+ OAuth2 가이드 -3rd party에서 Thing+ 자원을(resource) 이용하기 위해 -OAuth2 를 이용하여 authentication/authorization 획득 과정에 대한 간단한 가이드이다. -상세한 내용은 [여기](./OAuth2.md) 에서 설명한다. +모든 개발자는 Thing+ REST API 을 이용한 개발을 하기 위해 Thing+ Portal 사용자 계정에 OAuth Client 를 등록하고, 원하는 OAuth Client 에 대해 AccessToken을 발급 받을 수 있습니다. OAuth Client 등록시 OAuth Client ID 와 OAuth Client Secret 을 사용자가 설정해서 등록할 수 있습니다. 그리고 등록한 OAuth Client 로 Authorization Code Grant 방식 또는 Resource Owner Password Credentials Grant 방식으로 AccessToken 을 획득할 수 있습니다. 획득한 AccessToken 은 Thing+ Cloud 에 접근하여 Gateway, Device, Sensor, SensorData 와 같은 사용자 리소스 접근에 사용됩니다. 또한 Authorization Code Grant 방식으로 획득한 AccessToken 은 Scopes 옵션을 지정하여 사용자 리소스 접근 권한을 사용자가 자유롭게 지정할 수 있습니다. -## What is OAuth2 -https://oauth.net/2/ +이러한 과정을 거쳐 Thing+ OAuth2 AccessToken 을 획득하면 Thing+ Portal 사용자 비밀번호를 요청하지 않고도 외부 애플리케이션에서 AccessToken 만으로 편리하게 사용자 리소스에 접근 할 수 있습니다. 또한 AccessToken 을 Grant 하는 방식에 따라 사용자 리소스 접근 권한을 관리할 수 있으므로 사용자 필요에 따라 Thing+ Portal 사용자 계정의 OAuth Client 를 관리 할 수 있습니다. + +현재 Thing+ 는 AccessToken 획득에 **Authorization Code Grant 방식** 또는 **Resource Owner Password Credentials Grant 방식**을 지원하고 있습니다. + +|획득 방식|설명 +|---|---- +|Authorization Code Grant|사용자에게 리소스 접근 권한을 지정하고자 하는 경우 사용합니다. +|Resource Owner Password Credentials Grant|관리자(Admin)의 권한으로 관리 범위의 리소스에 접근하기 원하는 경우 사용합니다. + +**주의 : 등록한 OAuth client ID, OAuth client secret 과 획득한 AccessToken 을 잘 보관하시기 바랍니다.** + +획득한 AccessToken 과 이에 포함된 정보는 Thing+ 운영 정책에 따라 변경될 수 있습니다. + +[Thing+ 기본 가이드 문서를 찾으려면 이 문서를 참조하십시오.](../README.md) + +[Thing+ REST API 기술 문서를 찾으려면 https://thingplus.api-docs.io 를 참조하십시오.](https://thingplus.api-docs.io/) + +## 목차 +Thing+ OAuth2 가이드를 쉽게 이해할 수 있도록 목차를 제공합니다. +* [OAuth2 란 무엇인가?](./OAuth2Guide_kr.md#oauth2-란-무엇인가) +* [단계1. Thing+ OAuth2 인증 진행 - OAuth client 등록](./OAuth2Guide_kr.md#단계1-thing-oauth2-인증-진행---oauth-client-등록) +* [단계2-1. Thing+ OAuth2 인증 진행 - Authorization Code Grant](./OAuth2Guide_kr.md#단계2-1-thing-oauth2-인증-진행---authorization-code-grant) +* [단계2-2. Thing+ OAuth2 인증 진행 - Resource Owner Password Credentials Grant](./OAuth2Guide_kr.md#단계2-2-thing-oauth2-인증-진행---resource-owner-password-credentials-grant) +* [단계3. Thing+ OAuth2 인증 진행 - Application Header](./OAuth2Guide_kr.md#단계3-thing-oauth2-인증-진행---application-header) + +## OAuth2 란 무엇인가? +Thing+ 는 클라이언트 사용자 편의를 위해 **OAuth2** 인증을 사용합니다. OAuth2는 인증을 위한 산업 표준 프로토콜입니다. OAuth2 는 웹 어플리케이션, 데스크톱 어플리케이션, 모바일 폰, 개인 임베디드 디바이스에 권한을 부여하기 위해 사용되는 산업 표준 프로토콜이며, 단순성에 중점을 두어 클라이언트 개발자가 더욱 편리하게 인증을 사용할 수 있게 합니다. 아래 OAuth 2.0 flow 를 이해하시면 더 쉽게 Thing+ 를 이용한 개발을 할 수 있습니다. ![OAuth](./images/oauth2.png "OAuth") +[OAuth2 를 더 자세히 알아보려면 이 웹사이트를 참조하십시오.](https://oauth.net/2) + +## 단계1. Thing+ OAuth2 인증 진행 - OAuth client 등록 +### 요구사항 +Thing+ 는 **실제 사용자를 위한 Commercial** 과 **실험적 기능이 추가 되어있는 Sandbox** 를 지원합니다. Thing+ 에서는 추후 유료 고객을 위해 상용 서버를 운영하고, 일반 사용자를 위해서는 샌드박스 서버를 운영할 계획입니다. 개발시 참고해서 사용해주시기 바랍니다. + +OAuth client 등록을 시작하기 전에 다음이 필요합니다. +> Commercial 사용시 +* [Thing+ Portal](https://thingplus.net) 회원가입. Thing+ 는 개인 사용자를 위한 무료 계정 생성과 비즈니스 고객을 위한 계정 생성을 지원합니다. +* [Thing+ Portal](https://thingplus.net) 로그인 + +> Sandbox 사용시 +* [Thing+ Sandbox Portal](https://www.sandbox.thingplus.net) 회원가입. Thing+ 는 개발자를 위한 무료 계정 생성을 지원합니다. +* [Thing+ Sandbox Portal](https://www.sandbox.thingplus.net) 로그인 + +### OAuth client 등록하기 +첫 번째 단계는 Thing+ Cloud 에 **OAuth client** 를 등록하는 것입니다. + +#### Step1. API 호출을 위한 HTTPS API 호출 도구 설치 + +OAuth Client 등록 API 호출을 위해 HTTPS API를 호출할 수 있는 도구가 필요합니다. +* [Google Chrome](https://www.google.co.kr/chrome/browser/desktop) : Thing+ Portal에 로그인할 때 사용합니다. +* [Postman](https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en) : 원하는 HTTPS API를 호출할 때 사용하는 Google Chrome App입니다. +* [Postman Interceptor](https://chrome.google.com/webstore/detail/postman-interceptor/aicmkgpgakddgnaphhhpliifpcfhicfo?hl=en) : Thing+ Portal에 로그인 했을 때 생성된 쿠키를 Postman에서 공유할 수 있도록 지원하는 Google Chrome Extension입니다. + +위의 도구를 사용하지 않더라도 Thing+ Portal에서 쿠키를 공유할 수 있는 다음과 같은 HTTPS POST API 도구를 사용하시면 됩니다. +* [Fiddler](http://www.telerik.com/fiddler) +* [DHC](https://client.restlet.com) + +#### Step2. Thing+ authClients API 호출하기 + +**Postman** 을 설치하셨다면 툴을 실행하고, **Postman Interceptor** 가 웹브라우저로부터 쿠키를 가져올 수 있도록 **On** 한 상태에서 설정할 값을 입력한 다음 API를 호출합니다. + +다른 HTTPS POST API 도구를 설치하셨다면 Thing+ Portal 에 사용자 계정을 로그인 한 뒤 다음 API 를 호출합니다. + +[Thing+ authClients API 를 자세히 알아보려면 이 문서를 참조하세요.](https://thingplus.api-docs.io/2.0/oauth2/create-authclients) + +[Postman 사용에 도움을 얻으려면 Getting Started with the Thing+ REST APIs 이 문서를 참조하십시오.](./GettingStarted_authToken.md) + +> Commercial +``` +URI : https://api.thingplus.net/v2/authClients +Method : POST +Content-Type : application/json +``` + +> Sandbox +``` +URI : https://api.sandbox.thingplus.net/v2/authClients +Method : POST +Content-Type : application/json +``` + +> Body 파라미터 + +|파라미터|설명 +|---|---- +|name|**(필수)** 사용자 이름 +|reqId|**(필수)** 사용자 **OAuth client ID** (AccessToken 획득에 필요합니다.) +|clientSecret|**(필수)** 사용자 **OAuth client secret** (AccessToken 획득에 필요합니다.) +|scopes|**(필수)** client에 부여할 권한 **(권장 : user-profile-read, gateway-update, timeline-read, tag, rule-read, service-read)** + +> Body 예시 (JSON) +``` +{ + "name": "daligali", + "reqId": "daliworks", + "clientSecret": "gali1234", + "scopes": ["user-profile-read", "gateway-update", "timeline-read", "tag", "rule-read", "service-read", "site-read"] +} +``` + +추가 권한이 필요하신 경우 contact@thingplus.net 로 요청하시기 바랍니다. + +[scopes 에 대해 자세한 설명이 필요하시면 이 문서를 참조하십시오.](./AuthorizationScopes_kr.md) + +## 단계2-1. Thing+ OAuth2 인증 진행 - Authorization Code Grant +### Authorization Code Grant 방식으로 AccessToken 획득하기 +`AccessToken` 을 획득하기 위해 `Authorization Code` 가 필요합니다. Authorization Code 방식으로 획득한 `AccessToken` 은 **15일간 유효**합니다. 아래 지침을 따르십시오. + +[Thing+ OAuth2Token API 를 자세히 알아보려면 이 문서를 참조하세요.](https://thingplus.api-docs.io/2.0/oauth2/oauth2token) + +#### Step1. Authorization Code 획득 +웹 브라우저로 아래 URI 을 GET 하여 수락 후 redirect_uri Query에 부여된 `Authorization Code` 를 획득 합니다. + +> Commercial +``` +URI : https://api.thingplus.net/v2/oauth2/authorize?client_id={CLIENT_ID}&response_type=code&redirect_uri={REDIRECT_URI} +Method : GET +Example : https://api.thingplus.net/v2/oauth2/authorize?client_id=daliworks&response_type=code&redirect_uri=https://thingplus.net +``` + +> Sandbox +``` +URI : https://api.sandbox.thingplus.net/v2/oauth2/authorize?client_id={CLIENT_ID}&response_type=code&redirect_uri={REDIRECT_URI} +Method : GET +Example : https://api.sandbox.thingplus.net/v2/oauth2/authorize?client_id=daliworks&response_type=code&redirect_uri=https://thingplus.net +``` + +> URI Query 파라미터 + +|파라미터|설명 +|---|---- +|client_id|**(필수)** 등록한 OAuth client reqId +|response_type|**(필수)** "code" 를 사용 +|redirect_uri|**(필수)** Authorization Code 와 함께 redirect 될 URI + +> 사용자가 요청을 수락하면 URI 에 "code" 가 포함된 redirect_uri 사이트로 리디렉션됩니다. +``` +REDIRECT URI : {REDIRECT_URI}/?code={AUTHORIZATION_CODE} +Example : https://thingplus.net/?code=FKr1INPriNvGcMEC +``` + + Sandbox Thing+ Potal 에 로그인이 안되는 경우 **브라우저 쿠키를 삭제**하십시오. + +#### Step2. Authorization Code 로 AccessToken 획득 +다음 API를 이용하여 `AccessToken` 을 획득합니다. `Authorization Code` 는 **10분 간 유효**하며, `AccessToken` 을 획득하면 해당 `Authorization Code` 는 만료됩니다. +> Commercial +``` +URI : https://api.thingplus.net/v2/oauth2/token +Method : POST +Content-Type : x-www-form-urlencoded +``` + +> Sandbox +``` +URI : https://api.sandbox.thingplus.net/v2/oauth2/token +Method : POST +Content-Type : x-www-form-urlencoded +``` + +> Body 파라미터 + +|파라미터|설명 +|---|---- +|code|**(필수)** 획득한 **Authorization Code** +|client_id|**(필수)** 위에서 등록한 사용자 **OAuth client** +|client_secret|**(필수)** 위에서 등록한 사용자 **OAuth client secret** +|redirect_uri|**(필수)** Redirect 할 URI (원하는 URI 를 쓰시면 됩니다.) +|grant_type|**(필수)** authorization_code **(주의 : 문자열을 그대로 입력합니다.)** + +> x-www-form-urlencoded POST body 예시 +``` +code : FKr1INPriNvGcMEC +client_id : daliworks +client_secret : gali1234 +redirect_uri : https://thingplus.net +grant_type : authorization_code +``` + +> 획득한 `AccessToken` 예시 (JSON) +``` +{ + "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiI3MzY3IiwiY2xpZW50SWQiOiJkYWxpd29ya3M1MTIiLCJpYXQiOjE1MDc3MTA4NDYsImV4cCI6MTUwOTAwNjg0Nn0.wmr6MdEDJo5qk4i5EYn34epxRmn9BQq_Nt74AfNCSMc", + "token_type": "Bearer" +} +``` + +## 단계2-2. Thing+ OAuth2 인증 진행 - Resource Owner Password Credentials Grant +### Resource Owner Password Credentials Grant 방식으로 AccessToken 획득하기 +`AccessToken` 을 획득하기 위해 Thing+ Portal 사용자 암호로부터 생성한 `MD5 hash` 가 필요합니다. Resource Owner Password Credentials 방식으로 획득한 `AccessToken`은 **90일간 유효**합니다. 아래 지침을 따르십시오. + +[Thing+ OAuth2Token API 를 자세히 알아보려면 이 문서를 참조하세요.](https://thingplus.api-docs.io/2.0/oauth2/oauth2token-1) + +[MD5 hash 에 대한 자세한 내용은 이 웹페이지를 참조하십시오.](https://github.com/blueimp/JavaScript-MD5) + +#### Step1. MD5 hash 생성 +Mac OS X 또는 Linux 에서 아래 명령어를 이용해 `MD5 hash` 를 생성합니다. + +> Mac OS X +``` +$ echo -n Your_Password | md5 +bbff9cb88fcd3e847923e1bd96aa578f +``` + +> Linux +``` +$ echo -n Your_Password | md5sum +bbff9cb88fcd3e847923e1bd96aa578f +``` + +#### Step2. MD5 hash 로 AccessToken 획득 +다음 API를 이용하여 `AccessToken` 을 획득합니다. +> Commercial +``` +URI : https://api.thingplus.net/v2/oauth2/token +Method : POST +Content-Type : x-www-form-urlencoded +``` + +> Sandbox +``` +URI : https://api.sandbox.thingplus.net/v2/oauth2/token +Method : POST +Content-Type : x-www-form-urlencoded +``` + +> Body 파라미터 + +|파라미터|설명 +|---|---- +|grant_type|**(필수)** password **(주의 : 문자열을 그대로 입력합니다.)** +|client_id|**(필수)** 위에서 등록한 사용자 **OAuth client** +|client_secret|**(필수)** 위에서 등록한 사용자 **OAuth client secret** +|username|**(필수)** Thing+ Portal 에 **등록한 아이디**를 입력합니다. (이메일 주소가 아닙니다.) +|password|**(필수)** Thing+ Portal 사용자 암호로 생성한 **MD5 Hash** 를 입력합니다. + +> x-www-form-urlencoded POST body 예시 +``` +grant_type : password +client_id : daliworks +client_secret : gali1234 +username : daligali +password : bbff9cb88fcd3e847923e1bd96aa578f +``` + +> 획득한 `AccessToken` 예시 (JSON) +``` +{ + "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiI3MzY3IiwiY2xpZW50SWQiOiJkYWxpd29ya3M1MTIyIiwiaWF0IjoxNTA3Nzk1NjM4LCJleHAiOjE1MTU1NzE2Mzh9.pejzZn8CgsXrbL9J1c1fd_hTYKdoSPmOk0HCAKC7cSc", + "token_type": "Bearer" +} +``` + +## 단계3. Thing+ OAuth2 인증 진행 - Application Header +### Header 에 AccessToken 등록 +`AccessToken` 은 Thing+ REST API 를 호출할 때 권한 인증을 위해 **Header**에 반드시 있어야합니다. + +Header 에 **Authorization 필드**를 추가하고, **token_type**과 획득한 **access_token** 값을 아래와 같이 입력해주십시오. +``` +Authorization : Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiI3MzY3IiwiY2xpZW50SWQiOiJkYWxpd29ya3M1MTIiLCJpYXQiOjE1MDc3MTA4NDYsImV4cCI6MTUwOTAwNjg0Nn0.wmr6MdEDJo5qk4i5EYn34epxRmn9BQq_Nt74AfNCSMc +``` -## 사전 준비 -1. API를 테스트 하기 위한 툴 - - Postman: https://www.getpostman.com/ - - Fiddler: http://www.telerik.com/fiddler - - DHC: https://client.restlet.com/ -2. authClient 생성 - - api guide의 authClients 항목을 참조하여 authClient를 생성 - - 생성된 authClient 에 대하여 별도 유지/관리 필요 - - authClient 생성시 사용할 `scope`는 [여기](./OAuth2.md#scopes)를 참조 - - -## [Authorization Code 방식](./OAuth2.md#authorization-code-grant-or-web-server) -특정 user의 지정된 권한에 대한 위임을 받는다. -별도의 앱/웹에서 유저별로 관리가 필요할 경우 사용한다. - -추가 요청시 oAuth Login 페이지에 대한 customizing 이 가능하다. - -1. oauth2/authorize API를 통해 thing+ page 이동 -1. 로그인이 되어 있지 않을경우 Login. 이미 로그인이 되어있다면 다음 단계로 -1. Redirect 된 URL의 query에서 code 를 획득 -1. oauth2/token API를 통해 access_token 획득 - * 해당 토큰은 15일간 유효하며 유지/관리가 필요하다 -1. 획득한 토큰을 API에서 이용한다 - * Request Header 에 Authorization 필드 추가 - * Value에 token API response의 Token_Type과 access_token 활용 값을 채움 - * {token_type} {access_token} 형태 - * ```Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiIyIiwiY2xpZW50SWQiOiJzd2l0aGVyIiwiaWF0IjoxNDkxMjc1MTMxLCJleHAiOjE0OTI1NzExMzF9.bG1pusWH5pwJ4_BxQ-v0tmgkqMix3H82uUSxZycBWOo``` -1. 위의 과정을 이용하여 개발한다 - - - -## [Resource Owner Password Credentials 방식](./OAuth2.md#resource-owner-password-credentials-grant) -serviceAdmin 의 권한으로 서비스내 리소스를 접근한다. - -1. oauth2/token API를 통해 access_token 획득 - * 해당 토큰은 90일간 유효하며 유지/관리가 필요하다 -1. 획득한 토큰을 API에서 이용한다 - * Request Header 에 Authorization 필드 추가 - * Value에 token API response의 Token_Type과 access_token 활용 값을 채움 - * {token_type} {access_token} 형태 - * ```Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiIyIiwiY2xpZW50SWQiOiJzd2l0aGVyIiwiaWF0IjoxNDkxMjc1MTMxLCJleHAiOjE0OTI1NzExMzF9.bG1pusWH5pwJ4_BxQ-v0tmgkqMix3H82uUSxZycBWOo``` -1. 위의 과정을 이용하여 개발한다 -1. serviceAdmin으로 리소스 접근시 여러 사용자의 데이터가 접근됨으로 해당 기능을 고려하여 개발한다 - -## 상세 설명 -[Link](./OAuth2.md) +[Thing+ OAuth2 API Errors 에 대한 자세한 설명을 보시려면 이 문서를 참조하십시오.](./AuthorizationErrors_kr.md) +기타 추가 지원이 필요하시면 contact@thingplus.net 로 요청하시기 바랍니다. 감사합니다.