This article is relevant if you are seeking to program against NetSuite sFTP module.
Background
Shortly after the release of NetSuite SuiteScript 2.0, a new sFTP module (N/sftp) was made available. I was pleased when I was at SuiteWorld and the NetSuite Product team sought me out because they noticed that my firm offers up, free of software license charge, a fully automated FTP service. See my article, Link NetSuite to FTP via Open Source Middleware. While we have implemented our FTP service for a number of clients, on a few occasions, we have had clients want to use NetSuite’s built-in module.
We found that the module takes some understanding to get it working. One of our senior consultants, Boban, ultimately figured out how to work with the peculiarities. Thus, this article is a credit to him as I want to share his findings to help the larger community.
NetSuite sFTP Authentication Setups
In traditional Secure FTP programming, you need to provide the following parameters in order to connect to a remote host:
- URL
- Port
- Userid
- Password
But when reviewing the NetSuite documentation, it is clear that there are two differences in their implementation:
- Provide a parameter called hostKey
- Provide ‘passwordGuid’ instead of ‘password’
The documentation attempts to explain these parameters, but if you don’t have experience in either, it can be a bit confusing.
What is NetSuite N/sftp hostKey parameter?
According to the NS documentation:
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.
Here is what this means. The remote server identifies itself with its hostkey when connecting to it, but NetSuite wants you to provide that value in advance in order to verify this connection. And NetSuite intentionally doesn’t provide a way for you to “request” the host key from the remote server. Instead, it wants you to “look it up manually” by using the ssh-keyscan utility (built into Windows command shell, for example).
Example: ssh-keyscan -t rsa -p 1234 acme.com
This example will obtain (and show you) the RSA host key for acme.com when connecting on port 1234. Once you get this value, you can use it when establishing a connection using NetSuite’s “sftp.createConnection” call.
How to work with NetSuite’s N/sftp passwordGuid Parameter
This passwordGuid parameter is more demanding to work with because you have to build a one-time utility ahead of time to get the value. This parameter requirement is simply NetSuite’s way of forcing you to NOT hard-code a password inside a script. It is forcing you to store the password in NetSuite’s own “password repository” – and when you use it, it hands you back a “key” (the passwordGuid). Then, when you need that stored password, you reference the passwordGuid, and it retrieves and uses your password.
You add things to the password repository by creating a very simple suitelet (example below) which asks the user for the password, and it automatically stores it for you. Part of the security features is that you can tell NetSuite to only allow the use of this passwordGuid by specific users, specific scripts, and/or specific URLs. Readers may want to reference a related previous article where Netsuite is working with passwords and limited the scope of where that credential can be used. See How to Use NetSuite’s nlapiRequestURLWithCredentials API
Here is a sample suitelet for asking the user for a password, and then storing it, and allowing it only to be used for a particular URL, and by a particular script:
if (context.request.method === 'GET') { var form = ui.createForm({title: 'Password Form'}); form.addCredentialField({ id: 'password', label: 'Password', restrictToDomains: ['ftp.acme.com'], restrictToCurrentUser: false, restrictToScriptIds: 'customscript_my_ftp_example' }); form.addSubmitButton(); context.response.writePage({pageObject: form}); } else { var passwordGuid = context.request.parameters.password; // at this point NetSuite has already stored the password in its repository; store the value of passwordGuid for future use }
Other Important NetSuite’s SFTP Limitations
No sFTP Directory Lookup
One limitation that we ran into almost immediately is that the NetSuite SFTP module only supports download and upload methods. There is no support for any kind of directory/file discovery. In other words, if you want to download a file from the remote server, you must know the exact filename that you want to download. There is no method to retrieve a list of files in a folder.
If the remote server (which is the case for many projects) creates files with date/timestamps in the filename or the filenames are random, even though you know the directory they are in, you have no way of downloading them.
No Certificate or Token Based Authentication
Another limitation, though it did not affect our senior consultant, is that only traditional userid/password authentication is supported. Certificate-based or token-based authentication is not supported.
Only sFTP Services / No FTP
Many folks assume that sFTP is simply FTP in a secure setup. They are not the same and are not interchangeable. See related article. If you need to connect to regular FTP services, you will need another option. Our FTP service works with any protocol because we are leveraging the open source middleware platform, Camel.
Get Robust NetSuite FTP Capacities
My hope is that this article saves you much time when developing a project to use NetSuite’s sFTP module. There are important gotchas that increase the risk to produce the project. In my mind, our FTP service gives us full control over the situation. Because we offer this as an implementation service, we are happy to work with your technical people to “own the bits” so that you can configure it any way you need. If you need assistance, let’s have a conversation.
No sFTP Directory Lookup: Netsuite is introducting the API list for Remote directory lookup from 2019.2 and it’s available in release preview.
Connection.list(options) Lists the remote directory.
https://netsuite.custhelp.com/app/answers/detail/a_id/87208
Thank you Ignatius. This is good to reference.