From 755b3e4d44bc90fb65e5ae40a098e88c3714969d Mon Sep 17 00:00:00 2001 From: khujin Date: Fri, 29 Oct 2021 09:39:20 +0900 Subject: [PATCH] =?UTF-8?q?deeplink=20=EA=B7=9C=EA=B2=A9=20=EC=B6=94?= =?UTF-8?q?=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/index.md | 2 +- docs/initial_deeplink.md | 119 +++++++++++++++++++++++++++++++ docs/open_api_auto_connection.md | 30 +++++--- docs/open_api_message.md | 3 +- docs/web_console_guide.md | 11 ++- mkdocs.yml | 7 +- 6 files changed, 150 insertions(+), 22 deletions(-) create mode 100644 docs/initial_deeplink.md diff --git a/docs/index.md b/docs/index.md index 995215c..d17be13 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -Document version : v2.1.1 (last updated 2021-10-15) +Document version : v2.1.2 (last updated 2021-10-28) Welcome to initial DID Platform Developer Site =============== diff --git a/docs/initial_deeplink.md b/docs/initial_deeplink.md new file mode 100644 index 0000000..2938f14 --- /dev/null +++ b/docs/initial_deeplink.md @@ -0,0 +1,119 @@ +initial App2App Deeplink Spec +================ + +
+

note

+

initial은 App to App 호출을 위한 Deeplink 규격을 제공합니다.

+
+ +
+ +### Deeplink 연동 Spec + +initial의 deeplink는 등록된 기관 및 증명서에 한해서 동작합니다.
+아래와 같은 scheme으로 동작합니다. + +- Scheme : initial://reqService?**{{Parameter}}** + +#### Deeplink Parameters + + Parameter | M / O | Type | Value | Description + --- | :---: | :---: | :---: | --- + process | 필수 | string | I
V
E
O
F | I - Issue, Credential 발급
V - Verify, Credential 제출/검증
E - 행안부 전자문서 제출
O - OCR scan 문서 제출
F - 추가서류 제출 + ynCloud | 필수 | String | Y
N | Cloud Agent 기관 여부 (Y/N) + orgName | 옵션 | string | 기관명 | 등록된 기관명 + svcPublicDID | 필수 | String | did:ssw:{{did}}| 기관의 PublicDID + credDefId | 옵션 | String | cred_def_id | 증명서 ID + seq | 필수 | String | 고객구분자 | 고객구분자 / 신청번호 + govDocs | 옵션 | String | 코드 | 전자정부 문서 제출 목록
process=E일 경우 필수 + govWalletAdd | 옵션 | String | 지갑 주소 | 제출할 곳의 전자정부 지갑 주소
process=E일 경우 필수 + masking | 옵션 | String | Y
N | 마스킹 처리 여부 + submitUrl | 옵션 | url | URL | 제출 완료를 위한 URL + invitationUrl | 필수 | URL | URL | 등록된 invitation url + invitation | 필수 | string | invitation json | create-invitation으로 생성된 json + callback | 옵션 | String | URL |제출완료 후 복귀할 deeplink URL + + + - sample : 발급요청 / Cloud Agent 기관 / Public DID / 발행할 Cree_Def_ID / invitation + + +`initial://reqService?process=I&ynCloud=Y&svcPublicDID=did:ssw:DrLbXFSao4Vo8gMfjxPxU1&credDefId=DrLbXFSao4Vo8gMfjxPxU1:3:CL:1617698238:81df0010-62b4-45b1-bd00-8d0ad74762fd&invitation=https://dev-console.myinitial.io/agent/endpoint?c_i=eyJAdHlwZSI6ICJkaWQ6c292OkJ6Q2JzTlloTXJqSGlxWkRUVUFTSGc7c3BlYy9jb25uZWN0aW9ucy8xLjAvaW52aXRhdGlvbiIsICJAaWQiOiAiNWQ5NDI5MTgtMDNjNC00ZTQyLTljMDgtMzZiNGM1YTY0ZDMxIiwgImRpZCI6ICJkaWQ6c3N3OkRyTGJYRlNhbzRWbzhnTWZqeFB4VTEiLCAiaW1hZ2VVcmwiOiAiaHR0cHM6Ly9rci5vYmplY3QubmNsb3Vkc3RvcmFnZS5jb20vZGV2LWltYWdlLWZpbGUvZDQxZDhjZDlfYTMyODYxZTdfMTYyNzg2NjUzMiIsICJsYWJlbCI6ICIoXHVjMGQ4XHVkNTBjKSBTS1QgXHVkMWEwXHVjNzc1XHVjMTMxXHVjODAxIFx1Yzk5ZFx1YmE4NVx1YzExYyJ9` + + +#### Parameter 상세 설명 및 예시 + +##### process + +- process=VE : 연결 완료되면 Verify를 요청하고, 완료되면 행안부 전자문서를 제출 요청 +- process=I : 연결 완료 후 발행 요청 + +##### ynCloud + +- ynCloud=Y : Cloud Agent 사용 기관임을 명시 +- ynCloud=N : Cloud Agent 사용 기관과 다른 방식으로 동작 + +##### orgName + +- orgName=skt : 회사명 + +##### svcPublicDID + +해당 기관의 public DID를 did:ssw method를 포함해서 입력 + +- svcPublicDID=did:ssw:DrLbXFSao4Vo8gMfjxPxU1 + +##### credDefId + +발급/검증을 위한 target cred_def_id를 입력 + +- credDefId=DrLbXFSao4Vo8gMfjxPxU1:3:CL:1617698238:81df0010-62b4-45b1-bd00-8d0ad74762fd + +##### seq + +- seq=1038555586867 + +##### govDocs + +전자정부 문서 제출 목록. 1개 이상 제출 시 "_"로 구분 + + - govDocs=30000200076_30000100010 + +문서 코드표 (update 예정) + +##### govWalletAdd + +기관의 수취용 전자정부 지갑 주소 + +- govWalletAdd=2V3mcLB7ieZ1Y7XcdBW3rYPcvu6sfEupULzqKaN + + +##### govWalletAdd + +민감정보 마스킹 + +- masking=Y + +##### submitUrl(작성 중) + +제출 완료 되면 아래와 같은 message를 webhook으로 전달 한다. + +Key | M / O | Type | Value | Description +--- | :---: | :---: | :---: | --- + +##### invitationUrl + +connection에 사용하기 위한 invitation-url을 전달한다. + +invitationUrl=https://issue.sktelecom.com/invitation-url + +##### invitation + +invitation-url통해서 생성된 값을 전달한다. invitation-url public open이 불가능한 기관에서 사용할 수 있다. + +`invitationUrl=https://dev-console.myinitial.io/agent/endpoint?c_i=eyJAdHlwZSI6ICJkaWQ6c292OkJ6Q2JzTlloTXJqSGlxWkRUVUFTSGc7c3BlYy9jb25uZWN0aW9ucy8xLjAvaW52aXRhdGlvbiIsICJAaWQiOiAiNWQ5NDI5MTgtMDNjNC00ZTQyLTljMDgtMzZiNGM1YTY0ZDMxIiwgImRpZCI6ICJkaWQ6c3N3OkRyTGJYRlNhbzRWbzhnTWZqeFB4VTEiLCAiaW1hZ2VVcmwiOiAiaHR0cHM6Ly9rci5vYmplY3QubmNsb3Vkc3RvcmFnZS5jb20vZGV2LWltYWdlLWZpbGUvZDQxZDhjZDlfYTMyODYxZTdfMTYyNzg2NjUzMiIsICJsYWJlbCI6ICIoXHVjMGQ4XHVkNTBjKSBTS1QgXHVkMWEwXHVjNzc1XHVjMTMxXHVjODAxIFx1Yzk5ZFx1YmE4NVx1YzExYyJ9` + +##### callback + +발행/검증 완료 후 복귀한 url 주소이다. + +- callback=initial://mainPage \ No newline at end of file diff --git a/docs/open_api_auto_connection.md b/docs/open_api_auto_connection.md index ee424f7..c938a96 100644 --- a/docs/open_api_auto_connection.md +++ b/docs/open_api_auto_connection.md @@ -185,21 +185,29 @@ curl -X 'POST' \ 2. [deeplink] App to App 요청 - Scheme : initial://reqService?**{{Parameter}}** - Parameter | M / O | Value | Description - --- | :---: | :---: | --- - process | 필수 | string | I - Issue, Credential 발급
V - Verify, Credential 제출/검증 - ynCloud | 필수 | string | Cloud Agent 기관 여부 - orgName | 옵션 | string | 기관명 - svcPublicDID | 필수 | String |Issuer or verifier의 PublicDID - nonce | 옵션 | String | Issuer or verifier의 nonce - credDefId | 옵션 | String | Issuer or verifier의 증명서 ID - invitation | 필수 | URL | invitation-url - callback | 옵션 | String | 제출완료 후 복귀할 deeplink URL + Parameter | M / O | Type | Value | Description + --- | :---: | :---: | :---: | --- + process | 필수 | string | I
V
E
O
F | I - Issue, Credential 발급
V - Verify, Credential 제출/검증
E - 행안부 전자문서 제출
O - OCR scan 문서 제출
F - 추가서류 제출 + ynCloud | 필수 | String | Y
N | Cloud Agent 기관 여부 (Y/N) + orgName | 옵션 | string | 기관명 | 등록된 기관명 + svcPublicDID | 필수 | String | did:ssw:{{did}}| 기관의 PublicDID + credDefId | 옵션 | String | cred_def_id | 증명서 ID + seq | 필수 | String | 고객구분자 | 고객구분자 / 신청번호 + govDocs | 옵션 | String | 코드 | 전자정부 문서 제출 목록
process=E일 경우 필수 + govWalletAdd | 옵션 | String | 지갑 주소 | 제출할 곳의 전자정부 지갑 주소
process=E일 경우 필수 + masking | 옵션 | String | Y
N | 마스킹 처리 여부 + submitUrl | 옵션 | url | URL | 제출 완료를 위한 URL + invitationUrl | 필수 | URL | URL | 등록된 invitation url + invitation | 필수 | string | invitation json | create-invitation으로 생성된 json + callback | 옵션 | String | URL |제출완료 후 복귀할 deeplink URL - sample : 발급요청 / Cloud Agent 기관 / Public DID / 발행할 Cree_Def_ID / invitation url - `initial://reqService?process=I&ynCloud=Y&svcPublicDID=DrLbXFSao4Vo8gMfjxPxU1&credDefId=DrLbXFSao4Vo8gMfjxPxU1:3:CL:1617698238:81df0010-62b4-45b1-bd00-8d0ad74762fd&invitation=https://dev-console.myinitial.io/agent/endpoint?c_i=eyJAdHlwZSI6ICJkaWQ6c292OkJ6Q2JzTlloTXJqSGlxWkRUVUFTSGc7c3BlYy9jb25uZWN0aW9ucy8xLjAvaW52aXRhdGlvbiIsICJAaWQiOiAiNWQ5NDI5MTgtMDNjNC00ZTQyLTljMDgtMzZiNGM1YTY0ZDMxIiwgImRpZCI6ICJkaWQ6c3N3OkRyTGJYRlNhbzRWbzhnTWZqeFB4VTEiLCAiaW1hZ2VVcmwiOiAiaHR0cHM6Ly9rci5vYmplY3QubmNsb3Vkc3RvcmFnZS5jb20vZGV2LWltYWdlLWZpbGUvZDQxZDhjZDlfYTMyODYxZTdfMTYyNzg2NjUzMiIsICJsYWJlbCI6ICIoXHVjMGQ4XHVkNTBjKSBTS1QgXHVkMWEwXHVjNzc1XHVjMTMxXHVjODAxIFx1Yzk5ZFx1YmE4NVx1YzExYyJ9` + +`initial://reqService?process=I&ynCloud=Y&svcPublicDID=DrLbXFSao4Vo8gMfjxPxU1&credDefId=DrLbXFSao4Vo8gMfjxPxU1:3:CL:1617698238:81df0010-62b4-45b1-bd00-8d0ad74762fd&invitation=https://dev-console.myinitial.io/agent/endpoint?c_i=eyJAdHlwZSI6ICJkaWQ6c292OkJ6Q2JzTlloTXJqSGlxWkRUVUFTSGc7c3BlYy9jb25uZWN0aW9ucy8xLjAvaW52aXRhdGlvbiIsICJAaWQiOiAiNWQ5NDI5MTgtMDNjNC00ZTQyLTljMDgtMzZiNGM1YTY0ZDMxIiwgImRpZCI6ICJkaWQ6c3N3OkRyTGJYRlNhbzRWbzhnTWZqeFB4VTEiLCAiaW1hZ2VVcmwiOiAiaHR0cHM6Ly9rci5vYmplY3QubmNsb3Vkc3RvcmFnZS5jb20vZGV2LWltYWdlLWZpbGUvZDQxZDhjZDlfYTMyODYxZTdfMTYyNzg2NjUzMiIsICJsYWJlbCI6ICIoXHVjMGQ4XHVkNTBjKSBTS1QgXHVkMWEwXHVjNzc1XHVjMTMxXHVjODAxIFx1Yzk5ZFx1YmE4NVx1YzExYyJ9` + + 3. [QR code] - 위 Deeplink를 QR code 생성하여 사용자 scan diff --git a/docs/open_api_message.md b/docs/open_api_message.md index bb45642..b3539af 100644 --- a/docs/open_api_message.md +++ b/docs/open_api_message.md @@ -143,7 +143,8 @@ STEP1에서 설명한 {{본문}}에 다음의 규격을 사용하면 App에서 "content":{ "message_code":"{{code}}", "message_main":"{{main message}}", - "message_sub":"{{sub message}}" + "message_sub":"{{sub message}}", + "button":["확인","취소"] } } ``` diff --git a/docs/web_console_guide.md b/docs/web_console_guide.md index d70f14c..559bf95 100644 --- a/docs/web_console_guide.md +++ b/docs/web_console_guide.md @@ -3,12 +3,11 @@ ![platform arch](img/initial_platform_architecture.png) ## 기관 참여자 구현/개발이 필요 항목 -위 그림을 참고하여 기관사용자 영역의 3개 항목에 대해서 구현 필요 +기관은 위 그림을 참고하여 Cloud Agent와 연동을 위한 Controller 개발이 필요하다. -1. 연결(Connection)요청 API -2. DID Agent API 사용위한 Controller -3. Event 수신 Webhook API -4. 참여사 개인정보 수집 및 이용 동의서 전달 +1. initial App과 최초 통신을 위한 연결(Connection)요청 API +2. Cloud Agent API 사용위한 Controller +3. Event 수신 Webhook controller ### 1. initial Console 가입 및 기관 생성 - initial console 가입을 진행하고, Master 권한 신청 및 기관 생성을 진행한다. @@ -104,7 +103,7 @@ https://dev-console.myinitial.io/agent/endpoint?c_i=eyJAdHlwZSI6ICJkaWQ6c292OkJ6
-### 6. Webhook API 개발 안내 +### 6. Webhook controller 개발 안내 - initial DID Platform의 DID Agent는 Event Driven(이벤트 구동형) 방식으로 기관, 사용자는 Event를 받을 수 있는 Webhook API를 개발하고 url 등록해아 한다. - 처리결과를 받기 위한 기관 사용자의 Webhook URL은 기관정보에 필수 등록해야 합니다. e.g)https://domain.com/webhooks - Webhook 서버의 API Key는 보안 강화를 위한 선택 사항입니다. https://domain.com/webhooks#org-api-key 와 같이 입력하시면 header의 x-api-key 항목에 값으로 "org-api-key"를 함께 전송합니다. diff --git a/mkdocs.yml b/mkdocs.yml index cd7b2a5..ccc1b5b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -38,6 +38,7 @@ nav: - 'Schema & Credential ID 등록': 'open_api_schema_creddef.md' # - 'Manual Credential Issue': 'm_credential.md' - 'Revocation': 'open_api_revocation.md' + - 'initial Deeplink' : 'initial_deeplink.md' - 'Reference - Demo Samples' : # - 'DID VCX Java Demo' : 'demo.md' # - 'DID VCX NodeJS Demo': 'node_demo.md' @@ -46,8 +47,8 @@ nav: # - 'SDK API' : # - 'Java APIs' : 'java_api/java_api.md' # - 'iOS APIs' : 'ios_api/ios_api.md' - - 'Blockchain Node' : - - 'Blockchain Network' : 'blockchain.md' +# - 'Blockchain Node' : +# - 'Blockchain Network' : 'blockchain.md' plugins: @@ -68,4 +69,4 @@ theme: hljs_style : github extra: - version: 2.1.1 \ No newline at end of file + version: 2.1.2 \ No newline at end of file