Connector iteration 2 installation and configuration guide

Installation

A prerequisite to build the Connector is to have at least Java 11 and Apache Maven 3.6 or later installed.

You should be able to compile entire packages from the parent POM file:

mvn clean install

It is also possible to compile each package separately by browsing to the folder and running the command above.

Package

The compilation process will be packaging the project into a .war file located on /target/ path, which should be deployable on any applications server.

Latest release version is available at GitHub of WP5.

Before deploying there are 2 files that need to be configured.

application.properties

Both files application.properties and phase4.properties from iteration 1 are now merged into application.properties file.

There are properties listed below that are not present in the application.properties file. Default value will be used if not present, but can be modified depending on your environment requirements.

General

• global.debug = false (boolean) - enable development debug functionality
• global.production = false (boolean) - enable production mode (performance optimizations, less checks)
• global.instancename = de4a-connector-global (string) - this is only used as the log prefix if the tracker is used
• http.tls.trustall = true (boolean) - use this to disable the hostname and trusted certificate check for SSL/TLS connections. Defaults to false. Using true just for testing purposes, not recomended for production.
• http.proxy.enabled (boolean) - is an HTTP proxy needed? Defaults to false.
• http.proxy.address (string) - the URL of the proxy server (including the scheme) (e.g. http://proxy.local)
• http.proxy.port (int) - the port to access the HTTP proxy server (e.g. 8080)
• http.proxy.non-proxy (string) - a list of hosts that should not be proxied. Use the pipe character as the separator for multiple entries (as in localhost|127.0.0.1).
• http.connection-timeout (int) - the HTTP connection timeout in milliseconds.
• http.read-timeout (int) - the HTTP read/socket timeout in milliseconds.
• de4a.tracker.enabled (boolean) - enable or disable the remote tracker. Defaults to false.
• de4a.tracker.viahttp (boolean) - true if the tracker should use http for transmission, false if it should use TCP. The default is TCP (aka false). When using an HTTP proxy, this should be set to true, as most HTTP proxies don't let plain TCP traffic through.
• de4a.tracker.url (string) (deprecated since 0.2.3) - the URL where the tracker is collecting data elements.
• de4a.tracker.url.tcp (string) (since 0.2.3) - the TCP URL where the tracker is collecting data elements.
• de4a.tracker.url.http (string) (since 0.2.3) - the HTTP/HTTPS URL where the tracker is collecting data elements.
• de4a.tracker.topic (string) - the tracker topic (left pane).
• de4a.ial.url (string) (since 0.2.4) - the HTTP/HTTPS URL where the IAL is waiting for queries.
• de4a.me.implementation (string) - the AS4 Gateway to use. Must be set. Currently supported values are:
  • phase4 for using phase4 - requires the subproject dcng-phase4 on the class path
  • holodeck for using Holodeck - requires the subproject dcng-holodeck on the class path
• de4a.me.incoming.url (string) - the external URL to which incoming, validated documents, received via AS4, should be forwarded to.
• de4a.webapp.status.enabled (boolean) - true if the /status API is enabled and may return details, false if not. Defaults to true.
• de4a.webapp.data.path (string) - The storage path for file etc. inside the Connector.
• de4a.smp.http.useglobalsettings = true (boolean) - true to use the global configuration items or false to use the custom ones from "smp client configuration". Defaults to true.
• de4a.smp.usedns = true (boolean) - use the SML system to dynamically discover partner systems? This should only be false for testing purposes. In production this should always be true.
• de4a.smp.static.endpointurl (string) - the absolute URL of the AS4 endpoint URL. This is only evaluated if de4a.smp.usedns is false.
• de4a.smp.static.certificate (string) - the PEM encoded X509 certificate of the AS4 gateway. This is only evaluated if de4a.smp.usedns is false.
• de4a.smp.static.smpurl (string) - the absolute URL of the SMP to use. This is only evaluated if de4a.smp.usedns is false.
• de4a.smp.sml.id (string) - the ID of a predefined SML configuration to be used. This can effectively be digitprod (CEF SML) or digittest (CEF SMK). The recommended value for this property is digittest. This is the preferred way to specify the SML. This is only evaluated if de4a.smp.usedns is true.
• de4a.smp.sml.name = SML DE4A (string) - internal name of the SML. Defaults to DE4A SML. This is only evaluated if de4a.smp.usedns is true and if de4a.smp.sml.id is not valid. Caution: don't use it, except you know what you are doing.
• de4a.smp.sml.dnszone = de4a.edelivery.tech.ec.europa.eu. (string) - the DNS zone of the SML. This is only evaluated if de4a.smp.usedns is true and if de4a.smp.sml.id is not valid. Caution: don't use it, except you know what you are doing.
• de4a.smp.sml.serviceurl = https://edelivery.tech.ec.europa.eu/edelivery-sml (string) - the management service URL of the SML. This is only evaluated if de4a.smp.usedns is true and if de4a.smp.sml.id is not valid. Caution: don't use it, except you know what you are doing.
• de4a.smp.sml.clientcert = true (boolean) - is a client certificate need when talking to this SML. This is only evaluated if de4a.smp.usedns is true and if de4a.smp.sml.id is not valid. Caution: don't use it, except you know what you are doing.
  Additionally the configuration items of the SMP client should be configured. The complete description can be found at https://github.com/phax/peppol-commons#configuration - the main items are:
  • smpclient.truststore.type = jks (string): the type of key store to be used (either JKS, PKCS12 or BCFKS - case insensitive). Defaults to JKS.
  • smpclient.truststore.path = truststore/de4a-truststore-smp-v3-pw-de4a.jks (string): the location of the trust store (of the specified type) to be used.
  • smpclient.truststore.password = **** (string): the password to access the trust store.

Kafka Logging

To enable Kafka logging, ‘de4a.kafka.enabled’ must be set to true.

# Kafka settings

• de4a.kafka.enabled = true

• de4a.kafka.url = de4a.simplegob.com:9092

Phase4 specific

Similar to phase4.properties file from iteration 1

• phase4.datapath = temp/phase4 (string) - The base path where phase4 should store data to. This property is only used if de4a.webapp.data.path is not used (which only has effect in dcng-webapp-*).
• phase4.debug.http = true (boolean) - true if AS4 HTTP debugging should be enabled. Recommended to be false. Switch the debug level of the used SLF4J Logger to "debug" for a more verbose output. This configuration item is only evaluated once on startup.
• phase4.debug.incoming = true (boolean) - true to debug log certain details of incoming AS4 messages. This configuration item is evaluated for each incoming message.
• phase4.dump.incoming.path = temp/phase4 (string) - The absolute path on disk where incoming messages should be dumped to. If the value of this property is null or an empty String no dumping happens. This configuration item only evaluated once on startup.
• phase4.dump.outgoing.path = temp/phase4 (string) - The absolute path on disk where outgoing messages should be dumped to. If the value of this property is null or an empty String no dumping happens. This configuration item only evaluated once on startup.
• phase4.send.fromparty.id (string) - The From/PartyId value for receiving party id. This value must be set and should be the CN part of the sender's X.509 AS4 certificate.
• phase4.send.fromparty.id.type (string) - The From/PartyId/@type for sending party id. Defaults to ignore-me because it must be set but we don't care.
• phase4.send.toparty.id.type (string) - The To/PartyId/@type for receiving party id. Defaults to ignore-mebecause it must be set but we don't care.

# AS4 keystore for signing/decrypting

• phase4.keystore.type = JKS(string) - the type of the keystore (either JKS, PKCS12 or BCFKS - case insensitive) - defaults to JKS.

• phase4.keystore.path = /path/to/jks_file/as4_keystore.jks (string) - the path to the keystore (can be classpath relative or an absolute file)
• phase4.keystore.password = ********** (string) - the password to access the keystore
• phase4.keystore.key-alias =
• phase4.keystore.key-password =
• phase4.truststore.type (string) - the type of the truststore (either JKS, PKCS12 or BCFKS - case insensitive) - defaults to JKS.
• phase4.truststore.path (string) - the path to the truststore (can be classpath relative or an absolute file)
• phase4.truststore.password (string) - the password to access the truststore

Backwards compatibility

For participants using the iteration 1 DE and DO components, it will be necessary to configure this property.

• legacy.do.url = https://localhost:8080/requestExtractEvidenceIM - Only necessary for Connector DT using backwards compatibility. It will contain the DO IM request endpoint.

Endpoints configuration

A new file de-do.json contains all the information to communicate with DE/DO. This file is replacing old import.sql fron iteration 1. It is intended to let the Connector know both Data Owner and Data Evaluator endpoints addresses.

It should only contain the information to communicate with your DE or DO instance.

• When the Connector is acting as a Data Requestor (Data Evaluator side), it will be needed to address DE endpoints.
• When the Connector is acting as a Data Transferor (Data Owner side), it will be needed to address DO endpoints.

Data Requestor

The information configured under dataEvaluators is used by the Connector-DR to know the endpoints where the responses must be sent in each case.

• dataEvaluators.redirect is used by the Connector-DR to receive the redirectUserType response to redirect the user to the Data Owner to accept/reject the evidence (USI Pattern).

• dataEvaluators.response is used by the Connector-DR when the evidence is accepted by the user and must be redirected to the Data Evaluator (USI/IM Patterns).

• dataEvaluators.response and dataEvaluators.subscription_resp will be used by the subscription/notification pattern (Still under development).
  

Data Transferor

The information configured under DataOwners is used by the Connector-DT to know the endpoitns to the respective data owner (or mock do)

As you can see in the image, each endpoint corresponds to the url based on the pattern.

Starting up the Connector

Once you have all configuration parameters well configured (if not, check the logs to find out the problem), it is time to deploy the component into an applications server. Once you have deployed the war file or the docker image, there are several checks to ensure that the deployment was successful:

• DE4A Connector index page will be at root path: http://host:port/

­     E.g.: UM Connector­

• The Connector will be able to process requests through the following interfaces:
  • /request/im - As DR, take an IM request (RequestExtractMultiEvidenceIMType) and send it with AS4 to DT. Returns a generic synchronous response (ResponseErrorType).
  • /request/usi - As DR, take a USI request (RequestExtractMultiEvidenceUSIType) and send it with AS4 to DT. Returns a generic synchronous response (ResponseErrorType).
  • /request/lu - As DR, take a USI request (RequestExtractMultiEvidenceLUType) and send it with AS4 to DT. Returns a generic synchronous response (ResponseErrorType).
  • /request/subscription - As DR, take a USI request (RequestEventSubscriptionType) and send it with AS4 to DT. Returns a generic synchronous response (ResponseErrorType).
  • /requestTransferEvidenceIM - This is the backwards compatibility layer for Iteration 1. As DR, take an Iteration 1 IM request (RequestTransferEvidenceUSIIMDRType) and send it with AS4 to DT. Wait synchronously until the DR receives a matching response from DT. Return an Iteration 1 IM response (ResponseTransferEvidenceType). It times out after 60 seconds.