SCP 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 SCP adapter, which adds SSH-secured file transfer capabilities to your BizTalk Server. If you're interested in using SCP 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 SCP adapter is now available as a transport type.

Adapter Properties - Send Port

One common situation in which the SCP 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 SCP-enabled SSH server.

After you add a new Send Port and set the transport type to "nsoftware.SCP 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.SCP 2024 Transport Properties" where you will specify the details of how and where the SCP 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.

• SCP

  The next group of properties are SCP properties. This is where you will tell the adapter where on the SCP-enabled SSH server to write the files.  Both of these properties are fairly self explanatory:

  Remote File	The name of the destination file on the remote SCP-enabled SSH server.
  Remote Path	The path on the remote SCP-enabled SSH server to which the Remote File should be uploaded.

• SSH

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

  SSH Accept Server Host Key	Instructs the adapter to accept the server host key that matches the supplied key. Clicking the ellipses will open the certificate selector dialog to load the public key. If you click the + symbol this will expand the property and reveal the associated fields. The "Accept Any" field may be set to Yes to instruct the adapter to accept any host key presented by the server.
  SSH Auth Mode	The type of authentication used by the adapter (public key, password, keyboard interactive, and multi-factor authentication are all supported).
  SSH Cert	This property shows the subject of the certificate that is currently specified for public key authentication. Clicking the ellipses of this property will open the certificate selector dialog where you will be able to easily load your certificate. With the certificate selector dialog you can load certificates from the User and Machine stores, as well as from PFX or PEM files.
  SSH Compression Algorithm	Can be either "none" (default) or "Zlib".
  SSH Host	The internet address of the SSH host.
  SSH Password	The password to use when connecting to the SSH host.
  SSH Port	The port on the SSH host on which to connect.
  SSH User	The user id to use when connecting to the SSH host.

  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

  Firewall	This may be expanded to configure the firewall type, host, port, user, and password if needed.
  Other	This allows you to specify additional configuration settings in the format configname1=value1. See the Configuration section of the documentation for a list of supported settings.

 

Usage - Send Port

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

• For the SCP 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 SCP-enabled SSH server.

Adapter Properties - Receive Port

Another common situation in which the SCP adapter might be used is one where files dropped in a folder on a remote folder on an SCP-enabled SSH 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 SCP 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.SCP 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.SCP 2024 Transport Properties" where you will specify the details of how and where the SCP 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 SCP adapter in a send port.

• SCP

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

  File Mask	Indicates the type of files to download from the SCP-enabled SSH server (for example, "*.txt").
  Temp Path	This property indicates a temporary directory where the adapter can store any data before the adapter processes it.

• SSH Properties

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

• Tuning Properties

  Error Threshold	This property limits the number of errors that the adapter can incur before it shuts down and stops processing messages.
  Max Batch Size	This property limits the maximum amount of data the adapter can store before finalizing and processing the current batch to the number of bytes indicated. The default value of 0 indicates no limit.
  Max File Count	This property places a limit on the number of files that can be transmitted in a single batch.
  Max File Size	This property limits the maximum size of any file in the current transmission batch to the number of bytes indicated. The default value of 0 indicates no limit.
  Polling Interval	The number of seconds to wait between download attempts (default is 60 seconds, so for example every 60 seconds the adapter would check the server for new files).

 

Usage - Receive Port

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

• As for the SCP properties, I'll set the "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 SCP receive location.  Then I will enable the ports, start BizTalk Server and drop some files in the remote SCP-enabled SSH 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 SCP 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.