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 functionalityglobal.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 usedhttp.tls.trustall = true
(boolean) - use this to disable the hostname and trusted certificate check for SSL/TLS connections. Defaults tofalse
. Usingtrue
just for testing purposes, not recomended for production.http.proxy.enabled
(boolean) - is an HTTP proxy needed? Defaults tofalse
.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 inlocalhost|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 tofalse
.de4a.tracker.viahttp
(boolean) -true
if the tracker should use http for transmission,false
if it should use TCP. The default is TCP (akafalse
). When using an HTTP proxy, this should be set totrue
, 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 subprojectdcng-phase4
on the class pathholodeck
for using Holodeck - requires the subprojectdcng-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 totrue
.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 orfalse
to use the custom ones from "smp client configuration". Defaults totrue
.de4a.smp.usedns = true
(boolean) - use the SML system to dynamically discover partner systems? This should only befalse
for testing purposes. In production this should always betrue
.de4a.smp.static.endpointurl
(string) - the absolute URL of the AS4 endpoint URL. This is only evaluated ifde4a.smp.usedns
isfalse
.de4a.smp.static.certificate
(string) - the PEM encoded X509 certificate of the AS4 gateway. This is only evaluated ifde4a.smp.usedns
isfalse
.de4a.smp.static.smpurl
(string) - the absolute URL of the SMP to use. This is only evaluated ifde4a.smp.usedns
isfalse
.de4a.smp.sml.id
(string) - the ID of a predefined SML configuration to be used. This can effectively bedigitprod
(CEF SML) ordigittest
(CEF SMK). The recommended value for this property isdigittest
. This is the preferred way to specify the SML. This is only evaluated ifde4a.smp.usedns
istrue
.de4a.smp.sml.name = SML DE4A
(string) - internal name of the SML. Defaults toDE4A SML
. This is only evaluated ifde4a.smp.usedns
istrue
and ifde4a.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 ifde4a.smp.usedns
istrue
and ifde4a.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 ifde4a.smp.usedns
istrue
and ifde4a.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 ifde4a.smp.usedns
istrue
and ifde4a.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 (eitherJKS
,PKCS12
orBCFKS
- case insensitive). Defaults toJKS
.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 ifde4a.webapp.data.path
is not used (which only has effect indcng-webapp-*
).phase4.debug.http = true
(boolean) -true
if AS4 HTTP debugging should be enabled. Recommended to befalse
. 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 isnull
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 isnull
or an empty String no dumping happens. This configuration item only evaluated once on startup.phase4.send.fromparty.id
(string) - TheFrom/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) - TheFrom/PartyId/@type
for sending party id. Defaults toignore-me
because it must be set but we don't care.phase4.send.toparty.id.type
(string) - TheTo/PartyId/@type
for receiving party id. Defaults toignore-me
because 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 keystorephase4.keystore.key-alias =
phase4.keystore.key-password =
phase4.truststore.type
(string) - the type of the truststore (eitherJKS
,PKCS12
orBCFKS
- case insensitive) - defaults toJKS
.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.