EDCI Code Library : Issuer
Issue degrees, diplomas, certificates of participation or other credentials to your learners. Any school, college, university or training provider in Europe may use this tool to issue credentials for free and secure them with their e-seal. Credentials can be e-mailed to learners or directly deposited to their Europass profiles.
The European Digital Credentials for Learning code is available both in Github and as Docker images.
Angular 7.x (eUI v7.41 - EUI Framework).
Java 8, Spring, JAXB, JPA 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, application server and database, the most tested configuration, the one explained in this document and the one used during development is the following:
Apache Tomcat 8.0
Oracle 12c
linux RedHat
The issuer application is divided into 8 modules that can also be split in two groups, those that are necessary for the app functionality, and extra modules that are not required but provide extra functionality.
The next two projects are shared across by multiple of the EDCI applications and are declared as a maven dependency. As a result, these two projects must be downloaded and compiled (or uploaded to a repository) prior to the EDCI Issuer project for the dependencies to be 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 has functions used for the sealing and validation of the signatures of the credentials using the DSS library. Any change required to the configuration of the DSS module will need to be included 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 the persistence layer of the application with it's DAOs and Repositories, all of the database related methods and queries reside here.
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:
- issuer - General configurations, such as datasources, url paths, remote endpoints...
- dss - Sealing configurations
- mail - SMTP Server properties and related configurations
- proxy - Proxy configurations
- 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 issuer needs to be configured for the particular environment where is going to be deployed, this includes both technical configuration (such as database, mail server...) as well as custom app configurations (QSeal enforce, OIDC security...) All of the configuration is stored in files inside the projects and it consists of value/key pairs. Some of it is included in the artifact at compilation time, and some of it is read from the filesystem by the application. Because of this, the configuration to be used must be decided and 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.
There are some important configurations that need to already present in the application server, namely the database and the mail session.
The mail session must be named mail/Session.
The database datasource must be named jdbc/mare.
- Maven
- node.js and npm - note that NodeJS 10.XX is required
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]
- Application Server - the development has been done in tomcat
- Internet access - the app requires 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
- the application server must have the drivers for your database of choice
- Relational database
If you are trying to deploy the EDCI Issuer project in a tomcat application server, you can check our tomcat configuration page.
The front-end application residing in edci-issuer-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 repositories, 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.
mvn clean install -P [profile]
This section describes the core functions of the issuer app, which allow the application to process, seal and issue credentials. Some of these functions can be done only in one way, other may have multiple options.
This functionality allows to upload multiple credentials or a verifiable presentations in XML format sample of the uploading format with wrapper can be found here. The specific datamodel format for credentials can be found here.
A more in-depth guide on how to upload a verifiable presentation instead of an credential can be found here
This functionality allows to define credential templates through a user interface, which then can be saved into a database. A user may select one of the owned credentials, and send it to any number of recipients.
The Credential templates represent the specifications of a particular credential, without any personal information. These templates contain all of the information regarding the achievements, organisations, environments... that are shared between multiple credentials, which allows mass-issuing of one credential.
A recipient is the subject to which the credential will be issued. After selecting a credential to issue, you will be able to select multiple recipients for the credential. This can be done by either entering them manually on the application itself, or by downloading an auto-generated excel, which you will need to fill and upload for the recipients to be processed.
During processing phase, validations take place. Mandatory fields are defined in the European Learning Model. Also, during processing time assets that may need to be downloaded, like multimedia assets or controlled lists items (check external dependencies section). After the processing, XML files are created inside the configured temporal folder.
During sealing process, the credentials are sealed following configuration properties, after that, the credentials are validated against an Schema, which is also defined at the configuration properties.
Issuing can be done in two ways, wallet uploading and email attachments.
- Wallet Upload : The EDCI Issuer will try to uplad the file to the property configured wallet.
- Email attachment : The EDCI Issuer will try to send an email with the credential attached, based on the email field of the credential itself.
If one of the methods fails, a message is shown.
The EDCI Issuer 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 issuer requires:
The EDCI Issuer makes use of the European Publications Office controlled lists, some of these are mandatory to use for some of the Code fields of the datamodel, you can expand on both of this matters in the datamodel page and the controlled lists page of this document.
The EDCI Issuer makes user of values in the ESCO Framework, to fill the values of certain Code fields. This information is queried through the ESCO Skill API, which must contain the information for the Code field to be correctly processed.
You can find more about the ESCO Framework utilization in EDCI here.
At the issuer_dss_[profile].properties file in the back-end server, it is mandatory to provide a valid TimeStamp provider in the form of URL.
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.
In order to send the attached credential through email, this must be configured. It is required that the email session is defined in the application server configuration as explained in the Configuration section of this document.
All of the extra configurations for this can be found in the mail_[profile].properties file. ##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.
- Preparing Credentials: This page will provide you information on how to prepare your data.
- Macro enabled template: The XLS macro enabled template can be found here
- XML upload format: The XML upload format can be found here.
- Verifiable Presentation format: How to build a verifiable presentation
The Source Code and technical documentation for the EDCI Wallet can be found here.
Here you will find information on the Background and Tech Stack, the project structure and the Core functions from a technical point of view.
Information regarding the required external dependencies such as the OAUTH Identity provider can also be found here.
You will also find information on how to build and deploy the EDCI Wallet from the source code, the project structure and core functions such as wallet creation or sharelink management.
The Source Code and technical documentation for the EDCI Viewer can be found here.
Here you will find information on the Background and Tech Stack, the project structure and the Core functions from a technical point of view.
Keep in mind that for the EDCI Viewer to work in conjunction with an EDCI Wallet, the external dependencies of both, such as the OIDC, must be aligned.
Information regarding the Core visualizing functions can also be found in this document.
For more information, please email us at this address: EMPL-ELM-SUPPORT@ec.europa.eu
Facebook
Twitter
Linkedin
Email