AS2OpenAS2TutorialEDISetup

OpenAS2 Setup Tutorial: Install, Configure, and Send Your First AS2 Message

14 min readBy AS2 Certify Team

What is OpenAS2 and why use it?

OpenAS2 is the most widely used open-source AS2 server: free, Java-based, and cross-platform, handling the full AS2 protocol — sending, receiving, encryption, signing, and MDN processing. For testing, development, or production use at moderate volume, it is a solid choice.

Successful setup hinges on three things: the server configuration, the certificate keystore, and the partner profiles. This guide walks through the complete process — installation, directory structure, certificate management, partnership configuration, sending your first message, and troubleshooting the errors you will inevitably hit.

What do you need before installing OpenAS2?

You need a Java runtime, an internet-reachable host if you will receive messages, and the certificates for both sides of the exchange. Specifically:

  • Java 8 or later (OpenAS2 4.x works with Java 8 through 21). Check with java -version.
  • A machine with a static IP or hostname if you'll be receiving messages from trading partners
  • Port 10080 (HTTP) and/or 10443 (HTTPS) available (these are OpenAS2 defaults; you can change them)
  • Your trading partner's public certificate (for encrypting messages to them and verifying their signatures)
  • Your own key pair, stored somewhere secure (OpenAS2 generates a default one, but you'll want to create a proper one for production)

How do you install OpenAS2?

Download the latest release zip from the OpenAS2 GitHub repository, extract it, and make the startup script executable. No installer is required.

# Download the latest release (check https://github.com/OpenAS2/OpenAs2App/releases for current version)
wget https://github.com/OpenAS2/OpenAs2App/releases/download/v4.8.0/OpenAS2Server-4.8.0.zip

# Unzip
unzip OpenAS2Server-4.8.0.zip -d /opt/openas2

# Make the startup script executable
chmod +x /opt/openas2/bin/start-openas2.sh

On Windows, download the zip and extract it to a directory like C:\OpenAS2. Use start-openas2.bat instead of the shell script.

How is the OpenAS2 directory structured?

Almost everything you will touch lives in config/ (server settings, partnerships, keystore) and data/ (outbound drop directories). Understand the layout before changing anything:

/opt/openas2/
  bin/                  # Startup scripts
    start-openas2.sh    # Linux/Mac startup
    start-openas2.bat   # Windows startup
  config/               # All configuration files
    config.xml          # Main server configuration
    partnerships.xml    # Trading partner definitions
    as2_certs.p12       # Java keystore with certificates
  data/                 # Message data
    toAny/              # Drop files here to send
    toPartnerName/      # Partner-specific outbound directories
  logs/                 # Log files
  lib/                  # Java libraries (don't modify)

The three files you'll edit most:

  1. config/config.xml for server settings (ports, logging, your AS2 ID)
  2. config/partnerships.xml for trading partner definitions
  3. config/as2_certs.p12 for managing certificates (via keytool commands, not direct editing)

How do you configure the OpenAS2 server (config.xml)?

Open config/config.xml and set two things: your AS2 identity (the local partner definition) and the receiver module that listens for inbound messages. Everything else can stay at defaults for a first run.

Your AS2 identifier

Find the local partner definition. This is your AS2 identity:

<partner name="OpenAS2A" 
  as2_id="OpenAS2A" 
  x509_alias="openas2a" 
  email="as2@yourcompany.com"/>

Change as2_id to your organization's AS2 ID. This is the value that goes in the AS2-From header of outbound messages. Your trading partner needs this exact string. Convention is to use your company name or DUNS number, all uppercase, no spaces.

HTTP receiver settings

The receiver module configures what port OpenAS2 listens on for incoming messages:

<module classname="org.openas2.processor.receiver.AS2ReceiverModule"
  port="10080"
  errordir="data/msgError"
  errorformat="$msg.sender.as2_id$, $msg.receiver.as2_id$, $msg.headers.message-id$"/>

For production, you'll want to put a reverse proxy (Nginx or Apache) in front of this with TLS termination on port 443, forwarding to OpenAS2's HTTP port.

HTTPS receiver (optional but recommended)

To enable HTTPS directly on OpenAS2:

<module classname="org.openas2.processor.receiver.AS2ReceiverModule"
  port="10443"
  protocol="https"
  ssl_keystore="config/ssl_certs.jks"
  ssl_keystore_password="changeit"
  ssl_protocol="TLSv1.2"/>

You'll need to create the SSL keystore separately (covered in the certificates section below).

How do you set up certificates in OpenAS2?

OpenAS2 stores all certificates — your private key and every partner's public certificate — in a single Java PKCS12 keystore, config/as2_certs.p12, managed with keytool. The default keystore password is testas2; change it for production.

Generate your key pair

If you don't already have an AS2 certificate, generate one:

# Generate a new key pair in the OpenAS2 keystore
keytool -genkeypair \
  -alias mycompany \
  -keyalg RSA \
  -keysize 2048 \
  -validity 730 \
  -storetype PKCS12 \
  -keystore config/as2_certs.p12 \
  -storepass testas2 \
  -dname "CN=MyCompany AS2, O=MyCompany Inc, L=City, ST=State, C=US"

This creates a self-signed certificate valid for 2 years. For production with strict partners, you may need a CA-signed certificate.

Export your public certificate (to send to your partner)

# Export your public certificate to share with trading partner
keytool -exportcert \
  -alias mycompany \
  -keystore config/as2_certs.p12 \
  -storepass testas2 \
  -file mycompany_as2_public.cer \
  -rfc

Send the .cer file to your trading partner. Never send the keystore file; it contains your private key.

Import your partner's certificate

# Import trading partner's public certificate
keytool -importcert \
  -alias partnercompany \
  -keystore config/as2_certs.p12 \
  -storepass testas2 \
  -file partner_public_cert.cer \
  -noprompt

The alias you choose here (partnercompany) is what you'll reference in the partnership configuration. Before importing, it's worth running the partner's file through the free AS2 certificate checker to catch expired or malformed certificates up front.

List all certificates in the keystore

keytool -list \
  -keystore config/as2_certs.p12 \
  -storepass testas2 \
  -v

This shows every certificate, its alias, type (PrivateKeyEntry for your keys, trustedCertEntry for partner certs), and expiration date.

How do you configure a trading partnership in OpenAS2?

Each partnership in config/partnerships.xml defines one direction of exchange with one partner — so you need a partner definition plus two partnership blocks, one outbound and one inbound. The AS2 IDs, certificate aliases, and algorithm attributes must match what you agreed with the partner exactly.

Define the partner

First, add the remote partner definition:

<partner name="PartnerCompany"
  as2_id="PARTNERCOMPANY"
  x509_alias="partnercompany"
  email="edi@partnercompany.com"/>

The as2_id must match exactly what your partner tells you. Case-sensitive. No extra spaces.

Define the partnership (outbound: you to partner)

<partnership name="MyCompany-PartnerCompany"
  sender="MyCompany"
  receiver="PartnerCompany">
  
  <!-- Partner's AS2 endpoint URL -->
  <attribute name="as2_url" value="https://partner.example.com/as2"/>
  
  <!-- Encryption: aes128-cbc, aes192-cbc, aes256-cbc, or 3des -->
  <attribute name="encrypt" value="aes256-cbc"/>
  
  <!-- Signing: sha-1, sha-256, sha-384, sha-512 -->
  <attribute name="sign" value="sha-256"/>
  
  <!-- Content type of outbound messages -->
  <attribute name="content_type" value="application/edi-x12"/>
  
  <!-- MDN settings -->
  <attribute name="as2_mdn_to" value="as2@mycompany.com"/>
  <attribute name="as2_mdn_options" 
    value="signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, sha-256"/>
  
  <!-- For async MDN, uncomment and set your receipt URL -->
  <!-- <attribute name="as2_receipt_option" value="https://your-server.com:10080/as2/HttpReceiver"/> -->
</partnership>

Define the reverse partnership (inbound: partner to you)

<partnership name="PartnerCompany-MyCompany"
  sender="PartnerCompany"
  receiver="MyCompany">
  
  <attribute name="as2_url" value="https://your-server.com:10080/as2/HttpReceiver"/>
  <attribute name="encrypt" value="aes256-cbc"/>
  <attribute name="sign" value="sha-256"/>
  <attribute name="content_type" value="application/edi-x12"/>
  <attribute name="as2_mdn_to" value="edi@partnercompany.com"/>
  <attribute name="as2_mdn_options" 
    value="signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, sha-256"/>
</partnership>

You need both directions defined. One for messages you send to the partner, one for messages the partner sends to you. If XML-by-hand is error-prone for you, the free AS2 configuration generator produces the partnership parameters from a short form.

How do you start OpenAS2?

Run the startup script from the installation directory and watch the console for the partnership and receiver modules to load. Errors at startup almost always point at the keystore or partnerships file.

# Linux/Mac
cd /opt/openas2
./bin/start-openas2.sh

# Windows
cd C:\OpenAS2
bin\start-openas2.bat

A successful startup looks like:

[INFO] - OpenAS2 Server - Version 4.8.0
[INFO] - Loading configuration...
[INFO] - Certificate store loaded: config/as2_certs.p12
[INFO] - Partnership loaded: MyCompany-PartnerCompany
[INFO] - Partnership loaded: PartnerCompany-MyCompany
[INFO] - AS2ReceiverModule started on port 10080
[INFO] - OpenAS2 Server Started

If you see errors here, check the troubleshooting section below.

How do you send a test message with OpenAS2?

OpenAS2 sends via a file drop: place a file in the partner's outbound directory and the directory poller (default interval: 30 seconds) picks it up, encrypts it, signs it, and POSTs it to the partner's AS2 URL. Watch the log to confirm the send and the returned MDN.

Create a test EDI file

# Create a minimal X12 997 test file
cat > /opt/openas2/data/toPartnerCompany/test_997.edi << 'EOF'
ISA*00*          *00*          *ZZ*MYCOMPANY      *ZZ*PARTNERCO      *230101*1200*U*00401*000000001*0*T*>~
GS*FA*MYCOMPANY*PARTNERCO*20230101*1200*1*X*004010~
ST*997*0001~
AK1*PO*1~
AK9*A*1*1*1~
SE*4*0001~
GE*1*1~
IEA*1*000000001~
EOF

Check the logs

# Watch the log for send activity
tail -f /opt/openas2/logs/openas2.log

A successful send shows:

[INFO] - Message sent: MyCompany-PartnerCompany, Message-ID: <OPENAS2-...-MyCompany-PartnerCompany@...>
[INFO] - MDN received: processed

A failed send shows the error with details. Check the troubleshooting section for specific errors.

How do you verify OpenAS2 can receive messages?

Inbound testing requires someone to send to your endpoint — either your partner or a second OpenAS2 instance running locally. Received messages land in the data/inbox/ directory (the exact path depends on your config.xml directory module settings).

# Instance A sends to Instance B on localhost:10080
# Instance B's partnership should have as2_url pointing to http://localhost:10080/as2/HttpReceiver

If you don't have a second instance or a cooperative partner yet, see how to test an AS2 connection without a partner.

How do you run OpenAS2 behind a reverse proxy?

Don't expose OpenAS2's port directly in production; terminate TLS at Nginx or Apache and forward to OpenAS2's HTTP port. The two settings people miss are proxy timeouts (synchronous MDN processing can exceed 60 seconds) and request body size limits.

# Nginx configuration for OpenAS2
server {
    listen 443 ssl;
    server_name as2.yourcompany.com;
    
    ssl_certificate /etc/ssl/certs/as2.yourcompany.com.crt;
    ssl_certificate_key /etc/ssl/private/as2.yourcompany.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    
    # Important: increase timeouts for large AS2 messages
    proxy_read_timeout 180s;
    proxy_send_timeout 180s;
    client_max_body_size 100M;
    
    location /as2/ {
        proxy_pass http://127.0.0.1:10080/as2/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

How do you run OpenAS2 as a system service?

On Linux, create a systemd unit so OpenAS2 starts on boot and restarts on failure. Run it as a dedicated non-root user.

# /etc/systemd/system/openas2.service
[Unit]
Description=OpenAS2 Server
After=network.target

[Service]
Type=simple
User=openas2
Group=openas2
WorkingDirectory=/opt/openas2
ExecStart=/usr/bin/java -cp "lib/*" org.openas2.app.OpenAS2Server config/config.xml
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable openas2
sudo systemctl start openas2
sudo systemctl status openas2

What are the most common OpenAS2 errors and how do you fix them?

Most OpenAS2 failures trace back to four causes: port conflicts, keystore/alias mismatches, AS2 ID mismatches, and certificate mismatches between you and the partner. Here are the errors you're most likely to hit, in order of frequency.

"java.net.BindException: Address already in use"

Another process is using port 10080 (or whatever port you configured).

# Find what's using the port
lsof -i :10080

# Or on Linux
ss -tlnp | grep 10080

Fix: Stop the conflicting process, or change OpenAS2's port in config.xml.

"java.io.IOException: Keystore was tampered with, or password was incorrect"

The keystore password in config.xml doesn't match the actual password of the as2_certs.p12 file.

Fix: Verify the password. The default is testas2. If you changed the keystore password with keytool, update the corresponding keystorePassword attribute in config.xml.

"java.security.cert.CertificateException: No certificate found for alias"

The x509_alias in your partner or partnership definition doesn't match any alias in the keystore.

# List all aliases in the keystore
keytool -list -keystore config/as2_certs.p12 -storepass testas2

Fix: Make sure the alias in partnerships.xml exactly matches an alias in the keystore. Case-sensitive.

"ClassNotFoundException" or "NoClassDefFoundError"

Java can't find the OpenAS2 classes. This usually means you're running the startup command from the wrong directory, or the lib/ folder is missing JAR files.

Fix: Always start OpenAS2 from its installation directory. Verify that lib/ contains the JAR files that shipped with the distribution. If you moved or renamed files, re-extract from the original zip.

"Connection refused" when sending

Your partner's AS2 URL is wrong, their server is down, or a firewall is blocking the connection.

# Test connectivity to partner
curl -v https://partner.example.com/as2
nc -zv partner.example.com 443

Fix: Verify the URL with your partner. Check that your outbound firewall allows HTTPS traffic to their IP.

"org.openas2.OpenAS2Exception: Partnership not found"

The AS2-From/AS2-To combination in the incoming message doesn't match any partnership in your partnerships.xml.

Fix: Check the exact AS2 IDs your partner is using. They must match the as2_id values in your partnership definition. Copy and paste from their configuration document. Watch for trailing spaces or case differences.

"Decryption failed" or "Unable to decrypt"

Your keystore doesn't contain the private key that matches the certificate your partner used to encrypt the message.

Fix: Your partner encrypted with your public certificate. Make sure the keystore has the corresponding private key entry (type PrivateKeyEntry, not trustedCertEntry). If you recently generated a new key pair, you need to send the new public certificate to your partner and have them update their configuration.

"Signature verification failed"

The partner's public certificate in your keystore doesn't match the private key they used to sign the message.

Fix: Get a fresh copy of the partner's current public certificate and re-import it into your keystore. They may have rotated their key pair without notifying you.

How do you tune OpenAS2 for higher throughput?

OpenAS2 runs well out of the box for hundreds of messages per day; beyond that, tune the JVM heap, polling interval, and storage. Specifically:

  • Increase Java heap: Edit the startup script to add -Xmx512m or -Xmx1g to the Java command line
  • Reduce polling interval: The directory polling module in config.xml has an interval attribute (in seconds). Lower it for faster pickup, but don't go below 5 seconds.
  • Use SSD storage: OpenAS2 writes message data and logs to disk. SSD reduces I/O bottlenecks.
  • Rotate logs: Configure log rotation in config.xml or use external log rotation (logrotate on Linux). Unmanaged logs can fill a disk.

How do you know your OpenAS2 setup is production-ready?

A test message that goes through once doesn't prove your encryption algorithm is strong enough, your certificate won't expire before your next audit, or your MDN configuration works end to end. Validate the whole stack against a known-good endpoint before a trading partner's first real message does it for you.

AS2 Certify runs a comprehensive test against your endpoint — TLS configuration, certificate validity and key strength, encryption and signing algorithm compliance, MDN generation and verification, and AS2 header correctness — and produces a graded report (A through F) that tells you exactly what's production-ready and what needs fixing. Start with the free AS2 connection tester.