Cloud Relay – Getting started guide

First things first, you will need a Microsoft Azure subscription before proceeding. If you don’t already have one, you can start a free trial using the link below:

So now that you have an Azure account let’s get started.

Create a Azure storage account

From the Azure portal, select All Services and then search for Storage accounts. From here, select New to create a new storage account.

Your new storage account can reside in any resource group, but we generally recommend creating a new resource group. The names can be anything desired, and standard tier performance is adequate in all but the most extreme circumstances.

The account kind should be general purpose v1. The storage redundancy should be selected based on the criticality of the environment.

The storage account must be accessible from all networks. Finally, create the new storage account.

Once created (this may take a few minutes), you will then need to open the Access Keys section of the storage configuration page. In this section you will find a primary and secondary connection string. Copy the primary connection string, we will use this later in the setup.

Setup an AS2 Cloud Relay subscription

When first loading the AS2 Cloud Relay dashboard, you will be presented with the New Application page. From here, you can provide:

Instance name: The name for this instance of the AS2 Cloud Relay. This would usually be something like Contoso Production.
Host region: This provides a guides as to where your dedicated AS2 servers will be located geographically. To help ensure resilience, higher tiered subscriptions will have AS2 servers spread across multiple geographic regions.
Description: Text that can be useful for DevOps engineers or other users e.g. a description of what systems are using this AS2 EDI service.
Company Name: The company name may be used for reporting purposes.

Storage Configuration

Once your subscription has been created, you can review the configuration by selecting Subscription Setup from the left hand menu.

The configuration shown will reflect those values entered when creation the subscription. You will however need to save an Azure storage connection string value. This value comes from the Access Keys page on your storage configuration (copied previously). Add the value and save. Note, once the value has been saved, for security reasons you cannot retrieve this value again, this field will show you the name of the storage account, but not access keys.

Configuring local AS2 parameters

Within the AS2 data interchange standard, both the sender and receiver must have a unique identifier, this is called the AS2 Name. To configure the AS2 name, select the Local Host option under AS2 Configuration:

In addition to setting up the AS2 Name, you can also upload certificates for use in encryption and signing. For more details on message security in AS2, please visit the AS2 introduction page at https://eis-web.azurewebsites.net/whatisas2/. You do not have to provide any certificates, and message exchange can still be secured with encryption using the HTTPS protocol (in the same way that visiting a secure website (i.e. your bank) does not require you to provide a certificate, it is managed via PKI).

Certificates:

When creating a certificate, you will have 2 files, one being the public key (usually a .crt file), and the other being the private key (usually a .p12 file). On the local host configuration, you will be uploading the private key of a certificate (usually in a p12 file format)

Inbound Decryption
This private key certificate will be used to decrypt messages that have been sent to you from another party. The other party will have been provided your public key certificate, which they will use for encrypting messages.
Outbound Signature
This private key certificate will be used to sign messages that are being sent from you to any another party. The other party will have been provided your public key certificate, which they can use to verify that the message was sent by you.

Configure an AS2 partner

An AS2 partner is a set of configuration properties that define how the AS2 cloud relay will send or receive electronic data from another system (another business partner).

Display Name
Used for reporting and display purposes, not sent to partner.
AS2 Name
This value uniquely identifies an AS2 partner, and must be provided to you by them.
Endpoint Address
The is the URL where outbound AS2 messages are sent. Again, provided by the parner.
Message Compression
When enabled, outbound messages are compressed before transmission. Please ensure your AS2 partner sup[port compression before enabling (most will). Any inbound message will be automatically decompressed no matter what is configured here.
MDN Type
Please read our introduction to AS2 for more details on MDN (https://eis-web.azurewebsites.net/whatisas2/). We recommend a Synchronous MDN pattern.
Default message subject
This is the HTTP subject that is sent with every message. If this field is left blank, then the value from the AS2 Cloud Relay windows service will be used (more details below on configuring this). Some partners require the AS2 subject to be a value such as ‘SALESORDER’.
Default message content type
This is the encoding of outbound messages. We recommend this is left with its default value unless your AS2 partner request something different.
Request MDN Message Signing
When enabled, outbound messages are marked with a request for all MDN responses to be signed. The signature of the response messages is then checked against the Inbound Signature certificate that is uploaded (below). This certificate will have been provided by your AS2 partner.
Message Encryption
This enables outbound message encryption. You must upload the public key certificate provided by your AS2 partner for message encryption.

Certificates:

Inbound Signature
Certificate is provided by your AS2 partner and is used for checking inbound message signatures. This certificate will usually be in a .crt or .cer format.
Outbound Encryption
Certificate is provided by your AS2 partner and is used for checking outbound message encryption. This certificate will usually be in a .crt or .cer format. Note, if the endpoint address setup above starts with HTTPS, then the communications channel is already encrypted, and that using outbound encryption here results in double message encryption.
You will need to select the format of encryption used, this will usually be specified by your AS2 partner, but if it’s not, we recommend AES256.
Inbound Decryption
This private key certificate will be used to decrypt messages that have been sent to you from another party. You cannot upload a certificate here, it is defined on your ‘Local Host’ configuration page. This is your private key certificate.
Outbound Signature
This private key certificate will be used to sign messages that are being sent by you. You cannot upload a certificate here, it is defined on your ‘Local Host’ configuration page. This is your private key certificate.
You will need to select the format of signing used, this will usually be specified by your AS2 partner, but if it’s not, we recommend SHA256.

Configure the on-premise Windows service

With the AS2 Cloud Relay subscription now configured, you now need a way of pulling received messages onto an server that will be loading the messages (or sending them). This is accomplished with the AS2 Cloud Relay client.

Once downloaded, install the service on one or more Windows servers. During the installation a new Windows Service is created.

You now need to configure the service by editing the configuration file CloudRelaySvc.exe.config

<configuration>
	<configSections>
		<section name="CloudRelaySettings" type="Org.Eis.Cir.Config.Data.CloudRelaySettings, Org.Eis.Cir.Config.Data"/>
		<section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" />
	</configSections>

	<CloudRelaySettings>
		<AzureSettings StorageConnectionString="COPY FROM AZURE" />
		<PartnerSettings>
			<CommunicationPartners>
				<Partner PartnerName="contoso">
					<OutboundFolders>
						<Folder Path="C:\Example\As2Send" QuarantineFolder="C:\Example\Quarantine" 
                                                 RetryPeriodMinutes="5" Subject="SALESORDER"/>
					</OutboundFolders>
					<InboundFolders DeadLetterFolder="C:\Example\Quarantine" >
						<Folder Path="C:\Example\As2Rx\Shipping" Subject="SHIPPING"/>
						<Folder Path="C:\Example\As2Rx\Sales" Subject="SALES"/>
					</InboundFolders>
				</Partner>
				<Partner PartnerName="companyX">
					<OutboundFolders>
						<Folder Path="C:\Example\As2Send_CX" QuarantineFolder="C:\Example\Quarantine_CX" 
                                                  RetryPeriodMinutes="5"/>
					</OutboundFolders>
					<InboundFolders DeadLetterFolder="C:\Example\Quarantine" >
						<Folder Path="C:\Example\As2Rx_CX\Shipping"/>
					</InboundFolders>
				</Partner>
			</CommunicationPartners>
		</PartnerSettings>
	</CloudRelaySettings>

</configuration>

The StorageConnectionString should be the exact same string that was copied from you Azure storage account and saved in the As2 Cloud Relay console earlier.

For each AS2 partner that you would like to send and receive messages from, you will need to created a <Partner> configuration. The PartnerName must match the name given to the AS2 partner in the As2 Cloud Relay console earlier.

Outbound Settings

QuarantineFolder (Required)
The QuarantineFolder property is where outbound messages are copied when they cannot be uploaded for sending. This would usually only occur if the file is corrupted, or the Azure storage is unavailable.
RetryPriodMinutes (Optional)
Defines how long the service should keep trying to upload an AS2 message into the Azure storage (this is separate from the retry period when sending an AS2 message to a partner). A value of 0 will result in no retries.
Subject (Optional)
This is the AS2 Subject to be sent with any messages picked up from this folder.

Inbound Settings

DeadLetterFolder (Required)
Specifies where any messages which have not been downloaded after 24 hours will be placed. The reason an AS2 message can become stuck in the cloud is when inbound folder definitions all specify a Subject value. So if the partner sends a message with a Subject that is not expected, it will be downloaded here.
Subject (Optional)
This is the AS2 Subject which must be present on a message before it is downloaded to the defined folder.