AS2 Communication

The AS2 protocol is a very common way to exchange documents between companies. Link has built-in support for the protocol, both ingoing and outgoing.

Partners

To facilitate AS2 communication in Link, the partners involved in said communication need to be configured accordingly.

Partner identification

In order to participate in AS2 communication, a Link partner must have a partner identification of the type “AS2”. If you are setting up AS2 communication for the first time on a given Link system, this identification type may not exist, in which case you just create it. Make sure to create it with the exact name “AS2”. Needless to say, the value of the partner identification should be the identifier the partner uses for AS2 communication.

Internal partner

This is the partner that should be able to send and receive AS2 on the Link system. In order to do this, the partner needs to have a private key certificate marked for AS2 usage registered in Link. The private key will be used for signing the outgoing AS2 messages and decrypting the ingoing ones.

It is possible to have multiple partners on a Link system set up in this way, so if for instance you have separate companies in different countries, you can have partners for each of them set up to send and receive AS2 separate from one another, provided they do not use the same AS2 identifiers.

External partners

Each external partner you need to exchange documents with via AS2 must have a public key certificate registered in Link, marked for AS2 usage. The public key will be used for validating the signature of incoming messages from this partner and for encrypting outgoing messages to the partner.

Sending via AS2

If you need to send messages to a partner via AS2 from Link, you need to create an outgoing transport location on the partner using the AS2 transport type.

Send location configuration

The configuration of an AS2 send location looks like this:

I will not go over every single field in the configuration, but will focus on the most important ones.

• Endpoint URL

  • This is the URL of the AS2 endpoint the message should be sent to.

• Sender ID

  • Only use this if this particular send location needs to use a different AS2 identifier from the one configured on the sender partner.

• Receiver ID

  • Same as above

• Type of MDN

  • Valid values are None, Signed and Unsigned. If in doubt, use Signed.

• Request async MDN

  • Only use this if you have a valid reason to request an asynchronous MDN.

• Async MDN URL

  • If you request an async MDN, use this field to provide the URL you want the async MDN sent to, either the endpoint of the Link AS2 host, or an AS2 Http handler endpoint you have set up beforehand.

• Sign Message

  • Determines whether the outgoing message will be signed. If in doubt, keep this checked.

• Encrypt Message

  • Determines whether the outgoing message will be encrypted. If in doubt, keep this checked.

• Override signing certificate selection

  • If checked this reveals a dropdown where you can choose a different certificate to use for signing than the one configured on the partner. Do not do this unless you have good reason to.

• Override encryption certificate selection

  • Same as above.

Receiving via AS2

Link has two ways of receiving AS2 communication: the AS2 API host, and the AS2 HttpHandler component, which can be used to mount custom AS2 endpoints on a Link system.

AS2 API host

The AS2 API host is the default method of receiving AS2 transmissions in Link. It has no configuration to set up, other than the configuration of the partners involved as detailed above.

The URL of the endpoint is: https://[CustomerName]-[Environment]-api-link.bizbrains.com/api/transport/as2

AS2 Http handler

The AS2 http handler can be used in situations where the AS2 communication needs to be handled differently from the normal setup. There can be various reasons for this.

One scenario is where the documents received via AS2 do not contain enough information for Link to determine what to do with them based on the contents of the document alone. In such cases it is necessary to provide Link with an InitConfiguration for the documents, and the AS2 Http handler lets you do that.

Another scenario could be that you need to receive AS2 from a sender who simply cannot encrypt their messages, so you want to, just for them, allow unencrypted AS2 messages while still requiring the rest of your incoming AS2 communication to be encrypted. The AS2 Http handler will also let you override that setting.

Simply set up an Http handler endpoint using the AS2 Http handler, configure it with the necessary information, and give the sender the address of the endpoint.

Http handler configuration

The AS2 Http handler configuration looks like this:

The AS2 Http handler configuration allows you to override various aspects of the AS2 communication if necessary, and from the list of configured Http handler endpoints you can set up an Init configuration for the endpoint. If you don’t need to do any of those things, there is no need to set up an endpoint in the first place, just use the normal endpoint in the AS2 host.

MDN

The MDN or Message Disposition Notification is the AS2 version of a technical acknowledgement message. If the sender of an AS2 message requests that an acknowledgement be returned, the receiver sends an MDN back, either synchronously or asynchronously. The MDN contains a status, a signature, and a hash value of the received message for verification purposes.

For outgoing AS2 messages in Link, the contents of the MDN determines whether the Link document ends up in Completed or Failed status.

MIC

The MIC or Message Integrity Check is a computed hash value of the received message. It is returned with the MDN so the sender of the original AS2 message can validate that what was received at the other end is the same as what was sent originally. It is computed using either the SHA1 or MD5 hash algorithms. In the request for an MDN to be returned it is also indicated which hash algorithms will be accepted for the returned MIC value.

Synchronous MDN

Usually, MDNs are sent synchronously, meaning that the MDN is returned in the Http response of the Http request used to send the AS2 message.

Asynchronous MDN

It is possible for an MDN to be sent asynchronously, but it is up to the sender of the original message whether this should be the case (or whether an MDN should be sent at all). Link can both send and receive asynchronous MDNs, but unless there is a specific reason to do it this way, synchronous transmission is the better option. It is also the default option, so unless you have a specific reason to configure an outgoing AS2 transmission to request an asynchronous MDN, just don’t worry about it.

If you do need to request an asynchronous MDN, you need to provide the URL that the receiver of the message should send the MDN to. This can be the normal AS2 endpoint in Link, or a custom endpoint set up using the AS2 Http handler.

TEST:

Inserted Link: Init configuration

Copied Link: Init configuration - Link 2.12 - Confluence