Getting started with the SFTP Connector for MuleSoft

Requirements: /n software Connectors for MuleSoft

Introduction

The /n software Connectors for MuleSoft include pure java Connectors and Modules designed to seamlessly integrate with MuleSoft. The /n software Connectors for MuleSoft extend the functionality of MuleSoft and provide robust enterprise ready enterprise ready Internet connectivity, secure messaging, and file transfer.

This guide will focus on the basics of the SFTP Connector, which is used to communicate with SFTP servers. SFTP relies on SSH encryption for built-in transport security. For details on installation and other connectors please see the Online Documentation.

Contents

SFTP Receiver Properties

Core Properties

To use an SFTP Receiver instance to a MuleSoft project, there are a few core properties that must be set:

PropertyDescription
SSH HostThe remote address of the SFTP server
SSH PortThe port on which to connect
SSH Auth Mode

Specifies the authentication mode to use. Possible values are:

  • Password (Default): Requires that SSH User and SSH Password are set to valid credentials
  • PublicKey: Requires that SSH Cert is set to the certificate holding the appropriate public key
  • KeyboardInteractive: The connector will attempt to answer the server's prompts with the values in SSH User and SSH Password
  • GSSAPIWithMic: Kerberos authentication will be attempted using the GGSSAPI-WITH-MIC scheme; authentication will be tried with the value of SSH User (single sign-on), or with alternate credentials if SSH Password is also specified.
SSH UserCredential for performing SSH logon; see SSH Auth Mode
SSH PasswordCredential for performing SSH logon; see SSH Auth Mode
SSH CertCertificate with public performing SSH logon; see SSH Auth Mode
Remote PathThe path on the SFTP host from which files should be downloaded
File MaskAn optional mask for the files at the Remote Path

Together, these properties determine the location (and credentials for that location) from which files will be received.

SSH Certificates

The SSH Accept Server Host Key property tells the connector which server certificate(s) to trust when connecting to an SFTP server. To set the fields of SSH Accept Server Host Key, the property should be set to Edit inline. The easiest approach to trusting server certificates is to set the Accept Any field to True. This will implicitly trust the specified SSH Host and no further fields should be specified. For more granular control, the Store Type, Store, Store Password, and Subject fields together identify the certificate within a certificate store to expect from the server.

SSH Cert is similarly comprised of four fields (and should be set to Edit inline to access these fields): Store Type, Store, Store Password, and Subject. Together these identify the certificate within a certificate store that the connector will use as a client credential for SSH logon (if necessary).

SFTP Receiver Usage

Dragging an instance of the SFTP Receiver into a Mule project will automatically establish an SFTP Source Connector. A configuration must be applied to the connector, including the core and certificate properties mentioned in the previous section. Additionally the polling settings should be configured in the general connector settings pane.

The connector will poll the specified SFTP Server at the specified Remote Path for any files matching the File Mask. Any files found will be sent through the MuleSoft message pipeline. The Delete Mode property can be set if files should be deleted after downloading.

After download, the files enter the Mule message flow. After the SFTP Receiver passes the file data off to another component within the Mule flow, certain attributes of the file are available. In Mule 3.X, these message context attributes are accessed by referencing the inboundProperties of the message, e.g. message.inboundProperties.ReceivedFileName. In Mule 4.X, these properties are available through the attributes keyword, e.g. attributes.ReceivedFileName.

Here is an example of a simple flow that receives files from an SFTP Server and writes them to the local drive:

An example SFTP Receive flow and configuration

SFTP Sender Properties

Core Properties

To use an SFTP Sender instance to a MuleSoft project, there are a few core properties that must be set:

PropertyDescription
SSH HostThe remote address of the SFTP server
SSH PortThe port on which to connect
SSH Auth Mode

Specifies the authentication mode to use. Possible values are:

  • Password (Default): Requires that SSH User and SSH Password are set to valid credentials
  • PublicKey: Requires that SSH Cert is set to the certificate holding the appropriate public key
  • KeyboardInteractive: The connector will attempt to answer the server's prompts with the values in SSH User and SSH Password
  • GSSAPIWithMic: Kerberos authentication will be attempted using the GGSSAPI-WITH-MIC scheme; authentication will be tried with the value of SSH User (single sign-on), or with alternate credentials if SSH Password is also specified.
SSH UserCredential for performing SSH logon; see SSH Auth Mode
SSH PasswordCredential for performing SSH logon; see SSH Auth Mode
SSH CertCertificate with public performing SSH logon; see SSH Auth Mode
Remote PathThe path on the SFTP host to which files should be uploaded
Remote FileThe name of the file once uploaded to the remote host

Together, these properties establish the SFTP connection and determine the location and name of the uploaded file(s). If files should retain their original name after upload, this can be accomplished by using the message context properties in the Remote File property. In Mule 3.X this should be set to #[message.inboundProperties.ReceivedFileName]. In Mule 4.X, the corresponding syntax is #[attributes.ReceivedFileName].

SSH Certificates

The SSH Accept Server Host Key property tells the connector which server certificate(s) to trust when connecting to an SFTP server. To set the fields of SSH Accept Server Host Key, the property should be set to Edit inline. The easiest approach to trusting server certificates is to set the Accept Any field to True. This will implicitly trust the specified SSH Host and no further fields should be specified. For more granular control, the Store Type, Store, Store Password, and Subject fields together identify the certificate within a certificate store to expect from the server.

SSH Cert is similarly comprised of four fields (and should be set to Edit inline to access these fields): Store Type, Store, Store Password, and Subject. Together these identify the certificate within a certificate store that the connector will use as a client credential for SSH logon (if necessary).

SFTP Sender Usage

Dragging an instance of the SFTP Sender into a Mule project will automatically establish an SFTP Process Connector. A Process Connector receives data from Source Connectors (with possible intermediary steps), and the SFTP Connector processes data by uploading it to remote SFTP hosts. A configuration must be applied to the connector, including the core properties mentioned in the previous section.

Whenever a Mule message is provided to the connector during the MuleSoft flow, the connector will connect to the specified SSH Host and upload the data at the location given by Remote Path and Remote File. The Overwrite property can be set if files should be uploaded even if a file of the same name already exists on the server.

Below is an example of a simple flow that receives files from an SFTP Server and then uploads them to a different location on the SFTP Server. You can imagine that the files are processed during the MuleSoft flow (not shown) and then uploaded back to an archive location.

An example SFTP Receive flow and configuration

We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.