EDCI Code Library: Viewer
The Source Code and technical documentation for the EDCI Issuer can be found on Github.
The EDCI Viewer is an application that provides a user interface from which credentials ca be visualized, verified, exported and shared. The visualization, verification and export of a credential can be done for both, an XML credential, or a credential stored in a wallet. On the other hand, sharing a credential is only possible when the credential is stored in a wallet.
Angular 7.x (eUI v7.4.1 - EUI Framework)
Java 8, Spring, JAXB, Mapstruct and CEF DSS – java library to create/validate e-signature (XAdES, PAdES, etc.)
Although it is possible to change the configuration to work with any OS and application server the most tested configuration, the one explained in this document and the one used during development is the following:
Apache Tomcat 8.0
linux RedHat
The Viewer application is divided into 7 modules that can also be split in 2 groups, those that are necessary for the app functionality, and extra modules that are not required but provide extra functionality.
The edci-commons project is used accros the issuer, which means that edci-commons must be downloaded and compiled (or uploaded to a repository) for the edci-viewer to have this dependency available.
This project contains both utility and service classes that can be used by all of the other projects, as well as the main DataModel classes. Also, common functionalities (such as security or DataModel services) are found in this project.
This module contains classes used by all the other modules, mostly Constants and DTOs that are used across the application.
This module contains most of the business logic, therefore most of the back-end core functions of the app reside here.
This module contains the angular folder with the front-end code of the application, and the index.jsp from which is served. Also, here reside all of the configuration files, as well as external or downloadable resources. It also contains all the configuration properties into the resource folder:
- viewer - General configurations, such as datasources, url paths, remote endpoints...
- security - Session and OIDC configurations
As the swagger codegen maven plugin resides in this module, compilation of this project will result in the typescript swagger files being recreated.
This module contains all of the Rest API endpoints used by the frontend angular components, thus all of the operations externally available reside here. Also, the swagger.json file is generated based on the annotations in this module, and during it's compilation time
This module contains all necessary files for swagger typescript generation, including mustache templates and custom Code Generators.
This module provies an automatic system of API documentation, it will take the swagger.json generated and copy it into this project, which will produce an artifact with the API documentation that can be deployed.
This module is only responsible of packaging all of the modules into an ear file for deployment, thus no code resides here.
The EDCI Viewer needs to be configured for the particular environment where is going to be deployed, this includes both technical configuration (such as log levels, api path...) as well as custom app configurations (OIDC security, associated wallet...) All of the configuration is stored in files inside the projects and it consists of value/key pairs. It is included in the artifact at compilation time. Because of this, the configuration must be set prior to compiling the project.
The project can be configured and compiled with a variety of profiles, which can be used to provide a set of configurations for multiple environments. The profile that is being used is specified at compilation time for both front-end and back-end, and must be the same for both compilation steps. The current supported profiles are:
- default
- local-tomcat
- dev-tomcat
- qa-tomcat
- acceptance
- production
Some of the properties that reside in the project, are used in XML files that are included in the artifact are compile time. Because of this, changing any of these properties requires a recompilation of the project.
The backend files containing properties that can only be changed in compile time reside in the edci-issuer-web module, inside the config folder, here you will find the following folders containing configuration:
- cache: contains ehcache.xml file.
- issuer: contains basic properties for all the profiles.
Also, you will find an ext folder with an example of the files required as run-time configuration properties.
For front-end properties, all of the configurations can be found under the /environments folder, with environment.[profile].ts naming.
A good portion of the properties reside outside of the project, by default, the application expects to found this files in the file:${catalina.base}/conf/edci/issuer/ folder. This path can be changed at the EDCIIssuerConfig class. The expected files are:
- issuer.properties
- issuer_dss.properties
- mail.properties
- proxy.properties
- security.properties
These properties can be changed without recompiling the EDCI Issuer, but keep in mind that the application server must be restarted for the changes to take place.
In order to compile the EDCI Viewer you will need
- Maven
- node.js and npm - note that NodeJS 10.XX is required
- Application Server - the development has been done in tomcat
- Internet accesss - the app requieres access to external resources, a proxy can be configured
- AppServer provided Jar Dependencies in the app server libraries directory:
- apache-log4j-extras-1.2.17.jar
- bcprov-jdk15on-1.62.jar
- javaee-api-7.0.jar
- javax.mail-1.5.0.jar
- jstl-1.2.jar
- log4j-log4j-1.2.17.jar
If you are trying to deploy the EDCI Issuer project in a tomcat application server, you can check our tomcat configuration page.
The source code is stored in this GIT repository: (TODO - repo URL)[REPO url] It can be downloaded easily is by cloning it into it's desired folder with this command:
git clone [TODO - repo URL]
The front-end application residing in edci-Viewer-web must be compiled prior to the backend, to do so, just use the standard npm install command to update your node_modules directory, and after that use npm run build-[profile] scripts. Configuration for these scripts can be found in package.json file. Keep in mind that any change to the API that would change swagger definition, requires a previous compilation of the back-end code.
npm install
npm run build-[profile]
This project uses maven to manage the projects build. Keep in mind that some of the edci-dss-utils project artifacts must be downloaded from specific respositories, Here is an example of a basic maven configuration that can be used as a template (keep in mind that some values must be changed). Once the maven settings are ready, just execute the usual maven command using parent pom.xml with the desired profile, if no one is selected, default is used.
##Core functions This section describes the core functions of the Viewer app, which allow the application visualize, verify and share credentials.
mvn clean install -P [profile]
The main function of the EDCI Viewer back-end is to get and parse the XML information of the credentials and verifiable presentations and serve it to the front-end in a way that is easily read by the angular front-end. This means that all of the XMLs will be parsed and mapped to java objects, and then to JSON. This is done through Mapstruct classes, from which main class involved is EuropassCredentialPresentationMapper, which needs to be modified if any new field is to be send to the frontend. There are two mains forms of mapping and sending the information of the credentials to the front-end, which are available for any visualization method.
When uploading a credential or verifiable presentation XML, the viewer will parse the file and create a java representation of the same, which will in turn be sent in JSON format to the viewer front-end, if the credential uploaded is not readable, a 400 http status code is returned.
When uploading an credential or verifiable presentation XML, the viewer will send the XML to the associated wallet, and then send the response to the front-end. The verification does not take place in the viewer, and because of this no verification logic resides in this project.
The viewer provides the possibility to visualize a credential or verifiable presentation for which no XML file is present but is stored in a wallet. To do this, the user needs to access a particular URL in the application with /#/view/[userId]/[xmlUUid] structure. Also, the credential must be stored in the viewer's associated wallet. Also, both of the systems need to be using the same Identity Provider. The most usual way of a user getting this view URL is either by a wallet email or from a software that can fetch this information in the associated wallet.
The viewer provides the possibility to verify a credential or verifiable presentation for which no XML file is present, but is stored in a wallet. When doing this, the viewer will send a request to the wallet for the validation, and the results will be directly returned to viewer, this means that the validation is not done in the viewer, and the XML actually is never in the viewer. For this functionality to work, both of the systems need to be using the same Identity provider.
The viewer provides two ways to download credentials that are being visualized: XML and PDF.
When exporting an asset, it does not matter if it corresponds to a credential or to a verifiable presentation, it will always be exported as a verifiable presentation, either as XML or PDF format.
A credential that is stored in a wallet can be temporarily shared by the creation of a link with a similar structure to the wallet-stored view URls. This allows to any other user to view the credential during the time that the sharelink is valid.
The EDCI Wallet provides an API to manage this sharelinks, and the EDCI Viewer provides a bridge to the creating sharelink process, meaning that the user can use a tool in the viewer front-end, which will be processed in the back-end and sent to the associated wallet in order to create a sharelink, the response will be sent back to the viewer.
Any operation described in this section that involves an operation over a wallet-stored credential requires that both the viewer and the associated wallet use the same OIDC Identity provider, and that the identity is propagated between the two applications.
When requesting any information from the associated wallet, the viewer will first ask for a new access token to the IDP by using the previously stored refresh token. For this purpose, two grant_types can be used: urn:ietf:params:oauth:grant-type:token-exchange or the refresh_token, the one that is used is defined through the oidc.use.token.exchange property in the security_[profile].properties file.
The EDCI Viewer project has external dependencies which are mandatory, and must be supplied in one way or another, otherwise core functions will be unusable. This means that the EDCI Viewer requires:
Although a mock user can be enabled por testing purposes, an OIDC Identity provider will be required for the credential builder to work properly. All of the required configurations for this can be found in the security_[profile].properties file. All fo this is implemented using the Authentication (Basic) flow. For implementations, spring-security and mitreId are used. If you want to know more about it, an in-depth explanation on the current configuration can be found here. ##Interest Links
- Developer Playground: A developer playground which allows users to build and issue credentials without the need for an e-seal is available here.
For more information, please email us at this address: EMPL-ELM-SUPPORT@ec.europa.eu
Facebook
Twitter
Linkedin
Email