Difference between revisions of "Installation and configuration guide of the DE4A SSI Authority Agent it2"
(Added content.) |
|||
Line 13: | Line 13: | ||
* Linux build-essentials (<code>sudo apt-get install build-essential</code>). | * Linux build-essentials (<code>sudo apt-get install build-essential</code>). | ||
− | + | == SSI Authority Agent configuration guide == | |
For a correct configuration of the Connector, three main property files must be considered: | 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) | + | * <code>.env</code>: main system configuration (Aries agent, public IP address and ports, CouchDB database) |
− | * docker-compose.yml: general script for deploying the SSI Authority Agent containers | + | * <code>docker-compose.yml</code>: 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.) | + | * <code>app.properties</code>: 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. | + | 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: | Bellow, a working example of the app.properties file is presented: | ||
Line 41: | Line 41: | ||
From now on, we will explain the main and most critical configuration. | From now on, we will explain the main and most critical configuration. | ||
− | + | === System configuration === | |
Line 64: | Line 64: | ||
db.name=<INSERT DB name> | 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: | 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). | + | * <code>alias</code> 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. | + | * <code>aries.enterprise.ip.address</code> 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. | + | * <code>signature.type</code> 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. | + | * <code>bearer.token</code> 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. |
* <code>organization.img.url</code> - 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; | * <code>organization.img.url</code> - 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; | ||
* <code>client.url</code> - 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; | * <code>client.url</code> - 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; | ||
Line 79: | Line 79: | ||
* <code>de.url</code> - 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. | * <code>de.url</code> - 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. | Once all configuration parameters are configured, it is possible to start the Docker containers by running the docker-compose.yml file. | ||
Line 85: | Line 85: | ||
$cd agent | $cd agent | ||
$docker-compose up -d | $docker-compose up -d | ||
+ | |||
If everything has gone well, the following list of containers will start running in the system: | If everything has gone well, the following list of containers will start running in the system: | ||
Creating couchdb.de4a.eu ... done | Creating couchdb.de4a.eu ... done | ||
Line 97: | Line 98: | ||
$docker-compose stop | $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 <code>government.agent.api.de4a.eu</code> Docker service representing the Authority Agent API logs events and error in <code>/usr/local/tomcat/logs/de4a-metrics-log.txt</code> 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): | 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 <code>government.agent.api.de4a.eu</code> Docker service representing the Authority Agent API logs events and error in <code>/usr/local/tomcat/logs/de4a-metrics-log.txt</code> 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): | ||
<code>docker exec -it government.agent.api.de4a.eu /bin/bash | <code>docker exec -it government.agent.api.de4a.eu /bin/bash | ||
Line 104: | Line 105: | ||
cat de4a-metrics-log.txt</code> | cat de4a-metrics-log.txt</code> | ||
− | + | == Authority Agent REST API requests flow == | |
The flow of API requests for the Issuer's side is the following: | The flow of API requests for the Issuer's side is the following: | ||
Latest revision as of 09:55, 7 December 2022
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 containersapp.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:
/did-conn-status/{userId}
/generate-invitation
/did-conn-status/{userId}
(for websockets purposes)/send-vc-offer
/check-offer-vc-response/{userId}
The flow of API requests for the Verifier's side is the following:
/did-conn-status/{userId}
/generate-invitation
/did-conn-status/{userId}
(for websockets purposes)/send-vp-request
/check-request-vp-response/{userId}