Difference between revisions of "DE4A SSI Authority and Edge Agent"

From DE4A
Jump to navigation Jump to search
m
 
(10 intermediate revisions by 2 users not shown)
Line 21: Line 21:
  
 
==== Receive and validate a Verifiable Presentation ====
 
==== Receive and validate a Verifiable Presentation ====
 +
If deployed on the Data Consumer side, the Authority Agent enables organizations to request a diploma in the form of Verifiable Presentations from the students. In that case, a student can directly submit his/her diploma from the mobile wallet to the eProcedure Portal. Once received, the Portal can validate several aspects of the diploma validity: schema, digital signature, issuer and subject.
  
 
=== Supported interaction patterns ===
 
=== Supported interaction patterns ===
Line 37: Line 38:
  
 
===Error handling===
 
===Error handling===
−
TODO: Since the Authority Agent performs multiple communications between different external components and some data and structure validations are performed, the Authority Agent needs to monitor all failure points and be able to identify them in order to build the corresponding messages and warnings to inform each external component. When an error happens, the corresponding component creates an error message with the information about the error to be sent back to the entity that sent the failed message.
+
The Authority Agent includes methods monitoring the communication between the REST API and the Aries agent and internal database, and it records produced log messages into an internal log file for easier metric monitoring (the ''de4a-metrics-log.txt'' file is automatically created in the ''/usr/local/tomcat/logs'' in the AA API Docker container). During each API request, the Authority Agent records error messages to the log file along with the information about the component that generated the message, the internal code and description of the message.  
 
===Logging messages===
 
===Logging messages===
−
TODO: Within the data flow and message exchange, there are many key points where it is important to know how the data is being managed, as well as identifying intermediate errors and unhandled system states. In this respect, the Connector can send messages to a Kafka server to track the data flow and trace the state of the system at certain points.
 
−
 
−
This feature is an advantage from a technical and business point of view, as the Connector performs the message exchange transparently to the other components.
 
−
 
−
It should be noted that the messages sent to the Kafka server are hardcoded, it is not a parameterizable feature, so any enhancements must be hardcoded again and deployed. It has been developed in such a way because the necessity of a Kafka server is not expected outside the DE4A project. In a real scenario, an alternative way of collecting logs should be implemented.
 
 
====Message types====
 
====Message types====
−
The Connector implements a Kafka message producer through the de4a-kafka-client library of the de4a-commons package. This producer provides several types of messages or severity levels:
+
The Authority Agent implements a custom DE4A Logger, which is responsible for producing a pre-defined format of the log message. The Logger provides the following types of messages:
−
*'''Success'''
 
 
*'''Info'''
 
*'''Info'''
−
*'''Warn'''
 
 
*'''Error'''
 
*'''Error'''
−
*'''Fatal error'''
+
Those basic message categories are used to record success or failure of individual operations executed within each API method call.
−
Those message categories can be easily used to specify the severity level of the message sent to the Kafka server to track and identify them.
 
 
====List of messages====
 
====List of messages====
−
The messages currently sent from the Connector to the Kafka server are as follows:
+
The messages currently logged by the Authority Agent are as follows:
  
 
'''Services''' – ''(Info level)''
 
'''Services''' – ''(Info level)''
−
*RequestTransferEvidenceIM message received - RequestId: <code>{0}</code>, CanonicalEvidenceType: <code>{1}</code>, DataEvaluator: <code>{2}</code>, DataOwner: <code>{3}</code>
+
 
−
*
+
* {0}: Received input eIDAS user data.
−
'''AS4''' – ''(Info level)''
+
* {0}: Received input userId data.
−
*Sending request message via AS4 gateway - DataEvaluatorId: <code>{0}</code>, DataOwnerId: <code>{1}</code>, CanonicalEvidenceType: <code>{2}</code>
+
* {0}: Generated DID invitation for edge agent.
 +
* {0}: Received input evidence data.
 +
* {0}: Signed a Verifiable Credential.
 +
* {0}: Sent a Verifiable Credential to the edge agent.
 +
* {0}: Accepted a submitted Verifiable Presentation.
 +
* {0}: Decoded input eIDAS user data.
 +
* {0}: Validated the digital signature of the submitted VP.
 +
* {0}: Validated the subject of the submitted VP.
 +
* {0}: Received HTTP response code: {1} from endpoint: {2}.
 +
* {0}: Processing the JSON response received from /{1}.
 +
* {0}: Stored current state in {1} internal database.
 +
* {0}: Received user {1} status data.
 +
* {0}: Converted input evidence in format: {1} to format: {2}.
 +
* {0}: Received response data PIID: {1}.
 +
* {0}: Found a {1} action match with PIID: {2}.
 +
* {0}: Found a Verifiable Presentation with name: {1}.
 +
* {0}: Found a Verifiable Presentation with ID: {1}.
 +
* {0}: Issuer DID has already been generated and registered in EBSI.
 +
* {0}: Successfully created files for EBSI integration.
 +
* {0}: Successfully generated key: {1}, value: {2}.
 +
* {0}: Successfully exported JWK private key.
 +
* {0}: Successfully imported DID document into Aries.
 
*
 
*
 +
 
'''Errors''' – ''(Error level)''
 
'''Errors''' – ''(Error level)''
−
*The corresponding request to the received response is not found on database - RequestId: <code>{0}</code>
+
 
 +
The following list of error messages are recorded on the Communications, Internal failure and Configuration layers:
 +
 
 +
* Connection error with {0} - {1}
 +
* Error on response from {0} - {1}
 +
* Arguments missing or invalid at {0} - {1}
 +
* Object conversion error on {0} - {1}
 +
* Error accessing/saving data on {0} - {1}
 +
* Error generating {0} key.
 +
* Error exporting JWK private key.
 +
* Error importing DID document into Aries.
 +
* Configuration error occurred on {0}.
 +
 
 
*
 
*
 
----[1] The <code>{x}</code> symbols are placeholders for dynamic text to be logged.
 
----[1] The <code>{x}</code> symbols are placeholders for dynamic text to be logged.
 
===Data management===
 
===Data management===
−
TODO: The Connector stores and manages certain information such as DE endpoints (not to be confused with SMP endpoints), DO endpoints, certain request records for asynchronous response matching, etc. All this data and where to find it is described in the following subsections.
+
The Authority Agent stores and manages certain information about the DID connections with students' mobile wallets, VC/VP status (e.g. VC offer sent, accepted/rejected, VP request send, VP received, etc.) and its internal EBSI-compliant DID(s).
−
====DID Information====
 
−
Once each Data Owner is publishing his Connector service information on the SMP, the request will arrive to that Connector service configured on the SMP (via the AS4 Gateway), and considering that one Connector could be serving to multiples DOs, this Connector has to know the addressing (base endpoint, without path name) information related to a specific participant identifier (e.g. iso6523-actorid-upis::9999:egov) to send forward the request to the corresponding Data Owner, so due to that, the Connector maintains a table, named  '''''<code>owner_addresses</code>''''', with two columns:
 
−
*'''AgentUrn''': participant identifier in the DE4A format, ''e.g., iso6523-actorid-upis::9999:ess2833002e –'' see the “DE4A Policy for use of identifiers” for further information about the participant identifiers policy.
 
−
*'''Endpoint''': base endpoint URL of the Data Owner who is exposing the service <code>/requestExtractEvidence</code>
 
−
The information above will be used by a Connector playing the Transferor role when the ''RequestExtractEvidence'' message is being sent.
 
−
 
 
−
==== DID Connection Status ====
 
−
 
 
−
==== VC Status ====
 
−
 
 
−
==== VP Status ====
 
  
 
==Technology used==
 
==Technology used==
Line 84: Line 100:
  
 
====System core architecture====
 
====System core architecture====
−
The SSI Authority Agent works as standalone Java EE application that runs different web services according to the RESTful API architecture principles. The application is built with the following tools:
+
The SSI Authority Agent includes several Docker containers necessary for successfull installment (HyperLedger Aries, CouchDB, Aries webhooks, REST API, etc.), where the Authority Agent REST API is the component responsible for the communication between the Evidence/eProcedure portal and the HL Aries agent. The API is implemented as a standalone Java EE application deployed as a WAR file to the Docker container. The application is built with the following tools:
 
*Maven
 
*Maven
 
*Java EE 16
 
*Java EE 16
 
====Third party libraries====
 
====Third party libraries====
−
TODO: As part of the bunch of libraries used by the Authority Agent, there are some of the related with the core features and which represent a starting point for the functionalities provided by the Authority Agent.
+
To achieve its functionality, the Authority Agent uses some external, third-party libraries explained in the folowing paragraphs.
 
=====Walt.ID library=====
 
=====Walt.ID library=====
−
The Walt.ID library is a set of shared utility functions used in the Authority Agent to perform common tasks that are required for a safe and interoperable data exchange. In the initial iteration the latest version of the TOOP Connector technical components were reused mainly for the usage of the built-in phase4 AS4 Gateway. Other elements of the TOOP Connector are currently ignored.
+
The Walt.ID library is an open-source library for implementing self-sovereign identity functionality. It comes with a set of shared utility functions, whereby the Authority Agent (AA) uses the functions necessary to interact with the EBSI registries through EBSI/eSSIF APIs (generating EBSI-compliant DID, onboarding the DID into the EBSI DID Registry, checking if the diploma issuer is registered in the EBSI Trusted Issuer Registry). The library is used both by the EBSI connector (component of the Authority Agent running on the AA REST API startup) as well as directly by the AA REST API during the diploma validation.
−
*Author: ''Walt.ID''
+
*Author: ''Walt.ID (recently open-sourced)''
−
*Repository:  
+
*Repository: [https://github.com/walt-id/waltid-ssikit]
 
=====Jackson =====
 
=====Jackson =====
−
Set of Java libraries to build Java web applications.
+
Set of Java libraries to parse JSON data when building Java web applications.
−
*Author:
+
*Author: open-source
−
*Repository:  
+
*Repository: [https://github.com/FasterXML/jackson]
 
====Data management====
 
====Data management====
 
To manage the model and the data stored by the SSI Authority Agent the following technologies are used:
 
To manage the model and the data stored by the SSI Authority Agent the following technologies are used:
 
*'''Ektorp:''' A Java Persistence API that used CouchDB as the underlying storage engine. It is used to persist data between Java objects and the CouchDB database.  
 
*'''Ektorp:''' A Java Persistence API that used CouchDB as the underlying storage engine. It is used to persist data between Java objects and the CouchDB database.  
−
====Utilities libraries====
+
 
−
TODO: The project uses several libraries and utilities to process and transform the data. They can be divided according to their nature:
+
=== Edge Agent ===
−
*'''Commercial libraries'''
+
 
−
To perform common and non-business operations on web and data exchange projects, the Connector uses different commercial solutions, also all the libraries embedded in the Java development kit.
+
==== System core architecture ====
−
*'''In-house solutions'''
+
The SSI Edge Agent works as standalone mobile device application that runs different components to implement SSI approach. The application is built with Android Studio using Kotlin language.
−
The Connector project includes some utilities that allow the data processing and internal tools to perform all the Connector tasks. Those utilities are within the Connector project as a module called ''de4a-commons.''
+
 
 
==Installation and configuration==
 
==Installation and configuration==
  
Line 111: Line 127:
  
 
====Installation====
 
====Installation====
−
//TODO: enter information from the WP5 Github.
+
The installation guidelines are available at https://github.com/de4a-wp5/ssi-authority-agent.
−
 
 
−
As a prerequisite to deploy the SSI Authority Agent is to have at least Java 16 and Apache Maven 3.6 or later installed.
 
−
 
 
−
You should be able to compile entire packages from the parent POM file:
 
−
 
 
−
mvn clean install
 
−
 
 
−
It is also possible to compile each package separately by browsing to the folder and running the command above.
 
−
=====Package=====
 
−
The compilation process will be packaging the project into a <code>.war</code> file located on <code>/target/</code> path, which should be deployable on any applications server. If you compile the parent pom, the IDK and Connector target paths will be created with their corresponding <code>war</code> files.
 
−
*'''de4a-commons'''
 
−
de4a-commons project is now on maven central OSS Sonatype repository
 
−
*'''Toop version v2.1.2-SNAPSHOT'''
 
−
Due to the lastest changes on de4a-commons Toop-connector-ng version should be <code>2.1.2-SNAPSHOT</code>, so you may need to add following repo server on your maven settings
 
−
 
 
−
https://oss.sonatype.org/content/repositories/snapshots/
 
 
====SSI Authority Agent configuration guide====
 
====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:
−
*<code>application.properties</code>: main system configuration
+
*<code>.env</code>: main system configuration (Aries agent, public IP address and ports, CouchDB database)
−
*<code>phase4.properties</code>: AS4 gateway configurations
+
*<code>docker-compose.yml</code>: general script for deploying the SSI Authority Agent containers
−
*<code>log4j2.xml</code>: logging configuration
+
*<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)
−
Bellow, a working example of the <code>application.properties</code> file:<pre># Database properties
+
Bellow, a working example of the <code>app.properties</code> file:<pre>db.ip.address=http://couchdb.de4a.eu:5984/
−
database.datasourceConf.url=jdbc:h2:mem:testdb
+
db.username=<INSERT DB administrator username>
−
database.datasourceConf.driverClassName=org.h2.Driver
+
db.password=<INSERT DB administrator password>
−
database.datasourceConf.username=sa
+
db.name=<INSERT DB name>
−
database.datasourceConf.password=password
+
alias=<INSERT ORGANIZATION ALIAS NAME>
−
database.datasourceConf.initializationMode=always
+
aries.enterprise.ip.address=http://<INSERT_PUBLIC_DOMAIN_HERE>:8082/
−
database.datasourceConf.jpaHibernate.dialectPlatform=org.hibernate.dialect.H2Dialect
+
signature.type=Ed25519Signature2018
−
database.datasourceConf.jpaHibernate.ddlauto=create-drop
+
bearer.token=<INSERT session token>
−
database.datasourceConf.jpaHibernate.generateddl=true
+
</pre>From now on, we will explain the main and most critical configuration.
−
database.datasourceConf.jpaHibernate.namingStrategy=org.hibernate.cfg.ImprovedNamingStrategy
+
===== System configuration =====
−
database.datasourceConf.jpaHibernate.showSql=true
+
The basic system configuration necessary for successful communication between Authority Agent components is listed in the <code>.env</code> 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.datasourceConf.jpaHibernate.formatSql=true
 
  
−
# H2 in-memory database console port (default 21080)
+
<pre>DOMAIN=<INSERT_PUBLIC_DOMAIN_HERE>
−
h2.console.port=21080
+
....
 +
COUCHDB_IMAGE=couchdb
 +
COUCHDB_IMAGE_TAG=3.1
 +
COUCHDB_PORT=5984
 +
COUCHDB_USER=<INSERT_COUCHDB_USER_HERE>
 +
COUCHDB_PASSWORD=<INSERT_COUCHDB_PASSWORD_HERE></pre>
  
−
# i18n properties
+
===== Database properties =====
−
spring.messages.basename=messages/messages
+
Regarding database configuration and structure, the component creates a CouchDB database, which name is specified in the <code>app.properties</code> configuration file:
−
spring.messages.default_locale=en
+
<pre>
 +
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>
 +
</pre>
  
−
# Spring allowing override beans
+
===== Authority Agent REST API application.properties =====
−
spring.main.allow-bean-definition-overriding=true
+
Besides the general system and database configurations, you must also specify the following properties to successfully run the REST API:
 +
*<code>alias</code> of your Authority Agent, which will be displayed to the user when sending invitations for connecting agents (e.g. MIZŠ Slovenia).
 +
*<code>aries.enterprise.ip.address</code> is the URL to the HL Aries government agent to which the REST API will send HTTP requests.
 +
*<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 <code>Ed25519Signature2018</code> type.
 +
*<code>bearer.token</code> refers to the token obtained from the [https://app.preprod.ebsi.eu/users-onboarding/ 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.
  
−
# Charset encoding
+
====Starting up the SSI Authority Agent====
−
server.servlet.encoding.charset=UTF-8
+
Once you have all configuration parameters well configured, you can start the Docker containers by running the <code>docker-compose.yml</code> file.  
−
server.servlet.encoding.enabled=true
 
−
server.servlet.encoding.force=true
 
  
−
# SSL context enabled (true|false)
+
The CouchDB database GUI will be available at <code>http://<IP ADDRESS:5984>/_utils</code>.
−
ssl.context.enabled=false
 
  
−
# SSL configuration (optional when ssl.context.enabled is false, otherwise, it must be configured)
+
Once started, you can test if the Authority Agent is working properly by checking the current DID connection status for a random user ID (note: replace IP ADDRESS:PORT with your Authority Agent server address). The following request is made:
−
#ssl.keystore.type=
+
curl -X 'GET' \
−
#ssl.keystore.path=
+
  'http://<IP ADDRESS:PORT>/v1/did-conn-status/alice' \
−
#ssl.keystore.password=
+
  -H 'accept: application/json'
−
#ssl.truststore.path=
+
Please note that the Authority Agent accepts only incoming requests via the HTTP protocol at the moment, so the API URL in your curl requests should start with <code>http://</code> instead of <code>https://</code>.
−
#ssl.truststore.password=
 
  
−
# Global flags for initializer
+
The above request should return <code>-1</code>, as there is no DID connection for user ID "alice" at the beginning.
−
global.debug = true
 
−
global.production = false
 
  
−
# Instance name for logging
+
The flow of API requests for the DP side is the following:
−
global.instancename = dev-from-ide
 
  
−
# DE4A Kafka settings
+
#<code>/generate-invitation</code>
−
de4a.kafka.enabled=true
+
#<code>/did-conn-status/{userId}</code>
−
# Enables the standard logging separately of the Kafka messages. It is necessary for print metrics messages - (default: true)
+
#<code>/send-vc-offer</code>
−
de4a.kafka.logging.enabled=true
+
#<code>/check-offer-vc-response/{userId}</code>
−
# Enables Kafka connection via HTTP (Only enable HTTP mode if outbound TCP connections are blocked from your internal network)
+
#<code>/send-vc</code>
−
de4a.kafka.http.enabled=false
 
  
−
# Kafka server address (Eg.: de4a-dev-kafka.egovlab.eu:9092)
+
The flow of API requests for the DC side is the following:
−
de4a.kafka.url=de4a-dev-kafka.egovlab.eu:9092
 
−
# Uncomment the following property and remove the above one if HTTP mode is enabled
 
−
# de4a.kafka.url=https://de4a-dev-kafka.egovlab.eu
 
  
−
# Establish a topic on kafka tracker - Pattern: de4a-<country-code>-<partner-name> - Eg.: de4a-se-egovlab - (default: de4a-connector)
+
#<code>/generate-invitation</code>
−
de4a.kafka.topic=de4a-connector
+
#<code>/did-conn-status/{userId}</code>
 +
#<code>/send-vp-request</code>
 +
#<code>/check-request-vp-response/{userId}</code>
 +
#<code>/validate-vp/{userId}</code>
  
−
# Logging metrics messages prefix - Default: DE4A METRICS
+
===Edge Agent===
−
log.metrics.prefix=DE4A METRICS
 
  
−
# toop legacy kafka properties (Do not touch)
+
====Installation====
−
toop.tracker.enabled = false
 
−
 
 
−
# DSD base URL (Do not modify)
 
−
toop.dsd.service.baseurl = http://dsd.dev.exchange.toop.eu
 
−
 
 
−
# What AS4 implementation to use?
 
−
toop.mem.implementation = phase4
 
  
−
# Our AS4 sending AP endpoint (holodeck)
+
To install the Edge Agent, it is necessary to install the DE4A Mobile App in a mobile device.
−
#toop.mem.as4.endpoint = http://localhost:8083/tc-webapp/as4
 
  
−
# Domibus server endpoint
+
=====Requirements=====
−
# domibus.endpoint=
+
To install the DE4A Mobile app in a mobile device, these are the requirements needed:
  
−
# SMP Client configuration stuff - Do not modify (default values)
+
*Android Operating System installed (version android 9.0 or superior)
−
smpclient.truststore.type = JKS
+
*Recommended 2Gb RAM and 1Ghz processor
−
smpclient.truststore.path = truststore/de4a-truststore-test-smp-pw-de4a.jks
+
*Fingerprint reader
−
smpclient.truststore.password = de4a
 
  
−
# Spring As4 gateway implementation bean(provided: phase4GatewayClient and domibusGatewayClient).Implements eu.toop.as4.client.As4GatewayInterface
+
=====Steps=====
−
as4.gateway.implementation.bean=phase4GatewayClient
+
*'''Download''' The apk is available here: https://github.com/de4a-wp5/de4a-mobile-app
−
 
 
−
# External endpoints
 
−
# SMP endpoint Eg.: https://de4a-smp.egovlab.eu/
 
−
smp.endpoint=
 
−
# IDK endpoint Eg.: https://de4a-dev-idk.egovlab.eu/
 
−
idk.endpoint=
 
−
 
 
−
# IM response timeout
 
−
as4.timeout.miliseconds=30000
 
−
 
 
−
# Properties to create the http client connection through a proxy (optional)
 
−
#http.proxy.enabled=
 
−
#http.proxy.address=
 
−
#http.proxy.port=
 
−
#http.proxy.non-proxy=
 
−
#http.proxyUsername=
 
−
#http.proxyPassword=
 
−
 
 
−
# Required renamed proxy configuration for BDXRClient (if is needed, only uncomment)
 
−
#http.proxyHost=${http.proxy.address}
 
−
#http.proxyPort=${http.proxy.port}
 
−
#http.nonProxyHosts=${http.proxy.non-proxy}
 
−
</pre>From now on, we will explain the main and most critical configuration.
 
−
=====Database properties=====
 
−
Regarding database configuration and structure, the component creates an in-memory database through an H2 DB Engine, which will be created and deleted on each execution.
 
−
*'''Datasource parameters'''
 
−
<pre>
 
−
spring.datasource.url=jdbc:h2:mem:testdb
 
−
spring.datasource.driverClassName=org.h2.Driver
 
−
spring.datasource.username=sa
 
−
spring.datasource.password=password
 
−
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect
 
−
spring.datasource.initialization-mode=always
 
−
spring.jpa.hibernate.ddl-auto=create-drop
 
−
spring.jpa.generate-ddl=true
 
−
</pre>On the previous properties you also can specify any driver o connection configuration in order to stablish the connection to any database engine.
 
−
*'''H2 in-memory database console'''
 
−
In order to access and manage information stored, until an external environment is created, the Connector expose H2 server engine console on the port defined by the property:
 
−
 
 
−
<code>h2.console.port=21080</code>
 
−
 
 
−
By default, even if you do not define the property (non-empty), port will be 21080, so you will be able to access through the following direction pattern:
 
−
 
 
−
<code>http://<host-endpoint>:<portH2Console></code>
 
−
=====SSL Context (not for AS4) application.properties=====
 
−
 
 
−
You can configure secure HTTP connections from the Connector by setting the following property to <code>true</code>:<pre>
 
−
# SSL context enabled (true|false)
 
−
ssl.context.enabled=true
 
−
</pre>In this case you should properly configure the following properties in order to create an SSL context for HTTP communications:<pre>
 
−
# SSL configuration (optional when ssl.context.enables is false)
 
−
ssl.keystore.type= #(JKS|PKCS12)
 
−
ssl.keystore.path= #(Path to keystore where signing private key are included)
 
−
ssl.keystore.password= #(Private key password)
 
−
ssl.truststore.path= #(JKS truststore)
 
−
ssl.truststore.password= #(Truststore password)
 
−
</pre>In the case that you disabled the SSL context property, you should configure the corresponding JVM parameters to specify the truststore, keystore, etc. or the further actions depending of your environment configuration.
 
−
====Starting up the SSI Authority Agent====
 
−
Once you have all configuration parameters well configured (if not, check the logs to find out the problem), it is time to deploy the component into an applications server. Once you have deployed the <code>war</code> file or the docker image, there are several checks to ensure that the deployment was successful:
 
−
*Open Swagger UI browsing: <code><nowiki>http://host:port/swagger-ui/</nowiki></code>
 
−
­     E.g.:
 
−
*DE4A Connector index page will be at root path: <code><nowiki>http://host:port/</nowiki></code>
 
−
­     E.g.:
 
−
*The Connector will be able to process requests through the following interfaces:
 
−
­    
 
−
*Accessing to CouchDB database: <code><nowiki>http://host:h2.console.port/</nowiki></code>
 
−
 
 
−
=== Edge Agent ===
 
−
 
 
−
====Installation====
 
−
 
 
−
To install the Edge Agent, it is necessary to install the DE4A Mobile App in Android mobile device.
 
−
*'''Download''' The apk is available here: [https://github.com/de4a-wp5/de4a-mobile-app https://github.com/de4a-wp5/de4a-mobile-app]
 
 
*'''Set-up''' Once the app is downloaded, tap on the apk file to open it. The Android device will prompt for allowing apps from an unknown sources to be installed.<gallery>
 
*'''Set-up''' Once the app is downloaded, tap on the apk file to open it. The Android device will prompt for allowing apps from an unknown sources to be installed.<gallery>
 
File:Mobile insta 1.png|Allow apps from unknown source
 
File:Mobile insta 1.png|Allow apps from unknown source
−
</gallery>The user has to tap on “Settings” button and the settings menu will appear with the following option for allowing the apps installation from this source, and to turn off this setting after the installation: [[File:Edge agent install 2.png|left|thumb|185x185px|Install apps from unknown sources setting]]
+
</gallery>The user has to tap on “Settings” button and the settings menu will appear with the following option for allowing the apps installation from this source, and to turn off this setting after the installation: [[File:Edge agent install 2.png|thumb|185x185px|Install apps from unknown sources setting|alt=|none]]
 +
 
 +
====User guide====
 +
The user manual can be found here: https://github.com/de4a-wp5/de4a-mobile-app/blob/master/DE4A%20Mobile%20App%20Manual%20v0.2.pdf

Latest revision as of 08:41, 8 January 2022

Introduction

The SSI Agent infrastructure is established through the use of the SSI Authority and Edge agents. The SSI Authority Agent is an enterprise-level solution to be deployed on the premises of organizations that act as diploma Issuers (Data Providers) or Verifiers (Data Consumers), while the Edge Agent is a mobile solution, which can be used by the end users (in case of the SA pilot, students) to interact with the Authority Agent.

  • Conceptual view of the DP technical flow.

    Conceptual view of the DP technical flow.

  • Conceptual view of the DC technical flow.

    Conceptual view of the DC technical flow.

SSI Authority Agent

Functionalities provided

The main purpose of the SSI Authority Agent is to provide functionalities related to establishing a DID connection between the Hyperledger Aries agent deployed on the organization's premises and the user's Edge Agent as well as issuing the user's diploma as a Verifiable Credential (Data Provider) or request and validate the submitted diploma in the form of a Verifiable Presentation (Data Consumer). The Authority Agent also facilitates the communication with EBSI ledgers for storing the information about the trusted diploma issuers and their EBSI-compliant DIDs used for digitally signing the issued verifiable credentials and validating the issuers of submitted verifiable presentations.

Generate and issue an EBSI-compliant DID for the organization

In order to digitally sign verifiable credentials for the users, which can later be validated by the Verifier, the DID used for signing must be trustworthy and publicly available. To achieve this, the information about organizations listed as trusted diploma issuers and their DIDs is anchored to EBSI ledgers, where it can be accessed by calling the DID and Trusted Issuers Registry REST APIs. This information is produced on the Authority Agent startup by the underlying EBSI Connector component, which makes sure that the necessary keys are generated and imported to the cloud HL Aries agent, so that they can be used to sign the verifiable credentials. During the VP validation, the Authority Agent is then able to retrieve and resolve the DID information from the EBSI ledgers to validate the diploma issuer.

Establish DID connection between agents

The first step necessary in the diploma issuance/submission flow is to establish a secure connection between the Evidence Portal/eProcedure Portal and the user's Edge Agent (i.e. digital wallet). This is done by generating a QR code to be displayed on the portal side, which includes information about the DID invitation generated by the Authority Agent. The user can use his/her mobile application to scan the QR code and accept the DID invitation. Once this is done, a DID connection is established between the two agents (specifically, between the two HL Aries agents in the background). This step is a pre-condition needed to uniquely identify the two agents that will echange messages in the later flow.

Issue a Verifiable Credential

Once deployed on the Data Provider side, the Authority Agent supports the process of issuing a diploma in the form of a Verifiable Credential (VC) digitally signed with an EBSI-compliant DID of the Issuer. The VC information is retrieved from the received diploma evidence data in the canonical XML format. Sending the Verifiable Credential produced by the Authority Agent includes sending the VC offer for the user to preview the included data, followed by actually sending the Verifiable Credential once the offer is accepted.

Receive and validate a Verifiable Presentation

If deployed on the Data Consumer side, the Authority Agent enables organizations to request a diploma in the form of Verifiable Presentations from the students. In that case, a student can directly submit his/her diploma from the mobile wallet to the eProcedure Portal. Once received, the Portal can validate several aspects of the diploma validity: schema, digital signature, issuer and subject.

Supported interaction patterns

Interaction patterns define the flow of data through the Connector and the intercommunication between the different components. Each pattern exchanges certain types of messages, and the incoming/outgoing information will depend on the processes occurring in the external components [3].

The SSI Authority Agent currently supports the following interaction pattern:

  • Verifiable Credentials (VC) pattern
    • ­Synchronous communication between the SSI Authority and Edge Agent.
    • The Mediator component enables the correct routing between multiple Edge Agents (multiple users) and the Authority Agent deployed on DR or DT premises.
    • Since the interaction flow is managed by the user, the Data Requestor does not need to communicate directly with the Data Owner.

SSI Authority Agent roles

A SSI Authority Agent instance can play two different roles:

  • Data Requestor (DR)
  • Data Transferor (DT)

No configuration is needed to differentiate the roles, it only depends on the usage, i.e., the behaviour will be according to the messages sent.

Error handling

The Authority Agent includes methods monitoring the communication between the REST API and the Aries agent and internal database, and it records produced log messages into an internal log file for easier metric monitoring (the de4a-metrics-log.txt file is automatically created in the /usr/local/tomcat/logs in the AA API Docker container). During each API request, the Authority Agent records error messages to the log file along with the information about the component that generated the message, the internal code and description of the message.

Logging messages

Message types

The Authority Agent implements a custom DE4A Logger, which is responsible for producing a pre-defined format of the log message. The Logger provides the following types of messages:

  • Info
  • Error

Those basic message categories are used to record success or failure of individual operations executed within each API method call.

List of messages

The messages currently logged by the Authority Agent are as follows:

Services – (Info level)

  • {0}: Received input eIDAS user data.
  • {0}: Received input userId data.
  • {0}: Generated DID invitation for edge agent.
  • {0}: Received input evidence data.
  • {0}: Signed a Verifiable Credential.
  • {0}: Sent a Verifiable Credential to the edge agent.
  • {0}: Accepted a submitted Verifiable Presentation.
  • {0}: Decoded input eIDAS user data.
  • {0}: Validated the digital signature of the submitted VP.
  • {0}: Validated the subject of the submitted VP.
  • {0}: Received HTTP response code: {1} from endpoint: {2}.
  • {0}: Processing the JSON response received from /{1}.
  • {0}: Stored current state in {1} internal database.
  • {0}: Received user {1} status data.
  • {0}: Converted input evidence in format: {1} to format: {2}.
  • {0}: Received response data PIID: {1}.
  • {0}: Found a {1} action match with PIID: {2}.
  • {0}: Found a Verifiable Presentation with name: {1}.
  • {0}: Found a Verifiable Presentation with ID: {1}.
  • {0}: Issuer DID has already been generated and registered in EBSI.
  • {0}: Successfully created files for EBSI integration.
  • {0}: Successfully generated key: {1}, value: {2}.
  • {0}: Successfully exported JWK private key.
  • {0}: Successfully imported DID document into Aries.

Errors – (Error level)

The following list of error messages are recorded on the Communications, Internal failure and Configuration layers:

  • Connection error with {0} - {1}
  • Error on response from {0} - {1}
  • Arguments missing or invalid at {0} - {1}
  • Object conversion error on {0} - {1}
  • Error accessing/saving data on {0} - {1}
  • Error generating {0} key.
  • Error exporting JWK private key.
  • Error importing DID document into Aries.
  • Configuration error occurred on {0}.

[1] The {x} symbols are placeholders for dynamic text to be logged.

Data management

The Authority Agent stores and manages certain information about the DID connections with students' mobile wallets, VC/VP status (e.g. VC offer sent, accepted/rejected, VP request send, VP received, etc.) and its internal EBSI-compliant DID(s).

Technology used

SSI Authority Agent

System core architecture

The SSI Authority Agent includes several Docker containers necessary for successfull installment (HyperLedger Aries, CouchDB, Aries webhooks, REST API, etc.), where the Authority Agent REST API is the component responsible for the communication between the Evidence/eProcedure portal and the HL Aries agent. The API is implemented as a standalone Java EE application deployed as a WAR file to the Docker container. The application is built with the following tools:

  • Maven
  • Java EE 16

Third party libraries

To achieve its functionality, the Authority Agent uses some external, third-party libraries explained in the folowing paragraphs.

Walt.ID library

The Walt.ID library is an open-source library for implementing self-sovereign identity functionality. It comes with a set of shared utility functions, whereby the Authority Agent (AA) uses the functions necessary to interact with the EBSI registries through EBSI/eSSIF APIs (generating EBSI-compliant DID, onboarding the DID into the EBSI DID Registry, checking if the diploma issuer is registered in the EBSI Trusted Issuer Registry). The library is used both by the EBSI connector (component of the Authority Agent running on the AA REST API startup) as well as directly by the AA REST API during the diploma validation.

  • Author: Walt.ID (recently open-sourced)
  • Repository: [1]
Jackson

Set of Java libraries to parse JSON data when building Java web applications.

  • Author: open-source
  • Repository: [2]

Data management

To manage the model and the data stored by the SSI Authority Agent the following technologies are used:

  • Ektorp: A Java Persistence API that used CouchDB as the underlying storage engine. It is used to persist data between Java objects and the CouchDB database.

Edge Agent

System core architecture

The SSI Edge Agent works as standalone mobile device application that runs different components to implement SSI approach. The application is built with Android Studio using Kotlin language.

Installation and configuration

SSI Authority Agent

Installation

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

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)

Bellow, a working example of the app.properties 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>
alias=<INSERT ORGANIZATION ALIAS NAME>
aries.enterprise.ip.address=http://<INSERT_PUBLIC_DOMAIN_HERE>:8082/
signature.type=Ed25519Signature2018
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: 

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>
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, you must also specify the following properties to successfully run the REST API:

  • alias of your 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 you have all configuration parameters well configured, you can start the Docker containers by running the docker-compose.yml file.

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

Once started, you can test if the Authority Agent is working properly by checking the current DID connection status for a random user ID (note: replace IP ADDRESS:PORT with your Authority Agent server address). The following request is made: 

curl -X 'GET' \
  'http://<IP ADDRESS:PORT>/v1/did-conn-status/alice' \
  -H 'accept: application/json'

Please note that the Authority Agent accepts only incoming requests via the HTTP protocol at the moment, so the API URL in your curl requests should start with http:// instead of https://.

The above request should return -1, as there is no DID connection for user ID "alice" at the beginning.

The flow of API requests for the DP side is the following:

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

The flow of API requests for the DC side is the following:

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

Edge Agent

Installation

To install the Edge Agent, it is necessary to install the DE4A Mobile App in a mobile device.

Requirements

To install the DE4A Mobile app in a mobile device, these are the requirements needed:

  • Android Operating System installed (version android 9.0 or superior)
  • Recommended 2Gb RAM and 1Ghz processor
  • Fingerprint reader
Steps
  • Download The apk is available here: https://github.com/de4a-wp5/de4a-mobile-app
  • Set-up Once the app is downloaded, tap on the apk file to open it. The Android device will prompt for allowing apps from an unknown sources to be installed.

    • Allow apps from unknown source

    The user has to tap on “Settings” button and the settings menu will appear with the following option for allowing the apps installation from this source, and to turn off this setting after the installation:

    Install apps from unknown sources setting

    User guide

    The user manual can be found here: https://github.com/de4a-wp5/de4a-mobile-app/blob/master/DE4A%20Mobile%20App%20Manual%20v0.2.pdf

    Retrieved from ‘https://wiki.de4a.eu/index.php?title=DE4A_SSI_Authority_and_Edge_Agent&oldid=3967’