bcgov / issuer-kit

Verifiable Credential Issuer Starter Kit
Apache License 2.0
51 stars 48 forks source link
citz hyperledger hyperledger-indy indy-catalyst verifiable-credentials verifiable-organizations-network von

img License

BC Gov Issuer Kit

This repo contains code and deployment instructions for running the BC Gov's Issuer Kit Verifiable Credentials proof of concept (PoC). The ID Kit PoC includes:

The instructions below allow you to run the application on your laptop in a couple of different ways. Once you are familiar with the app, you can configure the code to be deployed on enterprise hardware, with updates applicable to your environment.

An overview of the architecture of the IdKit and the administrator and participant flows can be found here.

Need a mobile app to try? Instructions are available here for getting an IOS mobile app. An Android app will be available Real Soon Now.

The instructions here are still a bit raw. We're iterating on them and check back if things don't go smoothly. We're happy to answer any questions you have. Easiest way to connect with us is to add an issue in this repo.

Pre-Requisites

jq and ngrok are available on package manager systems for different platforms such as Homebrew (Mac), Chocolatey (Windows) and various Linux distribution package managers.

Running the Issuer Kit

Issuer Kit can be started in different (demo, local and developer) modes by executing the steps in the respective sections below. The following are a couple important things to keep in mind as you start the apps:

Demo Mode

Demo mode runs Issuer Kit using the BCovrin Test ledger and uses ngrok to expose the agent running locally to the Internet. The Streetcred mobile agent (iOS and Android) can be used with Issuer Kit if you use demo mode.

To run in demo mode, open two shell/terminal sessions:

  1. From within the ngrok folder execute ./start-ngrok.sh. This will create a tunnel for the agent.

  2. From within the docker folder:

    • run ./manage build to assemble the runtime images for the services
    • when the build completes, run ./manage start-demo

Once started, the services will be exposed on localhost at the following endpoints:

Within the Streetcred app, check the settings to see what Ledger you are using. For this demo the Streetcred app must be set to use the "BCovrin Test" network, as follows:

For instructions on how to run the demo, please refer to this document.

To restart the applications:

Local Mode

In Local Mode the entire application runs locally and uses a locally deployed Indy ledger. In Local Mode you cannot use the Streetcred agent because it is unable to access the ledger being used.

To run in local mode, open two shell/terminal sessions:

  1. Follow the instructions to start von-network running locally
  2. Change to the Issuer Kit docker folder:
    • run ./manage build to assemble the runtime images for the services.
    • run ./manage start to start the containers

Once started, the services will be exposed on localhost at the following endpoints:

:information_source: When running in local OR demo mode, changes to the code will not be reflected in the containers unless a rebuild using ./manage build and restart using ./manage start is performed.

To restart the applications:

Development Mode

Development mode runs the admin frontend, public frontend and the api/controller in development mode with hot-reloading enabled. This means that any change to the code in the src directories of issuer-admin, issuer-web and api will automatically trigger a rebuild and reload of the associated service.

To run in development mode, run npm install in each one of the issuer-admin, issuer-web and api directories and then run the same steps as Local Mode above, but use ./manage start-dev in place of the ./manage start command in the second shell.

The services will be running at the following endpoints:

Keycloak Configuration and Users

While it is possible to provide a client id and token pair to use the GitHub integration for Keycloak (follow the on-screen instructions when starting the apps), two default users are shipped with the default Keycloak configuration:

:warning: The issuer-admin user can also access the public webapp, however issuer-web will only be able to access the public site. When testing locally, it is recommended to open admin and public sites in two different browsers in order to prevent cookies to auto-login the admin user onto the public site.

Credential Schema

Each api/controller can issue several credentials matching different schemas: the schema definitions that can be processed by the api/controller are described in this file. There are two ways of defining a schema: using the id of the schema on the target ledger or, alternatively, defining the schema_name, schema_version and attributes for the schema. Additionally, one schema in the provided list must be marked with the default: true property: this describes which schema will be used if no explicit request is forwarded to the api/controller.

When using Issuer Kit in demo mode the api/controller will use the schema marked as default, which corresponds to the schema definition that was published to the BCovrin Test Ledger by the BCGov issuer, and issue credentials that match that definition. In most cases updating the schema definition should not be necessary, however if this was the case the following steps will be required to instruct the controller/agent to publish a new schema definition on the target ledger, and use it:

"credentials": {
    "schema_id": "85459GxjNySJ8HwTTQ4vq7:2:verified_person:1.4.0"
  }

:information_source: If you are planning on using Issuer Kit in your own production-like environment - regardless of wether you will be re-using the BCGov schema or creating your own - you may want to update the ACAPY_WALLET_SEED environment variable with a unique value used only by your agent/organization rather than using the default value used for demo purposes.

App Configuration

The api, administrator and issuer applications can be configured by using a number of environment variables and settings stored in configuration files. The application is shipped with default configurations that work well when running in the provided dockerized environment, if settings need to be updated look for:

SMTP Settings

The api/controller uses nodemailer to send email invitations. When running on localhost a maildev service is used to intercept outgoing email messages.

If you are running a deployment and require emails to be sent, set the following environment variables appropriately:

API Docs

The api service exposes a Swagger documentation page at http://localhost:5050/swagger/docs. Publicly available APIs are documented there.

:information_source: at the time of writing, the response structure of the /connection POST method to request a new connection invitation is not accurate. The API docs represent the response the same as for the GET method, however in this case the response represent a new Aries connection invitation that matches the AriesConnection data model in this file.

Customizing the services

The configuration settings for the services in Issuer Kit can be found here.