SFTP (prebuilt connector) – Patchworks Support Portal

To view this content in our official product documentation, click here.

Description

The Patchworks SFTP connector is used to connect SFTP servers, for use in process flows.

Authentication

When adding connector instances for the Patchworks SFTP connector, the following authentication methods are supported:

Guidance for using these authentication methods is summarised below.

{% hint style="warning" %} If you are using a custom version of our prebuilt SFTP connector (i.e. if the authentication method and/or endpoint settings have been updated after the original installation), please be aware that your settings and requirements may vary. {% endhint %}

User pass

The Patchworks SFTP connector supports authentication via username/password. If you choose to add a connector instance with user pass authentication, you need to enter the following details:

Key pass

The Patchworks SFTP connector supports authentication via public/private keys. If you choose to add a connector instance with key pass authentication, you need to enter the following details:

Generating host fingerprint values

Server finger prints are created using the FTP server’s public key. The server will provide this in either SSH-RSA or SSH-SHA format. Patchworks chooses the most secure public key format available on the FTP server for fingerprint verification, noting that:

The public key must be Base64 decoded and then hashed with either md5 or sha512 algorithms.
The preferred key format is ssh-ed25519 but ssh-rsa format is acceptable.

The steps below summarise how to generate a host server fingerprint:

Step 1\ Assuming that your public key is stored on your FTP server, you can use the following OpenSSH command to scan the available public key and save it to a local file:

ssh-keyscan [Host Address]> [local filename]

More information about OpenSSH command can be find here: https://www.openssh.com.

Step 2\ Open the file - it should display the key with its hostname and key format - for example:

Step 3\ To generate your host server fingerprint you will need to copy the key, decode it and then hash it with either the md5 or sha512 algorithm. You can do this with https://onlinephp.io/ using the code snippet below:

{% code lineNumbers="true" %}

<?php
//$publicKey = [YOUR PUBLIC KEY];
$publicKey = 'ssh-ed25519 YOUR_PUBLIC_KEY_HERE';
$content = explode(' ', $publicKey);
$algo = $content[0] === 'ssh-rsa' ? 'md5' : 'sha512';
echo implode(':', str_split(hash($algo, base64_decode($content[1])), 2));

Here, you should replace the YOUR_PUBLIC_KEY_HERE placeholder in line 3 with your own public key, then execute the code to generate a fingerprint value:

The fingerprint is generated in either **md5** or **sha51** format, depending on whether the first element of the `$content` array (line 4) is **ssh-rsa**. If it is, the hash algorithm is set to md5 - otherwise, it's set to sha512.

Troubleshooting SFTP connections

If an error is given when you try to save connector instance settings, check that:

Your credentials are valid
The associated user has permissions to access the specified root and path directories on the FTP server

It's a good idea to try the same settings in an FTP client - if they work there, they should work when creating a Patchworks instance.

More information

For further information about working with the SFTP connector please see our Configuring SFTP connections page.

Credential	Notes
`Host`	Enter the host name provided by your SFTP provider. For example: `eu-west-1.sftpcloud.io`
`Username`	Enter the username provided by your SFTP provider.
`Password`	Enter the password provided by your SFTP provider.
`Port`	Enter the port number provided by your SFTP provider.
`Root`	Enter the initial directory that the SFTP client connects to once a connection is made. This becomes the reference point for subsequent file operations. For example: `/`
`Path`	Specify a location of specific files or directories relative to the root that you wish to use, or leave blank. Whenever the SFTP connector is added to a process flow, you need to enter the required `path` to be accessed. With this in mind, there's no need to be too specific when setting up the instance - entering `/` here is fine.
`Visibility`	Refers to file visibility - set to `public` or `private`. The default setting of `public` is typical however, set to `private` if your SFTP server requires. Private visibility is where an SFTP server does not list files within directories - which means you have to know the exact name of any file(s) that you want to target.
`Directory visibility`	Set to `public` or `private`. The default setting of `public` is typical however, set to `private` if your SFTP server requires. Private directory visibility is where an SFTP server does not list directories from the root - which means you have to know the exact name of any directory that you want to target.
`Max tries`	Enter the maximum number of connection attempts that should be made before the connection is determined to have have failed.
`Timeout`	Enter the maximum number of seconds that the connector should wait for a response from the SFTP server before it determines the connection attempt to be failed.

Credential	Notes
`Host`	Enter the host name provided by your SFTP provider. For example: `eu-west-1.sftpcloud.io`
`Username`	Enter the username provided by your SFTP provider.
`Port`	Enter the port number provided by your SFTP provider.
`Private key`	Copy/paste in the private key for this connection. The key should be pasted in full - for example: `-----BEGIN PRIVATE KEY----- MHc123456fNphsKI77lw/CaRA4v93oAoGCP4tchI5ac4t49 123UQDQgAE6i6U/g&KLD23456789ZBs0OWXOg5NJ7XAFxAwIJf78FJR2ORUI x+G2KPR123456789mkfAQP9FYg== -----END PRIVATE KEY-----` Currently, RSA (`.pem`) format must be used. If your key is in a different format, you can convert it using tools such as PuttyGen.
`Passphrase`	If you added a passphrase when generating public/private keys for this connection, enter it here.
`Host fingerprint`	This is an optional security measure, normally used to ensure that the server you are connecting to is not an imposter - it aims to mitigate threats such as 'man in the middle' attacks. Here, an MD5 or SHA512 fingerprint can be used. Fingerprints are tied to the hashing algorithm used to generate the public key - the default is often (but not always) MD5. For more information please see the Generating host fingerprint values section below.
`Root`	Enter the initial directory that the FTP client connects to once a connection is made. This becomes the reference point for subsequent file operations. For example: `/`
`Path`	Specify a location of specific files or directories relative to the root that you wish to use, or leave blank. Whenever the SFTP connector is added to a process flow, you need to enter the required `path` to be accessed. With this in mind, there's no need to be too specific when setting up the instance - entering `/` here is fine.
`Visibility`	Refers to file visibility - set to `public` or `private`. The default setting of `public` is typical however, set to `private` if your SFTP server requires. Private visibility is where an SFTP server does not list files within directories - which means you have to know the exact name of any file(s) that you want to target.
`Directory visibility`	Set to `public` or `private`. The default setting of `public` is typical however, set to `private` if your SFTP server requires. Private directory visibility is where an SFTP server does not list directories from the root - which means you have to know the exact name of any directory that you want to target.
`Max tries`	Enter the maximum number of connection attempts that should be made before the connection is determined to have have failed.
`Timeout`	Enter the maximum number of seconds that the connector should wait for a response from the SFTP server before it determines the connection attempt to be failed.