SFTPPlus Documentation

Start Page 5. Server-side Usage Instructions 5.7. HTTP / HTTPS Service

5.7. HTTP / HTTPS Service

5.7.1. Introduction

This page contains information on the usage and behaviour of the http and https file transfer services.

The HTTP / HTTPS file transfer service provides a HTML-based interface designed to work in any web browser, including older versions of browsers where JavaScript or cookie features are either not supported or enabled.

The HTTP protocol is implemented based on RFC 2616, while the HTTPS protocol is based on RFC 2818.

The Local Manager GUI provides configuration options and status indications to the state of the http or https service:

../_images/http-https-enabled.png

5.7.1.1. More resources about the HTTP / HTTPS service

For more details about the configuration options, please go to the dedicated HTTP/HTTPS configuration page.

For those interested in working with the HTTP Service JSON-based API, please refer to our Developer Documentation.

5.7.2. File management functionality

../_images/http-service.png

Above is a screenshot of the HTTP / HTTPS file management functionality.


../_images/http-invalid-folder-structure.png

Above is a screenshot of how errors are communicated - in this case, when an invalid folder is being created.


The HTTP and HTTPS service allows the same level of file access as the other available file transfer services such as FTPS or SFTP.

When using the file transfer service in a browser without JavaScript or cookies, some of the advanced features are not available.

Basic features, listed below, are supported:

  • Authenticate using HTTP Basic Auth method
  • Navigate folders’ structure
  • Download files
  • Create new folders
  • Upload files
  • Delete files and folders
  • Recursive deletion of a folder

5.7.3. Custom Appearance

The appearance of the HTTP service pages can be customized by overwriting the default CSS of the HTTP service pages and executing custom JavaScript code.

Using the theme_path configuration option you can instruct SFTPPlus to load a custom theme for the HTTP pages.

The theme path should contain at least the main.css and main.js files.

If you don’t need to customize the CSS or JavaScript leave the file empty.

The main.css file from the theme path is loaded as the last CSS file. The main.jss file from the theme path is loaded at the end of the page as the last JavaScript file.

The theme files are accessible inside the HTTP service as /__chsps__/theme/.

To load the theme files from C:\FTP-Service\Theme you need to configure the service as:

[services/9ac4-1054-f0e4]
name = HTTPS File Transfer Service
type = http

theme_path = C:\File-Server\Theme

For example C:\FTP-Service\Theme\main.css can insert the company name in the top navigation bar, and C:\FTP-Service\Theme\main.js can be empty:

.navbar-fixed-top:after {
    content: "ACME File Transfer Server";
    }

.navbar-inner {
    min-height: 60px;
    }

5.7.4. Custom trigger buttons

Using the triggers configuration of the HTTP and HTTPS file transfer service, you can define one or multiple custom buttons which are displayed on the web client page.

When defining the action name for a trigger, make sure you don’t use common operation names like delete, create-folder, upload-file, which will conflict with the existing file operations.

When pressed, these buttons will emit the event with ID 40043, event which can be linked to an event handler to trigger one or more actions on the selected files.

The following types are available:
  • primary (dark blue)
  • info (light blue)
  • success (green)
  • warning (amber)
  • danger (dark red)
  • inverse (black)

You can define custom button types, by creating btn-TYPE_NAME CSS classes inside the custom CSS file defined via theme_path.

The buttons can be displayed for all users, or only for the members of a specific group.

When no group configuration is defined, the button is displayed for members of all groups.

If you want a button to be visible to members of multiple groups, create separate trigger definition for each group.

Below is an example of 4 buttons which will be displayed under the following conditions.

Approve is a green button available only to members of the supervisor group.

Reject is an amber button available to members of the supervisor group and the users group.

Cancel is a light-blue button available only to members of the users groups.

Report button is a red button displayed for any user.

[services/9ac4-1054-f0e4] name = HTTPS File Transfer Service type = http

triggers:
Approve, success, SUPERVISORS_GROUPS_UUID Reject, warning, SUPERVISORS_GROUPS_UUID Reject, warning, USERS_GROUPS_UUID Cancel, info, USERS_GROUPS_UUID Raise incident, danger
../_images/http-service-custom-buttons.png

5.7.5. Load Balancer

The HTTP/HTTPS services of SFTPPlus can be integrated in a load balancing solution.

SFTPPlus requires no extra configuration when functioning behind a layer 4 TCP balancer or DNS load balancer.

AWS Network Load Balancer and Azure Load Balancer are examples of layer 4 load balancers.

For Layer 4 load balancers, make sure the forwarded traffic has a persistent session based on the client’s source IP address.

When using a layer 7 HTTP/HTTPS load balancer, you will need to adjust Cross-Site Request Forgery (CSRF) protection. This is because the HTTP load balancer is not updating some of the headers found in the initial request when forwarding a request to the load balanced node. This result in a request that appears to be coming from a different site.

AWS Application Load Balancer and Azure Application Gateway are examples of Layer 7 load balancers.

For HTTP / Layer 7 load balancers, make sure the forwarded traffic has sticky sessions enabled.

When the HTTP/HTTP file transfer service is not configured for the load balancer, you will see 400 Possible CSRF errors.

When the load balancer is configured with the listeners https://files.example.com on default port 443 and https://www.example.com on port 10443, and it forwards all requests to SFTPPlus at http://worker1.example.com, you will need to configure SFTPPlus as follows:

[services/9ac4-1054-f0e4]
name = HTTPS File Transfer Service
type = http
address = worker1.example.com
port = 18080

accepted_origins = files.example.com, www.example.com:10443

5.7.6. AS2 receive site

SFTPPlus can receive files using the EDIINT AS2 protocol defined in the RFC 4130 <https://tools.ietf.org/html/rfc4130> standard.

If you want to send files over AS2, you need to use an HTTP AS2 transfer as documented on the HTTP AS2 transfer page.

Received content can be confirmed using the message disposition acknowledgment (MDN) method defined in RFC 3798 <https://tools.ietf.org/html/rfc3798>.

File content can be compressed as defined in RFC 5402 <https://tools.ietf.org/html/rfc5402>, encapsulated in a CMS (Cryptographic Message Syntax) MIME entity.

We recommend setting up the message exchange with your AS2 partner using username and password or username and SSL certificate credentials authentication.

For HTTP authenticated requsts, SFTPPlus uses the username found in the AS2 HTTP authentication request to recognize and authorize an AS2 partner. In this case, the AS2-From value found in an AS2 message is only informative, but it is required in all messages by the AS2 standard.

You add an AS2 partner by creating a normal SFTPPlus file transfer account.

The files from the AS2 messages are stored in the home path as configured for each user, in a sub-directory defined by the as2_receive_path configuration.

Files received via AS2 will have to comply with the general security policy and permissions, similar to any other file transfer protocol.

The public AS2 site is available at the https://example.tld/as2receive URL, where the as2receive URL fragment is defined by the as2_receive_name configuration option:

[services/9ac4-1054-f0e4]
name = HTTPS with AS2 File Transfer Service
type = https

as2_organization = ACME Org
as2_receive_name = as2receive
as2_receive_path = /as2/receive
as2_receive_key = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    MORE RSA KEY CONTENT
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----
as2_receive_certificate = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    MORE CERTIFICATE CONTENT
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

[accounts/4a48fbf4-d029]
name = johnd
home_folder_path = C:/Users/JohnD
; One or more certificates used by the remote partner to sign the
; received files.
as2_certificates = -----BEGIN CERTIFICATE-----
    MIICpTCCAg6gAwIBAgIIP8vt0MYYvNIwDQYJKoZIhvcNAQELBQAwRjELMAkGA1UE
    MORE CERTIFICATE CONTENT
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    MIICoDCCAgmgAwIBAgIIKk0/vqmeDb4wDQYJKoZIhvcNAQELBQAwODELMAkGA1UE
    MORE CERTIFICATE CONTENT
    6sXcntbQ8jyu8fNCjoVKGUe9gsgZOK2KapWxU7HzvulVQslcOcWG3mM=
    -----END CERTIFICATE-----

[accounts/758185de-d029]
name = janer
home_folder_path = C:/Users/JaneR
permissions:
    allow-full-control
    *.exe, deny-full-control

With the above configuration, files received via AS2 for account johnd are stored inside C:/Users/JohnD/as2/receive and files for account janer are stored inside C:/Users/JaneR/as2/receive.

At the same time, any file with the name ending with .exe uploaded by account janer is rejected.

Note

Encrypted received messages should be encrypted using an RSA key. DSA public key based encryption is not supported. Contact us if you need to encrypt AS2 messages using DSA.

Non-authenticated AS2 messages are supported and the account name will match the value of the AS2-From HTTP header. You need to explicitly configure an account to not require HTTP authentication for AS2 messages.

Below is an example in which the configuration will allow a partner with ID AS2 Trade aMjV9XxNTFO to send AS2 messages without HTTP authentication. It is highly recommend to restrict the source IP for this account, as without HTTP authentication anyone can send messages for this account, just by knowing the name of the trading partner:

[accounts/4a48fbf4-d029]
    name = AS2 Trade aMjV9XxNTFO
home_folder_path = C:/Users/JohnD

as2_require_http_authentication = No
source_ip_filter = 24.12.231.23

When filtering by source IP is not possible and your requirement is to receive AS2 messages without authentication, we recommend to add a long and hard to guess value for your trading partner. This is why the above example uses the aMjV9XxNTFO value in the AS2 Trade aMjV9XxNTFO partner name.

When signed files are received, SFTPPlus will validate the configuration using the public certificate configured in the as2_certificates option in the user account.

When encrypted files are received, SFTPPlus will decrypt them using the RSA private key defined at as2_receive_key or as2_receive_certificate.

When signed message disposition notifications (MDN) are requested, SFTPPlus will sign them using the private key configured at as2_private_key and the certificate configured at as2_receive_certificate.

The delivery for asynchronous(ASYNC) MDN is retried 5 times, waiting 1 minutes for the first retry, they 2 minutes, and waiting 1 minute more with each retry.

The async MDN HTTPS request is made using the same TLS methods and ciphers configured for the HTTPS service over which the initial AS2 message was received.

When the remote partner is requesting an async MDN over HTTPS, the remote HTTPS connection is authenticated using the HTTPS SSL/TLS certificates configured for the associated account as part of the as2_async_mdn_ca configuration.

Our recommendation is to set up file transfers with your AS2 partner using synchronous MDN. This simplify the network configuration and provides improved security.

You can disable the support for async MDN by setting the as2_async_mdn_ca to the empty value.

Asynchronous MDN response delivery errors will emit a dedicated failure event.

No extra event is emitted on the successful delivery of synchronous or asynchronous MDNs, other than the general event for the successful receiving of the AS2 message.

5.7.7. Public site

SFTPPlus can serve as a public file transfer server. Visitors can access files on the server without prior authentication. This is similar to the Anonymous mode available in the FTP server, with the exception that no username is required.

To enable public access, you need to explicitly define an application account to be used for handling the files via the public interface.

The account will define the path from where the public files are served and the permissions used for each file.

The public site is not limited to read-only access. Visitors of the public site will have the same access as defined in the public account configuration.

The public file access is recorded in the audit log under the configured account. It is recommended to set up a dedicated account for the public access and not to reuse an existing account.

Below is an example for a general download-only public root access, which will deny downloading any .exe. file and allow uploading files inside the /reports/ folder.

The public files will be available at the following URL: https://example.tld/public-access.

In this example, public access will no longer be available after the 23rd of March 2025, when the public account is set to expire.:

[services/9ac4-1054-f0e4]
name = HTTPS File Transfer Service
type = https

public_account_uuid = 92ad5b32-d8d7-4ed8-94e1-dbb9f01383f4
public_name = public-access

[accounts/92ad5b32-d8d7-4ed8-94e1-dbb9f01383f4]
name = public-http
type = application
description = Files available without password over HTTP.
group = 95373161-b944-4d70-af5e-cab1976cc535

home_folder_path = /local/path/to/public/files
permissions:
    allow-read, allow-list
    *.exe, deny-full-control
    /reports/, allow-write

expire_datetime: 2025-03-23

[groups/95373161-b944-4d70-af5e-cab1976cc535]
name = http-group
virtual_folders: /shared, /ftp-files/shared

The create_home_folder and home_folder_structure account and group configurations are ignored for the public HTTP access.

5.7.8. Authentication Process

The HTTP file transfer service will use a single cookie to manage the authentication process.

A single session cookie is used for all the file transfer operations.

The session cookie is set with httpOnly and sameSite options. For the HTTPS service, cookies are set with the secure option.

For simple usage via the command line with tools like as cURL or Wget, HTTP Basic Auth is available.

Warning

HTTP Basic Auth will send credentials in a plain text encoding and it is not recommended to use HTTP Basic Auth over unsecured HTTP connections.

5.7.9. Usage Without Cookies

While we recommend using the HTTP file transfer server from a browser which allows cookies, SFTPPlus can be used without cookies.

The lack of availability of HTTP cookies will not affect the HTTP service server-side functionalities.

To trigger the authentication process you will need to access the file transfer service using the following URL:

https://SERVER:PORT/home/?without-cookies

When HTTP cookies are not available, the authentication in a web browser is done via HTTP Basic Auth. The logout functionality is not available without cookies.

Warning

HTTP Basic Auth will send credentials in a plain text encoding and it is not recommended to use HTTP Basic Auth over unsecured HTTP connections.

5.7.10. HTTP/1.1 100 Continue Status Code

HTTP/HTTPS file transfer service can handle HTTP/1.1 client requests made using the 100 (Continue) status. This allows the client sending the request message with a given request body to determine whether the origin server is willing to accept the request (based on the request headers) before the client sends the request body.

For example, it might be inappropriate or highly inefficient for the client to send a large body if the server rejects it solely based on the body size.