Documentation
Version 1.0

SFTP Integration

Introduction

When sending/receiving a large number of files over AS2, it’s better to use an integration mechanism like SFTP. And also, if you prefer to integrate internal systems with your trading platform, it’s a perfect choice for you to go with MFT Gateway SFTP connectivity which you can configure to automate message flow.

What is SFTP?

SFTP, which stands for SSH File Transfer Protocol, or Secure File Transfer Protocol, is a separate protocol packaged with SSH that works in a similar way over a secure connection. The advantage is the ability to leverage a secure connection to transfer files and traverse the filesystem on both the local and remote system.

MFT Gateway uses AWS Transfer Family service for SFTP integration. The AWS Transfer Family provides fully managed support for file transfers directly into and out of Amazon S3.

Setup SFTP with MFT Gateway

First go to the SFTP Integration view using the “Integrations” icon on the left navigation menu. Alternatively click on the link https://console.mftgateway.com/as2/integration/sftp to navigate to the SFTP Integration view.

Once you navigate to the SFTP Integration view, if you haven’t already done the SFTP setup, a form will be available.

sftp-setup

MFT Gateway allows SFTP access via key-based authentication. You can either use an existing SSH key pair generated by yourself or let MFT Gateway generate a new key pair on behalf of you.

To integrate SFTP,

  1. provide a suitable username; [Use latin letters (a-z, A-Z), digits (0-9), hyphen (-) and underscore (_) for the SFTP username. Cannot start with a hyphen.]
  2. if you already have a key pair, select Enable with existing key pair, provide that existing public key, and click Enable SFTP button to initiate the SFTP setup.
  3. if you don’t have a key pair, select a private key type from the dropdown list which is compatible with your SFTP client(FileZilla, WinSCP, or PSFTP). Currently, there are 3 private key types available as; PKCS1, PKCS8 and PPK. If you wish to add a password for your private key, select Add password for Private Key and provide a password. Then click the Enable SFTP button and the private key will be downloaded.

Please note that the password which you provided during the setup will be the passphrase for your private key and will be needed when connecting to the SFTP server. MFT Gateway does not store your credentials, and keys can not be recovered if you lose them. However, in case you misplace/forget your credentials, you can disable the existing SFTP account and create a new SFTP account at any time.

Once the SFTP setup is complete, you should be able to use any of the SFTP clients and connect to the SFTP server. After the setup, the SFTP view will display instructions on connecting to the SFTP server and listing/downloading attachments of the sent/received messages via the command line for Linux and MacOS users.

Login to SFTP server

Before using the login command, make sure that you set correct permissions to the private key file. In order to set the correct permissions, navigate to the directory where the downloaded private key file is stored and run the below command. Remember to replace <private_key_file> with the actual private key file name.

sudo chmod 400 <private_key_file>

Note that if you do not set correct permissions to the private key file, you’ll get an error message similar to the following when you try to run the SFTP login command.

key-permissions

Now you can run the SFTP login command as follows replacing <private_key_file> with your private key file name with path and <user_name> with SFTP username (the username which was used in the form when setting up SFTP):

sftp -i <private-key-path> <user_name>@sftp.mftgateway.com

When you run the command, you will be prompted for the private key passphrase if you have provided a password when setting up SFTP. Please provide the same password as the passphrase.

SFTP Folder Structure

Once logged in, you will be inside your own SFTP space. Your current directory will be as follows;

Eg:/mftg-<your-mftgateway-account-id>/

There you can find a folder named AS2 including subfolders files, headers, raw-mdn, raw-message and keystore which correspond to different aspects of your AS2 message flow such as attachments, MDNs, and HTTP header traces. Some of these are internally used by MFT Gateway; do not attempt to modify their content. (In most cases, you will not have access to them at all.)

For more details and examples, refer to the SFTP folder structure reference.

Note: all the commands listed in the document from now on assumes the current working (base) directory as mftg-<your-mftgateway-account-id>

Sending files (messages) via SFTP

To send a file as an AS2 message, simply upload the file to the send folder(AS2/send/<station-AS2-id>/<partner-AS2-id>/).

put <local-file> AS2/send/<station-AS2-id>/<partner-AS2-id>/<attachment-name>

In above command;

  • <local-file> = The relative/absolute path of the local file to be uploaded
  • <station-AS2-id> = Message sender(station) AS2 Identifier
  • <partner-AS2-id> = Message recipient(partner) AS2 Identifier
  • <attachment-name> = Filename with extension

Note: uploading multiple files via SFTP is not currently available. For now, we advise you to compress all the attachments to a zip file and upload.

Once the message is successfully sent, MFT Gateway will persist its attachment into SFTP, under mftg-<your-mftgateway-account-id>/AS2/files/<station-AS2-id>/<partner-AS2-id>/outbox/<timestamp-random-number>/ folder

As you can see, files for each sent message will be saved into its own timestamp-prefixed subfolder.

You can download the sent file using the below SFTP get command replacing necessary components.

get AS2/files/<station-AS2-id>/<partner-AS2-id>/outbox/<timestamp-random-number>/<attachment-name> <local-path>

In above command;

  • <station-AS2-id> = Message sender(station) AS2 Identifier
  • <partner-AS2-id> = Message recipient(partner) AS2 Identifier
  • <timestamp-random-number> = Automatically created timestamp-prefixed subfolder for the AS2 message
  • <attachment-name> = Filename with extension
  • <local-path> = Local destination where you would like to save the file

To list all the attachments in the outbox, run below command, replacing necessary components with correct values.

ls AS2/files/<station-AS2-id>/<partner-AS2-id>/outbox/

In above command;

  • <station-AS2-id> = Message sender(station) AS2 Identifier
  • <partner-AS2-id> = Message recipient(partner) AS2 Identifier

Receiving files (messages) via SFTP

When a new AS2 message is received, MFT Gateway will persist its attachments into SFTP, under mftg-<your-mftgateway-account-id>/AS2/files/<station-AS2-id>/<partner-AS2-id>/inbox/<timestamp-random-number>/ folder.

As you can see, files for each incoming message will be saved into its own timestamp-prefixed subfolder.

To list all the attachments in the inbox, run below command, replacing necessary components with correct values.

ls AS2/files/<station-AS2-id>/<partner-AS2-id>/inbox/

In above command;

  • <station-AS2-id> = Message recipient(station) AS2 Identifier
  • <partner-AS2-id> = Message sender(partner) AS2 Identifier

You can download the file using the below SFTP get command replacing necessary components.

get AS2/files/<station-AS2-id>/<partner-AS2-id>/inbox/<timestamp-random-number>/<attachment-name> <local-path>

In above command;

  • <station-AS2-id> = Message recipient(station) AS2 Identifier
  • <partner-AS2-id> = Message sender(partner) AS2 Identifier
  • <timestamp-random-number> = Automatically created timestamp-prefixed subfolder for the AS2 message
  • <attachment-name> = Filename with extension
  • <local-path> = Local destination where you would like to save the file

Disabling SFTP

If you wish to stop using SFTP, or completely reset the SFTP space with a new keypair,

navigate to the SFTP integration page, and click Disable SFTP.

sftp-disable

After disable, any previously downloaded SFTP access keys would no longer work.