Difference between revisions of "DE4A SSI Authority Agent"

From DE4A
Jump to navigation Jump to search
m (Updated headings.)
m
 
(7 intermediate revisions by one other user not shown)
Line 1: Line 1:
−
 
+
The SSI Authority Agent is an enterprise-level solution, which is part of the SSI agent infrastructure together with the [[DE4A SSI Edge Agent|SSI Edge agent]] and it serves to support the [[Verifiable Credentials Pattern|Verifiable Credentials]] pattern. The SSI Authority Agent is to be deployed on the premises of organizations that act as diploma Issuers (Data Providers) or Verifiers (Data Consumers). Its code is available here: [https://github.com/de4a-eu/ssi-authority-agent]<gallery>
−
==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.<gallery>
 
 
File:Conceptual view of the DP technical flow..png|alt=Conceptual view of the DP technical flow.|Conceptual view of the DP technical flow.
 
File:Conceptual view of the DP technical flow..png|alt=Conceptual view of the DP technical flow.|Conceptual view of the DP technical flow.
 
File:Conceptual view of the DC technical flow..png|alt=Conceptual view of the DC technical flow.|Conceptual view of the DC technical flow.
 
File:Conceptual view of the DC technical flow..png|alt=Conceptual view of the DC technical flow.|Conceptual view of the DC technical flow.
 
</gallery>
 
</gallery>
−
==SSI Authority Agent==
+
==Functionalities provided==
−
===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.
 
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====
+
===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.
 
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====
+
===Establish DID connection between agents===
 
The first step necessary in the diploma issuance/submission flow is to establish a secure connection between the [https://wiki.de4a.eu/index.php/Evidence_Portal Evidence Portal]/[https://wiki.de4a.eu/index.php/EProcedure_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.
 
The first step necessary in the diploma issuance/submission flow is to establish a secure connection between the [https://wiki.de4a.eu/index.php/Evidence_Portal Evidence Portal]/[https://wiki.de4a.eu/index.php/EProcedure_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====
+
===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.
 
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====
+
===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.
 
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 20: Line 17:
  
 
The SSI Authority Agent currently supports the following interaction pattern:
 
The SSI Authority Agent currently supports the following interaction pattern:
−
*'''Verifiable Credentials (VC) pattern'''
+
*'''[[Verifiable Credentials Pattern|Verifiable Credentials (VC) pattern]]'''
 
**­Synchronous communication between the SSI Authority and Edge Agent.
 
**­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.
 
**The Mediator component enables the correct routing between multiple Edge Agents (multiple users) and the Authority Agent deployed on DR or DT premises.
Line 30: Line 27:
 
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.
 
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===
 
===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.
+
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===
+
The following list of messages is recorded by the Authority Agent:
−
====Message types====
+
{| class="wikitable"
−
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:
+
|'''Component'''
−
*'''Info'''
+
|'''Level'''
−
*'''Error'''
+
|'''Template'''
−
Those basic message categories are used to record success or failure of individual operations executed within each API method call.
+
|'''Specific text message'''
−
====List of messages====
+
|-
−
The messages currently logged by the Authority Agent are as follows:
+
|AA
 +
|I
 +
|01
 +
|{APIMethod}: Received input eIDAS user data.
 +
|-
 +
|AA
 +
|I
 +
|02
 +
|{APIMethod}: Received input userId data.
 +
|-
 +
|AA
 +
|I
 +
|03
 +
|{APIMethod}: Generated DID invitation for edge agent with ID  {UUID}.
 +
|-
 +
|AA
 +
|I
 +
|04
 +
|{APIMethod}: Received input evidence data.
 +
|-
 +
|AA
 +
|I
 +
|05
 +
|{APIMethod}: Signed a Verifiable Credential.
 +
|-
 +
|AA
 +
|I
 +
|06
 +
|{APIMethod}: Sent Verifiable Credential {VC Id} to the edge agent  under invitation {UUID} from {DO URI}.
 +
|-
 +
|AA
 +
|I
 +
|07
 +
|{APIMethod}: Accepted a submitted Verifiable Presentation.
 +
|-
 +
|AA
 +
|I
 +
|08
 +
|{APIMethod}: Decoded input eIDAS user data.
 +
|-
 +
|AA
 +
|I
 +
|09
 +
|{APIMethod}: Validated the digital signature of the submitted VP.
 +
|-
 +
|AA
 +
|I
 +
|10
 +
|{APIMethod}: Validated the subject of the submitted VP.
 +
|-
 +
|AA
 +
|I
 +
|11
 +
|{APIMethod}: Received HTTP response code: {ResponseCode} from  endpoint: {Endpoint}.
 +
|-
 +
|AA
 +
|I
 +
|12
 +
|{APIMethod}: Processing the JSON response received from  /{AriesAPIMethod}.
 +
|-
 +
|AA
 +
|I
 +
|13
 +
|{APIMethod}: Stored current state in {Component} internal  database.
 +
|-
 +
|AA
 +
|I
 +
|14
 +
|{APIMethod}: Received user {DataObject} status data.
 +
|-
 +
|AA
 +
|I
 +
|15
 +
|{APIMethod}: Converted input evidence in format: {Format} to format: {Format}.
 +
|-
 +
|AA
 +
|I
 +
|16
 +
|{APIMethod}: Received response data PIID: {PIID}.
 +
|-
 +
|AA
 +
|I
 +
|17
 +
|{APIMethod}: Found a {DataObject} action match with PIID: {PIID}.
 +
|-
 +
|AA
 +
|I
 +
|18
 +
|{APIMethod}: Found a Verifiable Presentation with name: {VPName}.
 +
|-
 +
|AA
 +
|I
 +
|19
 +
|{APIMethod}: Found a Verifiable Presentation with ID: {VPID}.
 +
|-
 +
|AA
 +
|I
 +
|20
 +
|{APIMethod}: Received Verifiable Credential {VC Id} at the  verifier {DE URI} under invitation {UUID}
 +
|-
 +
|AA
 +
|I
 +
|21
 +
|{APIMethod}: Validated Verifiable Credential {VC Id} of type {CanonicalEvidenceTypeUri}  under invitation {UUID} for {DE URI}.
 +
|-
 +
|AA
 +
|I
 +
|22
 +
|{APIMethod}: Sent Offer for Verifiable Credential {VC Id} of type  {CanonicalEvidenceTypeUri} under invitation {UUID} from {DO URI}.
 +
|-
 +
|AA
 +
|I
 +
|23
 +
|{Component}: Issuer DID has already been generated and registered  in EBSI.
 +
|-
 +
|AA
 +
|I
 +
|24
 +
|{Component}: Successfully created files for EBSI integration.
 +
|-
 +
|AA
 +
|I
 +
|25
 +
|{Component}: Successfully generated key: {KeyType}, value:  {Value}.
 +
|-
 +
|AA
 +
|I
 +
|26
 +
|{Component}: Successfully exported JWK private key.
 +
|-
 +
|AA
 +
|I
 +
|27
 +
|{Component}: Successfully imported DID document into Aries.
 +
|-
 +
|AA
 +
|I
 +
|28
 +
|{APIMethod}: Overwriting  DID connection with ID {old invitation ID} to {new invitation ID} .
 +
|-
 +
|AA
 +
|I
 +
|29
 +
|{APIMethod}: DID  connection has been established for invitation ID {invitation ID}.
 +
|-
 +
|AA
 +
|I
 +
|30
 +
|{APIMethod}:  Validated the issuer of the submitted VP.
 +
|-
 +
|AA
 +
|I
 +
|31
 +
|{APIMethod}:  Validated the schema of the submitted VP.
 +
|-
 +
|AA
 +
|I
 +
|32
 +
|{APIMethod}: Event  notification of type ‘{event type}’ has been successfully sent to {frontend  URI}. Received HTTP response code: {response code}.
 +
|-
 +
|AA
 +
|I
 +
|33
 +
|{Component}: Successfully  anchored DID {did} for organization {organization alias} into the EBSI DID  Registry.
 +
|-
 +
|AA
 +
|E
 +
|01
 +
|Connection error with {destination component}: {inherited error  message}
 +
|-
 +
|AA
 +
|E
 +
|02
 +
|Error on response from {error source component}: {inherited error  message}
 +
|-
 +
|AA
 +
|E
 +
|03
 +
|Object conversion error in {error source component}: {inherited  error message}
 +
|-
 +
|AA
 +
|E
 +
|04
 +
|Error accessing/saving data on {error source component}:  {inherited error message}
 +
|-
 +
|AA
 +
|E
 +
|05
 +
|Missing or invalid arguments at {service requested}: {missing  arguments}
 +
|-
 +
|AA
 +
|E
 +
|06
 +
|Error generating {key} key.
 +
|-
 +
|AA
 +
|E
 +
|07
 +
|Error exporting JWK private key.
 +
|-
 +
|AA
 +
|E
 +
|08
 +
|Error importing DID document into Aries.
 +
|-
 +
|AA
 +
|E
 +
|09
 +
|Configuration error occurred on {error source component}
 +
|-
 +
|AA
 +
|E
 +
|10
 +
|Event notification  of type ‘{event type}’ could not be sent: {inherited error message}
 +
|-
 +
|AA
 +
|E
 +
|11
 +
|Error anchoring DID  {did} into EBSI DID Registry: {inherited error message}
 +
|}
  
−
'''Services''' – ''(Info level)''
+
===Data management===
−
*{0}: Received input eIDAS user data.
+
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).
−
*{0}: Received input userId data.
+
==Implementation prerequisites==
−
*{0}: Generated DID invitation for edge agent.
+
In the second iteration, the interaction flow of the VC pattern has been made simpler for the students. Consequently, there were changes in the Authority Agent's implementation in terms of the number of REST API calls needed to complete the interaction. The Authority Agent now relies on using webhook technology in its interaction with the HL Aries agent to detect any action (e.g. DID invitation acceptance) on the student's side. This change has the following implications on the flow implementation:  
−
*{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:
+
# The Authority Agent REST API includes the /webhook endpoint, which registers any changes in the status of the interaction between two HL Aries agents (issuer's/verifier's and student's agent). The endpoint processes incoming events registered when a student accepts a DID connection invitation, accepts a VC offer and accepts a VP submission request (i.e. submits VP);
−
*Connection error with {0} - {1}
+
# The Evidence/eProcedure Portal needs to include an additional POST API method, which will act as a listener to any status events received from the Authority Agent;
−
*Error on response from {0} - {1}
+
# The Evidence/eProcedure Portal needs to implement a realtime mechanism for refreshing the view (screen) displayed to the student depending on the status changes. Depending on the already existing Portal implementation, this can be either Single Page Application (SPA), WebSockets or something else.  
−
*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.
 
−
===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==
 
==Technology used==
 
===System core architecture===
 
===System core architecture===
Line 101: Line 283:
 
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.
−
 
−
==Installation and configuration==
 
−
===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:
 
−
*<code>.env</code>: main system configuration (Aries agent, public IP address and ports, CouchDB database)
 
−
*<code>docker-compose.yml</code>: general script for deploying the SSI Authority Agent containers
 
−
*<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>app.properties</code> file:<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>
 
−
alias=<INSERT ORGANIZATION ALIAS NAME>
 
−
aries.enterprise.ip.address=http://<INSERT_PUBLIC_DOMAIN_HERE>:8082/
 
−
signature.type=Ed25519Signature2018
 
−
bearer.token=<INSERT session token>
 
−
</pre>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 <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:<pre>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></pre>
 
−
====Database properties====
 
−
 
−
Regarding database configuration and structure, the component creates a CouchDB database, which name is specified in the <code>app.properties</code> configuration file:<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>
 
−
====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:
 
−
*<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 [https://wiki.de4a.eu/index.php/EBSI_Connector 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 <code>docker-compose.yml</code> file.
 
−
 
−
The CouchDB database GUI will be available at <code>http://<IP ADDRESS:5984>/_utils</code>.
 
−
 
−
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 <code>http://</code> instead of <code>https://</code>.
 
−
 
−
The above request should return <code>-1</code>, 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:
 
−
#<code>/generate-invitation</code>
 
−
#<code>/did-conn-status/{userId}</code>
 
−
#<code>/send-vc-offer</code>
 
−
#<code>/check-offer-vc-response/{userId}</code>
 
−
#<code>/send-vc</code>
 
−
The flow of API requests for the DC side is the following:
 
−
#<code>/generate-invitation</code>
 
−
#<code>/did-conn-status/{userId}</code>
 
−
#<code>/send-vp-request</code>
 
−
#<code>/check-request-vp-response/{userId}</code>
 
−
#<code>/validate-vp/{userId}</code>
 

Latest revision as of 13:47, 16 April 2023

The SSI Authority Agent is an enterprise-level solution, which is part of the SSI agent infrastructure together with the SSI Edge agent and it serves to support the Verifiable Credentials pattern. The SSI Authority Agent is to be deployed on the premises of organizations that act as diploma Issuers (Data Providers) or Verifiers (Data Consumers). Its code is available here: [1]

  • 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.

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. The following list of messages is recorded by the Authority Agent:

Component Level Template Specific text message
AA I 01 {APIMethod}: Received input eIDAS user data.
AA I 02 {APIMethod}: Received input userId data.
AA I 03 {APIMethod}: Generated DID invitation for edge agent with ID {UUID}.
AA I 04 {APIMethod}: Received input evidence data.
AA I 05 {APIMethod}: Signed a Verifiable Credential.
AA I 06 {APIMethod}: Sent Verifiable Credential {VC Id} to the edge agent under invitation {UUID} from {DO URI}.
AA I 07 {APIMethod}: Accepted a submitted Verifiable Presentation.
AA I 08 {APIMethod}: Decoded input eIDAS user data.
AA I 09 {APIMethod}: Validated the digital signature of the submitted VP.
AA I 10 {APIMethod}: Validated the subject of the submitted VP.
AA I 11 {APIMethod}: Received HTTP response code: {ResponseCode} from endpoint: {Endpoint}.
AA I 12 {APIMethod}: Processing the JSON response received from /{AriesAPIMethod}.
AA I 13 {APIMethod}: Stored current state in {Component} internal database.
AA I 14 {APIMethod}: Received user {DataObject} status data.
AA I 15 {APIMethod}: Converted input evidence in format: {Format} to format: {Format}.
AA I 16 {APIMethod}: Received response data PIID: {PIID}.
AA I 17 {APIMethod}: Found a {DataObject} action match with PIID: {PIID}.
AA I 18 {APIMethod}: Found a Verifiable Presentation with name: {VPName}.
AA I 19 {APIMethod}: Found a Verifiable Presentation with ID: {VPID}.
AA I 20 {APIMethod}: Received Verifiable Credential {VC Id} at the verifier {DE URI} under invitation {UUID}
AA I 21 {APIMethod}: Validated Verifiable Credential {VC Id} of type {CanonicalEvidenceTypeUri} under invitation {UUID} for {DE URI}.
AA I 22 {APIMethod}: Sent Offer for Verifiable Credential {VC Id} of type {CanonicalEvidenceTypeUri} under invitation {UUID} from {DO URI}.
AA I 23 {Component}: Issuer DID has already been generated and registered in EBSI.
AA I 24 {Component}: Successfully created files for EBSI integration.
AA I 25 {Component}: Successfully generated key: {KeyType}, value: {Value}.
AA I 26 {Component}: Successfully exported JWK private key.
AA I 27 {Component}: Successfully imported DID document into Aries.
AA I 28 {APIMethod}: Overwriting DID connection with ID {old invitation ID} to {new invitation ID} .
AA I 29 {APIMethod}: DID connection has been established for invitation ID {invitation ID}.
AA I 30 {APIMethod}: Validated the issuer of the submitted VP.
AA I 31 {APIMethod}: Validated the schema of the submitted VP.
AA I 32 {APIMethod}: Event notification of type ‘{event type}’ has been successfully sent to {frontend URI}. Received HTTP response code: {response code}.
AA I 33 {Component}: Successfully anchored DID {did} for organization {organization alias} into the EBSI DID Registry.
AA E 01 Connection error with {destination component}: {inherited error message}
AA E 02 Error on response from {error source component}: {inherited error message}
AA E 03 Object conversion error in {error source component}: {inherited error message}
AA E 04 Error accessing/saving data on {error source component}: {inherited error message}
AA E 05 Missing or invalid arguments at {service requested}: {missing arguments}
AA E 06 Error generating {key} key.
AA E 07 Error exporting JWK private key.
AA E 08 Error importing DID document into Aries.
AA E 09 Configuration error occurred on {error source component}
AA E 10 Event notification of type ‘{event type}’ could not be sent: {inherited error message}
AA E 11 Error anchoring DID {did} into EBSI DID Registry: {inherited error message}

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).

Implementation prerequisites

In the second iteration, the interaction flow of the VC pattern has been made simpler for the students. Consequently, there were changes in the Authority Agent's implementation in terms of the number of REST API calls needed to complete the interaction. The Authority Agent now relies on using webhook technology in its interaction with the HL Aries agent to detect any action (e.g. DID invitation acceptance) on the student's side. This change has the following implications on the flow implementation:

  1. The Authority Agent REST API includes the /webhook endpoint, which registers any changes in the status of the interaction between two HL Aries agents (issuer's/verifier's and student's agent). The endpoint processes incoming events registered when a student accepts a DID connection invitation, accepts a VC offer and accepts a VP submission request (i.e. submits VP);
  2. The Evidence/eProcedure Portal needs to include an additional POST API method, which will act as a listener to any status events received from the Authority Agent;
  3. The Evidence/eProcedure Portal needs to implement a realtime mechanism for refreshing the view (screen) displayed to the student depending on the status changes. Depending on the already existing Portal implementation, this can be either Single Page Application (SPA), WebSockets or something else.

Technology used

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: [2]

Jackson

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

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

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.
Retrieved from ‘https://wiki.de4a.eu/index.php?title=DE4A_SSI_Authority_Agent&oldid=5986’