SFTP Adapter for Microsoft BizTalk

Requirements: /n software Adapters for Microsoft BizTalk

Introduction

The /n software Adapters for Microsoft BizTalk include fully-managed .NET Adapters that seamlessly integrate with the BizTalk Messaging Pipeline. The /n software Adapters extend the features of BizTalk with advanced Internet communications and secure messaging capabilities.

There are many different BizTalk adapters currently supported: AS2 Adapters for EDI communications, FTPS, FTP, SFTP, SSH, Email adapters, etc. These adapters have completed the official adapter certification program (administered by Unisys) established by Microsoft for BizTalk server, which tests for scalability and interoperability with Microsoft BizTalk Server.

This guide will focus specifically on the SFTP adapter, which is used to communicate with SFTP servers. SFTP (which should not be confused with FTP or FTPS) is the SSH File Transfer Protocol. If you're interested in using SFTP communication in your BizTalk solution, you're in the right place. Before you continue reading, I recommend that you go ahead and download the product and follow along with me through the tutorial.

Contents

1. Adapter Installation
2. Adapter Properties - Send Port
3. Usage - Send Port
4. Adapter Properties - Receive Port
5. Usage - Receive Port

Adapter Installation

Before installing you should stop the BizTalk host instance and close the BizTalk Administration Console. After you run the setup application, all of the necessary files will be installed on your system. The adapters will automatically be added to the BizTalk Administration Console, so we can begin using them in send ports and receive locations. If you open the BizTalk Administration Console and create a new receive location or send port, you'll see that the /n software SFTP adapter is now available as a transport type.

Adapter Properties - Send Port

One common situation in which the SFTP adapter might be used is one where files dropped in a local folder need to be sent to a remote server. In this situation, a receive location of transport type FILE would be configured in BizTalk to monitor a folder, and you would configure a Send port that will send files picked up in this folder to a remote SFTP server.

After you add a new Send Port and set the transport type to "nsoftware.SFTP 2024" (also don't forget to set the Filters to associate this send port with the file pickup receive location), Clicking on the Configure button will bring up a new window called "nsoftware.SFTP 2024 Transport Properties" where you will specify the details of how and where the SFTP adapter should connect. There are four groups of properties:

Logging

The Transport Log property is the only property here. If you click the + symbol next to the property this will expand the property and expose it's fields. You will see Location, Log Mode, and Log Type. By default the adapter will log only errors to the application event log. You can change the Log Mode to a mode with greater detail so that information event log entries are written to the event log during the course of execution. You may also change the Log Type so that events will be written to file instead of the event log. In that case you'll need to specify the full path to a file in the Location field.

SFTP

The next group of properties are SFTP properties. This is where you will tell the adapter where on the SFTP server to write the files. All of these properties are fairly self explanatory:

SSH

The SSH properties specify where and how to connect for the SFTP connection.

It is very important to understand these SSH properties, since a complete understanding will help ensure the security of your transactions. To that end, I will go into a more complete discussion of each of these properties.

The "SSH Cert" property will allow you to specify a certificate in a variety of forms as mentioned above. The design of the certificate selector dialog is intended to allow you to easily select a certificate for public key authentication. If you are specifying a PEM File, please note that you must specify an SSH2 RSA or SSH2 DSA private key.

The "SSH Accept Server Host Key" setting tells the adapter what host key to accept during the security handshaking procedure of the connection to the remote server. If the value specified here does not match the key that the server presents, the connection will be terminated with an error. This property acts like the SSH Cert property in that clicking the ellipses will open the certificate selector dialog where you may select a certificate.

As mentioned above you may also click the + symbol and set the Accept Any field to "Yes" to always accept the server's host key.

If you want to use the hex encoded 16-byte MD5 fingerprint, this can be done through the use of the Other property in the Tuning section. You would give the Other property a value like so: SSHAcceptServerHostKeyFingerprint=0a:1b:2c:3d

The "SSH Auth Mode" specifies which form of authentication you would like to perform when connecting to the SSH server. The adapter supports regular "User/Password", public key, or keyboard interactive authentication. Multi-Factor authentication may be selected to use a combination of these three authentication mechanisms. If you choose to use public key authentication, you'll also need to set the "SSH Cert" property to point the adapter to the key pair it should use. This article is not meant to explain how public key authentication works, however if you would like to use this form of authentication you should generate a key pair on your own computer, and copy the public key to the SSH server. Then when you connect to the server, you can point the adapter to your private key to authenticate. The "SSH Cert" property is only used if you choose to use public key authentication.

The "SSH Compression Algorithm" property should be set to "ZLIB" if you'd like to implement ZLIB compression in your SSH communications. Use of compression will likely depend on your trading partner's requirements, but it's entirely optional. Generally, it's a good idea to compress large documents but inefficient to use it for small documents.

The "SSH Host", "SSH Port", "SSH User" and "SSH Password" settings are all self explanatory - just specify the server you'd like to connect to, on what port (the default is port 22), and the user and password to use to connect with. Note that if you use public key authentication, you will still need to specify an "SSH User", but the "SSH Password" will be ignored.

Tuning Properties

Usage - Send Port

In order to configure a send port to upload files from the pick-up folder to my remote SFTP server, I only need to set a few of these properties:

• For the SFTP properties, I'll set the "Remote File" to %SourceFileName%, and the "Remote Path" to the name of the specific folder location on the remote server where I want to store the files (in my case "myTests").
• For the SSH properties, I'll start by setting the Accept Any field of SSH Accept Server Host Key to "Yes" for testing. I'll use public key authentication since it is generally considered to be more secure, so I'll set the "SSH Auth Mode" to "Public Key". I'll get my certificate from a PEM file, so I'll use the certificate selector dialog from the "SSH Cert" to specify the PEM File. Then all that's left is to set the "SSH Host" and "SSH User" and I'm ready to go.

To test, I'll set the Filter of the send port to BTS.InboundTransportLocation == "C:\test\in\*.*", the location of my File adapter receive location. Then I'll enable the ports, start BizTalk Server and drop some test files. The adapter will transfer the picked up files to my remote SFTP server.

Adapter Properties - Receive Port

Another common situation in which the SFTP adapter might be used is one where files dropped in a folder on a remote SFTP server need to be retrieved in a BizTalk orchestration or passthrough configuration so that these remote files can be used locally or automatically transferred elsewhere. In this situation, a receive location of transport type SFTP would be configured in BizTalk to monitor a remote folder. You could configure a Send port that will send files picked up in this folder to a local folder using the FILE adapter.

After you add a new Receive Location and set the transport type to "nsoftware.SFTP 2024" (also don't forget to set the Filters to associate this receive location with the file send port), Clicking on the Configure button will bring up a new window called "nsoftware.SFTP 2024 Transport Properties" where you will specify the details of how and where the SFTP adapter should connect. Many of these properties are the same as those documented above in the Send Port section. Here I will only document the properties specific to using the adapter in a receive location, since many of the properties have the same meaning as in the above description of the SFTP adapter in a send port.

SFTP

This is where you will tell the adapter where on the SFTP server to retrieve the files. Again, these properties are fairly self explanatory:

SSH Properties

The adapter has the same SSH properties in a receive location as in a send port.

Tuning Properties

Usage - Receive Port

In order to configure a receive port to download files from the remote SFTP server, again I only need to set a few of these properties:

• As for the SFTP properties, I'll set the "Delete Mode" to "Never" (because I don't want to delete the remote files after I pick them up, and "File Mask" to . (because I want to get all the files).
• For the SSH properties, I'll use the same settings as in the above send port example since I am connecting to the same server.

To test, I will create a send port of transport type FILE with a filter pointing to this new SFTP receive location. Then I will enable the ports, start BizTalk Server and drop some files in the remote SFTP server folder. The files will be picked up by the adapter during the next poll, downloaded, and passed to the BizTalk Message Box for consumption by the FILE send port!

Conclusions

This article demonstrates the ease of use of the SFTP adapter in particular, but /n software provides a full set of adapters for connecting to various types of internet servers. The adapter properties are kept to a minimum for simplicity, but we make an effort to provide those properties that are necessary for effective control over configurations.