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.
Before you can start you need to have the following information in place:
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.xpeppol-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!
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.
/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.
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:
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).
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.
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.
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.
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.
Now that your new SMP server is up and running, you should perform some setup tasks.
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.
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.
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
}