This page explains how to setup my implementation of an OpenPEPPOL SMP from scratch. SMP is the abbreviation for Service Metadata Publisher which is the decentralized directory service of OpenPEPPOL. SMPs are normally only operated by Service Providers and not by endpoints. An SMP contains information about the endpoints of receivers - the URLs where to send the main documents to. The information within the SMP is structured by participant ID, document type ID and process ID.

phoss SMP is a fork of the CIPA e-Delivery SMP components on version 2.2.3. The goal is to keep the implementation simple and provide publicly available PEPPOL components to the world. An additional goal was to make the configuration as simple as possible. Please read the official SMP Server Wiki for all the details.

Prerequisites

Before you can start you need to have the following information in place:

  1. As the very first step you need to sign the TIAs (Transport Infrastructure Agreements) with OpenPEPPOL AISBL
  2. Afterwards you need to apply for an SMP certificate at OpenPEPPOL. This certificate is required to run the SMP.
  3. You should have a look at the official SMP specifications. It is important to understand that the specifications only specify the reading access to an SMP but not the writing access. Nevertheless the implementation discussed here also contains the possibility to write new entries.
  4. You should be familiar with Java 1.8+
  5. When using the SMP server implementation with a database backend basic knowledge of a relational database (e.g. MySQL) is required
  6. Basic knowledge about Apache Tomcat or Jetty (and optionally a web server) should be present

Technical resources

My phoss SMP server implementation is located on GitHub at peppol-smp-server. It contains the source code and a Wiki with the relevant documentation. Previously I had two separate versions - one with an SQL backend and one with an XML backend - but I now decided to merge these versions so that both backends can use the benefits of the management GUI. The backend can now be chosen via a configuration file property. The SMP servers uses shared components also available on GitHub: peppol-commons - a common library with shared PEPPOL components containing an SMP client library and an SML client library.

The sources and the binary resources are available on GitHub:

The technical SMP resources are divided into the following elements:

  • peppol-smp-server-library - A common used library with everything needed for an SMP server except the backend and the GUI.
  • peppol-smp-server-sql - The SQL backend implementation. Tested with MySQL 5.x
  • peppol-smp-server-xml - The XML backend implementation.
  • peppol-smp-server-webapp - The common parts for the web application.
  • peppol-smp-server-webapp-sql - The main web application with an SQL backend. It provides the GUI and assembles everything together.
  • peppol-smp-server-webapp-xml - The main web application with an XML backend. It provides the GUI and assembles everything together.
  • peppol-smp-client - An SMP client library to be used to access any SMP server.

Note: an SMP client for the console is currently not offered. If you need it, just drop me a note, and I will implement one.

All of the components are available as ready-to-use Eclipse projects. The easiest way to build the projects is therefore to import the projects into Eclipse.

Hint when using Eclipse: it is best to close the project in Eclipse when a commandline build is performed because otherwise Eclipse might want to refresh while the console build is in progress. After the build finished you may re-open the project in Eclipse and clean it there again, because the Eclipse compiler and the Oracle console compiler produce incompatible byte code for enumeration classes!

peppol-smp-server-webapp

This is the main SMP server application. It is provided as a Java web application that can be deployed in an application server like Apache Tomcat or Jetty.

The SMP service has been implemented as a REST interface with a backend that stores the data.

  • peppol-smp-server-sql uses a relational database as its backend. A copy of the MySQL database initialization script can be found in the /database_backups/ folder of the project. By default a user peppol_user with the password Test1234 is created! The database layout is compatible to the one of the CIPA SMP.
  • peppol-smp-server-xml uses XML files as its backend. smp-servicegroup.xml stores all the service groups, smp-servicemetadata.xml stores all the service metadata associated to the service groups and smp-redirect.xml stores all the service redirects related to a service group. Additional files for user management etc. are also used.

The application can be deployed in two ways:

  • Compiling the project on the command line using mvn clean install. The result is a WAR file in the target folder and additionally an exploded version of the WAR file in the target/peppol-smp-server-webapp-x.y.z directory (where x.y.z denotes the version number).
  • Run the application src/test/java/com/helger/peppol/smpserver/standalone/RunInJettySMPSERVER from within Eclipse. Than the application will be running on localhost port 80 and can be accessed with a browser or an SMP client.
Note that the SMP service MUST be deployed as the ROOT web application (at path "/") on the application server, since this is a prerequisite in the DNS lookup scheme. Furthermore it MUST be deployed on port 80 (standard http port) and may not use SSL to secure the transport.

Configuring the SMP server

The SMP server is configured with two files. One file (webapp.properties) is for the customization of the web application and the other file (smp-server.properties) is for the SMP functionality itself. Please read the Wiki page https://github.com/phax/peppol-smp-server/wiki/Configuration for all configuration options and example files.

Security considerations

As the SMP is publicly available on HTTP port 80 and does not require a client certificate or anything the like it especially the modifying actions (HTTP PUT and DELETE) must be handled with special care to avoid man in the middle attacks. Even though HTTP BasicAuth is used this is not really added security, as the username and password are only Base64 encoded - which is easily decodable - and are therefore vulnerable to Man in the Middle attacks.

The recommended scenario is to additionally configure the SMP to run on HTTPS (on any port other than 80), and do the modifying actions only via HTTPS. BasicAuth is required anyway but the data is not readable by third-parties because of the underlying transport security. This is something that is currently technically not available but should be used as a convention when running an SMP with this implementation. For a future release it may be of value when the modifying actions are presented with a separate path prefix (e.g. /secure) which can than easily be used to forward all HTTP request on /secure/* to HTTPS automatically.

Initialization

Now that your new SMP server is up and running, you should perform some setup tasks.

  • Change the default user admin@helger.com with the default password password to something more complex! This can be easily achieved by logging into the URL http://yourserver/secure and use the Change password page to perform the change.
  • When using the SQL backend, change the default DB user peppol_user with the default password Test1234 to something more complex! This can be easily achieved on the management page "DB users" or by altering the content of the database table smp_user manually. After this change, simply provide the new credentials for writing operations.
  • The SMP must be registered at the SML. For this purpose an online tool is integrated in this page to perform this task.

peppol-smp-client

This is the default Java library to query any SMP server (that is compliant to the specifications) for participant information. The client library has the sole purpose to provide reusable functionality. It does not offer executable functionality itself.

The com.helger.peppol.smpclient.SMPClient is the main class when using the library. The class contains methods for reading, saving and deleting both service groups and service metadata, as well as listing the service groups of a given user. The writing methods of this class can only be used in conjunction with the my SMP server or the CIPA SMP server as for different implementation the write access may have been implemented in a different way. Alternatively the class com.helger.peppol.smpclient.SMPClientReadonly can be used to access any SMP that complies to the SMP specifications. The library contains both static and non-static methods for performing all of these actions. The class is documented using JavaDoc.

The following is an example code of getting a service metadata object of a service group (participant) for a certain document type:

    // ServiceGroup = participant identifier; GLN = 0088
    final IParticipantIdentifier aServiceGroupID = EPredefinedIdentifierIssuingAgency.GLN.createParticipantIdentifier ("5798000000001");
    // Document type identifier from enumeration
    final IDocumentTypeIdentifier aDocumentTypeID = EPredefinedDocumentTypeIdentifier.INVOICE_T010_BIS4A.getAsDocumentTypeIdentifier ();
    // Main call to the SMP client with the correct SML to use
    final SignedServiceMetadataType aMetadata = SMPClientReadOnly.getServiceRegistrationByDNS (PeppolURLProvider.INSTANCE,
                                                                                               ESML.DIGIT_TEST,
                                                                                               aServiceGroupID,
                                                                                               aDocumentTypeID);
    if (aMetadata == null)
    {
      // No such metadata
    }
    else
    {
      // Evaluate metadata
    }
  

You must be logged in to post a comment!