SFTP Authentication
Please review the following sections for an overview of SFTP authentication when using SuiteScript.
Two-Factor Authentication
You can use two-factor authentication to connect to an SFTP server. A combination of password and key is supported. For more information, see sftp.createConnection(options).
Credential Tokenization
SuiteScript provides the ability for users to securely store authentication credentials in such a way that scripts are able to use encrypted saved credentials without being able to see their contents. The script author must specify which scripts and domains are permitted for use with the credential. To restrict the credential for use by SuiteScript automation triggered by the same user who originally saved the credential, the script author can set the restrictToCurrentUser parameter.
Creating a Suitelet Form that Contains a Credential Field
Credential fields have a default maximum length of 32 characters. If needed, use the Field.maxLength property to change this value
...
if (request.method === context.Method.GET){
var form = serverWidget.createForm({title: 'Enter SFTP Credentials'});
var credField = form.addCredentialField({
id: 'custfield_sftp_password_token',
label: 'SFTP Password',
restrictToScriptIds: ['customscript_sftp_script'],
restrictToDomains: ['acmebank.com'],
restrictToCurrentUser: true //Depends on use case
});
credField.maxLength = 64;
form.addSubmitButton();
response.writePage(form);
}
...
Reading the Credential Token in a Suitelet
The following code sample shows the syntax for this member. It is not a functional example. For a complete script example, see N/sftp Module Script Samples.
...
var request = context.request;
if (request.method === context.Method.POST){
// Read the request parameter matching the field ID we specified in the form
var passwordToken = request.parameters.custfield_sftp_password_token;
log.debug({
title: 'New password token',
details: passwordToken
});
// In a real-world script, "passwordToken" is saved into a custom field here...
}
...
Credential Management
User passwords can be stored using secure Credential Fields. This type of field is available on the serverWidget.Form Object in the N/ui/serverWidget Module.
Encrypted custom fields do not support tokenization and are not compatible with the SFTP module. Instead, you can add a credential field using Form.addCredentialField(options).
Credential GUID Persistence
Scripts may store credential tokens as convenient for the script author. Credential tokens are not related to the password in its original or encrypted form within NetSuite. These tokens are unique identifiers which allow a script to refer to an encrypted secret securely stored within the SuiteCloud platform. Automatic password expiration is not currently provided, nor is it possible to view an inventory of saved credentials in the user interface.
Protocols
The SFTP module allows scripts to transfer files using the SSH File Transfer Protocol only. Other file-based protocols such as FTP, FTPS, SCP are not supported by this module.
Host Key Verification
An SFTP server identifies itself using a host key when a client attempts to establish a connection. Host keys are unique keys that the underlying SSH protocol uses to allow the server to provide a fingerprint. Clients can verify that the expected server has responded to the connection request for a particular URL and port number.
SuiteScript requires that the host key is provided by the script attempting to connect so that the SFTP module can check the identity of the SFTP server. This security best practice is commonly referred to as "Strict Host Key Checking".
Host keys are used to verify the identity of the server, not the client. For more information, see SSH Keys for SFTP.
There is no SuiteScript API call for checking the host key of a remote SFTP server, or an option to disable strict host key checking. The script must always know the host key ahead of time.
You can use the OpenSSH ssh-keyscan tool to check the host key of an external SFTP site. See Retrieving the Host Key of an External SFTP Server and The OpenBSD’s ssh-keyscan page.
Retrieving the Host Key of an External SFTP Server
An example usage checking the RSA host key of URL: example.com at port: 1234 from a *nix shell follows:
$ ssh-keyscan -t rsa -p 1234 example.com
AATpn1P9jB+cQx9Jq9UeZjA1245X7SBDcRiKh+Sok56VzSw==
You should always pass the key type and port number. This practice helps to avoids ambiguity in the response from the external SFTP server.
Setting up SFTP Password GUID and RSA Host Key using a Bundled Tool
Prerequisites
Certain prerequisites are required before you can set up the SFTP password GUI and RSA host key. You must follow these steps before you can set up the SFTP configuration:
-
Make sure you have the host URL, user name, password, port number (default value is 22), default directory, and host key of the SFTP box (or customer).
-
Install the Git CLI.
-
If the host key is not in base64 form, run the following command using Git bash to scan the ssh public key in base64 format:
ssh-keyscan -t <host key algorithm type> -p <port number> <host name> -
Save the generated host key.
-
Install the SFTP Connection Tool — Password GUID bundle (Bundle ID: 413267).
Solution
After you complete the prerequisite steps above, follow these steps to set up the SFTP Configuration Record:
-
In your Administrator Account (Classic Center), go to Setup > Custom > SFTP Configuration > New.
-
On the SFTP Configuration page, set the following field values:
Field
Value
SFTP Server
The SFTP host URL
User ID
The SFTP user name.
Port
The SFTP port number (set to 22 by default).
Default File Directory
The folder path in the SFTP.
Test File For SFTP Connection
Select any dummy file for the SFTP connection test.
Test Download Folder Id
Specify an existing folder ID from your account’s File Cabinet. The test connection process will upload and re-download the file as part of the connection validation. The downloaded file will be stored on the folder specified here.
Applicable Scripts
Set multiple scripts that will be considered when generating a secure password GUI. By default, always add the script id “customscript_ns_sl_test_sftp_connection”.
Host Key
The host key generated from the Git CLI (Prerequisite step 2–4).
To generate the password GUI:
-
Go to Setup > Custom > Generate SFTP Passsword GUI.
-
Set the password that you received form the SFTP provider.
-
Click Save. A message similar to the following is displayed:
Secret key generated successfully.
-
Return to the SFTP Configuration page and verify the secret key/password GUID is set to your SFTP Configuration record.
To test the SFTP Connection:
-
Go to Setup > Custom > Test SFTP Connection.
-
Open the menu link in a new tab. The test will occur right away upon opening the link. A message similar to the following is displayed:
-
The file that was uploaded and re-downloaded from the SFTP can be found on the specified folder from your SFTP Configuration Record.
The SFTP Configuration Record can be used as your main configuration record for a custom SFTP solution.