Installation and configuration guide of the DE4A SSI Authority Agent it2

Installation

The complete installation guidelines are available at https://github.com/de4a-wp5/ssi-authority-agent.

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
• app.properties: main configuration of the REST API i.e. web application (database credentials, EBSI bearer token, HL Aries agent public address and port, URLs to Evidence/eProcedure portals, etc.)

For the second iteration, the app.properties file has been extended with additional parameters needed for logging purposes and VC schema checking.

Bellow, a working example of the app.properties file is presented:

db.ip.address=http://couchdb.de4a.eu:5984/ 
db.username=<INSERT DB administrator username>
db.password=<INSERT DB administrator password>
db.name=<INSERT DB name>
alias=<INSERT ORGANIZATION ALIAS NAME>
aries.enterprise.ip.address=http://<INSERT_PUBLIC_DOMAIN_HERE>:8082/
signature.type=Ed25519Signature2018
bearer.token=<INSERT session token>
organization.img.url=<PUBLIC URL WITH LOGO IMAGE OF THE ORGANIZATION>
client.url=<ENDPOINT URL OF THE PORTAL>
vc.schema.url=http://de4a-dev-schema.informatika.uni-mb.si:9099/de4a-diploma-schema.json
do.url=<EVIDENCE PORTAL PUBLIC URI> (optional for Verifiers)
de.url=<EPROCEDURE PORTAL PUBLIC URI> (optional for Issuers)

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:

DOMAIN=<INSERT_PUBLIC_DOMAIN_HERE>
....
COUCHDB_IMAGE=couchdb
COUCHDB_IMAGE_TAG=3.1
COUCHDB_PORT=5984
COUCHDB_USER=<INSERT_COUCHDB_USER_HERE>
COUCHDB_PASSWORD=<INSERT_COUCHDB_PASSWORD_HERE>

# Remote JSON-LD context provider configuration
DOMAIN_CONTEXT=de4a-dev-schema.informatika.uni-mb.si
CONTEXT_PROVIDER_URL=http://de4a-dev-schema.informatika.uni-mb.si:9099/agent-startup-contexts.json

Database properties

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

db.ip.address=http://couchdb.de4a.eu:5984/
db.username=<INSERT DB administrator username>
db.password=<INSERT DB administrator password>
db.name=<INSERT DB name>

Authority Agent REST API application.properties

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.
• organization.img.url - the parameter is needed during establishing DID connection with the student's mobile agent. The image available on this URL is displayed as an organization's icon in the student's mobile phone;
• client.url - the parameter is used to send status update notifications from the Authority Agent to the Evidence/eProcedure portal already used by the organization. The API endpoint implemented on this URL should be a POST method, which receives a string object in the POST request body;
• vc.schema.url - the parameter is needed to support VC schema evaluation during VC issuance and VP validation processes. The value does not need to be changed, as the schema description file is hosted by UM.
• do.url - the parameter is to be specified by the organization that acts as the Issuer of Verifiable Credentials, and it contains the main URL of the Issuer's Evidence Portal. The parameter is used *only for DE4A logging purposes.
• de.url - the parameter is to be specified by the organization that acts as the Verifier of submitted Verifiable Credentials, and it contains the main URL of the Verifier's eProcedure Portal. The parameter is used only for DE4A logging purposes.

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 couchdb.de4a.eu                         ... done
Creating de4a-dev.informatika.uni-mb.si              ... done
Creating government.agent.api.de4a.eu            ... done
Creating de4a-dev-schema.informatika.uni-mb.si   ... 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 government.agent.api.de4a.eu 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 government.agent.api.de4a.eu /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} (for websockets purposes)
4. /send-vc-offer
5. /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} (for websockets purposes)
4. /send-vp-request
5. /check-request-vp-response/{userId}