DomiSMP

The identifier uniquely identifies DomiSMP entities such as resources (e.g., ServiceGroups) and subresources (e.g., ServiceMetadata). The identifiers are being used in the URL requests as part of the URL request path segment, and also in the (sub)resource documents.

Example of the URL request (scheme:‘oasis:names:tc:ebcore:partyid-type:iso6523:0088’, value:‘4035811991021’) concatenated with single colon, :.

Example of the document element with the participant identifier split to scheme attribute and element value:

Creation or removal of ServiceGroup within SMP triggers a synchronous (un)registration of relevant record(s) in DNS. This process is required to allow Dynamic Discovery of SMPs to store Participant’s metadata.

Write access to DNS zone is facilitated by BDMSL (SML), a centralized application that exposes a SOAP interface for that purpose (see eDelivery BDMSL (SML). SMP is a consumer of the SML services. SML authorization of SMP is based on mutual HTTPS authentication. Therefore, SMP client TLS certificate with private key needs to be configured on SMP side.

If SMP serves data in only one domain, then a single certificate is needed. Otherwise, if the SMP is configured to work in multi-domain mode, the System Administrator will need to set up one certificate per subdomain.
See also Domain Multitenancy and Configuration, for more details.

An SML subdomain can be considered as a set of an inter-network of eDelivery components: SML, SMPs and Access Points for a business domain. All these members communicate with each other within that subdomain and exchange messages according to the strict rules defined for that business domain. One network can be used to exchange invoices between participants, another one could exchange health information between hospitals and insurance companies, etc.

In most scenarios there will be multiple SMPs in a single business domain and each of them will handle ServiceMetadata sets of multiple participants from the same subdomain. The business domain authority can set its own SMP to administrate its participants and the SMP is used only in one domain. But an SMP could be used in more than one business domain at the same time. Because of SML restrictions such setup implies the following SMP functionality:

Roles are documented with more details in the SMP Interface Description guide. The table below explains their meaning from a functional perspective:

The DomiSMP supports 3-layer security realms.

An example of the Resource is the “Service Group” document from the Oasis SMP specification.

The user can be a Resource member with Admin or Viewer membership roles. If the user has an Admin membership role, it can modify resource document(s) and manage the resource memberships. If the user has role Viewer, it can view/read the Resource if the Resource has visibility set to: “Private”.

One of the main DomiSMP sample implementation purpose is enabling the setup (and testing) of various network configurations. Designed with flexibility in mind, DomiSMP allows the implementation of custom logic of the document processing. To achieve this, developers can create custom extensions. These extensions are packaged as JAR files and extend one or more interface classes from the DomiSML module eu.europa.ec.edelivery:smp-spi.

Example of how to include an extension in your custom extension project:

The extension JAR must be added to the DomiSMP extension library path before starting up the application. The path where the extensions must be deployed is defined with file property: smp.libraries.folder.

An example:

Extension folder
path where SMP extensions are located. The Folder is loaded by the SMP classloader at startup.

smp.libraries.folder=/cef/test/smp/apache-tomcat-8.5.73/smp/ext-lib

DomiSMP 5.0.x supports two types of extensions:

In the next section we describe both extensions in more detail.

When the DomiSMP library is loaded by the class loader, the extension registrar searches for Spring beans that implement the “ExtensionInfo” interface. These beans provide essential information about the extensions.

One of the most important purposes of DomiSMP is to allow users to publish various connectivity capability documents for serving or business message exchange. Examples of these documents include OASIS SMP 1.0 and OASIS SMP 2.0 documents, as well as ServiceGroup and ServiceMetadata documents, CPP from Oasis CPPA3, and any other text-based custom documents.

The resource extension enables the following tasks:

When creating a resource handling extension, developers must implement the ResourceDefinitionSpi and optionally the SubresourceDefinitionSpi. These interfaces contain the resource definition such as identifier, version name, document mimetype, etc.

The ResourceDefinitionSpi and SubresourceDefinitionSpi contain the resource handling extension metadata for the Resources/Subresources. To process the document, the resource and subresource implementation must also contain the implementation of the ResourceHandlerSpi which handles the document processing such as: generation of empty document, validation of the document, and methods which are invoked while reading and storing the document.

To increase security, the eDelivery SMP offers the possibility of registering custom extensions for security scanning/validations of all binary documents such as the certificates and the keystores. The certificates can be uploaded by the users when setting the user certificate for authentication. The keystores binaries can be uploaded by the System Administrators when managing the SMP keystore.

When the user loads one of the mentioned payloads, the eDelivery SMP validation framework is activated. At this point, the payload binary data is passed to all registered spring beans, which implement the PayloadValidatorSpi interface below.

The implementers of the extension must implement the method validatePayload for payload validation. In the event of malware detection, the method MUST throw the PayloadValidatorSpiException to terminate the future payload handling by the eDelivery SMP.

A simple example of the PayloadValidatorSpi implementation can be found in the SMP project module smp-examples/smp-spi-example/. See Souce Code Overview.

To register the extension in the eDelivery SMP, the interface implementation class must be

as in the example below:

To prepare the extension for the deployment in the eDelivery SMP, the code must be compiled and stored in the java archive file format known as the JAR.

In the eDelivery SMP, the property libraries.folder must be configured in the smp.config.properties to point to the folder where extension libraries are located.
The SMP classloader loads the libraries in the folder at the startup of the SMP and registers the PayloadValidatorSpi beans.

SMP is a Java REST application shipped and packaged as a .war file.

The SMP project uses Maven 3 for its build process and dependency management.
Below is a description of SMP’s Maven project structure.

The SMP application is built with SpringFramework, the context is set up by classes with @Configuration annotations which are organized hierarchically. List of configuration classes, sample classes defining dependencies, scanning rules in packages and importing another context configuration are presented below.

The top layer, implemented within the smp-webapp module, uses Spring MVC’s framework. Both resources (ServiceGroup, ServiceMetadata) have a dedicated Controller implementation. Each controller has 3 public methods (GET, PUT, and DELETE) which share the same URL defined by @RequestMapping annotation at the Controller class level.

A sample method definition, utilizing also metadata transferred in the request headers is presented below.

This layer is responsible for: REST binding, security validation, request data validation, forwarding request to services layer and forwarding response back to the caller and for error handling.
See more details in the Security section.

The business logic is implemented within the smp-server-library module. Business logic is implemented as ServiceGroup and ServiceMetadata Services. Module contains additional classes for Integration with BDMSL, signing messages and transaction handling with use of Spring @Transactional annotation and TransactionManager.

Because the SMP is a small application without need of polymorphism, the implementation does not use interface patterns for its services.

The BDMSL integration used by ServiceGroupService is implemented by BDMSLConnector. Participant’s (un)registration is called synchronously as the last action Service’s method to make sure that any potential RuntimeException causes rollback of the whole transaction, including database changes.

To support multiple domains functionality BDMSLClientFactory was introduced. Its responsibility is to create and preconfigure client (BDMSLConnector) to set up needed HTTP headers, configure proxy, manage client X509 Certificate, for each domain.
See also Domain Multitenancy.

As functionally described in ebCore party identifier:

The eDelivery SMP has the feature to support handling participant identifiers as described in Use with eDelivery ebCore Party Identifiers, in the eDelivery SMP profile. In this case, the participant starts with the: urn:oasis:names:tc:ebcore:partyid-type: following by the words: unregistered or iso6523.

All ebCore party identifiers in the REST request must be URL-encoded using only one double colon separator :, as in the example below:

urn:oasis:names:tc:ebcore:partyid-type:iso6523:0088:4035811991021URL-encoded

example:

urn%23oasis%23names%23tc%23ebcore%23partyid-type%23iso6523%230088%234035811991021

The eDelivery SMP has the option to serialize ebCore party Id to XML according to the OASIS SMP Specification as separate values, as in the example below:

or according to the eDelivery SMP profile as concatenated value:

See Configuration for more info on the configuration of this behaviour.

Identifier’s case sensitivity" and Configuration is implemented by the CaseSensitivityNormalizer bean. Normalization is performed at the very beginning of each service method processing. Also, by separating this to a dedicated bean, normalization can be used as well for permissions verification in connection with Spring Security’s @PreAuthorize annotation:

The SMP stores data in a relational database. MySQL and Oracle DDL scripts are released with the application in smp-setup.zip file. The database object relations are presented in the following figure:

Besides all the necessary metadata used by the DomiSMP business logic, the database is also used to store XML documents in table (oracle: blob, mysql: TEXT type). The Resources and Subresources store versions of the document into the table SMP_DOCUMENT_VERSION. The documents are stored as a binary data because it could be electronically signed by Resource owner. Decomposing and composing XML could compromise the xml signature. When a user is querying for the resource/subresource, the original xml is returned with a valid xml signature.

The Java data access layer is implemented within the smp-server-library module. DataSource, EntityManager and TransactionManager are configured and registered into Spring context in the DatabaseConfig class.

Java classes located in eu.europa.ec.edelivery.smp.data.model package define the Model with the use of JPA2 annotations. All model classes implement the BaseEntity interface. Separate @Embeddable classes are defined for all composite primary keys:

All DAO classes located in the eu.europa.ec.edelivery.smp.data.dao package extend the BaseDao generic abstract class that already provides most common DAO operations (find, remove, etc.).

See some samples below:

Detailed functional description of all errors that might occur is presented in the SMP Interface Description guide. This section presents a generalized view on error groups and focuses on implementation perspective.

eDelivery SMP utilizes HTTP error codes according to the best RESTful recommendations, i.e., given codes are always returned for:

The OASIS SMP Specification does not specify error messages, so eDelivery SMP introduces its own simple XSD with XML namespace: ec:services:SMP:1.0.

This one describes the structure of error response messages as in sample below:

Classpath:

The SMP requires configuration file: smp.config.properties to be placed in the classpath. On tomcat server custom classpath folder (e.g. /conf_dir_path) can be set by modifying the starting scripts in the same way as for WebLogic, or by adding this entry in context.xml file:

NLS_CHARACTERSET must be set to AL32UTF8, otherwise SMP will face issues with non-ASCII characters.

Character set, collation and especially JDBC connection protocol encoding – all must be set to UTF-8, otherwise SMP will face issues with non-ASCII characters.

The Authentication Manager (id = smpAuthenticationManager) utilizes two Authentication One handles basic username/ password authentication and the second is SpringSecurity implementation PreAuthenticatedAuthenticationProvider class configured to handle X509Certificate and BlueCoat authentication. The pre-authenticated scenarios take precedence over basic authentication. That means if a client provided a valid certificate and also valid username and password, then he is logged in using his certificate and username/password is ignored.

Standard SpringSecurity mechanism is used to verify username and BCrypt hashed passwords using the SMPAuthenticationProvider. Username/Password authentication can be used for the UI authentication.

eDelivery SMP uses different credentials for UI and for WebService authentication.
The access token is randomly generated access token id and access token value. Together they are used as HTTP basic authentication when invoking the web-services.

Client Certificate authentication can be used only for authentication when invoking the REST API services. The purpose of the certificate authentication is to support mutual 2-way TLS authentication for machine-to-machine integration.

SMP supports two types of Client Certificate authentications: X509 certificate authentication and Authentication behind Reverse Proxy. Both scenarios are performed in 2 steps:

X509Certificate and Certificates HTTP Client-Cert header are validated with the following attributes:

Users that are authenticated by certificate are stored in the SMP_USER table, together with users authenticated by password. The USERNAME value of certificate authenticated users is a string value created from parts of certificate distinguish name (DN) and serial number by the following pattern (eDelivery format):

Application distinguished certificate authenticated users from password-authenticated user by an empty PASSWORD column.

Most eDelivery projects supporting client certificate authentication, utilize the same client certificate text representation and BlueCoat Client-Cert HTTP header patterns. For this reason, custom Java code responsible for client certificate authentication has been extracted and released within a separate JAR library; maven dependency gropuId/artifactId:
eu.europa.ec.edelivery/edelivery-springsecurity-2-way-ssl-auth.

The client X509 certificate authentication uses server’s (Tomcat or WebLogic) certificate authentication settings. After the request passes the server validation successfully, x509AuthFilter extract certificate details and then authentication proceeds in the way as described above.

The filter itself (class EDeliveryX509AuthenticationFilter) is a simple extension of SpringSecurity’s X509AuthenticationFilter class, which is a ready-to-use implementation handling java.security.cert.X509Certificate.

In this setup the basic certificate validation is configured in the BlueCoat reverse proxy. After certificate validation passed successfully, the BlueCoat reverse proxy adds a "Client-Cert" HTTP header and forwards the request to the SMP over HTTP(S). The spring filter blueCoatReverseProxyAuthFilter extracts the header, converts it from Bluecoat’s to the eDelivery format specified above and then authentication proceeds in the way as described above.

The filter itself (class BlueCoatAuthenticationFilter) is based on the SpringSecurity’s RequestHeaderAuthenticationFilter, dedicated for similar scenarios.

CAS authentication can be used only for the UI authentication, and it was made with intention to integrate with ECAS also called EU-Login. ECAS is based on the Central Authentication Service (CAS) version 2 developed at Yale University1. It is an authentication service to protect Web-based applications. SMP was tested only with ECAS, but it should also work with any CAS 2.0 implementation,

When the SMP does not find a service ticket granting access it redirects to EUs login page for user authentication. After user authenticates via the EU login, the response redirects the page back to the SMP UI page with granting ticket.

SMP validates ticket with ECAS. If validation is successful, the SMP authorize access to the user according to user authorization defined on SMP user configuration.

Authorities in SMP are organized into a two-dimensional space, with Roles as first dimension and Error! Reference source not found. as the second one.

Roles are documented with more details in the SMP Interface Description guide. The table below explains their meaning from the implementation perspective:

ICD mentions "System Admin" role, but it’s rather a sysadmin, not the business role to be considered in SMP source code.

Authorities' verification is very flexible thanks to loading all granted authorities to the security context.

The first level of verification is made on HTTP method level. GET is allowed to everybody, while all modifying actions are allowed only to authenticated users, which is configured in spring-security.xml file:

Once all granted authorities are present in the security context, they are validated at the business methods level with SpringSecurity’s annotations and Spring Expression Language (SpEL):

action allowed only for Group Admin, or:

action allowed either for Group Admin or Resource Admin owing the serviceGroupId provided as methods' parameter.

To deploy the SMP on Tomcat, the steps below need to be completed.

The SMP configuration is performed in two different locations, the:

The initial eDelivery SMP configuration is performed via the smp.config.properties file. The file contains basic configuration for defining the database connection, logging file configuration and smp folder for deploying the extensions.

At startup, the application looks for ./smp.config.properties in the classpath. This requires setting up the application server so that it includes the folder with the file in its classpath.

The smp_domain table is used to support the multitenancy feature of the SMP.
Its parameters/fields are:

Update the default single domain smp_domain table record:

or

The eDelivery SMP database back-end configuration is performed within the eDelivery SMP configuration file (smp.config.properties file).

Depending on the selected database back-end, modify the smp.config.properties files as indicated below. SMP database’s connection can be configured in the properties file, or it can use application server datasource configuration by JNDI.

eDelivery SMP uses keystore for storing keys for the two different purposes:

If the Keystore does not exist when the SMP is started for the first time, it is automatically created with a sample key/certificate 'sample_key'.

The user with a system administrator role can update/manage the Keystore entries using the user interface on the
System settings/Keystore page:

eDelivery SMP uses truststore for storing trusted X509Certificates for the WebService 2-way-SSL authentication and for storing the SML server certificate. The truststore is automatically created at the initial SMP start-up. The truststore can be managed with a System admin account using the UI tools under the page System settings / Truststore.

On some systems, generating new passwords and keys can take a long time. To speed up the initial startup, consider the following option:

Users can configure eDelivery SMP to use prepared keystores at initial startup. To achieve this, the Keystore must be generated manually and saved in the SMP security folder. If the Keystore already contains the keys/certificates, they must have the same Key password as it was set for accessing the Keystore.

The following properties must be set in smp.config.properties:

Download and copy smp-X.war file in the Tomcat /webapps directory (AS_HOME/webapps/smp.war).

The BDMSL integration data can be set using the UI Property tool:

Once BDMSL integration data is configured, the next step is to configure the SMP client certificate and ID for the BDMSL authentication. Because SMP 4.2 can handle multiple domains, each domain can have its X509Certificate to log into the correct BDMSL DNS domain.

The DomiSMP supports 3-layer security realms.

The provided database script creates the following users:

The following DomiSMP users can be of three types, as briefly described below:

Users can be added, modified and deleted using the SMP Admin console or directly by executing sql commands. Below are instructions on how to modify users in the dat abase.

To manage DomiSMP users, you can use the DomiSMP UI console.

Use the procedure below to create the first system admin user.
An alternative is to use the provided SQL init scripts and replace passwords by first login.

The DomiSMP uses the BCRYPT algorithm to hash users' passwords. A BCRYPT-hashing tool is bundled with the SMP WAR file.

To get the hashing code:

Adding an SMP user is done by adding a new entry in the SMP database SMP_USER table either directly or via the Administration console.

The User role is set in the SMP_USER table APPLICATION_ROLE column as follows:

In the following examples, a System Admin user is created.

The SMP logging properties are defined in the ./WEB-INF/classes/logback.xml file embedded in the SMP .war file.

It is possible to modify the configuration of the logs by editing the embedded logback.xml or by defining new logback file in smp.config.properties file as example:

log.configuration.file=/opt/apache-tomcat-8.5.30/smp/logback.xml

More details on how to configure logback can be found at:
https://logback.qos.ch/documentation.html