BizTalk Server 2013 R2: SFTP Adapter Tricks and Pitfalls

Article
1/17/2024

Introduction

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

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.
Does not support configuration with SSO Affiliate Administration.
Does not support temp file name while writing.

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.

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

Share via