Edit

Share via

SFTP Adapter

  • Article

BizTalk Server includes an SFTP adapter to send and receive messages from a secure FTP server using the SSH file transfer protocol. This topic includes the steps to configure an SFTP receive location, and configure an SFTP send port to receive and send messages from a secure FTP server. It also includes common questions and answers.

Prerequisites

Starting with BizTalk Server 2016, the SFTP adapter uses WinSCP to connect to SFTP, and therefore supports a larger range of SFTP servers. Download WinSCP on the BizTalk Server runtime. Be sure to check the supported WinSCP versions for each BizTalk Server verison:

  • BizTalk Server 2020 with CU1 or CU2 - WinSCP version 5.17.6
  • BizTalk Server 2020 - WinSCP version 5.15.4
  • BizTalk Server 2016 With CU9 - WinSCP version 5.19.2
  • BizTalk Server 2016 With CU7 - WinSCP version 5.15.9
  • BizTalk Server 2016 - WinSCP version 5.7.7

or in Hardware and Software Requirements

BizTalk Server 2013 and BizTalk Server 2013 R2 use older ssh library instead of WinSCP with limited server compatibility.

Configure the receive location

Note

Before creating the receive location, you must have already added a one-way receive port. See Create a Receive Port for the specific steps.

  1. In the BizTalk Server Administration console, expand BizTalk Server, expand BizTalk Group, expand Applications, and then expand the application under you want to create a receive location.

  2. In the left pane, click the Receive Ports node and in the right pane, right-click the receive port with which you want to associate the new receive location, and then click Properties.

  3. In the left pane of the Receive Port Properties dialog box, select Receive Locations, and in the right pane click New to create a new receive location.

  4. In the Receive Location Properties dialog box, in the Transport section, select SFTP from the Type drop-down list, and then click Configure to configure the transport properties for the receive location.

  5. In the SFTP Transport Properties, do the following:

    Others

    Use this To do this
    Connection Limit Specify the maximum number of concurrent connections that can be opened to the server.

    This setting is per server and per receive location. Consider the following scenarios:

    - There are two receive locations that have the same configuration property values, including the ConnectionLimit property set to the same value. For example, the property is set to 6. In this situation, there is one connection pool (with 6 available connections) that is used by both receive locations.

    - There are two receive locations configured with same configuration values, and have the ConnectionLimit property set to different values. For example, ReceiveLocation1 property is set to 6 and ReceiveLocation2 property is set to 5. In this situation, each receive location has its own connection pool with its own available connections. ReceiveLocation1 connection pool has 6 available connections. ReceiveLocation2 connection pool has 5 available connections.
    Log Available starting with BizTalk Server 2016.

    Enter the full path to create a client-side log file. Use this log file to troubleshoot any errors.
    Maximum Connection Reuse Time In Seconds Available starting with BizTalk Server 2016 CU 7.

    The maximum connection reuse time allows connections to be gracefully closed and removed from the pool after a connection has been in use for a specific amount of time. A value is 0 or less indicates that this behaviour is disabled.

    Polling

    Use this To do this
    Enable Timestamp Comparison Available starting with BizTalk Server 2016 cumulative update 6.

    If Retain After Download is set to True, this property determines whether a change in file timestamp will trigger a re-download of the file.

    Default value: False
    Polling Interval Specify the intervals at which the adapter polls the server. To poll continuously, set this value to zero.

    Default value: 5
    Redownload Interval Available starting with BizTalk Server 2016 cumulative update 6.

    Specifies interval after which the file will be downloaded again. Applicable if Retain After Download is True and Enable Timestamp Comparison is set to False. If set to -1, the file will not be downloaded again.

    Default value: 0

    -1 indicates that the adapter will not download files again.

    0 indicates that the adapter will download the file in each polling cycle.
    Retain After Download Available starting with BizTalk Server 2016 cumulative update 6.

    Specifies whether the adapter will retain a file from the SFTP server after downloading it.

    Default value: False
    Unit Specifies the unit in which the polling interval is specified, for example, Seconds, Minutes, Hours, or Days.

    Default value: Seconds

    Proxy (Available starting with BizTalk Server 2013 R2)

    Use this To do this
    Address Specifies either the DNS name or the IP address of the proxy server.
    Password Specifies the password for the proxy server.
    Port Specifies the port for the proxy server.
    Type Specifies the protocol used by the proxy server.
    UserName Specifies the username for the proxy server.

    Security

    Use this To do this
    Accept Any SSH Server Host Key When True, the receive location accepts any SSH public host key from the server. When False, the receive location uses the fingerprint of the server for authentication. You enter the fingerprint in the SSHServerHostKeyFingerPrint property.

    Default value: False
    Client Authentication Mode Select the authentication method that the receive location uses for authenticating the client to the SSH Server. If set to Password, you must enter the value in the Password property. If set to PublicKeyAuthentication, you must enter the private key of the user in the PrivateKey property. If set to MultiFactorAuthentication you must enter Username with its Password and PrivateKey. Additionally, if the private key is protected by a password, enter the password as well for the PrivateKeyPassword property.

    Default value: Password
    Encryption Cipher Available starting with BizTalk Server 2013 R2.

    Enter the kind of encryption cipher.

    BizTalk Server 2013 R2 options: Auto, AES, and TripleDES

    BizTalk Server 2016 options: Auto, AES, Arcfour, Blowfish, TripleDES, and DES
    Key Exchange Algorithm Selection Policy Available starting with BizTalk Server 2016 cumulative update 6.

    Specify comma-separated list of KEX preference order. Token WARN is used to delimit substandard KEXes. Anything after WARN will not be used by BizTalk SFTP adapter. Example: ecdh,dh-gex-sha1,dh-group14-sha1,rsa,WARN,dh-group1-sha1. Visit WinSCP website for latest information.
    Password Specify the SFTP user password if you set the ClientAuthenticationMode to Password.
    Private Key Specify the private key for the SFTP user if you set the ClientAuthenticationMode to PublicKeyAuthentication.

    Note: The private key file must be the specified .ppk file.
    Private Key Password Specify a private key password, if required for the key specified in the PrivateKey property.
    SSH Server Host Key FingerPrint Specifies the fingerprint of the public host key for the SSH server.
    SSO Affiliate Available starting with BizTalk Server 2020.

    Specify the Enterprise Single Sign-On affiliate application.
    User Name Specifies a username to log on to the SFTP server.

    SSH Server

    Use this To do this
    File Mask Specifies the file mask to use when retrieving files from a secure FTP server. To improve performance, be more specific to avoid attempting to download other protected files.
    Folder Path Specifies the folder path on the secure FTP server from where the receive location can retrieve files. To improve performance, avoid using folders with lots of files which you don't receive.
    Port Specifies the port address for the secure FTP server on which the file transfer takes place.
    Server Address Specifies the server name or IP address of the secure FTP server.

  6. Click OK.

  7. Enter the appropriate values in the Receive Location Properties dialog box to complete the configuration of the receive location and click OK to save settings. For information about the Receive Locations Properties dialog box, see Create a Receive Location.

Configure the send port

  1. In the BizTalk Server Administration console, create a new send port or double-click an existing send port to modify it. For more information, see Create a Send Port. Configure all of the send port options and specify SFTP for the Type option in the Transport section of the General tab.

  2. On the General tab, in the Transport section, click the Configure button.

  3. In the SFTP Transport Properties, enter the following:

    Others

    Use this To do this
    Connection Limit Specify the maximum number of concurrent connections that can be opened to the server.
    Log Available starting with BizTalk Server 2016.

    Enter the full path to create a client-side log file. Use this log file to troubleshoot any errors.
    Maximum Connection Reuse Time In Seconds Available starting with BizTalk Server 2016 CU 7.

    The maximum connection reuse time allows connections to be gracefully closed and removed from the pool after a connection has been in use for a specific amount of time. A value is 0 or less indicates that this behaviour is disabled.
    Temporary Folder Available starting with BizTalk Server 2013 R2.

    A temporary folder on the SFTP server to upload large files to, before they can be atomically moved to the required location on the same server.

    Proxy (available starting with BizTalk Server 2013 R2)

    Use this To do this
    Address Specifies either the DNS name or the IP address of the proxy server.
    Password Specifies the password for the proxy server.
    Port Specifies the port for the proxy server.
    Type Specifies the protocol used by the proxy server.
    User Name Specifies the username for the proxy server.

    Security

    Use this To do this
    Access Any SSH Server Host Key When True, the send port accepts any SSH public host key from the server. When False, the port matches the host key with the key specified in the SSHServerHostKey property.

    Default value: False
    Client Authentication Mode Specifies the authentication method that the send port uses for authenticating the client to the SSH Server. If set to Password, you must enter the value in the Password property. If set to PublicKeyAuthentication, you must enter the private key of the user in the PrivateKey property. If set to MultiFactorAuthentication you must provide Username with its Password and PrivateKey. Additionally, if the private key is protected by a password, enter the password as well for the PrivateKeyPassword property.

    Default value: Password
    Encryption Cipher Available starting with BizTalk Server 2013 R2.

    Enter the kind of encryption cipher.

    BizTalk Server 2013 R2 options: Auto, AES, and TripleDES

    BizTalk Server 2016 options: Auto, AES, Arcfour, Blowfish, TripleDES, and DES
    Key Exchange Algorithm Selection Policy Available starting with BizTalk Server 2016 cumulative update 6.

    Specify comma-separated list of KEX preference order. Token WARN is used to delimit substandard KEXes. Example: ecdh,dh-gex-sha1,dh-group14-sha1,rsa,WARN,dh-group1-sha1. Visit WinSCP website for latest information.
    Password Specify the SFTP user password if you set the ClientAuthenticationMode to Password.
    Private Key Specify the private key for the SFTP user if you set the ClientAuthenticationMode to PublicKeyAuthentication.
    Private Key Password Specify a private key password, if required for the key specified in the PrivateKey property.
    SSH Server Host Key Finger Print Specifies the fingerprint of the server used by the adapter to authenticate the server if the AccessAnySSHServerHostKey property is set to False. If the fingerprints do not match, the connection fails.
    SSO Affiliate Available starting with BizTalk Server 2020.

    Specify the Enterprise Single Sign-On affiliate application.
    User name Specifies a username for the secure FTP server.

    SSH Server

    Use this To do this
    Append If Exists If the file being transferred to the secure FTP server already exists at the destination, this property specifies whether the data from the file being transferred should be appended to the existing file. If set to True, the data is appended. If set to False, the file at the destination server is overwritten.

    Default value: False
    Folder Path Specifies the folder path on the secure FTP server where the file is copied.
    Port Specifies the port address for the secure FTP server on which the file transfer takes place.
    Server Address Specifies the server name or IP address of the secure FTP server.
    Target File Name Specifies the name with which the file is transferred to the secure FTP server. You can also use macros for the target file name.

  4. Click OK and OK again to save settings.

Use a newer WinSCP version

To use a newer version of WinSCP with BizTalk Server, add an assembly redirection so BizTalk knows which assembly to load. The redirection is configured in the BizTalk Server configuration files: BTSNTSVC.exe.config (32-bit host instances) and BTSNTSVC64.exe.config (64-bit host instances).

The following includes sample configuration syntax. Be sure to replace %NEWVERSION% with your version:

<configuration>
 <runtime>
  <assemblyBinding>
   <dependentAssembly>
    <assemblyIdentity name="WinSCPnet" publicKeyToken="2271ec4a3c56d0bf" culture="neutral" />
    <bindingRedirect oldVersion="1.0.0.0-1.65535.65535.65535" newVersion="%NEWVERSION%"/>
   </dependentAssembly>
  </assemblyBinding>
 </runtime>
</configuration>

When finished, your configuration looks similar to the following:

Assembly redirect in the configuration file.

Frequently asked questions

Question Answer
What SFTP servers are supported? See Supported SFTP Servers. Starting with BizTalk Server 2016, the SFTP adapter uses WinSCP to connect to SFTP. As a result, SFTP servers that support WinSCP should work.
Can the SFTP Adapter be used with the mutual authentication method (public key and password)? - Starting with BizTalk Server 2013 R2, yes. If set to MultiFactorAuthentication you must provide Username with its Password and PrivateKey. Additionally, if the private key is protected by a password, specify the password as well for the PrivateKeyPassword property.

- For BizTalk Server 2013, either Password or PublicKeyAuthentication can be used. MultiFactorAuthentication is not supported in the SFTP adapter shipped with BizTalk Server 2013.
What private key formats are supported? Can the OpenSSH private key format be used? The SFTP adapter supports only the PuTTY private key file format. PuTTYgen can be used to convert from OpenSSH to the .ppk format.
For SSHServerHostKeyFingerPrint, which fingerprint algorithm and format should be used? You should use the MD5 fingerprint of the server’s key in the format: ssh-rsa 2048 90:e4:9b:67:d9:22:a7:5f:6f:33:db:6a:b1:23:96:12.
Does the SFTP adapter support 256-bit encryption? Yes - The SFTP adapter supports 256-bit encryption. The supported encryption algorithms include:

- AES encryption: 256-bit, 192-bit, or 128-bit SDCTR or CBC

- 3DES (Triple-DES) encryption: 168-bit SDCTR or CBC
What SSH versions does the adapter support? Only SSH2. Connection cannot be established with SFTP servers having SSH1 version.
Is file mask case sensitive? No. *.txt and *.TXT works alike. Please install the latest cumulative update for BizTalk Server 2013. BizTalk Server 2013 RTM release had case-sensitive file masks.
Exporting bindings give a blank password field. When trying to create a receive location by importing these bindings what all changes are to be made? Edit the binding file by editing the password field. Also, in <Password vt="1">MySecretPassword</Password>, vt=”1” indicates a null value. Change that to vt=”8”, which indicates a string. For example:

<Password vt="8">MySecretPassword</Password>

For more details, see https://msdn.microsoft.com/library/system.runtime.interopservices.varenum(v=vs.100).aspx
How do I specify the file paths? Normally, paths are specified in the format /folder/pathname. However, different servers require different formats, with or without leading or trailing slashes. So, you can also try the following:

- /folder/pathname

- /folder/pathname/

- folder/pathname

- folder/pathname/