From 2a5c3ce47f207a2818db1867a5fc414ec69ac591 Mon Sep 17 00:00:00 2001 From: Ian Costanzo Date: Wed, 4 Mar 2020 17:15:17 -0700 Subject: [PATCH 1/2] Separate 2 API docs Signed-off-by: Ian Costanzo --- demo/AriesOpenAPIDemo-mobile.md | 230 ++++++++++++++++++++++++++++++++ demo/AriesOpenAPIDemo.md | 202 ---------------------------- 2 files changed, 230 insertions(+), 202 deletions(-) create mode 100644 demo/AriesOpenAPIDemo-mobile.md diff --git a/demo/AriesOpenAPIDemo-mobile.md b/demo/AriesOpenAPIDemo-mobile.md new file mode 100644 index 0000000000..8f924f1e33 --- /dev/null +++ b/demo/AriesOpenAPIDemo-mobile.md @@ -0,0 +1,230 @@ +# Aries OpenAPI Demo + +You can use the Faber aca-py agent to issue credentials to a mobile wallet. To do this you need to run the Faber agent on a publicly accessible port (for example you can run the agent on Play With Docker), and you need a compatible wallet. One available wallet is the Streetcred Identity Agent, which is available on both iOS and Android, and you can read about it [here](https://github.com/bcgov/identity-kit-poc/blob/master/docs/GettingApp.md). + +# Contents + +- [Getting Started](#getting-started) +- [Running in a Browser](#running-in-a-browser) +- [Running in Docker](#running-in-docker) +- [Installing the Streetcred Agent](#installing-the-streetcred-agent) +- [Creating an Invitation](#creating-an-invitation) +- [Converting the Invitation to a QR Code](#converting-the-invitation-to-a-qr-code) +- [Accepting the Invitation with Streetcred](#accepting-the-invitation-with-streetcred) +- [Accepting Streetcred's connection request](#accepting-streetcreds-connection-request) +- [Issuing a Credential](#issuing-a-credential) +- [Accepting the Credential with Streetcred](#accepting-the-credential-with-streetcred) +- [Issuing a Proof Request](#issuing-a-proof-request) +- [Responding to the Proof Request with Streetcred](#responding-to-the-proof-request-with-streetcred) +- [Review the Received Proof](#review-the-received-proof) +- [Conclusion](#conclusion) + +## Getting Started + +Make sure you've gone through the [Aries OpenAPI Demo](./AriesOpenAPIDemo.md), as this will give you the background on how to run and interact with an Aries agent. + +## Running in a Browser + +Run Play With Docker and start your agent using the BCovrin Test network: + +```bash +git clone https://github.com/hyperledger/aries-cloudagent-python +cd aries-cloudagent-python/demo +LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber --events +``` + +This is similar to the instructions in the prior "Play with Docker" section, except note that: + +- We are using the BCovrin Test network (it has to use the same network as the mobile app) +- We are running in "auto" mode, so we will have to do fewer manual acknowledgements +- Play with Docker exposes the Agent's' port (in this case port 8021 of the container) on a public URL that the mobile app can access + +Running in Docker + +An alternative for running locally - left as an excercise for the user - is to use ngrok and then set your agent's endpoint to the ngrok url. + +## Installing the Streetcred Agent + +Search for "Streetcred Identity Wallet" on the App Store or Google Play. + +
+ Click here to view screenshot (iOS) + App Store +
+ +Start the app and accept the terms of service to create an Agent. + +
+ Click here to view screenshot (iOS) + Create Agent +
+ +Enble Face ID (or Android equivalent) to secure the Agent. + +
+ Click here to view screenshot (iOS) + Enable Security +
+ +Enable notifications (or else you will have to continually refresh the Agent to get updates). + +
+ Click here to view screenshot (iOS) + Enable Notifications +
+ +Before connecting with the BC Government applications, you must do some additional setup, as follows: + +- Go to settings by clicking the menu icon in the top right (the "hamburger" icon—three stacked horizontal lines) +- Click on the "Network" item and from the subsequent list select "BCovrin Test" network. +- Click the back arrow to return to the settings and again to return to the main menu.Streetcred app screen. + +
+ Click here to view screenshot (iOS) + Select BCovrin Network +
+ +## Creating an Invitation + +When the Faber agent starts up it automatically creates an invitation. We will copy the "url" format of the invitation for the next step. Copy all the text between the quotes (do not include the quotes) - the copied text should be a properly formatted URL. + +
+ Click here to view screenshot + Select Invitation URL +
+ +## Converting the Invitation to a QR Code + +To send the invitation to the agent, we need to convert the URl into a QR code. Your application can do this, but for this demo we will use https://www.the-qrcode-generator.com/ + +Open up https://www.the-qrcode-generator.com/ in a new browser window, and: + +- Select the "URL" option +- Paste your invitation url into the provided input field + +
+ Click here to view screenshot + Generate QR Code +
+ +## Accepting the Invitation with Streetcred + +On the Streetcred mobile app, select "SCAN CODE" and point your camera at the generated QR code. Streetcred should automatically capture the code and ask you to confirm the connection. GO ahead and confirm. + +
+ Click here to view screenshot + Accept Invitation +
+ +Streetcred will then give you a message that "A connection was added to your wallet". + +
+ Click here to view screenshot + Add Connection to Wallet +
+
+ Click here to view screenshot + Add Connection to Wallet +
+ +## Accepting Streetcred's connection request + +At this point Faber has issued an invitation, and you have accpted the invitation and asked Faber to establish a connection to your agent. Faber must now accept this request. You can see the Event in the Faber console window. Find this event, and select and copy the "connection id". + +
+ Click here to view screenshot + Accept Connection Request +
+ +Now, in Faber's swagger page (at the top of the console window, click on port `8021` to open the swagger page in a new window) scroll down to the **`POST /connections/{id}/accept-request`** endpoint, paste the connection id and click on "Execute". + +
+ Click here to view screenshot + Accept Connection Request +
+
+ Click here to view screenshot + Accept Connection Request +
+ +Scroll to the **`GET /connections`** endpoint to check the status of the connection. + +
+ Click here to view screenshot + View Connection Status +
+ +Note - if the connection status does not update to `active`, try sending a `trust-ping` or `basic-message` on the connection. This will force a handshake between the agents that whould upate the connection status. + +## Issuing a Credential + +We will use the Faber console to issue a credential. (This could be done using the REST API as we have done above, this will be left as an exercise to the user.) + +In the Faber console, select option `1` to send a credential to streetcred. + +
+ Click here to view screenshot + View Connection Status +
+ +### Accepting the Credential with Streetcred + +The credential should automatically show up in streetcred - accept the offered credential. + +
+ Click here to view screenshot + View Connection Status +
+
+ Click here to view screenshot + View Connection Status +
+
+ Click here to view screenshot + View Connection Status +
+ +## Issuing a Proof Request + +We will use the Faber console to ask Streetcred for a proof. (This could be done using the REST API as we have done above, this will be left as an exercise to the user.) + +In the Faber console, select option `2` to send a proof request to streetcred. + +
+ Click here to view screenshot + View Connection Status +
+ +## Responding to the Proof Request with Streetcred + +In streetcred, respond to the proof + +
+ Click here to view screenshot + View Connection Status +
+
+ Click here to view screenshot + View Connection Status +
+
+ Click here to view screenshot + View Connection Status +
+ +## Review the Received Proof + +In the Faber console window, the proof should be received as validated. + +
+ Click here to view screenshot + View Connection Status +
+ +## Conclusion + +That’s the OpenAPI-based tutorial. Feel free to play with the API and learn how it works. More importantly, as you implement a controller, use the OpenAPI user interface to test out the calls you will be using as you go. The list of API calls is grouped by protocol and if you are familiar with the protocols (Aries RFCs) the API call names should be pretty obvious. + +One limitation of you being the controller is that you don't see the events from the agent that a controller program sees. For example, you, as Alice's agent, are not notified when Faber initiates the sending of a Credential. Some of those things show up in the terminal as messages, but others you just have to know have happened based on a successful API call. + + diff --git a/demo/AriesOpenAPIDemo.md b/demo/AriesOpenAPIDemo.md index a113817a4e..648e6350bc 100644 --- a/demo/AriesOpenAPIDemo.md +++ b/demo/AriesOpenAPIDemo.md @@ -19,7 +19,6 @@ What better way to learn about controllers than by actually being one yourself! - [Requesting/Presenting a Proof](#requestingpresenting-a-proof) - [Notes](#notes-2) - [Bonus Points](#bonus-points-1) -- [Issuing Credentials to a Mobile Agent](#issuing-credentials-to-a-mobile-agent) - [Conclusion](#conclusion) ## Getting Started @@ -642,7 +641,6 @@ If you would like to perform all of the proof request/response steps manually, y The following table lists endpoints that you need to call ("REST service") and callbacks that your agent will receive ("callback") that your need to respond to. - | Protocol Step | Faber (Verifier) | Alice (Holder/Prover) | Notes | | -------------------- | ---------------------- | ------------------------- | ----- | | Send Proof Request | **`POST /present-proof/send-request`** | | REST service | @@ -654,206 +652,6 @@ The following table lists endpoints that you need to call ("REST service") and c | Validate Proof | **`POST /present-proof/records/{id}/verify-presentation`** | | REST service | | Save Proof | | | application data | -## Issuing Credentials to a Mobile Agent - -You can use the Faber aca-py agent to issue credentials to a mobile wallet. To do this you need to run the Faber agent on a publicly accessible port (for example you can run the agent on Play With Docker), and you need a compatible wallet. One available wallet is the Streetcred Identity Agent, which is available on both iOS and Android, and you can read about it [here](https://github.com/bcgov/identity-kit-poc/blob/master/docs/GettingApp.md). - -### Installing the Streetcred Agent - -Search for "Streetcred Identity Wallet" on the App Store or Google Play. - -
- Click here to view screenshot (iOS) - App Store -
- -Start the app and accept the terms of service to create an Agent. - -
- Click here to view screenshot (iOS) - Create Agent -
- -Enble Face ID (or Android equivalent) to secure the Agent. - -
- Click here to view screenshot (iOS) - Enable Security -
- -Enable notifications (or else you will have to continually refresh the Agent to get updates). - -
- Click here to view screenshot (iOS) - Enable Notifications -
- -Before connecting with the BC Government applications, you must do some additional setup, as follows: - -- Go to settings by clicking the menu icon in the top right (the "hamburger" icon—three stacked horizontal lines) -- Click on the "Network" item and from the subsequent list select "BCovrin Test" network. -- Click the back arrow to return to the settings and again to return to the main menu.Streetcred app screen. - -
- Click here to view screenshot (iOS) - Select BCovrin Network -
- -### Setting up your Issuing Agent on a Public Port - -Run Play With Docker and start your agent using the BCovrin Test network: - -```bash -git clone https://github.com/hyperledger/aries-cloudagent-python -cd aries-cloudagent-python/demo -LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber --events -``` - -This is similar to the instructions in the prior "Play with Docker" section, except note that: - -- We are using the BCovrin Test network (it has to use the same network as the mobile app) -- We are running in "auto" mode, so we will have to do fewer manual acknowledgements -- Play with Docker exposes the Agent's' port (in this case port 8021 of the container) on a public URL that the mobile app can access - -(An alternative for running locally - left as an excercise for the user - is to use ngrok and then set your agent's endpoint to the ngrok url.) - -### Creating an Invitation - -When the Faber agent starts up it automatically creates an invitation. We will copy the "url" format of the invitation for the next step. Copy all the text between the quotes (do not include the quotes) - the copied text should be a properly formatted URL. - -
- Click here to view screenshot - Select Invitation URL -
- -### Converting the Invitation to a QR Code - -To send the invitation to the agent, we need to convert the URl into a QR code. Your application can do this, but for this demo we will use https://www.the-qrcode-generator.com/ - -Open up https://www.the-qrcode-generator.com/ in a new browser window, and: - -- Select the "URL" option -- Paste your invitation url into the provided input field - -
- Click here to view screenshot - Generate QR Code -
- -### Accepting the Invitation with Streetcred - -On the Streetcred mobile app, select "SCAN CODE" and point your camera at the generated QR code. Streetcred should automatically capture the code and ask you to confirm the connection. GO ahead and confirm. - -
- Click here to view screenshot - Accept Invitation -
- -Streetcred will then give you a message that "A connection was added to your wallet". - -
- Click here to view screenshot - Add Connection to Wallet -
-
- Click here to view screenshot - Add Connection to Wallet -
- -### Accepting Streetcred's connection request - -At this point Faber has issued an invitation, and you have accpted the invitation and asked Faber to establish a connection to your agent. Faber must now accept this request. You can see the Event in the Faber console window. Find this event, and select and copy the "connection id". - -
- Click here to view screenshot - Accept Connection Request -
- -Now, in Faber's swagger page (at the top of the console window, click on port `8021` to open the swagger page in a new window) scroll down to the **`POST /connections/{id}/accept-request`** endpoint, paste the connection id and click on "Execute". - -
- Click here to view screenshot - Accept Connection Request -
-
- Click here to view screenshot - Accept Connection Request -
- -Scroll to the **`GET /connections`** endpoint to check the status of the connection. - -
- Click here to view screenshot - View Connection Status -
- -Note - if the connection status does not update to `active`, try sending a `trust-ping` or `basic-message` on the connection. This will force a handshake between the agents that whould upate the connection status. - -### Issuing a Credential - -We will use the Faber console to issue a credential. (This could be done using the REST API as we have done above, this will be left as an exercise to the user.) - -In the Faber console, select option `1` to send a credential to streetcred. - -
- Click here to view screenshot - View Connection Status -
- -### Accepting the Credential with Streetcred - -The credential should automatically show up in streetcred - accept the offered credential. - -
- Click here to view screenshot - View Connection Status -
-
- Click here to view screenshot - View Connection Status -
-
- Click here to view screenshot - View Connection Status -
- -### Issuing a Proof Request - -We will use the Faber console to ask Streetcred for a proof. (This could be done using the REST API as we have done above, this will be left as an exercise to the user.) - -In the Faber console, select option `2` to send a proof request to streetcred. - -
- Click here to view screenshot - View Connection Status -
- -### Responding to the Proof Request with Streetcred - -In streetcred, respond to the proof - -
- Click here to view screenshot - View Connection Status -
-
- Click here to view screenshot - View Connection Status -
-
- Click here to view screenshot - View Connection Status -
- -### Review the Received Proof - -In the Faber console window, the proof should be received as validated. - -
- Click here to view screenshot - View Connection Status -
- ## Conclusion That’s the OpenAPI-based tutorial. Feel free to play with the API and learn how it works. More importantly, as you implement a controller, use the OpenAPI user interface to test out the calls you will be using as you go. The list of API calls is grouped by protocol and if you are familiar with the protocols (Aries RFCs) the API call names should be pretty obvious. From 49f01e27a6538947b9acf6f7eedfcc645175dd17 Mon Sep 17 00:00:00 2001 From: Ian Costanzo Date: Wed, 4 Mar 2020 17:20:04 -0700 Subject: [PATCH 2/2] Separate 2 API docs Signed-off-by: Ian Costanzo --- demo/AriesOpenAPIDemo-mobile.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demo/AriesOpenAPIDemo-mobile.md b/demo/AriesOpenAPIDemo-mobile.md index 8f924f1e33..a3dc3e02b7 100644 --- a/demo/AriesOpenAPIDemo-mobile.md +++ b/demo/AriesOpenAPIDemo-mobile.md @@ -1,4 +1,4 @@ -# Aries OpenAPI Demo +# Aries OpenAPI Mobile Demo You can use the Faber aca-py agent to issue credentials to a mobile wallet. To do this you need to run the Faber agent on a publicly accessible port (for example you can run the agent on Play With Docker), and you need a compatible wallet. One available wallet is the Streetcred Identity Agent, which is available on both iOS and Android, and you can read about it [here](https://github.com/bcgov/identity-kit-poc/blob/master/docs/GettingApp.md).