OpenAS2 on Ubuntu 24.04 on Azure User Guide

Overview

This guide covers the deployment and configuration of OpenAS2 on Ubuntu 24.04 on Azure using cloudimg Azure Marketplace images. OpenAS2 is an open source Java implementation of the AS2 protocol (RFC 4130), the standard for exchanging EDI and other business documents securely over HTTP with digital signatures, encryption and signed MDN (Message Disposition Notification) receipts. A partner sends you a signed and encrypted payload over HTTP, OpenAS2 verifies the signature, decrypts the content, writes it to an inbox and returns a signed MDN as cryptographic proof of receipt.

The image builds OpenAS2 from the pinned upstream v4.8.3 release and runs it as the unprivileged openas2 system user under systemd. The AS2 receiver listens on port 10080.

Security by design — a fresh per VM AS2 keystore, no baked key. The upstream distribution ships a demo PKCS#12 keystore that holds live private keys for its example stations and is unlocked by the well known password testas2. That demo keystore is removed at build time. On first boot the image generates a brand new per VM PKCS#12 keystore with fresh self signed AS2 key pairs and a unique 28 character keystore password, so no two instances ever share a private key and nothing secret is baked into the image.

Security by design — no default management credential. The upstream configuration also runs an embedded H2 message tracking TCP server guarded by a default password, and ships default REST and console command processor credentials. All of these are disabled in this image: the H2 tracking TCP server is turned off, and the console and REST command processors are disabled, so there is no management listener and no management credential to rotate.

Security by design — certificate trust, not passwords. AS2 security is built on mutual certificate trust rather than a login. A trading partner can only exchange messages with you once you have swapped public certificates and defined a partnership. An inbound message from an unconfigured sender, or one that fails signature verification, is rejected.

What is included:

• OpenAS2 v4.8.3 built from the pinned upstream source, run under systemd as the unprivileged openas2 user (openas2.service)

• The AS2 receiver on port 10080 (RFC 4130) and the MDN receiver on port 10081

• A fresh per VM PKCS#12 AS2 keystore and password generated on first boot, with the vendor demo keystore and default passwords stripped out

• A ready to run MyCompany to PartnerA loopback partnership and a self test helper so you can prove the send, receive and MDN round trip immediately

• Signed and encrypted messaging with SHA-256 signatures and 3DES encryption, full message tracking in an embedded database, and signed MDN receipts written to disk

• Unattended security upgrades left enabled so the OS keeps receiving patches

Prerequisites

• Active Azure subscription, SSH public key, VNet + subnet in the target region

• Subscription to the OpenAS2 listing on Azure Marketplace

• Network Security Group rules allowing TCP 22 (administration) and TCP 10080 (inbound AS2 messages) from the trading partners that will send to you

Recommended virtual machine size: Standard_B2s (2 vCPU, 4 GB RAM). Higher message volumes benefit from Standard_D2s_v5 or larger.

Step 1: Deploy from the Azure Portal

Search OpenAS2 in Marketplace, select the cloudimg publisher, and click Create. Configure the Network Security Group to allow TCP 10080 (inbound AS2 messages) from your trading partners, and TCP 22 for administration.

Step 2: Deploy from the Azure CLI

RG="as2-prod"; LOCATION="eastus"; VM_NAME="openas2"
GALLERY_IMAGE_ID="/subscriptions/<sub-id>/resourceGroups/azure-cloudimg/providers/Microsoft.Compute/galleries/cloudimgGallery/images/openas2-ubuntu-24-04/versions/<version>"
SSH_KEY="$(cat ~/.ssh/id_rsa.pub)"
az group create --name "$RG" --location "$LOCATION"
az vm create \
  --resource-group "$RG" --name "$VM_NAME" \
  --image "$GALLERY_IMAGE_ID" \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values "$SSH_KEY" \
  --public-ip-sku Standard
# Open the AS2 receiver and admin ports on the VM's NSG:
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 10080 --priority 1001
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 22 --priority 1002

Step 3: First boot

On first boot the image generates the fresh per VM AS2 keystore and keystore password, renders them into the OpenAS2 configuration, exports your own AS2 public certificate, resolves the VM address for the receiver URL, and writes /root/openas2-credentials.txt. This completes within a minute. SSH in as azureuser and read the details:

sudo cat /root/openas2-credentials.txt

The file records the per VM keystore password, the local AS2 station id, the AS2 receiver URL and the path to your public certificate.

Step 4: Confirm the server is running

openas2.service is active, the AS2 receiver is listening on port 10080 and the MDN receiver on port 10081. The default credential H2 tracking TCP server on port 9092 is deliberately not listening.

systemctl is-active openas2.service
sudo ss -tln | grep -E ':10080 |:10081 '
sudo ss -tln | grep -q ':9092 ' && echo "H2 exposed" || echo "H2 tracking TCP server not exposed (secure by default)"

Step 5: Confirm the secure by default posture

The vendor demo keystore is removed and a fresh per VM keystore exists, owned by the openas2 service user.

test -e /opt/openas2/config/as2_certs.p12 && echo "demo keystore present" || echo "demo keystore removed (secure by default)"
sudo stat -c 'per-VM keystore: %n  perms: %a  owner: %U:%G' /var/lib/openas2/as2_certs.p12
sudo grep -E '^AS2_LOCAL_STATION_ID=|^AS2_RECEIVER_URL=' /root/openas2-credentials.txt

Step 6: Prove the AS2 round trip with the loopback self test

The image ships a ready to run MyCompany to PartnerA partnership that loops back to the local AS2 receiver. The self test helper drops a payload into that partnership's outbox; OpenAS2 signs and encrypts it, POSTs it to its own receiver, the receiver decrypts and verifies it and writes it to the inbox, and a signed MDN receipt is returned and written to disk. This exercises the full signed and encrypted AS2 message plus MDN flow end to end.

sudo /opt/openas2/bin/openas2-loopback-selftest.sh

You can see the persisted results of the exchange on disk: the decrypted message in the inbox and the signed MDN receipt.

sudo ls -1 /var/lib/openas2/data/MyCompany_OID-PartnerA_OID/inbox/ | tail -3
sudo find /var/lib/openas2/data/MyCompany_OID-PartnerA_OID/mdn/ -type f | tail -3

Step 7: Inspect your AS2 keystore and public certificate

The per VM keystore holds the private keys for your local AS2 stations. List its entries by reading the per VM keystore password from the credentials file, then view the public certificate you share with a trading partner.

KSPW="$(sudo grep '^AS2_KEYSTORE_PASSWORD=' /root/openas2-credentials.txt | cut -d= -f2-)"
sudo keytool -list -keystore /var/lib/openas2/as2_certs.p12 -storetype pkcs12 -storepass "$KSPW"
sudo openssl x509 -in /var/lib/openas2/mycompany-as2-public.cer -noout -subject -issuer -dates

Step 8: Add a real trading partner

To exchange messages with a real partner you swap public certificates and define a partnership. First send the partner your public certificate:

sudo cat /var/lib/openas2/mycompany-as2-public.cer

Import the partner's public certificate into the keystore under an alias, then define the partner and the partnership. These steps use your own values, so run them yourself rather than as part of an automated walk through:

# Import a partner's public certificate under an alias:
sudo -u openas2 /opt/openas2/bin/import_public_cert.sh <partner.cer> <alias>

# Define the partner and partnership by editing the partnerships file:
sudo -u openas2 nano /opt/openas2/config/partnerships.xml

In partnerships.xml, add a <partner> for the trading partner (with their AS2 id and the x509_alias you imported), then a <partnership> naming your station as the sender and theirs as the receiver, with their as2_url and the encrypt and sign algorithms you have agreed. OpenAS2 reloads the partnerships file automatically.

Step 9: Send a file to a partner

OpenAS2 sends by watching an outbox directory. A file placed in a partnership's outbox is signed, encrypted and delivered to that partner's as2_url, and the returned MDN is stored as proof of delivery. The shipped loopback partnership sends anything dropped into its outbox to the local receiver:

echo "cloudimg AS2 send demo $(date)" | sudo tee /var/lib/openas2/data/outbox/PartnerA_OID/order-demo.edi >/dev/null
sudo chown openas2:openas2 /var/lib/openas2/data/outbox/PartnerA_OID/order-demo.edi
sleep 12
sudo find /var/lib/openas2/data/MyCompany_OID-PartnerA_OID/mdn/ -type f | tail -1

The MDN receipt written for the file confirms it was delivered and acknowledged. For a real partner the outbox path follows the pattern data/outbox/<receiver AS2 id>/.

Step 10: Message tracking and logs

Every message and MDN is tracked in an embedded database and logged. The daily OpenAS2 log at /var/lib/openas2/logs/log-<date>.txt records send, receive and MDN events, and the received messages and MDN receipts accumulate on disk:

sudo ls -lt /var/lib/openas2/logs/
echo "Messages received:"; sudo find /var/lib/openas2/data -path '*/inbox/*' -type f | wc -l
echo "MDN receipts written:"; sudo find /var/lib/openas2/data -path '*/mdn/*' -type f | wc -l

Step 11: Security recommendations

• Restrict the NSG. Allow TCP 10080 only from the trading partners that need to send to you, and TCP 22 for administration only. AS2 security is certificate based, so the receiver is safe to expose to your partners, but a tight NSG is still good practice.

• Swap certificates out of band. Exchange public certificates with each partner through a trusted channel before enabling a partnership, and reject unsigned messages for partnerships that require signing.

• Keep the per VM keystore password safe. It is unique to this VM and stored only in /root/openas2-credentials.txt (mode 0600). Back it up securely, because it protects the private keys of your AS2 stations.

• Consider AS2 over HTTPS. For public internet exchange you can enable the HTTPS receiver on port 10443 with a TLS certificate in addition to the message level signing and encryption.

• Keep the OS patched. Unattended security upgrades remain enabled on the running VM.

Step 12: Support and Licensing

OpenAS2 is developed by the OpenAS2 project and distributed under the GNU General Public License v3.0. This cloudimg image builds the unmodified upstream OpenAS2 v4.8.3 release. cloudimg provides the packaging, the removal of the demo keystore and default passwords, the per VM keystore and password generation on first boot, the ready to run loopback self test, and 24/7 support with a guaranteed 24 hour response SLA.

cloudimg is not affiliated with or endorsed by the OpenAS2 project. OpenAS2 is a mark of its respective owner and is used here only to identify the software.

Deploy on Azure

Find OpenAS2 on Ubuntu 24.04 LTS on the Azure Marketplace, published by cloudimg. Deploy from the Portal or the Azure CLI as shown above.

Need Help?

Email support@cloudimg.co.uk for deployment help, configuration questions, or licensing enquiries.