Code development platform for open source projects from the European Union institutions 🔵 EU Login authentication by SMS has been phased out. To see alternatives please check here

Skip to content

Changes

Page history
update domibus setup authored by Oussama MOULANA's avatar Oussama MOULANA
Show whitespace changes
Inline Side-by-side
CrossBorder-Gateway/Domibus/Server-setup-guide.md
View page @ ba870f2f
# :construction: Working in progress :construction:
[[_TOC_]] [[_TOC_]]
# Introduction # Introduction
This document describes the process to deploy and configure a Crossborder Gateway v0.1 for a POC Node. This component will allow each poc node to provision an eDelivery access point in order to exchange messages with the Central Poc Node. This guide outlines the steps for deploying and configuring **Domibus version 5.1.1** as a CrossBorder Gateway, specifically tailored for each Access Point enabling the exchange of messages with the EU Access Point.
This deployment and configuration guidelines are inspired by the official documentation of eDelivery Domibus. To find more information, please refer to this [web site](https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/Domibus).
During this process you will : The deployment and configuration instructions draw inspiration from the official documentation of eDelivery Domibus, accessible on the official website.
- Set up a Domibus single instance on your server using Docker
- Configure the keystore and trustore to secure messages to the central poc node Throughout this process, you will:
- Configure the Pmode file to reference the central poc node
- Enable authentication to access your Domibus through APIs - Establish a single-instance Domibus on your server using Docker.
- Exchange AS4 messages with the eDelivery Domibus Access Point using SoapUI and the Web Service Plugin - Configure the KeyStore and TrustStore to enhance message security with the EU Access Point.
- Adjust the PMode file to reference the parties you want to exchange with.
- Activate authentication of a Plugin Users for accessing your Domibus through APIs.
- Conduct AS4 message exchanges with the eDelivery Domibus Access Point using SoapUI and the Web Service Plugin.
## Variables ## Variables
The instructions described in those guidelines are using variables that needs to be replaced by the appropriate values in your context : The instructions in these guidelines use variables that must be replaced with the appropriate values in your context:
- **{DOMIBUS_SERVER_DIRECTORY}** : This refers to the directory on your server where Domibus will be set up.
- **{DOMIBUS_HOSTNAME}** : Denotes the public IP address of the server where you plan to install Domibus. **`{DOMIBUS_SERVER_DIRECTORY}`**: This signifies the directory on your server where Domibus will be installed.
- **{DOMIBUS_PORT}** : Represents the internet-accessible port that you will open for Domibus. **`{DOMIBUS_HOSTNAME}`**: Denotes the public IP address of the server where you intend to install Domibus.
- **{DOMIBUS_ACCESS_POINT}** : This is the designated name for your Domibus instance. Opt for a clear and descriptive name, like _france_ap_. **`{DOMIBUS_PORT}`**: Represents the internet-accessible port that you will open for Domibus.
**`{DOMIBUS_ACCESS_POINT}`**: This is the designated name for your Domibus instance. Choose a clear and descriptive name, such as `france_ap`.
## Requirement **`{KEYSTORE_PASSWORD}`**: Refers to the password for your Java KeyStore.
Before executing the above steps, please make sure that you comply with the below prerequisites: **`{PRIVATE_KEY_PASSWORD}`**: Refers to the password for the private key within your Java KeyStore.
- You have provisioned a linux server running the Docker engine including docker compose. As a reference, the central POC node is running on a server with the following properties : **`{TRUSTORE_PASSWORD}`**: Refers to the password for your Java TrustStore.
- 3 vCPUs
## Requirement:
Before proceeding with the above steps, ensure that your environment meets the following prerequisites:
Provision a Linux server with the Docker engine, including Docker Compose. As a reference, the EU Domibus server is running with the following specifications:
- 3 CPUs
- 4 GB of RAM - 4 GB of RAM
- 40 GB of storage - 40 GB of storage
- OS : Ubuntu 22.04 Jammy Jellyfish
- Your server is publicly reachable from internet through a public IP Ensure your server is publicly accessible from the internet through a public IP. The instructions are demonstrated on an `Ubuntu 22.04 Jammy Jellyfish` server, but other Linux distributions are also compatible.
- You have access to the following [materials](https://drive.google.com/drive/folders/1MSr2KryZ6jtsm5IfdZ-UP3MX0V5Pe-e9?usp=share_link) (Pmode file template, europe_ap certificate)
## Sources
- [Domibus official documentation](https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/Domibus)
- [eDelivery repository](https://code.europa.eu/edelivery)
# How to setup # How to setup
## 1 - Docker Compose ## 1 - Docker Compose
...@@ -96,268 +105,165 @@ If necessary, change the **18080** port to the port you have opened to the inter ...@@ -96,268 +105,165 @@ If necessary, change the **18080** port to the port you have opened to the inter
> **Note**: If using a reverse proxy, configure it to forward to the internal port. > **Note**: If using a reverse proxy, configure it to forward to the internal port.
Execute the following commands at the same level as your `compose.yaml`: Execute the following commands within the directory identified as **`{DOMIBUS_SERVER_DIRECTORY}`**
```shell ```shell
docker compose up -d docker compose up -d
``` ```
The startup process may take 2-5 minutes. Once completed, you can verify that your Domibus server is running by accessing it through the following URL: The startup process may take 2-5 minutes. Once completed, you can verify that your Domibus server is running by accessing it through the following URL:
```url ```http
http://{DOMIBUS_HOSTNAME}:{DOMIBUS_PORT}/domibus http://{DOMIBUS_HOSTNAME}:{DOMIBUS_PORT}/domibus
``` ```
![console](/img/domibus/image1.png) ![console](/img/domibus/image1.png)
Stop your Domibus instance using the following command at the same level as your `compose.yaml`: ## 2 - Self-Signed Certificate
```shell > :warning: **Attention**:
docker compose down Self-signed certificates are intended for testing purposes only and should not be used in production. For production use, consider obtaining certificates from a trusted certificate provider. Additional information on certificate providers can be found [here](https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/PKI+Service).
```
## Step 2 - Keystore and Trustore configuration Make sure you have the Java KeyStore/TrustStore located in **`{DOMIBUS_DOCKER_DIRECTORY}/domibus/keystores`** :
You should now have two JAVA keystores located in **`{DOMIBUS_DOCKER_DIRECTORY}/domibus/keystores`** : - `gateway_keystore.jks` store your private and public keys.
- The `gateway_keystore.jks` will be used to store your own private and public keys. - `gateway_truststore.jks` store the public keys of other eDelivery Access Points for message exchange.
- The `gateway_truststore.jks` will be used to store the public keys of the other eDelivery access points you want to exchange messages with.
Inside the **{DOMIBUS_DOCKER_DIRECTORY}/domibus/keystores** To ensure a minimal installation for managing keys and using the `keytool` command, it's recommended to install the headless version of `OpenJDK-17`, such as `OpenJDK-17-jre-headless`.
Remove `gateway_keystore.jks` and `gateway_trustore.jks` by running this command:
In the **`keystores`** folder, remove existing KeyStore/TrustStore with the following command:
```shell ```shell
rm gateway_keystore.jks gateway_truststore.jks rm gateway_keystore.jks gateway_truststore.jks
``` ```
Generate a keystore with this command line: Upon executing the following command, intended for generating a new `JKS` _Java KeyStore_, you'll be prompted to provide necessary information for the keystore:
```shell ```shell
keytool -keystore gateway_keystore.jks -genkey -alias {DOMIBUS_ACCESS_POINT} -keyalg RSA -keysize 2048 -validity 1461 -storetype JKS keytool -genkeypair -alias {DOMIBUS_ACCESS_POINT} -keystore gateway_keystore.jks -storetype JKS -keyalg RSA -validity 1461 -keysize 2048 -storepass {KEYSTORE_PASSWORD} -keypass {PRIVATE_KEY_PASSWORD}
``` ```
After executing this command, you will be prompted to enter information for the keystore.
> **NOTE:** You will need to fill several properties in the interactive prompt. The default password is “test123”, if you change it you have to change it in the domibus.properties as well. This step is described in the next step.
Exports your certificate from a keystore : Export your certificate from your KeyStore :
```shell ```shell
keytool -export -alias {DOMIBUS_ACCESS_POINT} -keystore gateway_keystore.jks -rfc -file {DOMIBUS_ACCESS_POINT}.cert keytool -export -alias {DOMIBUS_ACCESS_POINT} -keystore gateway_keystore.jks -rfc -file {DOMIBUS_ACCESS_POINT} -storetype JKS -storepass {KEYSTORE_PASSWORD}
``` ```
Import your certificat to your trustore:
Import your certificate into your TrustStore:
```shell ```shell
keytool -import -alias {DOMIBUS_ACCESS_POINT} -file {DOMIBUS_ACCESS_POINT}.cert -storetype JKS -keystore gateway_truststore.jks keytool -import -file {DOMIBUS_ACCESS_POINT}.cer -alias {DOMIBUS_ACCESS_POINT} -keystore gateway_truststore.jks -storetype JKS -storepass {TRUSTSTORE_PASSWORD}
``` ```
## Step 3 - Domibus properties configuration Contact the WP5 core team and provide them with the following information:
In the file **{DOMIBUS_DOCKER_DIRECTORY}/domibus/domibus.properties**, find the section:
`Keystore/Truststore (Single Tenancy)`
And assign a password for the keystore you configured earlier
``` ```
#The password used to load the keystore {DOMIBUS_HOSTNAME}:{DOMIBUS_PORT}
domibus.security.keystore.password=test123
....
#The private key password
domibus.security.key.private.password=test123
...
#The password used to load the trustStore
domibus.security.truststore.password=test123
``` ```
Attach the certificate file, `{DOMIBUS_ACCESS_POINT}.cer`, generated in your **`keystores`** folder. This step is crucial for the WP5 core team to include your public key in the list of authorized parties on the EU Access Point.
## 3 - Domibus Properties
In the file **`{DOMIBUS_DOCKER_DIRECTORY}/domibus/domibus.properties`**, locate the section labeled `Keystore/Truststore (Single Tenancy)` and set the passwords you configured on the previous step:
Set the alias your configured earlier ```properties
``` # ---------------------------------- Keystore/Truststore (Single Tenancy) -----------------------
...
#The password used to load the keystore
domibus.security.keystore.password={KEYSTORE_PASSWORD}
#Private key
#The alias from the keystore of the private key #The alias from the keystore of the private key
domibus.security.key.private.alias={DOMIBUS_ACCESS_POINT} domibus.security.key.private.alias={DOMIBUS_ACCESS_POINT}
```
In the `Security` section of the file, activate the security of the following propertie: #The private key password
domibus.security.key.private.password={PRIVATE_KEY_PASSWORD}
...
#The password used to load the trustStore
domibus.security.truststore.password={TRUSTORE_PASSWORD}
``` ```
In the `Security` section of the file, uncomment and enable security by setting the following property to the value `false`:
```properties
...
#To activate security set this to false #To activate security set this to false
#domibus.auth.unsecureLoginAllowed=false domibus.auth.unsecureLoginAllowed=false
...
``` ```
## Step 4 - Domibus server configuration > **Note**:
Inside your **{DOMIBUS_SERVER_DIRECTORY}** While you might consider creating a `PKCS12` KeyStore, please be aware that it currently appears to be non-functional.
Start again the server by doing the command:
## 4 - Domibus Console
Within the directory or any of its subdirectories of the **`{DOMIBUS_SERVER_DIRECTORY}`**
Restart your Domibus server by doing the command:
```shell ```shell
docker compose up -d docker compose restart
``` ```
From your browser, access to your domibus server with the following URL: From your browser, access to your Domibus server with the following URL:
```url ```http
http://{DOMIBUS_HOSTNAME}:{DOMIBUS_PORT}/domibus http://{DOMIBUS_HOSTNAME}:{DOMIBUS_PORT}/domibus
``` ```
### A - Users Credentials
#### - Dashboard Users
Access the Domibus Admin Console using the default credentials:
```
Username: admin
Password: 123456
```
You have the option to change this password at the top right of the console.
![dashboard](/img/domibus/image2.png)
Alternatively, user management can be performed in the `Users` section of the left navigation bar.
Login in the Domibus Admin Console with the default credentials: #### - Plugin Users
- login : admin A plugin user, specifically utilized for eDelivery message exchange through our Connector API, can be added in the `Plugin Users` section. To do so, navigate to this section, click on `+ New`, and provide the desired username, password, and role.
- password : 123456
You can change this password on the top right of the console.
On the left section
Download a copy of the PMode template file [pmode_default.xml](uploads/domibus/PMode-Default-2023-05-02_104857.xml) and replace the following variables with the correct values and upload the file.
<details>
<summary>pmode.xml</summary>
<code>
<?xml version="1.0" encoding="UTF-8"?>
<db:configuration xmlns:db="http://domibus.eu/configuration" party="{DOMIBUS_ACCESS_POINT}">
<mpcs>
<mpc name="defaultMpc"
qualifiedName="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/defaultMPC"
enabled="true"
default="true"
retention_downloaded="0"
retention_undownloaded="14400"
retention_sent="14400"
delete_message_metadata="false"
max_batch_delete="1000" />
</mpcs>
<businessProcesses>
<roles>
<role name="defaultInitiatorRole"
value="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/initiator" />
<role name="defaultResponderRole"
value="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/responder" />
</roles>
<parties>
<partyIdTypes>
<partyIdType name="partyTypeUrn"
value="urn:oasis:names:tc:ebcore:partyid-type:unregistered" />
</partyIdTypes>
<party name="{DOMIBUS_ACCESS_POINT}"
endpoint="http://{DOMIBUS_HOSTNAME}:{DOMIBUS_PORT}/domibus/services/msh">
<identifier partyId="{DOMIBUS_ACCESS_POINT}" partyIdType="partyTypeUrn" />
</party>
<party name="europe_ap"
endpoint="http://51.159.133.186:8080/domibus/services/msh">
<identifier partyId="europe_ap" partyIdType="partyTypeUrn" />
</party>
</parties>
<meps>
<mep name="oneway"
value="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/oneWay" />
<mep name="twoway"
value="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/twoWay" />
<binding name="push"
value="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/push" />
<binding name="pull"
value="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/pull" />
<binding name="pushAndPush"
value="http:// docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/ pushAndPush" />
</meps>
<properties>
<property name="originalSenderProperty"
key="originalSender"
datatype="string"
required="true" />
<property name="finalRecipientProperty"
key="finalRecipient"
datatype="string"
required="true" />
<propertySet name="eDeliveryPropertySet">
<propertyRef property="finalRecipientProperty" />
<propertyRef property="originalSenderProperty" />
</propertySet>
</properties>
<payloadProfiles>
<payload name="businessContentPayload"
cid="cid:message"
required="true"
mimeType="text/xml" />
<payload name="businessContentAttachment"
cid="cid:attachment"
required="false"
mimeType="application/octet-stream" />
<payloadProfile name="MessageProfile" maxSize="2147483647">
<attachment name="businessContentPayload" />
<attachment name="businessContentAttachment" />
</payloadProfile>
</payloadProfiles>
<securities>
<security name="eDeliveryAS4Policy"
policy="eDeliveryAS4Policy.xml"
signatureMethod="RSA_SHA256" />
</securities>
<errorHandlings>
<errorHandling name="demoErrorHandling"
errorAsResponse="true"
businessErrorNotifyProducer="true"
businessErrorNotifyConsumer="true"
deliveryFailureNotifyProducer="true" />
</errorHandlings>
<agreements>
<agreement name="agreement1" value="A1" type="T1" />
</agreements>
<services>
<service name="testService1" value="bdx:noprocess" type="tc1" />
<service name="testService"
value="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/service" />
</services>
<actions>
<action name="tc1Action" value="TC1Leg1" />
<action name="testAction"
value="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/test" />
</actions>
<as4>
<receptionAwareness name="receptionAwareness" retry="12;4;CONSTANT"
duplicateDetection="true" />
<reliability name="AS4Reliability" nonRepudiation="true" replyPattern="response" />
</as4>
<legConfigurations>
<legConfiguration name="pushTestcase1tc1Action"
service="testService1"
action="tc1Action"
defaultMpc="defaultMpc"
reliability="AS4Reliability"
security="eDeliveryAS4Policy"
receptionAwareness="receptionAwareness"
propertySet="eDeliveryPropertySet"
payloadProfile="MessageProfile"
errorHandling="demoErrorHandling"
compressPayloads="true" />
<legConfiguration name="testServiceCase"
service="testService"
action="testAction"
defaultMpc="defaultMpc"
reliability="AS4Reliability"
security="eDeliveryAS4Policy"
receptionAwareness="receptionAwareness"
propertySet="eDeliveryPropertySet"
payloadProfile="MessageProfile"
errorHandling="demoErrorHandling"
compressPayloads="true" />
</legConfigurations>
<process name="tc1Process"
mep="oneway"
binding="push"
initiatorRole="defaultInitiatorRole"
responderRole="defaultResponderRole">
<initiatorParties>
<initiatorParty name="{DOMIBUS_ACCESS_POINT}" />
<initiatorParty name="europe_ap" />
</initiatorParties>
<responderParties>
<responderParty name="{DOMIBUS_ACCESS_POINT}" />
<responderParty name="europe_ap" />
</responderParties>
<legs>
<leg name="pushTestcase1tc1Action" />
<leg name="testServiceCase" />
</legs>
</process>
</businessProcesses>
</db:configuration>
</code>
</details>
You can check on the Parties tab if every parties are configured correctly.
Still on the left side, go to`Certificates` -> `Keystore` section and upload your keystore you generated earlier.
Next, navigate to `Certificates` -> `Truststore` and add the certificates for each Access Point you wish to establish an exchange with.
You can find the `europe_ap` certificate here[europe_ap.cert](uploads/domibus/europe_ap.cert)
Reach out the WP5 core team with the following details:
Provide the URL of your Domibus, which should be: **http://{DOMIBUS_HOSTNAME}:{DOMIBUS_PORT}/domibus**
Attach the certificate you generated earlier in your keystores folder, named {DOMIBUS_ACCESS_POINT}.cert.
In the menu bar, navigate to `Plugin User`. Create a new plugin user by clicking on “New”
Make sure that you save your modification. Make sure that you save your modification.
# Test your connection > **Example**:
Navigate into `Connection Monitoring` and try to send a message, if the status is green your domibus is ready to exchange messages. For the French-Connector, you might create a user named `frc_user`.
\ No newline at end of file
![plugin_user](/img/domibus/image3.png)
### B - Processing Modes
Processing Modes _PModes_ are used to configure Access Points. The PMode parameters are loaded into the Access Point via an XML file.
Begin by downloading the PMode template file [pmode.xml](uploads/domibus/pmode-2023-11-24.xml) and replacing the variables with the appropriate placeholder values. Upload the modified file under:
`PMode` → `Current`
Ensure that you save your modifications.
Similar to sharing our certificate with the EU Access Point previously, we also need to import the EU Access Point certificate to grant them exchange authorization. To achieve this, follow these steps for each Access Point you wish to authorize.
Navigate to:
`PMode` → `Party`
Click on `+ New`
Create a name such as `europe_ap` and set the endpoint with the `/domibus/services/msh` path.
```http
http://51.159.133.186:8080/domibus/services/msh
```
![party](/img/domibus/image4.png)
>**Note**:
The host `51.159.133.186:8080` is the EU Domibus server's address. If you add another Access Point, include the address of that Domibus server.
Import the [EU Access Point Certificate](/uploads/domibus/europe_ap.cer)
Scroll down to the `Identifiers` section, click on `+ New`, and add the Access Point name, which is `europe_ap` for the EU Access Point and set this for the following properties:
```
Party Id Type: partypTypeUrn
Party Id Value: urn:oasis:names:tc:ebcore:partyid-type:unregistered
```
These last two values are the same for any Access Point.
![identifier](/img/domibus/image5.png)
In the `Processes` block, check the checkboxes for both `Initiator` and `Responder`
Press `Ok` and save the configuration.
You are now able to communicate with the Access Point you just added.
Verify on the `Parties` tab to ensure that all parties are configured correctly.
# Testing Configuration
Congratulations on setting up your Domibus server. Let's conduct some tests to ensure everything is working correctly.
### Console Monitoring test
Navigate to the `Connection Monitoring` section and try sending a message to your own Access Point and to `europe_ap`. If the status shows as green for both, your Domibus server is ready for message exchange.
![monitoring](/img/domibus/image6.png)
### SoapUI test
# :construction: Working in progress :construction:
\ No newline at end of file

For further information about the platform and support, please see https://code.europa.eu/info/about