11.2.1. Introduction¶

The server-side security of SFTPPlus is designed based on the Authentication, Authorization and Accounting (AAA) components.

This pages focuses on the Authorization component. For the Authentication part, check the authentication documentation while for the Accounting, check the account documentation.

Once an account is authorized as part of the login procedure of each file transfer service, SFTPPlus will receive the configuration for that account.

As part of the account's configuration, the permissions option is dedicated to defining access rights to files and folders.

The permissions are applied to all of the files and folders that are available in that account.

11.2.2. Effective Permissions¶

In SFTPPlus, permissions are defined based on paths, and are not attached to actual files or directories. Permissions are applied based on a path-matching expression.

One advantage of this method is that you can define permissions for files and folders not created yet.

Another advantage against traditional file system permissions is that, for example, it's easy to set different permissions based on file extension.

Different permissions can be applied for different files and folders available to an account.

The path used for selecting permissions is the virtual path. That is the path as it is visible to the file transfer client, and not the actual full path on the server storage.

11.2.3. Combined Permissions and Precedence¶

When establishing permissions, you need to specify whether an operation should be accepted (allow) or rejected (not allow / deny) for the targeted path.

An account can have multiple permissions.

In this case, an operation permission is granted if it is permitted by at least one of the configured permissions.

For example, to allow reading and writing files and to disallow creating or deleting folders, you can set the permissions as:

[accounts/202da724-a73d-4590-abfb-0717cded0d86]
permissions = allow-read, allow-write

"Deny" permissions take precedence over "allow" permissions. If you set allow-read, deny-full-control, the effective permission would be deny-full-control, and read access would be denied.. The implicit deny-read implied by deny-full-control takes precedence over the explicit allow-read configuration.

11.2.4. Global and Per-Path Permissions¶

In the example below the account johnd has its home folder in c:\Users\johnd\ftp-files and access is locked (chrooted, jailed) in that folder. File transfer client will see that folder as their root folder. The /inbox/* path matching expression will apply to the files and folders from c:\Users\johnd\ftp-files\inbox\

[accounts/202da724-a73d-4590-abfb-0717cded0d86]
enabled = True
type = application
name = johnd
home_folder_path = c:\Users\johnd\ftp-files
permissions =
    allow-read
    /inbox/*, allow-full-control

The first set of permissions are called global permissions and they apply to any path for which there is no explicit configuration.

The permission rules are checked from the first to the last configuration, in the order that is added in the configuration file. As soon as a path matches an expression, it will apply the permissions associated to that expression and continue on with the check until the process is finished. Global permissions are applied when it is found that no expression has matched the path.

The configuration below shows an account which has read control to any file. Regardless of its location, it can read or write CSV files. It has full control permissions to any files or folders inside the /inbox/ folder. It can delete / create files and folders inside inbox which is located in the root of the banse folder. Note that the rule for CSV files has both allow-read and allow-write permission since a path specific rule will replace the defined global permissions:

[accounts/202da724-a73d-4590-abfb-0717cded0d86]
permissions =
    allow-read
    /inbox/*, allow-full-control
    *.csv, allow-read, allow-write

For the configuration example below, the account will only have write access to CSV files located outside of the /inbox/ folder. For the /inbox/ folder, it still has full control:

[accounts/202da724-a73d-4590-abfb-0717cded0d86]
permissions =
    allow-read
    /inbox/*, allow-full-control
    *.csv, allow-write

The order in which the rules are defined is important. A good practice is to define them starting with the most specific and ending with the most generic. In the configuration example defined below, the account does not have the the right the delete CSV files located in the /inbox/ folder. This is because the rule for inbox is defined after the generic rule for CSV files:

[accounts/202da724-a73d-4590-abfb-0717cded0d86]
permissions =
    allow-read
    *.csv, allow-write
    /inbox/*, allow-full-control

The previous examples were all using the simple globbing rules. For complex path matching expressions, you can use regular expressions. For example, to give allow-write access to files prefixed by a number, you can use:

[accounts/202da724-a73d-4590-abfb-0717cded0d86]
permissions =
    allow-read
    m/\d+-.*/, allow-write

Regular expressions can also be used to negate an expression. The configuration example below allows allow-read permission to any file, while granting allow-write permissions for PDF files:

[accounts/202da724-a73d-4590-abfb-0717cded0d86]
permissions =
    allow-write
    e/.*\.pdf/, allow-read

The path matching expression will only take into consideration the path regardless of whether the path points to a file or a folder. For example, the configuration example below will allow full control to any file or folder inside /inbox/, but the /inbox folder itself will have the allow-read permission since it does not match the /inbox/* expression:

[accounts/202da724-a73d-4590-abfb-0717cded0d86]
permissions =
    allow-read
    /inbox/*, allow-full-control

For more details about the available expressions, see the matching expression documentation.

11.2.5. Permissions for dynamic username-based paths¶

When configuring the permissions of a group, you can target paths that include the name of the authenticated user.

In the below example, when the account JohnD is authenticated, it gets full access to the path /queue/JohnD/pending. Note that the ${USER} placeholder can be used anywhere in the path's name:

[groups/202da724-a73d-4590-abfb-0717cded0d86]
permissions =
    allow-list, allow-write
    /inbox/*, allow-read
    /queue/${USER}/pending*, allow-full-control

11.2.6. Folders and their members¶

As permissions are based on the path, there are a few caveats that you should be aware of.

In the following examples you will get allow-full-control for folder /inbox/ and for any path inside it, like /inbox/test.text or /inbox/sub/folder/file.txt. In the same time, you also get allow-full control for a folder named /inbox-qa/, as this path is matching the /inbox* expression:

[accounts/202da724-a73d-4590-abfb-0717cded0d86]
permissions =
    allow-read
    /inbox*, allow-full-control

When you want to limit permissions for a specific folder and any of its subfolders, the configuration should be defined as the example below. In this case, a path like /inbox-qa/ will only get allow-read:

[accounts/202da724-a73d-4590-abfb-0717cded0d86]
permissions =
    allow-read
    /inbox, allow-full-control
    /inbox/*, allow-full-control

11.2.7. allow-full-control Permission¶

When an account is set with allow-full-control permissions, it can perform any file transfer operation.

All extra permissions are ignored.

11.2.8. deny-full-control Permission¶

When an account is set with deny-full-control permissions, it can't perform any file transfer operation.

All extra permissions are ignored, and any action is denied.

11.2.9. allow-read Permission¶

With the allow-read permission, an account can obtain the attributes and read the contents of existing files.

It cannot set attributes, read the target of symbolic links, list folders or delete or rename files or folders.

11.2.10. allow-list Permission¶

The allow-list permission allows an account to list the contents of a folder and get the attributes for the files in that folder.

It also allows reading the target of symbolic links.

All other operations are denied. For example, it cannot set attributes, delete or rename files or folders in the targeted folder.

11.2.11. allow-traverse Permission¶

The allow-traverse permission allows an account to only see the folders during a normal listing operations.

It behaves like the allow-list permission, but non-folder members are hidden.

The FTP NLST command is not allowed under this permission. NLST is only allowed with allow-list. Please get in touch if you need allow-traverse to allow the FTP NLST command.

All other operations are denied. For example, it will not allow getting the attributes for files.

11.2.12. allow-create-folder Permission¶

With the allow-create-folder permission, an account can create new folders.

All other operations are denied. For example, this permission does not allow creating files or renaming folders.

11.2.13. allow-write Permission¶

With the allow-write permission, an account can create new files, overwrite or append the content of existing files.

All other operations are denied. For example, this permission does not allow reading files or listing folders.

11.2.14. allow-rename Permission¶

Using the allow-rename permission, an account can rename existing files.

The rename operation allows overwriting existing files as part of the rename process.

The allow-rename permission needs to be set for both source and destination. Otherwise, either the source or destination path will require full permissions.

11.2.15. allow-delete-file Permission¶

With the allow-delete-file permission, an account can delete existing files.

All other operations are denied. For example, this permission does not allow deleting folders or writing to existing files.

11.2.16. allow-delete-folder Permission¶

With the allow-delete-folder permission, an account can delete existing folders.

All other operations are denied. For example, this permission does not allow deleting files or renaming existing folders.

11.2.17. allow-set-attributes Permission¶

With the allow-set-attributes permission, an account can set the attributes of existing files and folders.

All other operations are denied. For example, this permission does not allow writing to existing files or creating folders.