Installation and configuration guide of the DE4A SSI Authority Agent

From DE4A
Jump to navigation Jump to search


The complete installation guidelines are available at

Requirements (installation of tools for Linux)

  • Linux server (scripts were not tested on other OSes).
  • Git.
  • Docker (20.10.2): for Debian based installations of Linux (e.g. Ubuntu) installation instructions for Docker can be found here and for Fedora here. Note: make sure the user is in the docker group (no sudo required for docker command), instructions can be found here.
  • Docker Compose (1.27.4): for Debian distributions installation instructions are here and for Fedora here.
  • Linux build-essentials (sudo apt-get install build-essential).

SSI Authority Agent configuration guide

For a correct configuration of the Connector, three main property files must be considered:

  • .env: main system configuration (Aries agent, public IP address and ports, CouchDB database)
  • docker-compose.yml: general script for deploying the SSI Authority Agent containers
  • main configuration of the REST API i.e. web application (database credentials, EBSI bearer token, HL Aries agent public address and port, etc.)

Bellow, a working example of the file is presented:

db.username=<INSERT DB administrator username>
db.password=<INSERT DB administrator password><INSERT DB name>
bearer.token=<INSERT session token>

From now on, we will explain the main and most critical configuration.

System configuration

The basic system configuration necessary for successful communication between Authority Agent components is listed in the .env file. Among others, there is a definition of necessary Docker images and the URL of the EBSI DID resolver. As an additional configuration, it is necessary to specify the public domain of the server where the Authority Agent is going to be deployed as well as database configuration properties by editing the following properties:

Database properties

Regarding database configuration and structure, the component creates a CouchDB database, which name is specified in the configuration file:

db.username=<INSERT DB administrator username>
db.password=<INSERT DB administrator password><INSERT DB name>

Authority Agent REST API

Besides the general system and database configurations, the following properties need to specified to successfully run the REST API:

  • alias of the organization's Authority Agent, which will be displayed to the user when sending invitations for connecting agents (e.g. MIZŠ Slovenia).
  • aries.enterprise.ip.address is the URL to the HL Aries government agent to which the REST API will send HTTP requests.
  • signature.type refers to the type of the digital signature used to sign verifiable credentials issued to the student. By default, the verifiable credentials will be signed by the Ed25519Signature2018 type.
  • bearer.token refers to the token obtained from the EBSI onboarding service, which is used by the EBSI Connector in case of onboarding and registering the Authority Agent's DID into the EBSI DID Registry during its first startup.

Starting up the SSI Authority Agent

Once all configuration parameters are configured, it is possible to start the Docker containers by running the docker-compose.yml file.

To start the containers, it will be necessary to execute the following command:

$cd agent
$docker-compose up -d

If everything has gone well, the following list of containers will start running in the system:

Creating                         ... done
Creating              ... done
Creating            ... done

The CouchDB database GUI will be available at http://<IP ADDRESS:5984>/_utils.

To stop the containers, the following command needs to be executed:

$cd agent
$docker-compose stop

SSI Authority Agent logging

The logging functionality of the Authority Agent has been externalized to correspond to the pilot metrics and remove sensitive data from the output. Specifically, the Docker service representing the Authority Agent API logs events and error in /usr/local/tomcat/logs/de4a-metrics-log.txt file in the Docker container. To access the contents of that file, you need to enter the command line of the Docker container by executing the following line (once the containers are running):

docker exec -it /bin/bash
cd ..
cd logs
cat de4a-metrics-log.txt

Authority Agent REST API requests flow

The flow of API requests for the Issuer's side is the following:

  1. /did-conn-status/{userId}
  2. /generate-invitation
  3. /did-conn-status/{userId}
  4. /send-vc-offer
  5. /send-vc
  6. /check-offer-vc-response/{userId}

The flow of API requests for the Verifier's side is the following:

  1. /did-conn-status/{userId}
  2. /generate-invitation
  3. /did-conn-status/{userId}
  4. /send-vp-request
  5. /check-request-vp-response/{userId}
  6. /validate-vp/{userId}