Share via

Using FTPS adapter in BizTalk (FTP + SSL)

  • Article

I recently came across a customer who owned a FTP site wanting to implement a trading solution to deal with his partners. The solution was evidently easy; Use BizTalk and leverage on the new FTP adapter capabilities. It didn’t take long to set up a demo and he was more than impressed. This article explains the steps to launch a FTP site, create certificate for SSL, configure the BizTalk solution and the list of plausible errors you might encounter.

So what’s FTPS or FTP + SSL

FTPS (also known as FTP-ES, FTP-SSL and FTP-Secure) is merely an extension to the commonly used File Transfer Protocol with added support for Transport Layer Security (TLS) and the Secure Sockets Layer (SSL) protocols. It is not to be confused with SSH File Transfer Protocol
(SFTP), which is an incompatible secure file transfer subsystem for the Secure Shell protocol. As you may know, in BizTalk we have a different adapter altogether that is designed to deal with SFTP servers.

Step 1: Create a FTP site

The easiest way to create one is on IIS. If you don’t have IIS and FTP on your server machine,

  1. Open Server Manager, go to Roles and Click Add Roles.
  2. In the Add Role Wizard, select Web Server (IIS) role to install.
  3. Click next until you reach the Select Role Services Page, check the FTP Server, FTP Service and FTP Extensibility at the bottom. Follow the wizard and finish the role installation.

Now, create a FTP site and this is explained at https://www.iis.net/learn/publish/using-the-ftp-service/configure-ftp-with-iis-manager-authentication-in-iis-7#03 

Step 2: Create and configure the certificate

For this demo, I created a self-signed certificate with a private key using IIS.

 

In the next dialog, give the certificate a friendly name and click ok. Post this you should be able to see the newly created cert in the list of Server Certificates.

Now, export the certificate as a *.pfx file. Select the certificate and click Export. Provide a path and set the password. (A pfx file essentially contains the public key of the certificate.)
You will use this certificate at a later point in time.

Step 3: Configure FTP site to use SSL

Navigate to your FTP site and select the “FTP SSL settings” on the home page.

  • Allow SSL – Allows the FTP server to support both non-SSL and SSL connections with a client.
  • Require SSL – Mandates SSL encryption for all clients.

I chose Allow SSL as my customer has many trading partners with not-so-sensitive data and can live without SSL encryption.

Courtesy: https://www.iis.net/configreference/system.applicationhost/sites/sitedefaults/ftpserver/security/ssl

Step 4: Install the public key in the BizTalk machine

For the SSL channel to establish, the client machine (here, BizTalk) needs the certificate for authentication purpose. Copy the public key which you exported earlier to the BizTalk machine. Important thing to note is the certificate has to be in the personal store of the account, the BizTalk FTP host instance runs under.

Go to Run > MMC > Add / Remove Snap In > Certificates > Personal > All Tasks > Import > Select the certificate and type in the password.

 

Step 5: Configure the BizTalk FTP Receive location

https://msdn.microsoft.com/en-us/library/aa559095.aspx clearly explains how you should go about configuring a FTP receive location. The SSL tab is where it gets tricky if the transport needs to be over SSL. First, you need the thumbprint value of
the imported certificate. Open the certificate and copy the highlighted value.

 

BizTalk FTP Receive location SSL configuration as below.

 

Enable the port and place the file in your drop location in the FTP server. If not for surprises, the file should be picked up.

And below are some of the errors I encountered in the due course of setting up the FTP receive. I thought I will list them too in interest of saving your time.

1. The adapter "FTP" raised an error message. Details "Unable to connect to FTP server "<server name>" as user "<username>". Inner Exception details: "The specified client certificate hash is invalid. Provide a valid client certificate hash. ". ".
This error actually took me by surprise. The certificate thumbprint and the one in the Client Certificate Hash property of the FTP adapter looked exactly same at the first glance. Make sure the thumbprint that you copy is devoid of whitespaces.

2. The adapter "FTP" raised an error message. Details "Unable to connect to FTP server "<server name>" as user "<username>". Inner Exception details: "The server name in the server certificate does not match with the name of the physical server. Make sure you provide the right server name. ". ".

This may not be an issue with the certificate, the error says so though. You may want to check the FTP receive location on BizTalk. Ensure that you have a fully qualified server name against the “server” property. As you may imagine, the issuer name on the certificate is directly bound to the complete server name. I have seen issues with IP Addresses put in this field.

  

3. The adapter "FTP" raised an error message. Details "Unable to connect to FTP server "<server name>" as user "<user name>". Inner Exception details: "The FTP server did not accept a FTP command for an unexpected reason. “
Well, this error could be thrown in a variety of scenarios. In my case, surprisingly it was merely a wrong username – password combination that caused this. I had to look deep into the FTP logs for the error code – 503 which stands for “Bad sequence of commands / Invalid authentication”. You may need to follow a similar strategy here.

Happy BizTalking!

Written By
Rajkumar Damodaran

Reviewed By
Jainath Ramanathan

Microsoft GTSC, India

Comments

  • Anonymous
    July 05, 2015
    Nice illustrations

  • Anonymous
    May 25, 2016
    The comment has been removed