Local AS2 Server
A Local AS2 Server is a type of Endpoint that represents an AS2 receiver that UDMG Server hosts locally to enable partners to securely upload files using the AS2 protocol.
This Endpoint type provides the essential infrastructure for accepting incoming AS2 connections, functioning as the Source Endpoint within a Pipeline of type Local AS2 Server to Local Filesystem.
Before You Begin
Listener IP Address and Port
The Listener IP Address and Port together define the local listening address for this Local AS2 Server Endpoint:
- Listener IP Address is the local IPv4 address that the UDMG Server binds to for this listener. If you set Listener IP Address to
0.0.0.0, UDMG binds to all IPv4 interfaces on the host. If you set a specific IP (for example,192.168.1.10), UDMG accepts connections only on that IP. - Port is the TCP port on that same host where the listener accepts connections.
When creating a new Endpoint, avoid selecting a Listener IP Address/Port pair that is already assigned to another Endpoint (in any Domain) or used by another service.
Although UDMG allows multiple Endpoints to use the same Listener IP Address/Port combination, only one of those Endpoints—and therefore its associated Pipelines—can be active at a time.
The following considerations apply:
- No Cross-Domain Validation: The system does not automatically prevent duplicate Listener IP Address/Port combinations within or across Domains.
- Manual Validation Required: After configuring an Endpoint, always use the Validate button to see if the Listener IP Address/Port combination is already in use by another service (across all Domains). This action does not check if the IP/port can be specifically used by the Endpoint. See Validating the Configuration for more information.
The partner-facing AS2 URL is http[s]://<host>:<port>/as2. The /as2 path is fixed and required — omitting it returns a 404.
AS2 Identifiers
The Local AS2 Identifier field specifies your organization's unique AS2 identifier, which partners need to know to identify UDMG as the intended recipient of an AS2 message.
The AS2 identifier has no fixed standard: it can be any unique value, such as your name, your company's name, or another distinctive identifier.
The value must match the AS2-To header of each incoming message; otherwise, the transfer is rejected. Before enabling the Endpoint, coordinate this identifier with your partner to ensure consistent configuration on both sides.
HTTPS TLS Certificate Pair
The HTTPS TLS Certificate Pair secures the connection between the partner's AS2 sender and UDMG at the transport layer. Select None to run the server over plain HTTP instead of HTTPS.
The HTTPS TLS Certificate Pair and the AS2 TLS Certificate Pair must be different credentials. Using the same credential for both is not supported.
AS2 TLS Certificate Pair
The AS2 TLS Certificate Pair establishes UDMG's cryptographic identity for AS2 communications. It combines the private key and X.509 public certificate into a single Credential:
- The private key is used to decrypt incoming AS2 messages and sign Message Disposition Notifications (MDNs) returned to partners. When a partner requests a signed receipt via the
Disposition-Notification-Optionsheader, UDMG signs the MDN using this key and returns it as amultipart/signedresponse. - The X.509 public certificate is shared with partners so they can encrypt messages to your organization and verify MDN signatures.
The MIC (Message Integrity Check) value included in the returned MDN is computed using the digest algorithm requested by the partner in the signed-receipt-micalg parameter of their Disposition-Notification-Options header. If no algorithm is requested or the requested algorithm is not supported, UDMG falls back to SHA-256.
Authentication Methods
The Authentication Method defines how partners are authenticated when connecting to the Local AS2 Server Endpoint. UDMG supports two options:
- Partner Certificate Mapping: UDMG authenticates the partner by checking if the AS2-From header matches the Partner Identifier and validating the digital signature using the X.509 Certificate, both configured in the partner's UDMG Account.
- Partner Certificate Mapping plus Basic Authentication: In addition to the certificate-based verification above, the partner must first authenticate with the Username and Password configured in their Account before the AS2 message exchange begins.
| Authentication Method | Username | Password | AS2-From Header | X.509 Certificate |
|---|---|---|---|---|
| Partner Certificate Mapping | ||||
| Partner Certificate Mapping plus Basic Authentication |
Both the AS2-From header and the X.509 Certificate are configured in the partner's UDMG Account.
Regardless of the Authentication Method selected, UDMG requires a matching Account for every AS2 partner. The Account holds the Partner Identifier (matched against the incoming AS2-From header) and the X.509 Certificate (used to verify the partner's digital signature). After the partner is identified, UDMG resolves the destination Pipeline through the Account's Account Group associations. If no matching Account exists or no Account Group links the Account to a compatible Pipeline, the transfer is rejected.
Message Level Security (MLS) Enforcement
This setting defines the minimum security requirements that incoming AS2 messages must meet. You can choose between the following options:
- Signed and Encrypted: Messages must be digitally signed and encrypted.
- Compressed, Signed, and Encrypted: Messages must be compressed using ZLIB, digitally signed, and encrypted.
Messages that do not comply with the selected policy are rejected.
Message ID Retention Period (Minutes)
This value determines how long UDMG keeps a record of received Message-ID values to detect and block duplicate messages. By maintaining this cache, UDMG prevents replay attacks (attempts to resend a previously accepted message) within the defined retention window.
Choose a duration appropriate for your operational and compliance requirements; typical configurations range from 1440 to 86400 minutes (1 to 60 days).
Adding an Endpoint
To add an Endpoint, follow these steps:
- From the Sidebar, select Configuration > Endpoints.
- Click Add Endpoint.
- Select Local AS2 Server in the Endpoint Type dropdown.
- Complete the Name and Description details for the new Endpoint.
- Enter the Listener IP Address and Port.
- Enter the Local AS2 Identifier your partners will use for inbound authentication.
- Select the TLS Certificate Pair from the Credentials Name (AS2 TLS Certificate Pair) dropdown.
- Select the Authentication Method your partners will use to authenticate to the Local AS2 Server.
- Complete the MDN configuration fields using the table below as a guide.
- Click Add to create the Endpoint.
- Click Validate to confirm that the IP address and port combination is not already in use by another service (across all Domains). See Validating the Configuration.
- Click Start to launch the server. See Starting, Stopping, and Restarting Endpoints.
UDMG allows creating identical Endpoints with unique names, but this practice is strongly discouraged due to potential downstream complications.
Field Descriptions
The following table describes the fields that are configured for the Endpoint:
| Name | Description | Specifications | Required |
|---|---|---|---|
| Endpoint Type | Select Local AS2 Server to expose an AS2 listener that receives files uploaded by business partners. | The type cannot be changed after creation. | Yes |
| Name | The name of the Local AS2 Server Endpoint. |
| Yes |
| Description | The description of the Local AS2 Server Endpoint. | No | |
| Business Service | Assigning a Business Service to this Endpoint restricts updating, deleting, and other actions so only Users with the same Business Service can perform them (role permissions still apply). For details, see Business Services. |
| No |
| Listener IP Address | The local IPv4 address that the UDMG Server binds to for this AS2 listener. | Must be in IPv4 format. | Yes |
| Port | The port number of the Local AS2 Server Endpoint.
|
| Yes |
| Local AS2 Identifier | Your organization's AS2 ID used for inbound matching. Incoming messages must present AS2-To equal to this value or they are rejected. | Yes | |
| Credentials Name (HTTPS TLS Certificate Pair) | TLS Certificate containing the X.509 Public Certificate and corresponding private key for this server, used for securing the HTTPS connection. Select None to run the server over plain HTTP instead. |
| Yes |
| Credentials Name (AS2 TLS Certificate Pair) | TLS Certificate containing the X.509 Public Certificate and corresponding private key for this server, used to decrypt inbound AS2 messages and sign asynchronous MDNs. A copy of the public certificate should be shared with your AS2 partner for encrypting messages sent to you. For more information, refer to AS2 TLS Certificate Pair. | Must reference an existing TLS Certificate Pair. | Yes |
| Authentication Method | Enforces sender authentication using Partner ID and certificate binding, with optional support for Basic Authentication. Aligns with Drummond expectations for identity assurance via AS2 headers and digital signatures. Options:
| Default value: Partner Certificate Mapping. | Yes |
| Message Level Security (MLS) Enforcement | Specifies the Drummond-aligned security policy applied to incoming AS2 messages. Messages that do not meet the selected requirement are rejected. Options:
| Default value: Signed and Encrypted. | Yes |
| Message ID Retention Period (Minutes) | Defines how long the system retains a record of received message identifiers to detect and block duplicates. A duplicate is considered a potential replay if it arrives within this retention window. |
| Yes |
| Auto-start Endpoint | When enabled, the Endpoint is automatically started if the UDMG Server is started or restarted. Due to a known issue in UDMG 3.3.2, in Active/Active environments, Local Endpoints with the Auto-Start Endpoint option disabled are automatically stopped approximately 5 minutes after manual startup. For a workaround and more details, see Auto-Starting an Endpoint. | Default value: Enabled. | No |
Editing an Endpoint
To edit an Endpoint, follow these steps:
- From the Sidebar, select Configuration > Endpoints.
- Click the Name field of the Endpoint you want to edit.
- Click Edit above the Endpoint details.
- Edit details for the Endpoint, using the Field Descriptions table as a guide.
- Click Update.
- Click Restart or Stop/Start.
Configuration changes remain inactive until the Local AS2 Server Endpoint is restarted and the Account disconnects/reconnects to its client.
After changes are made, restart the Endpoint to apply the changes. All active connections are terminated.
Managing an Endpoint
The Local AS2 Server Endpoint has multiple management capabilities that allow you to manage and validate the Endpoint.
Viewing Endpoint Details
To view the details of an Endpoint, follow these steps:
- From the Sidebar, select Configuration > Endpoints.
- Click the Name of the Endpoint you want to view.
- Additionally, click the Pipelines tab to see all the Pipelines the Endpoint is associated with.
Endpoint Metadata
Endpoint details include all parameters given in the Field Descriptions table, plus the following read-only metadata:
| Name | Description |
|---|---|
| UUID | Universally Unique Identifier of this Endpoint. |
| Version | Version number of the configuration. Every change increases the number. |
| Created | Date and time this Endpoint was created. |
| Updated | Date and time this Endpoint was last updated. |
| Test Status | Status of the Validate Endpoint configuration test. Options:
|
| Runtime Status | The status of the server Endpoint. Options:
|
Validating the Configuration
The configuration can be validated to confirm if the Local AS2 Server Endpoint's IP Address/Port combination is used by another service (across all Domains).
It is important to note that, even if a port is not being used elsewhere in UDMG, it is not necessarily available.
AS2 operates over HTTP or HTTPS standards, and the most common ports for AS2 file transfers are 80 for HTTP and 443 for HTTPS.
Avoid using:
- Ports already taken by other Endpoints.
- Ports
1344,111, and81. - UDMG Server ports (most likely
7070/7071,8080/8081,4222/6222). - Ports blocked by your IT controls.
To validate the configuration, stop the Endpoint first (click the Stop button) and then click the Validate button. One of the following messages appears:
- Error/Fail: 'Endpoint test has failed. The port #### on address #.#.#.# is already in use.'
- If validation fails, then the IP Address/Port is not available and should not be used. You must review and modify the IP Address/Port combination.
If the Endpoint's Runtime Status is Running, then the validation test will fail because the IP Address/Port is being used by that Endpoint.
- Pass: 'Endpoint has passed the test.'
- If validation passes, the IP Address/Port is not currently being used by another service.
The test does not confirm if the IP Address/Port can be used by the Endpoint. The IP Address/Port must be available based on your network IT controls, such as firewalls.
Starting, Stopping, and Restarting Endpoints
Local AS2 Server Endpoints function as virtual servers that require proper management for file transfer operations. After initial creation, these Endpoints must be activated before they can process transfers. Endpoints can be initiated through one method:
- Manual Start: Click the Start button on the Details page.
Additionally, configuration changes only take effect following an Endpoint restart or stop/start cycle. Once the Endpoint is running, three control actions are available from the Details page:
- Start: Launches the Endpoint connection when currently stopped.
- Stop: Initiates the shutdown of the Endpoint. New connections are not allowed, while the pending sessions remain until they are disconnected. Utilize the Active Sessions field on the Details page.
- Restart: Executes a complete stop/start sequence to apply configuration changes.
After the initial server creation and initiation, the Endpoint has a Runtime Status indicator that shows the real-time operational state of the server. The current status determines which management actions can be performed. The current state (Runtime Status) of each Local AS2 Server Endpoint is displayed in the Endpoint Record Table and Details page with the following statuses:
- Starting: Server is starting, but not operational yet.
- Running: Server is operational and processing connections.
- Stopped: Server is not running. Especially after a Stop request, it is possible that sessions remain until they disconnect. Utilize the Active Sessions field on the Details page.
- Error: listen tcp 0.0.0.0:2041: bind: address already in use: Server's IP/Port is in use on another Endpoint (across all Domains).
Auto-Starting an Endpoint
Local AS2 Server Endpoints can be configured for auto-start functionality, allowing them to launch automatically if the UDMG Server is stopped after initial creation or upon startup of the UDMG Server. This setting is established during Endpoint creation and can be modified later.
- Enabled: The Endpoint automatically starts without manual intervention after the UDMG Server is stopped (Auto-start active).
- Disabled: The Endpoint remains inactive until manually started after the UDMG Server is stopped (Auto-start inactive).
To set an Endpoint to auto-start, follow these steps:
- From the Sidebar, select Configuration > Endpoints.
- Click the Name of the Endpoint you want to update.
- Click Edit.
- If the Endpoint is currently auto-started, you can remove the auto-start feature by moving the toggle to the left.
- Click Update.
The Auto-Start Endpoint status is reflected as the Enabled field on the Details page.
Due to a known issue in UDMG 3.3.2, in Active/Active environments, Local Endpoints with the Auto-Start Endpoint option disabled are automatically stopped approximately 5 minutes after manual startup.
Workaround: Enable the Auto-Start Endpoint option for Local Endpoints in Active/Active environments, or operate the cluster in Active/Passive mode.
Deleting an Endpoint
To delete an Endpoint, follow these steps:
- From the Sidebar, select Configuration > Endpoints.
- Click the Name of the Endpoint you want to delete.
- Click the Delete button above the Endpoint details.
- You will be asked to confirm the deletion. Click Continue.
UDMG prevents the deletion of a Configuration Item if it is currently referenced by another Configuration Item (i.e., Pipeline). The Configuration Item must be edited or the reference removed before you can delete the Endpoint. Deletion cannot be undone.