DDWS( 디지털배포웹서비스 ) API 인증안내서

Transcription

1 DDWS( 디지털배포웹서비스 ) API 인증안내서

2 목차 개정내역 Autodesk 를통한 API 인증 개요 DDWS 디지털서명및액세스토큰생성 예 액세스토큰을생성하기위한 OAuth 호출 액세스토큰을사용하여 API 호출 오류코드 Postman 을통한연결 Postman 설치 Postman 을통해 DDWS API 액세스 액세스토큰생성 API 서비스액세스테스트 OAuth 및서비스 API 호출을위한헤더생성... 16

3 개정내역 버전 날짜 작성자 주석 /10/22 AR 섹션 요청 URL 업데이트 /03/04 MG 섹션 1.1 업데이트 /04/30 MG 형식 /12/03 AR 섹션 및 의끝점을 에서 로수정 토큰서명형식추가 섹션 1.2 업데이트 토큰및 API 서명형식추가 섹션 업데이트 라이센스가져오기를위한서명정보추가 에서 으로번호표기수정 /04/19 PL 섹션 2 의모든내용을편집및개정 /08/10 FX 포함된유틸리티 DDWS-Client 가서명을생성하는데 SHA-1 알고리즘대신 SHA-256 을사용해야한다고 업데이트했습니다.

4 1 Autodesk 를통한 API 인증 1.1 개요제공되는인증 API 는 Autodesk API 서비스에대해원치않는무단액세스로부터 DDWS( 디지털배포웹서비스 ) 를보호합니다. 디지털서명을통해호출인증을확인하고각파트너가 2 레그 OAuth 2.0 을통해호출할수있는 API 리소스의범위를관리할수있도록합니다. DDWS API 서비스는 OAuth 2.0 메커니즘을통해인증되도록설계되었습니다. 모든 API 요청은인증을위해디지털서명을포함해야합니다. 파트너는요청마다서명을생성하고 DDWS API 를사용할때헤더에포함해야합니다. 프록시레이어내에서액세스토큰생성은다음파트너매개변수의검증과관련되어있습니다. 1. 기본 64 인코딩자격증명 2. 시간스탬프 (5 분이내 ) 3. 생성된서명 OAuth 요청의인증헤더에는콜론으로구분된클라이언트 ID 및클라이언트비밀문자열의 Base 64 인코딩값이있어야합니다. 문자열의인코딩값은다음과같이계산됩니다. client_id client_secret 인코딩값 3PPWWSSSS4SSffssSSTTLLrr2ffbb1ttaaaaQQ6JJllwwMMooMMaabbggoo mmhcc90ttssiiff2mmee2ffmmff client_id:client_secret 3PPWWSSSS4SSffssSSTTLLrr2ffbb1ttaaaaQQ6JJllwwMMooMMaabbggoo:mmhcc90ttssIIff2mmee2ffMMFF 기본 64 인코딩문자열은다음형식으로구성될수있습니다. Authorization Header = Concatenate( Basic, Base64Encode(Concatenate (client_id, :, client_secret))

5 결과적으로다음과같은기본 64 인코딩값이나타납니다. MM1BBXXUU1MM0UU2ZZzzUU1RRMMccjjJJmmYYjjFF0YYWWFFRRNNkkppssdd01vvTTWWFFiiZZ286bbWWhjjOOTTBB0cc0llmmMMmm1llMMmmZZNNRRgg == API 서비스를호출할때최초 OAuth 토큰생성호출로부터받은액세스토큰은베어러토큰으로각요청의인증헤더에포함되어야합니다. 참고 : 토큰은 15 분동안만유효합니다. " 갱신 " 토큰은제공되지않습니다. 새로운호출을통해새로운토큰을생성해야합니다. 1.2 DDWS 디지털서명및액세스토큰생성먼저다음에대한설명을제공합니다. 콜백 : 개발자포털에서응용프로그램을등록할때제출되는콜백 URL 클라이언트 ID: 응용프로그램을성공적으로등록한후개발자포털에서얻습니다. 고객키와동일한용어입니다. 시간스탬프 : 서명이생성된정확한시간 ( 초단위 ) timestamp = current Epoch Time (10 Digits) 액세스토큰 : 토큰을생성하기위한 OAuth 호출의응답에서얻음. 서명생성은 message_string 의표준기반 64 HMACSHA256 암호화와관련되어있습니다. 액세스토큰을생성하기위해 OAuth 끝점을호출하는경우질문의 message_string 에는다음값이표시된순서대로연속포함됩니다. 콜백 + 클라이언트 _id + 타임스탬프 signature = Base64Encode(HMACSHA256(Concatenate (callbackaddress, client_id, timestamp)) /orders/fulfillment 또는 /partner/test 등다른 API 서비스끝점을호출하는경우 message_string 에는다음값이표시된순서대로연속포함됩니다.

6 콜백 + 액세스토큰 + 시간스탬프 signature = Base64Encode(HMACSHA256(Concatenate (callbackaddress, Access_Token from the service(no bearer string here), timestamp)) 다음은 OAuth 호출에사용되는서명을생성하기위한 Python 스크립트의예입니다. 참고 : 여기에서사용된값은더미값입니다. 고유한서명을생성하려면고유한 클라이언트 ID, 클라이언트비밀등을제공해야합니다. import re import time import calendar from base64 import b64encode from datetime import timedelta, datetime from hmac import HMAC import sys, os, base64, hashlib, hmac base_path = " timestamp = calendar.timegm(time.gmtime()) client_id = "2LDR5j0yG0PhW23PranLQ6JlwMoMabgo" client_secret = "op30uee2kdei2fmf" signed_signature = base64.b64encode(hmac.new(client_secret, base_path +client_id+ str(timestamp), hashlib.sha256).digest()) print("signed_signature-- >"+signed_signature) print("timestamp-- >"+str(timestamp)) API 서비스호출에필요한서명의경우, 위의스크립트를참조하여 client_id 값을 OAuth 호출에서받은액세스토큰으로전환하십시오.

7 1.3 예 액세스토큰을생성하기위한 OAuth 호출 사후요청은서명, 기본 64 인코딩자격증명및요청의헤더에위치한시간스탬프를사용하여끝점 /v2/oauth/generateaccesstoken 에서수행됩니다. 쿼리에권한유형이클라이언트자격증명임을명시합니다. JSON 응답에서질문의액세스토큰은 access_token 필드에위치합니다. 요청 POST autodesk.com/v2/oauth/generateaccesstoken?grant_type=client_credential s HTTP/1.1 Authorization: Basic MkxEUjVqMHlHMFBoVzIzUHJhbkxRNkpsd01vTWFiZ286b3AzMHVlZTJL== signature: pbfumincypcpqrxenehq6skc+84= timestamp: 응답 HTTP/ OK Content-Type: application/json Content-Length: 523 Connection: keep-alive { "access_token" : "Q0K4S7iVJnuCVYP9ydARATNBJLyn", "expires_in" : 899, "token_type" : "BearerToken" }

8 1.3.2 액세스토큰을사용하여 API 호출 아래에서는파트너가액세스토큰에필요한 API 호출을시뮬레이션하기위해사용할수있는끝점 /v1/partner/test 를사용합니다. 토큰정보를포함하는인증헤더가있는끝점을호출합니다. 또한참여, API 호출을위해생성된새로운서명및서명에사용되는시간스탬프에서받은 CSN( 고객특정번호 ) 가헤더에포함됩니다. 호출이 Autodesk 시스템에도달했음을알리기위해상태확인응답이반환됩니다. 요청 GET HTTP/1.1 Authorization: Bearer sdfh89rd4idj29ie9dfjed29d3dj CSN: signature: yfm0ddyhqnq2emfwicxdxpdpgef3y+ogofggjfticjo= timestamp: 응답 HTTP/ OK Content-Type: application/json Connection: keep-alive { status : ok } 특별히 getlicense 에대해서만헤더에두개의매개변수가더있어야합니다. 1. REQUESTINGAPPLICATIONNAME: 항상 partner 와같아야합니다. 2. EFFECTIVEUSERID: 파트너에대해생성된 sysid_xxxxx 와같아야합니다 (Autodesk 팀이이값을생성합니다. 요청을보내려면 partner.integration.team@autodesk.com 에문의하십시오 ).

9 1.4 오류코드 HTTP 상태코드 Autodesk 오류코드 내부메시지 확인 작성 수정되지않음 잘못된요청 오류 : 4000 정확하지않거나잘못된요청 인증되지않음 오류 : 4100 요청에 CSN 이전달되지않았습니다 인증되지않음 오류 : 4101 요청에 HMAC 서명이전달되지않았습니다 인증되지않음 오류 : 4102 요청에 HMAC 클라이언트 ID 가전달되지않았습니다 인증되지않음 오류 : 4103 요청에 HMAC 시간스탬프가전달되지않았습니다 인증되지않음 오류 : 4104 요청에인증이전달되지않았습니다 인증되지않음 오류 : 4105 유효하지않은토큰 인증되지않음 오류 : 4106 토큰생성중에문제가발생했습니다 금지 오류 : 4301 HMAC 서명이전달되었지만올바르지않습니다 금지 오류 : 4302 HMAC 시간스탬프가전달되었지만올바르지않습니다 금지 오류 : 4300 CSN 이전달되었지만올바르지않습니다.

10 2 Postman 을통한연결 Chrome 응용프로그램인 Postman 을사용하여 Autodesk API 에연결하고, 상호작용을 테스트할수있습니다. 다음섹션에서는 Postman 을설치하고사용하여 Autodesk API 를 인증하고, 상호작용하는방법을자세히설명합니다. 2.1 Postman 설치 아래단계에따라패키지앱버전의 Postman 을설치하십시오. i. Chrome 브라우저를열고 으로이동합니다. ii. 시스템에맞는플랫폼을다운로드합니다. iii. Chrome Web Store 가열립니다. 이제 CHROME 에추가버튼을클릭합니다.

11 iv. 설치중에 Postman 이로컬컴퓨터및기타웹사이트에액세스할것이라는경고가 표시됩니다. 추가버튼을클릭합니다. v. 설치하고나면 Postman 을 Chrome 응용프로그램으로사용할수있습니다.

12 2.2 Postman 을통해 DDWS API 액세스 서비스액세스프로세스의한과정으로파트너는다음단계를수행해야합니다. OAuth 특정호출에대한서명및기타헤더상세정보생성 OAuth 끝점을호출하여액세스토큰생성 API 특정호출에대한서명생성 필수헤더 ( 서명및액세스토큰등 ) 로 DDWS API 액세스 액세스토큰생성 DDWS API 에액세스하려면요청시액세스토큰을제공해야합니다. 액세스토큰생성프로세스는유효한클라이언트자격증명, 서명된서명및타임스탬프의검증과관련되어있습니다. 클라이언트자격증명은참여프로세스중에생성된유효한자격증명이어야합니다. 액세스토큰생성단계 : i. Chrome 앱실행기또는 Chrome 브라우저를통해 Postman 을엽니다. a. Postman 아이콘을선택하여앱을실행합니다.

13 b. Chrome 브라우저를열고 chrome://apps/ 로이동합니다. 1. Chrome Web Store 가열립니다. Postman 아이콘을클릭하여 앱을실행합니다. ii. Postman REST Builder 페이지에서여기에요청 URL 입력필드에 OAuth URL grant_type=client_credentials 를입력합니다. iii. API 에대한방법을 POST 로선택합니다. iv. 다음헤더매개변수를제공하고보내기버튼을클릭합니다. 헤더값을생성하려면섹션 의지침대로수행하십시오. 헤더이름 : Authorization, 값 : Basic < 클라이언트자격증명의 Base64 인코딩 > 헤더이름 : signature, 값 : < 서명 >

14 헤더이름 : timestamp, 값 : < 타임스탬프 > v. 액세스토큰이포함된응답을받습니다. 액세스토큰값을저장합니다. 이값은 APIs 액세스를인증및승인하는데사용되며, 액세스토큰은 15 분동안만유효합니다. 토큰이만료되면새토큰을생성해야합니다 API 서비스액세스테스트 아래에서는파트너가핸드쉐이킹을테스트하기위해호출할수있는일반끝점을표시합니다. 파트너가 Status OK 응답을받으면백엔드와의통신이성공했음을의미합니다. 아래예는끝점과의성공적인통신을위해인증및권한부여에필요한헤더의형식지정을보여줍니다. 각 API 서비스를호출하는방법을보려면해당서비스참조안내서를참조하십시오. i. 여기에요청 URL 입력필드에 API URL 를입력합니다. ii. API 에대한방법을 GET 로선택합니다.

15 iii. 다음헤더매개변수를제공하고보내기버튼을클릭합니다. 헤더값을생성하려면섹션 의지침대로수행하십시오. 헤더이름 : CSN, 값 : < 파트너 CSN> 헤더이름 : Authorization, 값 : Bearer < 액세스 _ 토큰 > 헤더이름 : signature, 값 : < 서명 > 헤더이름 : timestamp, 값 : < 타임스탬프 > iv. 호출에성공하면시스템으로부터 Status: OK 메시지가수신됩니다.

16 2.2.3 OAuth 및서비스 API 호출을위한헤더생성 Autodesk 에서는 OAuth 호출및서비스 API 호출모두에대해타임스탬프및서명과같은헤더를생성하는두개의옵션을제공합니다. 파트너는 GUI 유틸리티를사용하거나제공된 Python 스크립트를온라인으로실행할수있습니다. 다음섹션에서는이러한옵션을자세히설명합니다. 옵션 1: Autodesk 가개발한 GUI 유틸리티를사용하여서명생성 GUI 유틸리티를사용하여서명을생성하려면아래단계를따르십시오. i. 다음 DDWS-Client.zip 폴더를로컬시스템에저장합니다. DDWS-Client.zip ii. 시스템에 DDWS-Client.zip 파일의압축을풉니다. iii. DDWS-Client.html 파일을 Chrome 브라우저를사용하여엽니다. iv. OAuth Endpoints 섹션아래에서클라이언트 ID, 클라이언트비밀및콜백 URL( 참여프로세스의일부로설정및수신된 ) 을제공합니다. 생성버튼을 클릭합니다. v. 그러면 OAuth 요청의헤더에필요한유효한권한, 서명및타임스탬프값이 생성됩니다. 서명은 5 분동안만유효합니다.

17 액세스토큰이생성되면서비스 API 호출에필요한서명을생성하기위해유사한단계집합을 수행해야합니다. i. DDWS-Client.html 의 API Endpoint 섹션에서 OAuth 응답 ( 섹션 v) 으로부터 수신된액세스토큰, 클라이언트비밀및콜백 URL 을제공하고생성버튼을 클릭하십시오. ii. 그러면서비스 API 요청의헤더에필요한유효한서명및타임스탬프값이 생성됩니다. 서명은 5 분동안만유효합니다.

18 옵션 2: Python 스크립트를온라인에서실행하여서명생성 Python 스크립트를온라인에서실행하여서명을생성하려면아래단계를따르십시오. i. 로이동합니다. 다음과 같은창이열립니다. ii. OAuth 끝점을호출하려면 main.py 를다음과같이신중하게변경하고, client_id, client_secret 및 callback_url( 아래스키마에서노란색강조표시로표시되어있음 ) 을참여프로세스도중설정및수신된값으로대체합니다. 아래스키마의값은더미값입니다. 대체원본 : # Hello World program in Python print "Hello World!\n"

19 대체대상 : import re import time import calendar from base64 import b64encode from datetime import timedelta, datetime from hmac import HMAC import sys, os, base64, hashlib, hmac callback_url = " timestamp = calendar.timegm(time.gmtime()) client_id = "2LDR5j0yG0PhW23PranLQ6JlwMoMabgo" client_secret = "op30uee2kdei2fmf" signed_signature = base64.b64encode(hmac.new(client_secret, callback_url +client_id+ str(timestamp), hashlib.sha256).digest()) s = client_id + ":" + client_secret b64_string = base64.b64encode(s) print("b64 string--- " + b64_string) print("signed_signature-- >"+signed_signature) print("timestamp-- >"+str(timestamp)) iii. 실행버튼을클릭합니다. 그러면서명, 타임스탬프및인증헤더가생성됩니다. 서명은 5 분동안만유효합니다. 이러한값은 OAuth 요청의헤더에사용됩니다. iv. 서비스 API 끝점을호출하려면위스크립트의 client_id 값을 OAuth 응답 ( 섹션 v) 의수신된액세스토큰값으로바꿉니다. 생성된서명및타임스탬프는다음 5 분동안 API 요청에유효합니다.