- 3 Minutes to read
- Print
- DarkLight
URL Encoding in FTP, SFTP, and FTPS Connection Strings
- 3 Minutes to read
- Print
- DarkLight
General Information
This document applies to Engage GUI dialog windows like Report, Export, and Raw Data Export where an SFTP, FTP, or FTPS username:password, and server name connection string are specified like this:
ftp://username:password@domainname.com/optionalpaths
The username and password cannot contain certain "reserved" symbols unless they are URL-encoded.
As a simple example, given that the symbol ":" separates the username from the password, and the "@" character separates the username and password pair from the domain to be connected, these cannot be present without particular encoding. Otherwise, the FTP client cannot determine what is part of the username, part of the password, and what separates that from the domain.
Characters that do not require URLEncoding
Suppose a username or password contains basic ASCII characters in the list below. In that case, the username and password will be directly usable without any extra transformation:
A through Z
a through z
0 through 9
Hyphen: -
Underscore: _
Full stop: .
Tilda: ~
Example
The password "AgJ.fh-fg_G68" can be used directly.
Characters that require URL encoding
If other symbols are needed, then the string must be URL-encoded so that any unsupported characters are converted into a numerical code that will be allowed.
You can URL-encode a string with several online tools, such as https://www.urlencoder.org/.
As an example, you can replace some of the reserved characters with their URL-encoded variants. This should allow you to use other characters in a username or password string:
% should be replaced by %25
! should be replaced by %21
@ should be replaced by %40
: should be replaced by %3A
; should be replaced by %3B
, should be replaced by %2C
? should be replaced by %3F
* should be replaced by %2A
+ should be replaced by %2B
= should be replaced by %3D
Example
The username:password pair "a%t56:rte*57" must have the special characters URL-encoded to "a%25t56:rte%2A57". Note that the ":" is the separator between the username part and the password part and must not be converted as this is used as its special reserved separator meaning (if ":" was part of the password, for example, then this would need to be converted to "%3A")
Why this confusion occurs
One issue happens when one of these reserved characters with a special meaning is present in either the username or the password, so the characters ":" and "@": As we noted above, the format of these strings is username:password@domain.
If the username or the password also contains a reserved character, especially ":" and "@", the server cannot identify where the username stops and starts or where the domain name stops and starts. So for the format username:password@domain, for example:
Username is tok:l8@-84
Password is eljkHT@Hr!
This would make the chain contain the following:
tok:l8@-84:eljkHT@Hr!@example.com
However, due to control characters being used in the password, the server cannot determine where a username ends, where the password starts, and what the actual domain names are, given that there are now multiple control characters in the string.
What is the username: tok or tok:l8 or tok:l8@-84b?
What is the password: l8 or l8@-84 or l8@-84:eljkHT or l8@-84:eljkHT@Hr! or even no password?
What is the domain name: -84:eljkHT@Hr!@example.com or Hr!@example.com or example.com?
URL-encoding these reserved characters in the username and password will resolve these incoherencies and change the connection string to the more complex but technically unambiguous: tok%3Al8%40-84:eljkHT%40Hr%21@example.com
Final Notes
If connection problems persist even when using a URL-encoded username or password, try recreating the username and password strings with characters that do not require URL encoding.
If you use a file transfer client that requires you to enter the username and the password in separate fields, you do not need to recode these strings. This must only happen when using a single connection stream in the username:password@domain format, as used in the Engage automations or export pages.