This repository is deprecated and is no longer being maintained.
The Indy World Demo implements the Alice Demo described in Getting Started with Indy. The demo shows how a self-sovereign identity ("SSI") can be used to obtain credentials from an issuer and supply these credentials to a verifier in response to a proof request thus providing a verifiable proof.
This repo provides a hands on tutorial as well as a narrated video recording (File Mirror).
Note: The file mirror video requires a mp4 compatible video player.
As part of an initiative to manage Verifiable Organizations with Self-Sovereign Identities, the Government for the Province of British Columbia ("BC-Gov") in partnership with Public Services and Procurement Canada and the Government of Ontario, has contributed several open-source projects that are helpful in bootstrapping new applications that make use of Hyperledger Indy ("Indy") and Verifiable Credentials. This Indy World Demo is derived from the permitify and von-network repositories.
The Indy World Demo is intended to serve as a complimentary tutorial for anyone interested in learning how verifiable credentials are exchanged within a Hyperledger Indy environment.
Know your customer ("KYC") is a business process associated with the regulatory activities used by banks and other institutions to identify and verify the identity of their clients. After graduating from college Alice desires to open a new account with Thrift Bank. The bank has a new self-service offering whereby new clients can quickly and seamlessly use digital credentials to satisfy the bank's KYC requirements.
As luck would have it, Alice recently took advantage of a new digital transcript offering from her alma mater, Faber College. This digital transcript came in handy during her application process with her new employer, Acme Corporation ("Acme"). Upon being hired, Acme issued Alice a digital Job Credential. Using her digital wallet which contains education and employment credentials, Alice is confident she can take advantage of Thrift Bank's new self-service offering.
Given the roles and responsibilities outlined in the Verifiable Credentials specification, Alice's KYC story can be described using the following abstract concepts:
| Role | Description | Examples |
|---|---|---|
| Holder | An entity that is in control of one or more verifiable credentials. | A holder can be a person, organization or a connected device. Alice is a holder. |
| Issuer | An entity that creates a verifiable credential, associates it with a particular subject, and transmits it to a holder. | Issuers include corporations, governments, and individuals. Faber College and Acme are issuers. |
| Inspector-Verifier | An entity that receives one or more verifiable credentials (specified by a proof request) for processing. | Verifiers include employers, security personnel, and websites. Acme and Thrift Bank are verifiers. |
| Identifier Registry | Mediates the creation and verification of subject identifiers. | Identifier registries include corporate employee databases, government ID databases, and distributed ledgers. For demonstration purposes we use a distributed ledger comprised of a pool of Indy nodes. |
This Indy World Demo leverages three repositories contributed by BC-Gov to enable a person to register for a ficticious Government ID, and then use that ID to obtain a college transcript, apply for and get hired by a company, and apply for a loan.
The repositories are:
VON Network: The VON Network creates a 4-node Indy node pool. Each node contains a blockchain ledger. These ledgers are kept in sync and verified using a consensus algorithm.
The Org Book: The Org Book is a repository of businesses and their associated credentials and permits. It was modified to hold verifiable credentials for individuals. These credentials are issued by Issuers such as colleges, companies and banks.
Permitify: Permitify instantiates the Issuers for the demo. There are four Permitify-Issuer services:
- Government SSI App, which issues a Gov ID
- Faber College SSI App, which issues a Student Transcript
- Acme SSI App, which issues a Credential of Employment
- Thrift Bank SSI App, which issues a Bank Account
Each one of these Issuers creates a verifiable credential for an individual that is described by a credential schema definition. Before issuing a credential, a proof request must be filled out using the individual's currently held credentials and verified by the institution.
The figure below shows the various components for the demo.
Indy SDK: Indy is an implementation of a self-sovereign identity ecosystem on top of a distributed ledger.
Wallet: Secure storage for keys, credentials, and other private data used by holder, issuer, inspector-verifier or identifer registry.
Indy Node: A computer network server running an instance of the Sovrin Open Source Code (Indy) to maintain the Sovrin Ledger.
VON Agent: A higher-level API created by BC-Gov that wraps the Indy SDK.
Docker and Docker Compose are used to build and run the demo. To see what versions are currently installed on your system, run:
$ docker --version
$ docker-compose --version
Information on downloading and installing Docker for various platforms can be found here.
The source-to-image (s2i) tool is also required to build the docker images used in the demo. S2I can be downloaded here. If you are using a Mac and have Homebrew installed, the following command will install s2i:
$ brew install source-to-image
The website gives instructions for installing on other platforms.
Verify that s2i is in your PATH. If not, then edit your PATH and add the directory where s2i is installed. The manage.sh scripts will look for the s2i executable on your PATH. If it is not found you will get a message asking you to download and set it on your PATH.
This project includes three git repositories from BC-Gov (VON Network, TheOrgBook and Permitify) as described under the architecture section.
Cloning the indy-world repo will fetch all of the code for our customized versions of the BC-Gov repos need to build and run the Indy World demo.
$ git clone https://github.com/IBM-Blockchain-Identity/indy-ssivc-tutorial.git
$ cd indy-ssivc-tutorial
You need to build the components VON Network, TheOrgBook and Permitify.
To build VON Network:
$ cd von-network
$ ./manage build
To build TheOrgBook:
$ cd TheOrgBook/docker
$ ./manage.sh build
To build Permitify:
$ cd permitify/docker
$ ./manage build
You can rebuild the docker images using the 'rebuild' option.
VON Network needs to be started first.
To start VON Network, open a new terminal and enter the commands:
$ cd von-network
$ ./manage start
Wait until all the nodes have completely started before starting TheOrgBook.
TheOrgBook needs to be started next.
To start TheOrgBook, open a new terminal and enter the commands:
$ cd TheOrgBook/docker
$ ./manage.sh start
Wait until TheOrgBook has completely started before starting Permitify.
To start Permitify, open a new terminal and enter the commands:
$ cd permitify/docker
$ ./manage start all
Once all containers are started, you can view the node pool and ledger by visiting the following web page in your browser:
To view the node pool (VON Network):
http://localhost:9000/
The VON Network web UI enables the ledgers to be inspected. The genesis file can also be viewed.
You can run the demo by visiting the following web page in your browser:
To run the demo:
http://localhost:8080/
To stop an application, press Ctrl-C. This should stop all docker containers that the command started.
If there are still containers running, you can use the following command to stop them:
VON Network:
$ cd von-network
$ ./manage stop
TheOrgBook:
$ cd TheOrgBook/docker
$ ./manage.sh stop
Permitify:
$ cd permitify/docker
$ ./manage stop
The docker containers and volumes created when running the demo can be removed using the manage rm parameter. If you are having problems adding a user or veriying credentials, this command can also be called to reset the data used for the demo.
VON Network:
$ cd von-network
$ ./manage rm
TheOrgBook:
$ cd TheOrgBook/docker
$ ./manage.sh rm
Permitify:
$ cd permitify/docker
$ ./manage rm
To run the demo, load the homepage in your browser:
http://localhost:8080/
The homepage shows an outline of the demo steps in an order that is enforced by verifiable credentials. For example, a person can't be hired for a job and obtain a job credential until they can prove that they hold a degree. The verification of a degree is accomplished by filling out a proof request (Acme Corp) with information from a previously obtained and verified credential (Faber College).
The demo consists of 5 steps:
- Register a person
- Obtain a college transcript
- Apply for a job
- Get hired
- Apply for a loan
To register a person and create a new online government identity, click on the Register Person button.
After registering a new person, a list of credential issuers is shown. To obtain a credential from one of these issuers, click on the corresponding button. Note that only those issuers that have all dependencies met can be successfully called.
Alice can obtain a government ID by clicking on the Register Person button. This displays a form hosted on the Gov ID website that could have been filled out by a government employee after vetting Alice in person, or filled out by Alice after logging in to the Gov ID website with credentials she already uses to access other government services. Either way, this is Alice's on-ramp to using verifiable credentials.
When the Submit button is pressed, a credential is generated by Gov ID and downloaded into Alice's wallet. Note that Alice's credential is also saved in the issuers (Gov ID) wallet.
Now that Alice has a credential, she can use that credential to prove who she is to other issuers.
The demo now shows which credentials Alice has obtained and which ones she needs before requesting a new credential from a particular issuer.
The webpage shows that Alice has a Gov ID credential, and can now request a transcript from Faber College since she holds all Depends on credentials in her wallet. Note that she cannot apply for a job yet, since the transcript dependency isn't met, as indicated by a red X.
Before Alice requests her transcript from Faber College, she wants to view her credential from Gov ID. Clicking on View Certificate in the Gov ID section, Alice's credential is displayed. This credential can be verified by clicking on the Verify Credential button.
This creates a proof request from Alice, which is filled in using information from the Gov ID credential in Alice's wallet. It is cryptographically verified and determined to be valid. The content below the Verify Credential button shows the details of the proof request. This is only for demo purposes, and would not be normally revealed to a user.
Clicking the Back to Person Info link shows the various credentials that Alice has collected in her wallet. At this point, there's only one - the Gov ID credential.
Click Back to return to the list of issuers.
From the credentials list Alice now clicks on Get college transcript. This operation may take 20 seconds or more. Under the covers Alice obtains a proof request definition from Faber College, automatically fills in with her ID credential, sends it to Faber College, and then Faber College cryptographically validates the contents of the proof. Once this process has completed, a form is displayed from the Faber College website. Normally, this form would be filled in by the registrars office; however, for demo purposes, we are filling it out now.
Notice the claim data displayed at the bottom of the form. This is the verified data provided by Alice's Gov ID credential from her wallet in response to a proof request from Faber College.
When Submit is pressed, Faber College creates the transcript credential and sends it to Alice. Alice then saves it in her wallet.
To apply for a job at Acme Corp, Alice clicks on Apply for a job. This displays the Job Application form with most of the information filled in from credentials that Alice holds in her wallet.
Clicking on Submit will create a job application credential, which is saved in both Alice's and Acme Corp's wallet. Acme will use this verified credential information as part of the interviewing process to decide if they want to hire Alice.
Good news! Alice has been hired by Acme Corp. Someone from the human resources department at Acme will click on the Issue certificate for a job button to create a credential for Alice attesting to her employment.
Alice might be notified that a job credential is available from Acme via e-mail or on their employee website. Either way, Alice can add this credential to her wallet to validate her employment status. For this demo, the job credential is added to Alice's wallet by clicking on the Submit button.
Now that Alice has a job, she can apply for a loan from Thrift Bank. She clicks on Apply for a loan to display the loan application from Thrift Bank.
The loan application form is completely pre-populated with verified information from multiple credentials in Alice's wallet.
Note that Alice has the opportunity to edit and disclose only the information that she wants Thrift Bank to know. In a real application, each of these input boxes would allow Alice to pick which credential to use for that particular data.
Alice clicks the Submit button to apply for the loan.
Alice has obtained all credentials from the list of issuers in the demo. She can view any of the credentials by clicking on the View certificate button.
All of the credentials that Alice has in her wallet can be viewed by clicking on the View record of person button.
The individual credentials can be viewed and verified if desired.
