Phidiax Tech Blog

Adventures in custom software and technology implementation.

Microsoft BizTalk Server 2013 R2 SFTP Adapter Tricks and Pitfalls - The Messaging Engine failed while notifying an adapter of its configuration

Recently, I was tasked with a BizTalk application and infrastructure migration from a legacy version to BizTalk Server 2013 R2. This included working to migrate legacy BizTalk code and third-party SFTP Adapter functionality. One of the main perceived value adds of migration to the latest versions of BizTalk, is to delete third-party SFTP adapter components and utilize the newly built-in BizTalk SFTP adapter. 

...Sounds like a great idea...then you realize there are more hurdles and pitfalls than expected. Some are deal-breakers! The native BizTalk SFTP adapter has limited features, hard requirements, and extremely limited cryptic exception management. It seems that for everything that may go wrong with the BizTalk SFTP adapter, we receive the following:

The receive location with URL is shutting down. Details:"The Messaging Engine failed while notifying an adapter of its configuration. ".

This post lists tricks, pitfalls, lessons learned, and discoveries, in hopes to ease your burden of BizTalk SFTP implementation. 

  • What are the target SFTP Folder Security Settings required by the BizTalk SFTP adapter?
  • How to authenticate with the target SFTP site using Certificate Authentication.
  • What are the requirements for the target SFTP Folder Variable Setting?
  • Miscellaneous findings.

SFTP Folder Security Settings

The BizTalk SFTP Adapter has target folder security requirements that may inhibit usage of the adapter. BizTalk requires Read/Write access for the target SFTP folder. 

The image to the LEFT will fail. The image to the RIGHT is acceptable.

If this is misconfigured, you will receive the following:

The receive location with URL is shutting down. Details:"The Messaging Engine failed while notifying an adapter of its configuration. ".

This could be a deal-breaker for implementations where you do not have control over security settings of the target SFTP folder. Perhaps the target SFTP folder is set to Read access due to policy settings. If so, the BizTalk SFTP adapter will simply fail to start, with minimal cryptic notification. Nevertheless, there are other third-party BizTalk SFTP adapters with robust feature sets which may overcome the native BizTalk SFTP limitations,  

Certificate Authentication

Certificate authentication is a scheme that may be preferred. This enables a client to log into the target SFTP server with User Name, Certificate, and URL. There must of had been some prior key exchange where we are in possession of the .PPK file. This is very important, the Microsoft SFTP documentation currently says .PKF file, which is WRONG. You must use a .PPK file.

Assuming you have a proper Private Key .PPK file, you have the associated User Name, and the target SFTP url Server Address, you will have to determine two other required settings.

  • Accept Any SSH Server Host Key: The Default and most common is True, which means the server will supply a public Host Fingerprint to manage communication. Else, False, assumes that a specified Fingerprint will be used, which you would then need to populate in the SSH Server Host Key Finger Print variable setting.
  • Client Authentication Mode: Password is for User and Pass combination and is not Certificate Authentication. PublicKeyAuthentication is what we are looking for in this sample. MultiFactorAuthentication is for Cert plus User / Pass combination.

SFTP Folder Variable Setting

I have noticed, in some cases the Folder Path must set to "/" in the case that we are working with the Root node of the target SFTP Server folder structure.

Miscellaneous Findings

  1. It is frustrating that there is not a setting to choose if a file should be deleted after read. This could be a deal-breaker depending upon business requirements.

In general, it is useful to conduct cost analysis of removing third-party adapters to utilize what is delivered native within the BizTalk Adapter framework. However, we are cautious to utilize the BizTalk SFTP adapter due to lack of a rich feature-set found in third party adapters, and lacking exception notification details. The cost savings starts to diminish if business requirements are impacted due to the BizTalk adapter shortcomings, or if excessive debug cycles ensue due to lacking exception notification detail. Extensive testing must be performed before committing to migration of SFTP functionality to the native BizTalk Server SFTP adapter.

As we stumble across more details, we will be sure to post them. 

Comments (10) -

  • Ritu Raj

    3/11/2016 11:49:25 AM | Reply

    Very nice findings and options. It was exactly because of these and many other feature set loss that we planned to stick with third party adapter during our migration to BizTalk 2013R2.
    BizTalk SFTP adapter does not support SSO Affiliates in the configuration.
    BizTalk SFTP doesnot have setting for temp file name while writing

    There are few more critical misses in the adapter. May be we need to wait for a major release for the adapter

    • Jason Sauers

      3/12/2016 9:29:24 PM | Reply

      Thanks for the comment. Voicing your findings is critical to the next versions of enhancements. Please keep them coming.

      What third party adapter did you decide to stick with?

  • Deepa Kamalanathan

    9/18/2016 9:24:28 PM | Reply

    I tried to configure SFTP in BizTalk 2013 R2. Followed the steps but I am getting below error,

    "Authentication Error. Ensure that the specified private key filename and Private key Password are correct."
    Do I need to configure the password also?


    • Jason Sauers

      10/18/2016 11:14:11 AM | Reply

      It seems that you have MultiFactor set, which utilized PublicKey and Password. If you just want to authenticate utilizing PrivateKey, be sure your ClientAuthenticationMode setting is set to PublicKeyAuthentication. Make sure your PrivateKey setting is set to your .ppk file. PPK is the file type that the adapter uses. Finally, be sure the UserName setting is set to the proper value.

      Assuming all this is accurate, you should be fine.

      You may want to create a test SFTP server on your Windows Box for sanity test. I did notice that some servers from other vendors did not authenticate as expected.

      SFTP was also upgraded in BizTalk 2016 which should overcome some of these shortcomings.

      Please post back any findings!

  • Wills

    4/3/2017 6:27:57 AM | Reply

    Hi ,
    I am using native BizTalk SFTP adapter in Biztalk 2013 R2. I am facing a strange problem  my receive location is picking up all the files less then 800 KB but all the files above 1MB are not picked up, neither reported any error.

    • Ritu raj

      4/3/2017 8:26:57 AM | Reply

      Check if the file size limit on adapter is not there ..

      • Wills

        4/3/2017 9:03:40 PM | Reply

        Rita Raj,

        I am not sure if we have such configuration at the adapter level. FYI I am able to place file upto 5MB on sftp location using sftp send port, the problem I am facing is at the receiving end

    • Jason Sauers

      4/3/2017 8:48:35 AM | Reply

      Hello Wills

      I believe this is a Server problem not applying a Write Lock to the file as the file is being written from some source to the destination on the SFTP Server. You may need to work with the SFTP Server to block reads until the file is fully written. You can work with a temporary file location, and a temporary file name until the write is complete.

      Let us know how it goes, and good luck.


  • Wills

    4/3/2017 8:59:40 PM | Reply

    Thanks Jason,

    I will check the SFTP server thing you responded. I am curious to know if anyhow we can track the logs or monitor the adapter.


Privacy Policy  |  Contact  |  Careers

2009-2017 Phidiax, LLC - All Rights Reserved