DE4A SSI Authority Agent
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).
Conceptual view of the DP 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.
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
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.