Configuring Integration Server to Connect to an SFTP Server

Overview of SFTP

The SSH File Transfer Protocol (SFTP) is a network protocol that is based on the Secure Shell protocol (SSH). SFTP facilitates secure file access, file transfer, and file management over any reliable data stream.

You can configure Integration Server to connect to an SFTP server to perform the following tasks using the SFTP protocol:

Transfer files between Integration Server and the SFTP server. You can get a file from the SFTP server and store it in the local machine or upload a file from your local machine to the SFTP server.
Access files in the SFTP server. You can view the directories and files in the SFTP server and also view their permissions and ownership information.
Manage directories or files in the SFTP server. You can create, rename, or delete files or directories in the SFTP server. You can also change the permissions or ownership of files in the SFTP server.

You can use Integration Server Administrator to define the following SFTP aliases:

SFTP server alias. The SFTP server alias contains configuration parameters that Integration Server uses to connect to an SFTP server.
SFTP user alias. The SFTP user alias contains client configuration parameters that Integration Server uses to authenticate and function as an SFTP client.

Creating an SFTP Server Alias

About this task

An SFTP server alias is a named set of parameters that Integration Server uses to connect to an SFTP server.

Important: You must create at least one SFTP server alias before creating an SFTP user alias.

To create an SFTP server alias

Procedure

Open Integration Server Administrator.
In the Navigation panel, select Settings > SFTP.
Click Create Server Alias.

Configure the following server alias settings:

Note: Version 2 SFTP Client is introduced for PIE-59929 in IS_10.5_Core_Fix5.

Parameter	Specify
SFTP Server Alias Properties
SFTP Client Version	The SFTP client to use. Note: The Version 2 client has additional configuration properties, Key Exchange Algorithms, Machine Access Code (MAC) algorithms, and ciphers that are not available in the Version 1 client.
Alias	A name for the SFTP server alias. An SFTP server alias name: Can contain only underscores (_) and periods (.) as special characters. Cannot begin with the string "http://". Can be of a maximum length of 255 characters.
Host Name or IP Address	The host name or IP address of the SFTP server.
Port Number	The port number of the SFTP server. The port number must be in the range of 0 to 65535 (inclusive).
Proxy Alias	The proxy alias through which requests should be routed. The proxy alias can be HTTP, HTTPS, or SOCKS. If a proxy alias is not specified, Integration Server makes outbound requests using each enabled proxy server alias until the request is sent successfully or all proxy servers have been tried. For more information about proxy aliases, see Creating a Proxy Server Alias.
Host Key Location	The location of the public key of the SFTP server. Integration Server validates the SFTP server using its public key. Important: The public key file must be present on the same machine on which you have installed Integration Server. If you do not have the public key of the SFTP server, click Get Host Key. Integration Server retrieves the public key for the specified host and port and saves it in a temporary folder. Integration Server then displays the temporary folder path in the Host Key Location field. The version 2 SFTP client supports OpenSSH format host keys, and the existing key may be in the unsupported SSH2 format. So, you may not be able to save the server alias successfully. In such cases, regenerate the host key in the OpenSSH format, and click Get Host Key to get the regenerated key for the server alias. Note: This change is applicable after installing IS_10.5_Core_Fix22, which upgrades maverick-client-1.7.23.jar to 1.7.34 for PIE-77771.
SFTP Server Alias Advanced Settings (Optional)
Min DH Key Size	The minimum DH key size. This parameter is not applicable to SFTP Client Version 1.
Max DH Key Size	The maximum DH key size. This parameter is not applicable to SFTP Client Version 1.
Preferred Key Exchange Algorithms	A list of key exchange algorithms that Integration Server presents to the SFTP server for key exchange. The algorithms are listed in the order of preference.
Preferred MAC Algorithms S2C	A list of Message Authentication Code (MAC) algorithms applicable to the messages sent from an SFTP server to the Integration Server. The algorithms are listed in the order of preference.
Preferred MAC Algorithms C2S	A list of Message Authentication Code (MAC) algorithms applicable to the messages sent from Integration Server to an SFTP server. The algorithms are listed in the order of preference.
Preferred Ciphers S2C	A list of preferred ciphers applicable to messages sent from an SFTP server to Integration Server .
Preferred Ciphers C2S	A list of preferred ciphers applicable to messages sent fromIntegration Server to an SFTP server .

To specify the order in which Integration Server presents the algorithms to the SFTP Server, select an algorithm, and click Up or Down.
Every SFTP server supports a pre-defined set of algorithms and ciphers. The algorithm that both Integration Server and the SFTP server support is chosen.
To exclude an algorithm from a list, select the algorithm, and click Right. The algorithm moves to the list of excluded algorithms.

For more information, see Migration of Existing Server Aliases Data from watt.ssh.jsch.* Properties.

Click Save Changes.

Note: If you see the error message: "com.maverick.ssh.SshException: Minimum DH p value not provided [2048]", set Min DH Key Size to 2048.

Note: Key Exchange Algorithms such as diffie-hellman-group-exchange-sha1 and diffie-hellman-group-exchange-sha256 consider values set for the Min DH Key Size and Max DH Key Size parameters. All other algorithms ignore these values.

Integration Server stores the SFTP server alias configuration along with the host key information in the /<IntegrationServer_directory>/instances/<instance_name>/config/sftp/sftpServerAliases.cnf file.

Editing an SFTP Server Alias

About this task

You can edit only the Host Name or IP Address, Port Number, and Host Key Location properties. You cannot leave the Host Name or IP Address and Port Number fields empty.

To edit an SFTP server alias

Procedure

Open Integration Server Administrator.
In the Navigation panel, select Settings > SFTP.
In the SFTP Server List, click the name of the SFTP server alias that you want to edit.
In the properties screen for the selected alias, make the necessary modifications.
Click Save Changes.

Creating an SFTP User Alias

About this task

An SFTP user alias is a named set of parameters that contains SFTP user account details and client configurations that Integration Server uses to function as an SFTP client.

In many organizations, a system administrator provides the SFTP user account information that you require to create an SFTP user alias.

You can have multiple SFTP user aliases for the same SFTP user account. Each SFTP user alias name in an Integration Server must be unique.

Keep the following points in mind when configuring Integration Server to act as an SFTP client:

Integration Server supports password authentication and public key authentication for authenticating itself as the client to the SFTP server.
For both password and public key authentication, you must have an account on the SFTP server that is set up for SFTP access.
For public key authentication, the SFTP server and Integration Server must have access to their own private key and each other's public key.

Important: You must create at least one SFTP server alias before creating an SFTP user alias.

To create an SFTP user alias

Procedure

Open Integration Server Administrator.
In the Navigation panel, select Settings > SFTP.
Click User Alias Settings.
Click Create User Alias.

Under SFTP User Alias Properties, provide the following information:

Parameter	Specify
Alias	A name for the alias. An SFTP user alias name: Can contain only underscores (_) and periods (.) as the special characters. Cannot begin with the string "http://". Can be of a maximum length of 255 characters.
User Name	The user name for the SFTP user account.
Authentication Type	The type of authentication that Integration Server uses to authenticate itself to the SFTP server. Client authentication can be either by password or by public and private keys.
	Select	To
	Password	Use password authentication.
	Public Key	Authenticate Integration Server by using public and private keys. To use this authentication type, the SFTP server and Integration Server must each have access to their own private key and each other's public key. If you select public key authentication, Integration Server saves the private key file in the `Integration Server_directory` /instances/`instance_name`/config/sftp/identities folder.
Password	If you are using password authentication, enter the password for the specified user to connect to the SFTP server.
Re-type Password	Re-enter the above password.
Private Key Location	If you selected Public Key as the authentication type, enter the location of the private key of the specified SFTP user.
PassPhrase	If you selected Public Key as the authentication type and if the private key you specified requires a passphrase, enter the passphrase for the private key file of the specified user.
Re-type PassPhrase	Re-enter the above passphrase.
SFTP Server Alias	The alias of the SFTP server to which you want the specified user to connect.
Maximum Retries	The number of times Integration Server attempts to connect to the SFTP server. The maximum allowed value is 6. The minimum allowed value is 1. The default is 6 retries.
Connection Timeout (seconds)	The amount of time (measured in seconds) Integration Server waits for a response from the SFTP server before timing out and terminating the request. The default is 0, which indicates that the session will never time out.
Session Timeout (minutes)	The number of minutes you want Integration Server to wait before terminating an idle session. The default is 10 minutes.
Strict Host Key Checking	Whether Integration Server verifies the host key of the SFTP server before establishing a connection to the SFTP server.
	Select	To
	Yes	Allow Integration Server to verify the host key of SFTP server against the host key that was imported during the SFTP server alias configuration. If the host key is found to be the same, then Integration Server establishes a connection to SFTP server, else the connection to SFTP server fails.
	No	Prevent Integration Server from verifying the host key of SFTP server during connection.
	Note: For added security, Software AG recommends you to choose Yes and enable the host key verification.
Compression	Whether or not to compress the data to reduce the amount of data that is transmitted. Integration Server supports compression using the compression algorithm zlib. Note: You can use compression only if the SFTP server that you are connecting to supports compression.
	Select	To
	zlib	Compress the data that is transmitted between the SFTP server and Integration Server.
	None	Not compress the data.
Compression Level	The compression level to use if you selected the compression algorithm zlib in the Compression field. The minimum allowed value is 1 (fast, less compression). The maximum allowed value is 6 (slow, most compression). The default is 6.

Click Save Changes.

Integration Server saves the SFTP user alias configuration in the Integration Server_directory /instances/instance_name/config/sftp/sftpUserAliases.cnf file.

Editing an SFTP User Alias

About this task

You can edit all the fields except the alias name and the user name for the SFTP user account.

To edit an SFTP user alias

Procedure

Open Integration Server Administrator.
In the Navigation panel, select Settings > SFTP > User Alias Settings.
In the SFTP User List, click the name of the SFTP user alias that you want to edit. Integration Server displays the properties screen for that alias.
In the properties screen for the selected alias, make the necessary modifications.
Click Save Changes.

Migration Impact on SFTP Configurations

Prior to Integration Server 9.12, Preferred Key Exchange Algorithms and Proxy Alias fields were specified in the SFTP user alias. These fields are now specified in the SFTP server alias. When you migrate to Integration Server 9.12 or later from an earlier version, Integration Server determines the values of the Preferred Key Exchange Algorithms and Proxy Alias fields as follows:

If an SFTP server alias was never used in an SFTP user alias, Integration Server uses the default order for the Preferred Key Exchange Algorithms and the default value of None for the Proxy Alias.
If an SFTP server alias was used in only one SFTP user alias, Integration Server migrates the order of Preferred Key Exchange Algorithms and the value of Proxy Alias from the SFTP user alias to the SFTP server alias.
If an SFTP server alias was used in multiple SFTP user alias, Integration Server migrates the order of Preferred Key Exchange Algorithms and value of Proxy Alias from the first SFTP user alias associated with the SFTP server alias.

Upgrade Impact on Existing Server Alias Data

For Version SFTP client

The SFTP Version 1 client fields are populated with the values of the watt.ssh.jsch.* properties in the following manner:

Preferred Key Exchange Algorithms: The algorithms included in the value of the watt.ssh.jsch.kex server property are added to "Preferred Key Exchange Algorithms", and all other algorithms are added to "Excluded Key Exchange Algorithms". If the value of the watt property is empty, the default Key Exchange algorithms are added to "Preferred Key Exchange Algorithms".
Preferred MAC Algorithms S2C: The algorithms included in the value of the watt.ssh.jsch.mac_s2c server property are added to "Preferred MAC Algorithms S2C" and all other algorithms are added to "Excluded MAC Algorithms S2C". If the value of the watt property is empty, then the default server-to-client MAC algorithms are added to "Preferred MAC Algorithms S2C".
Preferred MAC Algorithms C2S: The algorithms included in the value of the watt.ssh.jsch.mac_c2s server property are added to "Preferred MAC Algorithms C2S" and all other algorithms are added to "Excluded MAC Algorithms C2S". If the value of the watt property is empty, then the default client-to-server MAC algorithms are added to "Preferred MAC Algorithms C2S".
Preferred Ciphers S2C: The ciphers included in the value of the watt.ssh.jsch.ciphers server property are added to "Preferred Ciphers S2C" and all other ciphers are added to "Excluded Ciphers S2C".
Preferred Ciphers C2S: The ciphers included in the value of the watt.ssh.jsch.ciphers server property are added to "Preferred Ciphers C2S" and all other ciphers are added to "Excluded Ciphers C2S ".

For Version 2 SFTP client

The latest Version 2 SFTP client supports OpenSSH format host keys, and the existing key may be in the unsupported SSH2 format. So, you may not be able to save the server alias successfully. In such cases, regenerate the host key in the OpenSSH format, and click Get Host Key to get the regenerated key for the server alias.
The Preferred MAC Algorithms list excludes hmac-sha256, hmac-sha256@ssh.com, hmac-sha512, hmac-sha512@ssh.com, hmac-ripemd160, hmac-ripemd160@openssh.com, hmac-ripemd160-etm@openssh.com as they are not supported by the latest Version 2 SFTP client.

Note: The upgrade impact for SFTP Version 2 SFTP client is applicable after installing IS_10.5_Core_Fix22, which upgrades maverick-client-1.7.23.jar to 1.7.34 for PIE-77771.

Note:

All watt.ssh.jsch.* parameters, except watt.ssh.jsch.logging, are deprecated. Do not use the deprecated parameters because the preferred key exchange algorithms, ciphers, and MAC algorithms are configured from the user interface.
Integration Server uses the watt.ssh.jsch.logging server configuration property to enable logging for both versions of the SFTP client.

Testing the Connection to the SFTP Server

About this task

After you add an SFTP user alias, you can test the connection to ensure that Integration Server can establish a connection with the SFTP server using the credentials and details you specified for the alias.

To test the connection to an SFTP server

Procedure

Open Integration Server Administrator.
In the Navigation panel, select Settings > SFTP > User Alias Settings.

Integration Server Administrator displays all the SFTP user alias definitions.
In the Test column for the alias that you want to test, click the icon.

Integration Server Administrator displays a status line that indicates whether or not the connection is successful.

If testing the user alias results in java.security.NoSuchProviderException, add the org.bouncycastle.jce.provider.BouncyCastleProvider security provider class in Integration Server Administrator > Security > Keystore > Add Security Provider.