Getting started with AS2 protocol using AS2Gateway and OpenAS2
Most of the large retail providers and consumer product suppliers such as Walmart, Amazon and Morgan Foods etc. have decided to go with AS2 protocol in last few years. Based on this trend, all of their suppliers are asked to send their invoices, purchase orders and other B2B trading messages over the AS2. Because of that, the trend for the usage of AS2 has been significantly increased over the last couple of years. In this blog, I’m going to explain how to get started with AS2 protocol and how do you send and receive AS2 messages using two software applications which provide AS2 capabilities.
What is AS2?
In simple terms, the Applicability Statement 2 or AS2 specification defines a mechanism for secure and reliable transfer of structured business data over the Internet. In contrast to other traditional B2B trading protocols, AS2 offers a secure, efficient and simple to use trading environment without a need for proprietary devices, software or expensive private networks or value added networks. If you are new to AS2 protocol, I highly recommend you to read this description on AS2 protocol before going to use in your production requirements. It describes what is AS2, why do we need AS2 and what are the key benefits of that in simple terms and you don’t have to have a technical background to understand that. If you have some technical background and you want to know how the protocol operates over the HTTP/S protocol, you can refer this and get a better understanding about the implementation of the AS2 protocol.
There are few software applications (on-premise and SaaS) which provide AS2 capability. For this exercise, I have used AS2Gateway and OpenAS2 to explain how do you configure these two applications to send messages back and forth.
What is OpenAS2?
OpenAS2 is a Java-based implementation of the AS2 standard which supports XML file-based configuration — user interface configuration is not yet implemented, but it’s there on their road map. You can download OpenAS2 from the above mentioned location. Make sure you download the latest version to minimize the effect of already fixed issues.
What is AS2Gateway?
AS2Gateway is a SaaS application which implements the AS2 specification while providing the ability to configure AS2 stations and trading partners from a nice and simple user interface. Compare to the OpenAS2 it’s quite easy to configure AS2Gateway for your AS2 requirements - specially if you are user who doesn’t have a good technical background and not familiar about server type application to work without a graphical UI. You will understand the difference while reading this blog. Since it has a GUI, it provides additional utility functionalities for advance requirements on AS2 such as certificate management, SFTP integration and much more.
So in this exercise, I’m using two hypothetical organizations — Company X and Company Y, which expects to send and receive AS2 messages back and forth based on there B2B trading requirements. Company names will be important here, because I’m going to use AS2 identifiers based on the company name, for Company X, AS2 identifier will be company-x-as2-id and for Company Y, it company-y-as2-id. Company X uses OpenAS2 as the AS2 software while Company Y uses AS2Gateway as its AS2 software.
First I’ll explain how Company X should configure its AS2 Station and trading partners in OpenAS2 and then explain the same on the AS2Gateway.
Set up OpenAS2
First you need to install OpenAS2 in your machine.
You just need to download and extract the ZIP file for the installation. Once it’s extracted, you can start the AS2Server, by executing the bin/start-openas2.sh file. Make sure scripts are executable.
In OpenAS2 there isn’t a concept called AS2 Station. It identifies both station and partner as two different partners and configures their relationship as a partnership. There are two main configuration files that you need to focus on basic AS2 options.
First one is the config/config.xml. In this file, you can configure modules for AS2 message handling. In this file, you need to configure a set of AS2DirectoryPollingModule modules to fetch files to send to different partner. For each partnership between two partners, you need to have an AS2DirectoryPollingModule module element to send files from one partner to another.
The second one is the config/partnership.xml. There you need to configure declarations of each partner and relationships between those declared partners. To declare partners, you should have a partner type XML element with partner name, partner AS2 ID, partner x509 alias (for certificate management) and email — just focus on partner name, AS2 ID and partner alias.
All the relationships between each partner should be defined as a partnership XML element in the partnerships.xml file. This element represents one-way relationships between one partner to another. If you want to send messages in both sides, you have to configure two partnerships XML elements.
The next main important thing is certificate management which is the tricky part :-) Here you have to import and export your certificates manually to/ from your keystore. By default, it uses config/as2_certs.p12 as the key store. You can configure the keystore path, by changing the filename attribute of the certificates XML element in the config/config.xml file. In the default keystore, there are two keys for two default partners — openas2a and openas2b.
For keystore, configuration, there are two things you have to do,
- Import your trading partner’s certificate into keystore using some keystore managing software or keytool — you can get the certificate of the AS2Gateway station (company-y-as2-id) using “View partner configuration” option in the AS2Gateway
- Export certificate chain of the key of your side partner (or in other words, your AS2 station — in this example this should be the key of AS2 station with AS2 ID company-x-as2-id) and use it to configure your trading partner at the other end (in this example other end is the Company Y)
To configure OpenAS2 as explained in the following section, you need information about the AS2Gateway side station. You can get this information from the “Partner Configuration” view of your AS2 station — AS2Station view -> View Partner Configuration. This view will have all the required information to configure AS2Gateway side station in some other AS2 server as a trading partner. Generally, users’ of the AS2Gateway will use this and send this information to their trading partners via Share Configuration option in the Partner Configuration view page
Configure OpenAS2 for the example use case
From the OpenAS2 side, sending party would be AS2Station with AS2 ID — company-x-as2-id and receiving party AS2 ID should be company-y-as2-id.
1. For this first, you have to configure partnerships.xml file as below — from the Company X point for view, Company X is the AS2 station and Company Y is the trading partner.
2. Next, you need to configure config/config.xml file for file polling configurations — OpenAS2 gets input files (to send out as an AS2 message), by polling directories configured from following XML elements.
3. Then you have to configure certificates and your keystore. For that first, you have to create a key pair for your Company-X side station. You can easily do that using some tool like Portacle. Since we have configured CompanyXStaion partner’s x509 alias as company-x, you have to give the entry name/alias for the key pair that you’re going to create for your Company-X.
4. Then you can export your OpenAS2 station’s certificate chain, as shown in the below screenshot. You just have to select the correct key and export the certificate chain via keystore management utility — Portacle
5. Then, you have to import your ComanyYPartner’s certificate to your OpenAS2 side trust store. For that, you have to get this from the Company-Y side. In this case, you can get this certificate from the AS2Gateway.
With this, your are done with the OpenAS2 side configuration.
Set up the AS2 Gateway
For AS2Gateway, you just have to sign up as a free user and get an evaluation period of one month with the exact same features like a premium/ paid user. For the registration, you don’t have to provide any credit card information, you just need a valid email address for that. You can sign up/ register for AS2Gateway from here. Go to that link and click on Create Account option to create a new account for you.
From the configuration point of view, I think I don’t have to introduce anything for that. Since there is a user interface and it’s self-explainable, you should be able to identify key components of that. For our example, you just have to create a Station with AS2 ID company-y-as2-id and trading partner for Company X. I’ll explain this in next steps.
Configure AS2Gateway for the example use case
As per our example, Company-Y should configure AS2Gateway to send/ receive messages with Company-X. From the AS2 point of view, we should send messages to AS2 station with AS2 ID, company-y-as2-id to the trading partner with AS2 ID, company-x-as2-id. Go through following steps to configure AS2Gateway.
1. Assuming that you have already registered with AS2Gateway, you just have to create AS2Station using the graphical UI. You can easily navigate to Stations view using left navigation menu of the AS2Gateway. Click on New Station button at the top of the page. Then you just have to give an AS2 ID for your station. In our example, AS2 ID should be company-y-as2-id. And then click the Save button.
2. Then you should create a Partner within the AS2Gateway to represent your trading partner — in our case, Company-X is the trading parter for Company-Y. For that, you just have to go to the Partner view using left navigation menu and then click on New Partner button at the top of the page.
2.1. In partner creation page, you have to specify the AS2 ID of the partner — company-x-as2-id in our example.
2.2. Specify the URI to be used while sending messages to this partner. In our example, this URI should be “http://my-public-ip:10080" — my-public-IP part should be replaced with your current public IP and it makes sure it’s publicly reachable.
2.3. Then you have to upload your partner’s certificate for the Encryption Certificate field. This should get from the OpenAS2 side (as explained in the following section you have to export certificate chain of your OpenAS2 side station) since it’s the partner for this example.
2.4. Optionally you can configure a subject to be included while sending messages to this partner. Then click on the Save button to complete the partner creation.
Now it’s all done and you should be able to send and receive AS2 messages between AS2Gateway and OpenAS2. To send messages from the AS2Gateway side, you just have to navigate to the messages view using left navigation menu, and send a new message using the Compose Message option. All the received messages to the AS2Gateway will be there in the Inbox tab of the messages view and you can see all the information including transport headers, MDN related information and message payload using the view message option.
To send a message from OpenAS2 side to AS2Gateway, you have placed an input file to the configured input file folder. As per above configuration, it should be the
data/toAS2GStation. Received MDNs will be saved in data/OpenAS2A-to-AS2GStation/mdn folder. Received messages from AS2Gateway to OpenAS2, should be saved to the data/AS2GStation-to-OpenAS2A/inbox folder.
As you have already felt, configuring AS2Gateway for AS2 communication is much easier since it has a simple user interface and utility functionalities for certificate management and SFTP integration.
Hope you have enjoyed the blog and it’s useful for you. If you have any comments or suggestions, feel free to share in comments.