Configure an AS4 Connection
Version 24.3.9106
Version 24.3.9106
Configure an AS4 Connection
Overview
CData Arc supports establishing an AS4 connection with a trading partner in a simple two-step process. First, the AS4 Profile should be configured with local AS4 details (identifier, private certificates, etc); then, an AS4 Connector is configured in the Flows page with the AS4 details for a specific trading partner.
AS4 Profile Configuration
The Profiles page contains an AS4 Profile tab where local AS4 details are configured. The two primary configuration details are:
- Party Identifier (the value identifies Arc to your trading partners as an AS4 entity)
- Private Certificate (the certificate that is used to decrypt incoming messages and sign outgoing messages)
These values (explained in detail below) should be set in the AS4 Profile:
Party Identifier
Your AS4 identifier is included in outgoing AS4 messages and identifies you as the sender; additionally incoming AS4 messages must be addressed to this identifier to be accepted by the application. AS4 identifiers have a few restrictions, for example they cannot include whitespace characters and they are case-sensitive. Other than this (and any further restrictions imposed by trading partners), AS4 identifiers can be any value so long as it is mutually agreed-upon.
Some identifiers must be qualified by the Party Identifier Type to provide context to the identifier value.
Private Certificate
Your private certificate is used for digital cryptography (decryption, digital signatures). The private certificate contains a private key that is paired with your public encryption key; when a trading partner uses your public encryption key to secure an AS4 message, it ensures that only you can decrypt the message (with the paired private key).
Arc supports private certificates in PKCS#12 format (.pfx or .p12 files), and PEM-encoded public key certificates (.cer files).
Creating a New Certificate Pair
If you do not already have a private/public key pair to use for AS4 security, Arc supports creating a self-signed certificate. Self-signed certificates are common in the AS4 space, but some partners may require purchasing a certificate from a trusted Certificate Authority (CA).
To create a new certificate pair, click the Create Certificate
button to open the certificate creation wizard:
Within this wizard, configure the following required fields:
- Common Name - The hostname of the server using the certificate; used in conjunction with the serial number to identify the certificate
- Organization - The company or group to which the certificate belongs
- File Name - The name of the certificate file (with .pfx extension); the corresponding public key certificate will have the same name with a .cer extension
- Serial Number - A unique serial number that is used in conjunction with the common name to identify the certificate
- Password - The password required to access the private key
- Validity Period - Determines the expiration date of the certificate
- Key Size - Whether to create a 512, 1024, or 2048-bit key
- Signature Algorithm - The algorithm to use when applying a digital signature to the certificate, verifying its authenticity
The remaining fields can optionally be configured to provide further context and metadata to the certificate.
Once created, the new certificate files are placed in the ‘data’ directory for the application. When certificate files reside in the ‘data’ directory, then are included in the dropdown menu for any Certificate-type settings in the application.
Application URLs
The Application URLs section of the AS4 Profile tab defines the publicly-accessible endpoints where trading partners can send AS4 messages to Arc. The Base URL field in Settings → Advanced should be set to the base url leading to the machine/network where Arc is hosted (e.g. https://mydomain.com/Arc). The Receiving URL endpoint is generated based on this domain value and the port on which the application’s web server is listening.
AS4 Connector Configuration
After the AS4 Profile is configured, navigate to the Flows
page and create an instance of the AS4 Connector. Each AS4 Connector is configured with the AS4 details for a single trading partner.
Required Configuration Settings
AS4 configuration details must be solicited from the trading partner. At a minimum, the details that the trading partner provides must include:
- Party Identifier
- URL/endpoint where outgoing AS4 messages should be sent
- Agreement
- Public certificate/key for encryption
- Service
- Service Action
- Roles
The AS4 protocol includes several pieces of metadata to convey information about how the AS4 message should be received and interpreted, primarily: Agreement, Service, Service Action, From Role, and To Role. These values are mutually agreed-upon with AS4 trading partners, so make sure to clearly communicate with any partners which values they expect in these fields.
Configure these values under the Trading Partner Info and Trading Partner Certificates of the AS4 Connector:
Additional Configuration Settings
Partners may additionally include further requirements:
- Synchronous vs Asynchronous receipts (if not specified, assume synchronous)
- SSL Server Certificates for connecting to an HTTPS server (configured under Trading Partner Certificates)
- Message Properties (additional metadata included in the AS4 payload)
- Specific encryption or signature algorithms (configured in the Advanced tab under Encryption Algorithm and Signature Algorithm)
- A separate certificate (in addition to the encryption certificate) for verifying signatures (configured in the Advanced tab under Partner Signing Certificate)
Testing the AS4 Connection
Once the AS4 Connector for a trading partner is configured, the connector supports generating dummy documents to test the outgoing connection. Navigate to the AS4 Connector’s Input tab, expand the ‘More’ dropdown, and select ‘Create Test Files’.
Unless Send Automation is disabled in the Automation tab, the connector will automatically attempt to process these test files. Any errors that occur when sending the test files to the configured partner are reported in the Input tab, including a log file with context and details on the error. The Log Level and Log Requests options can be set in the Advanced tab to further diagnose any connection issues.
Successfully processed files will be shown with a green ‘Sent’ status in the Input tab. Successfully sending test files establishes that the AS4 configuration is correct.
Providing AS4 Details to Trading Partners
In the same way that trading partners must provide AS4 configuration details in order to configure an AS4 Connector for that partner, you are responsible for providing AS4 configuration details to your partners.
At a minimum, you must provide your partner with:
- Your AS4 identifier
- Your public key/encryption certificate
- Your receiving URL
Additionally, the metadata in AS4 messages must be mutually agreed-upon: Agreement, Service, Service Action, From Role, To Role.
Sending AS4 Messages
Once an AS4 Connector has successfully established an outgoing AS4 connection, files can be securely and reliably sent to your trading partner.
Input Tab
Files that are placed in the Input tab for the configured AS4 Connector are scheduled to be sent by the connector.
If Send Automation is enabled in the Automation tab (enabled by default), the connector will automatically poll this folder for files to process. Otherwise, files can be manually sent via the connector’s Input tab. Within the Input tab, click the checkbox to the left of the target file(s) and click the Send
button.
The Input tab can also be used to upload files into the Input folder using the More
dropdown button and the ‘Upload Files’ option.
The ‘Upload Files’ tool is not required to add files to the connector’s Input folder. Files can also be manually dropped into the Input folder by navigating to the filepath listed at the top of the Input tab, and files can arrive at the AS4 connector naturally if it is part of a connected FLow.
Sending as Part of a Flow
In most configured workflows, files are processed by other Arc connectors before they should be sent out by the AS4 Connector. When another connector is connected to the AS4 Connector in a Flow, files are automatically passed into the AS4 Connector’s Input folder.
Receiving Receipts
The AS4 Connector automatically waits for receipts if Enable Receipt is checked. If the receipt contains a negative response (e.g. if the partner has rejected the exchange for some reason), the connector will report an error instead of a successful send.
If an Asynchronous receipt is requested, the connector will stay in ‘pending’ status until the receipt is returned by the partner. Synchronous receipts are recommended unless the files exchanged over AS4 are very large (e.g. 500MB).
Receiving AS4 Messages
When an AS4 message arrives on the Arc web server, the application attempts to route the message to a specific AS4 Connector. Arc uses the AS4 identifiers in the headers of the message to route the incoming file to the AS4 Connector configured for the partner that sent the message.
If the application cannot find an AS4 Connector configured for the incoming message (based on AS4 identifiers), an error is logged in the Application Log and the file is not received.
Output Tab
When the file received over AS4 is routed to a specific AS4 Connector (based on configured AS4 identifiers), the file arrives in the Output tab for the connector.
If the AS4 Connector is connected to other connectors in the Flow, files will not stay in the Output folder and will instead be passed along to the next connector in the flow.
If the AS4 Connector is not connected to another connector in the Flow, the files received by the AS4 Connector will remain in the Output folder. These files can be viewed in the Output tab of the connector, or by navigating on disk to the filepath displayed at the top of the Output tab.
Sending Receipts
If the incoming AS4 message requests a receipt, the AS4 Connector automatically generates and sends it. If an error occurs while receiving the AS4 message, this error is logged in Arc and included in the receipt returned to the trading partner.
The settings required for sending receipts are included in the incoming AS4 message and does not need to be explicitly configured in the AS4 Connector.