SSI configuration hints

Self-Sovereign Identities is an incubating feature. It is intended to implement proof-of-concept use cases and it is expected that the plugins provided will change fundamentally and without further notice in future releases of Airlock IAM.

Create a schema on the ledger

A schema must be published on the ledger to issue a verifiable credential. This schema defines which attributes will be available in the verifiable credential.

Use the following command to create a schema on the ledger:

curl --location 'http://0.0.0.0:8000/schemas' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: apIkeY' \
--data '{
  "attributes": [
      "firstName",
      "lastName",
      "email" 
  ],
  "schema_name": "ErgonIDSchema",
  "schema_version": "1.2"
}'

The above command should return with a response similar to this output:

{
  "sent": {
    "schema_id": "XEXYpiUBJtzhheyuMNxDLr:2:ErgonIDSchema:1.2",
    "schema": {
      "ver": "1.0",
      "id": " XEXYpiUBJtzhheyuMNxDLr:2:ErgonIDSchema:1.2",
      "name": "ErgonIDSchema",
      "version": "1.2",
      "attrNames": [
        "email",
        "lastName",
        "firstName"
      ],
      "seqNo": 50181
    }
  },
  "schema_id": "XEXYpiUBJtzhheyuMNxDLr:2:ErgonIDSchema:1.2",
  "schema": {
    "ver": "1.0",
    "id": "XEXYpiUBJtzhheyuMNxDLr:2:ErgonIDSchema:1.2",
    "name": "ErgonIDSchema",
    "version": "1.2",
    "attrNames": [
      "email",
      "lastName",
      "firstName"
    ],
    "seqNo": 50181
  }
}

Make sure to note down the schema_id provided by this output. It is required to retrieve the schema definition from the ledger and is part of the plugin configuration of multiple plugins in Airlock IAM.

Create a credential definition on the ledger

Hyperledger Aries requires a credential definition related to a credential schema on the ledger.

To run the following command, replace the schema_id with the output from the previous command:

curl --location 'http://0.0.0.0:8000/credential-definitions' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: apIkeY' \
--data '{
      "schema_id": "XEXYpiUBJtzhheyuMNxDLr:2:ErgonIDSchema:1.2",
      "support_revocation": false,
      "tag": "1.0"
}'

The above command should return with a response similar to this output:

{
  "sent": {
    "credential_definition_id": "XEXYpiUBJtzhheyuMNxDLr:3:CL:50181:1.0"
  },
  "credential_definition_id": "XEXYpiUBJtzhheyuMNxDLr:3:CL:50181:1.0"
}

Running ACA.Py

The following is a template file for docker-compose.yml that can run ACA.Py with postgres and ngrok as docker container.

version: "3.4"
services:
  db:
    image: postgres:13.9-alpine
    #restart: always
    environment:
      - POSTGRES_USER=${DBUSER}
      - POSTGRES_PASSWORD=${DBPASSWORD}
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "pg_isready -U ergon"
        ]
      interval: 10s
      timeout: 5s
      retries: 5
    ports:
      - '5432:5432'
  ngrok:
    image: ngrok/ngrok:latest
    restart: unless-stopped
    command:
      - "start"
      - "--all"
      - "--config"
      - "/etc/ngrok.yml"
    volumes:
      - ./ngrok.yml:/etc/ngrok.yml
    ports:
      - 4040:4040
  issuer:
    image: bcgovimages/aries-cloudagent:py36-1.16-1_0.8.1
    command:
      - start
      - '--debug-connections'
      - '--debug-presentations'
      - '--inbound-transport'
      - http
      - 0.0.0.0
      - '8002'
      - '--admin'
      - 0.0.0.0
      - '8000'
    ports:
      - "8002:8002"
      - "8000:8000"
    depends_on:
      - db
    environment:
      - ACAPY_WALLET_SEED=${SEED}
      - ACAPY_GENESIS_URL=${GENESISURL, e.g. http://test.bcovrin.vonx.io/genesis}
      - ACAPY_AUTO_PROVISION=True
      - ACAPY_RECREATE_WALLET=True
      - ACAPY_ENDPOINT=${NGROK_URL}
      - ACAPY_OUTBOUND_TRANSPORT=http
      - ACAPY_WALLET_TYPE=askar
      - ACAPY_WALLET_NAME=issuer
      - ACAPY_WALLET_STORAGE_TYPE=postgres
      - ACAPY_WALLET_STORAGE_CONFIG={"url":"db:5432","wallet_scheme":"public"}
      - ACAPY_WALLET_STORAGE_CREDS={"account":${USER},"password":${PASSWORD},"admin_account":${ADMUSER},"admin_password":${ADMPASSWORD}}
      - ACAPY_WALLET_KEY=${WALLETKEY}
      - ACAPY_ADMIN_API_KEY=apIkeY
      - ACAPY_ENDORSER_ROLE=none
      - ACAPY_AUTO_VERIFY_PRESENTATION=true
      - ACAPY_AUTO_PING_CONNECTION=true
      - ACAPY_LOG_LEVEL=debug
      - ACAPY_LOG_FILE=./acapy.log

Wallet connection and using ngrok

The ACA.Py installation must be reachable over the Internet to enable the wallet to communicate with the ACA.Py instance. In most test environments a permanent connection to the internet is neither desired nor permitted.

A possible solution is the use of a VPN service like ngrok as follows:

Create a login account on the ngrok homepage.
Log in and go to:
Tunnels >> Agents
Click on the existing tunnel.
Create an ENV variable $NGROK_URL with the tunnel URL (e.g. export NGROK_URL="https://1234-56-789-123-45.ngrok-free.app/").
Go to:
Getting Started >> Your Authtoken
Create an ENV variable $AUTH_TOKEN with the tunnel URL (e.g. AUTH_TOKEN="123456789abcdefghijklmnopqr_123456789ABCDEFGHIJKL").
Start the ngrok container with a YAML file like this:

authtoken: ${AUTH_TOKEN}
version: 2
tunnels:
  acapy:
    proto: http
    addr: issuer:8002