Integration Server 10.3 | Built-In Services Reference Guide | Client Folder | Summary of Elements in this Folder | pub.client.sftp:login
 
pub.client.sftp:login
WmPublic. Creates a secure connection to the SFTP server using the specified user alias or configuration parameters.
Important:
The sessionKey returned by this service is used by most other pub.client.sftp services.
Note:
The SFTP configuration parameters for SFTP Client Version 2 was introduced for PIE-61188 in IS_10.3_Core_Fix10.
Input Parameters
userAlias
String. Optional. Alias containing the SFTP client configuration for an SFTP user account.
Integration Server creates a new session each time it logs in to the SFTP server and returns the session key to the user.
This parameter is optional. Instead of using this parameter, you can pass the login credentials and the configuration parameters using the fields within the sftpConfigurationParameters document.
Note:
It is recommended to use userAlias instead of the fields within the sftpConfigurationParameters document because it is resilient to changes in configuration, such as removal of algorithms or ciphers in favor of stronger algorithms and ciphers.
If you provide inputs for both userAlias and SFTP configuration parameters, then userAlias takes precedence.
reuseSession
String. Optional. Flag indicating whether or not Integration Server reuses a session that is already open for the specified user alias. Set to:
*true, to reuse the session that is already open for the specified user alias. If a session is not open for this user alias, the pub.client.sftp:login service creates a new session and returns the key for this new session.
*false, to create a new session for the specified user alias. This is the default.
sftpConfigurationParameters
Document. Optional. The following parameters are part of this document.
sftpClientVersion
String. Indicates the Integration Server SFTP client version, which can be version1 (existing) or version2 (new). Set to version2, if you want Integration Server to use the new SFTP client that has new configuration properties, additional Key Exchange Algorithms, Machine Access Code (MAC) algorithms, and ciphers.
serverHost
String. The IP address or the host name of the SFTP server.
serverPort
Integer. The SFTP server port number. The port number must be within the range of 0 and 65535 (inclusive).
hostKeyBytes
Object. Optional. An array of bytes (byte[]). The host key of the SFTP server. If this field is empty, then host key verification is not strict: Integration Server ignores the value of the strictHostKeyChecking field and trusts the host key received from the SFTP server while creating a connection.
Note:
You can get the host key of the SFTP server by using the pub.client.sftp.admin:getHostKey service.
userName
String. The user name for the SFTP user account.
authenticationType
String. Type of authentication that Integration Server uses to authenticate itself on the SFTP server. Set to:
*password, to use password-based authentication.
*public key, to use public key-based authentication. If the authentication type is password, then the value in the password field is used. If the authentication type is publicKey, then the value provided in the privateKeyBytes field is used.
password
String. Optional. Password of the specified SFTP user account. This is required if authenticationType is password.
privateKeyBytes
Object (an array of bytes (byte[])). Optional. If the authentication type is publicKey, then provide the private key of the specified SFTP user account.
passPhrase
String. Optional. It is required if you select publicKey as the authentication type and the private key that you specified requires a passphrase
minDHKeySize
Integer. Optional. The minimum DH key size. The default value is 1024. This field is not applicable if sftpClientVersion is version1.
maxDHKeySize
Integer. Optional. The maximum DH key size. The default value is 8192. This field is not applicable, if sftpClientVersion is version1.
preferredKeyExchangeAlgorithms
String. Optional. A comma-separated list of preferred key exchange algorithms. If not defined, then the default list of key exchange algorithms (in the default order) is used.
Note:
You can get the list of default key exchange algorithms, MAC algorithms, and ciphers by using the pub.client.sftp.admin:getDefaultAlgorithms service.
preferredCiphersS2C
String. Optional. A comma-separated list of preferred server-to-client ciphers. If no value is provided, then the default list of server-to-client ciphers (in the default order) is used.
preferredCiphersC2S
String. Optional. A comma-separated list of preferred client-to-server ciphers. If a value is not provided, then the default list of client-to-server ciphers (in the default order) is used.
preferredMacC2S
String. Optional. A comma-separated list of preferred client-to-server Message Authentication Code (MAC) algorithms. If a value is not provided, then the default list of client-to-server MAC algorithms (in the default order) is used.
preferredMacS2C
String. Optional. A comma-separated list of preferred server-to-client Message Authentication Code (MAC) algorithms. If a value is not provided, then the default list of server-to-client MAC algorithms (in the default order) is used.
proxyAlias
String. Optional. The proxy alias through which the request 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 are tried.
maximumRetries
Integer. Optional. The maximum number of times Integration Server tries to connect to the SFTP server, if login fails. The default value is 5. This field is applicable, if sftpClientVersion is version1.
connectionTimeout
Integer. Optional. The time (in seconds) that 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 never times out.
sessionTimeout
Integer. Optional. The number of minutes that Integration Server waits before terminating an idle session. The default is 30 minutes.
compression
String. Optional. Determines whether data should be compressed or not, to reduce the size of the data in transition. Integration Server supports compression using the zlib compression algorithm. The allowed values for this field are none and zlib.
Note:
Use compression, only if the SFTP server to which you connect supports compression.
compressionLevel
Integer. Optional. The compression level to use, if you select zlib in the compression field. The minimum allowed value is 1 (fast, minimum compression). The maximum allowed value is 6 (slow, maximum compression). The default value is 6. This field is not applicable if sftpClientVersion is version2.
strictHostKeyChecking
String. Optional. Enables host key checking. The default value is Yes.
*If set to Yes and the host key does not match the host key provided in the hostKeyBytes field at the time of handshake, then the connection fails.
*If set to No, then the host key is not checked during the handshake.
This field is ignored if the hostKeyBytes field is empty.
Output Parameters
sessionKey
String. On successful login, this field contains the session key.
returnCode
String. The code returned for the login command.
returnMsg
String. The message returned for the login command.
Usage Notes
You cannot execute SFTP commands in parallel using the same session key.
If the watt.client.sftp.session.logoutOnServiceCompletion parameter is set to true, the FTP session created by the pub.client.sftp:login service closes automatically when the invoking service completes execution. If the value is set to false, then the pub.client.sftp:logout service must be invoked to close the FTP(S) session.