SFTPPlus Documentation

4.9. Accounts

4.9.1. Introduction

SFTPPlus can be configured to allow both application and operating system accounts supplied by third party identity providers.

SFTPPlus specific / application / virtual accounts are defined inside the main configuration file.

Accounts for which the authentication is provided by the operating system can also be defined inside the main configure file to augment or overwrite the account configuration provided by the operating system. For example, you can authenticate an account using the operating system, but once authenticated use a different home folder, other than the one provided by the operating system.

Each account has a dedicated folder, called the home folder, which can be accessed using one of the available file transfer protocols.

Warning

For security reasons, by default, SFTPPlus will restrict access of each user to only the files and folders located inside the home folder.

4.9.2. Configuring administrators

Administrators are only dedicated to accessing the Local Manager. For documentation around configuring administrators, please go to the Administrators section.

4.9.3. Adding a new account via Local Manager

Accounts can be added or changed via Local Manager. Options will differ depending on which account type is used.

../_images/gallery-add-account.png

4.9.4. Adding a new account via text configuration

Accounts can be added or changed by editing the configuration file.

Configurations for each account are grouped inside an account section. A section name is prefixed by an accounts/ text followed by the account’s universally unique identifier (UUID), all surrounded by square brackets.

The account’s UUID can be any unique string used to identify the account. Once defined, the UUID should not be changed.

For more information about UUIDs, please see the dedicated UUID documentation.

The following example defines two accounts, one called john, which is an application type account, and another named anna, which is an account authenticated by the operating system:

[accounts/92ad5b32-d8d7-4ed8-94e1-dbb9f01383f4]
name = john
type = application
group = 9e3c5562-9b86-43da-a984-1d8751f2f060
enabled = Yes
password = some_password
home_folder_path = /path/to/john
permissions: read

[accounts/745fff10-4370-4d75-a172-21819046c76f]
name = anna
type = os
group = 01d2e30b-05f7-40c3-a86d-58744995970d
enabled = Yes
home_folder_path = /path/to/anna/files
permissions: inherit

Each configuration option available for an account or a group is explained in the following sections.

4.9.5. New accounts

Adding a new account is done by creating a new section inside the configuration file.

For example, to add a new account named mark:

[accounts/514e5b73-e9a4-46ce-a9c0-96c3d7eabf3b]
name = mark
enabled = Yes
type = application
group = fb40336d-8e5b-4275-950e-5f76fc387281
description = DESCRIPTION_OR_MORE_DETAILS
home_folder_path = /PATH/TO/USER/HOME
password = PASSWORD
permissions: read, write

4.9.6. Application accounts configuration

Application accounts are special accounts only available inside the SFTPPlus application.

All application accounts will be mapped inside the operating system to the operating system account configured using the server account configuration option.

If no group is defined for an application account, it will be attached to the DEFAULT_GROUP group.

Note

It is highly recommended to define an explicit group (other than the DEFAULT_GROUP) for each application account. This will make the configuration file much easier to understand by removing any implicit behaviour associated with an unspecified group.

4.9.7. Operating system accounts configuration

SFTPPlus allows operating system accounts to access their files once they are authenticated by providing a set of valid credentials.

The OS accounts are mapped to the authenticated OS user. The low level file access rights will be enforced by the operating system permissions based on the OS user and not the SFTPPlus service user.

When an operating system account creates new files or folders, the ownership for those files or folders will be set to that account.

The SFTPPlus

Note

On Windows, if an account is a member of the Administrators group, the owner will be set to the Administrators Group.

On Windows 2008, members of the Administrators group will always create new files owned by the Administrators group, and there is no option to configure this behaviour.

For operating system accounts, SFTPPlus will validate the user’s credentials against the operating system authentication mechanism.

An operating system account can be configured to use the same home folder as the one provided by the operating system. Or it can be configured to use a custom home folder, specific for file transfer operations.

The server allows the authentication of operating system accounts not defined in the configuration file. These accounts are associated with the DEFAULT_GROUP group, and the group’s properties are applied.

For Domain Controller accounts, the username must be provided in the user principal name (UPN) format: USERNAME@EXAMPLE.COM

4.9.8. Configuration options available to all account types

Most of the configuration options available for an account are optional. When a configuration option is not explicitly defined inside an account section, the default value for that option will be applied.

Some of the configuration options can also take the Inherit value. In this case, the value for this option will be defined based on the group configuration. More information about available group options can be found in the Groups configuration documentation.

Here are some examples:

[accounts/92ad5b32-d8d7-4ed8-94e1-dbb9f01383f4]
name = john
enabled = yes
type = application
group = ccac2941-261d-4797-af5f-b4fd1453bf59
password = john_s_password
home_folder_path = c:\Users\John\transfer_files
create_home_folder = yes
ssh_authorized_keys_path = c:\Users\John\authorized_keys

[accounts/514e5b73-e9a4-46ce-a9c0-96c3d7eabf3b]
name = mark
enabled = yes
type = os
group = 0a3f3aa7-50d2-44ef-9456-4f0beb69cf7d
home_folder_path = /home/mark/transfer_files
create_home_folder = Inherit
ssh_authorized_keys_path = /home/mark/.ssh/authorized_keys

[accounts/459245-7ea4-49ce-e4c0-98d3d7eabf3b]
name = mike
enabled = yes
type = application
group = ccac2941-261d-4797-af5f-b4fd1453bf59
home_folder_path = /home/mike/
ssh_authorized_keys_content = ssh-rsa AAAAB3NzaC1yc2EAAAADAQAB mike@comment

4.9.8.1. name

Default value:

‘’

Optional:

No

From version:

2.0.0

Values:
  • Any text.
Description:

Human-readable short string used to identify this account.

It is used as the login name in the authentication process.

4.9.8.2. enabled

Default value:

Yes

Optional:

Yes

From version:

1.6

Values:
  • Yes
  • No
Description:

This option specifies whether or not this account is enabled.

This option is overwritten by the group configuration option. If the group associated with this account is disabled, the account is also disabled, no matter what value is defined in the account’s configuration option. If a role has been disabled, the administrator associated with that role will still be enabled. However, it will show an authentication failed message when a login attempt is made.

4.9.8.3. type

Default value:

application

Optional:

Yes

From version:

1.6

Values:
  • application
  • os
Description:

This option specifies the type of the account.

  • Accounts of type application are defined entirely by the server
  • Accounts of type os are defined in the operating system, but some more attributes can be added when used in SFTPPlus.

4.9.8.4. group

Default value:

DEFAULT_GROUP

Optional:

No

From version:

1.8.2

Values:
  • UUID of the group associated with this account.
Description:

This option specifies the group to which this account is associated.

The value is the group’s UUID and not the group’s name. This allows renaming the group without having to update the configuration for all the accounts associated with the group.

4.9.8.5. description

Default value:

‘’

Optional:

Yes

From version:

1.7

Values:
  • Any character string.
Description:

This is a human-readable text that describes the entity using this account or the purpose of the account.

Example:

[accounts/92ad5b32-d8d7-4ed8-94e1-dbb9f01383f4]
name = john
description = Incoming files from John Doe as part of ACME Inc.

4.9.8.6. email

Default value:

‘’

Optional:

Yes

Available since:

3.43.0

Values:
  • Email address.
Description:

Email address associated with this account.

4.9.8.7. home_folder_path

Default value:

Inherit

Optional:

Yes

From version:

1.6

Values:
  • A path to a folder located in the operating system’s file system.
  • ${OS_HOME} - to use the home folder path provided by the operating system.
  • Inherit - to get the value from the associated group.
Description:

This option specifies the base path to the account’s home folder. The home folder is used as the initial folder for new connections.

When defined, it should be defined as an absolute path.

When this option is set to Inherit, the value defined for the account’s group will apply. For a better understanding, please follow the explanations and examples on proprieties inheritance.

Note

On Linux, OSX and other Unix systems the home folder path is case sensitive, to match the file system provided by the operating system.

Note

For domain accounts, the server cannot automatically create missing Windows home folders, also known as user profiles. Because of this, you cannot use ${OS_HOME} placeholder when configuring the home_folder_path for a domain account.

For domain accounts, a regular folder can be set as home_folder_path. The folder can be automatically created, just as for regular accounts.

4.9.8.8. ssh_authorized_keys_path

Default value:

Disabled

Optional:

Yes

From version:

1.7.0

Values:
  • Path to a file containing a list of allowed SSH keys.
  • ${USER} can be used as a placeholder for the username, and it is replaced in the file path.
  • Disabled
  • Inherit
  • Empty
Description:

This option specifies whether or not the server will permit access using a list of public SSH keys retrieved from the specified file.

More details about SSH key authentication can be found in the dedicated section.

To disable reading SSH public keys from local files, leave it empty or set to Disabled.

This feature is not available in Windows for local or domain accounts. Use application accounts for implementing SSH key-based authentication on Windows.

When this option is set to Inherit, the value defined for the account’s group will apply. For a better understanding, please follow the explanations and examples on proprieties inheritance.

In the Local Manager GUI, ${USER} must be in the file path, otherwise it is appended at the end.

4.9.8.9. ssh_authorized_keys_content

Default value:

Disabled

Optional:

Yes

From version:

2.9.0

Values:
  • SSH public key line in OpenSSH public key format.
  • Empty
  • Disabled
Description:

This option specifies the list of valid SSH public keys for this account.

To disable reading SSH public keys from this configuration option, leave it empty or set it to Disabled.

You can configure multiple public keys in the following way:

[accounts/92ad5b32-d8d7-4ed8-94e1-dbb9f01383f4]
ssh_authorized_keys_content =
    ssh-rsa KEY_CONTENT_1 user1@comment
    ssh-dsa KEY_CONTENT_2 user2@comment

Warning

Public keys must be configured, one key per line and in OpenSSH format.

4.9.8.10. source_ip_filter

Default value:

Inherit

Optional:

Yes

From version:

3.45.0

Values:
  • IPv4 address
  • IPv6 address
  • Comma-separated list of IPv4 or IPv6 addressed.
  • Inherit
  • Empty
Description:

This option defines the source IP addresses (v4 or v6) from which file transfer clients are allowed to authenticate.

You can configure a single source IP for which to allow authentication for this account.

To allow authentication from multiple source IPs, define them as a comma-separated list.

Set it to Inherit to use the configuration defined for the group associated with this account.

Leave it empty to allow this account to be authenticated from any source IP address.

Note

Host names or FQDN are not supported. IP classes are not supported. Only IP addresses are supported.

4.9.8.11. allow_certificate_authentication

Default value:

Yes

Optional:

Yes

From version:

1.8.1

Values:
  • Yes
  • No
  • Inherit
Description:

Allow this account to authenticate using SSL certificates.

Certificates need to be issued using the same Common Name field (CN) as the account name.

If SSL certificate-based authentication is not enabled, accounts will have to use other means of authentication.

When this option is set to Inherit, the value defined for the account’s group will apply.

4.9.8.12. permissions

Default value:

allow-full-control

Optional:

Yes

From version:

3.28.0

Values:
  • Comma separated list of permissions
  • Inherit
Description:

This allows access rights to be defined in the file management operations permitted for this account.

When this option is set to Inherit, the value defined for the account’s group will apply. Any other value directly configured is ignored.

For more details see the permission documentation described for the group.

4.9.8.13. expire_datetime

Default value:

None

Optional:

Yes

From version:

3.27.0

Values:
  • ISO 8601 date
  • ISO 8601 combined date and time
  • ISO 8601 combined date, time, and timezone
Description:

This defines the date and time after which the account will no longer be authorized.

By default, this is an empty value which will cause the account to never expire.

Date and time are defined in ISO 8601 format for combined date and time. Beside the standard format YYYY-MM-DD HH:MM:SSZ in UTC, it supports a few relaxed formats like:

  • YYYY-MM-DD
  • YYYY-MM-DD HH:MM:SS
  • YYYY-MM-DD HH:MM:SS+hh
  • YYYY-MM-DD HH:MM:SS+hh:mm

When no timezone is defined, it will use the local timezone.

When no hour is defined, it will assume the time as 00:00:00 (midnight). When no minute or seconds are defined, it will assume them as 00.

When a date is defined, it needs to have the full year, month and day.

4.9.8.14. amend_write_name

Default value:

Disabled

Optional:

Yes

From version:

3.30.0

Values:
  • uuid-prefix
  • Inherit
  • Disabled
Description:

This configurations adds the option to transparently amend the file name used during a file write request (write new file or append).

Set it to uuid-prefix to have an UUID version 4 prefixed to the file name.

Remote clients are unaware of the file name being changed. They will make a request to upload a file with name /parent/REPORT.CSV and in the background, the SFTPPlus server will store it on disk as /parent/f1efde05-9b54-4fd7-a6cb-9fffc62cc631-REPORT.CSV.

When this is enabled, the write request will prevent any overwriting actions. If a file with the randomly generated name already exists, the write request will fail.

When this is enabled, any request to write the file in any way (write new file, append, or write updates) will result in a new file being creating and the specific write request to be ignored.

When this option is set to Inherit, the value defined for the account’s group will apply.

Set it to disabled to not amend the file names for the upload requests.

4.9.8.15. create_home_folder

Default value:

No

Optional:

Yes

From version:

1.6.0

Values:
  • Yes
  • No
  • Inherit
Description:

This option specifies whether or not the server should create the home folder for an account, in the case that it is missing.

If this option is set to No, the server will not allow users for which the home folder is not already created. When set to Yes, the server will try to create missing home folders for users that are successfully authenticated.

For application accounts, new home folders are created using the same account under which the server is executed. They will be owned by the server’s service account.

For operating system accounts, the home folders are owned by the associated OS accounts. On Windows, they are created by the OS together with the associated Windows Profile. On Unix, they are created by the root account, and the permissions are changed to the associated OS account.

Warning

On Windows operating systems, for domain accounts for which home_folder_path is defined as ${OS_HOME}, the server will not be able to create a missing home folder. The server will still be able to create missing home folder when using custom home folder paths.

4.9.9. Configuration options available to application accounts

Some configuration options are only available for application accounts.

4.9.9.1. password

Default value:

Disabled

Optional:

Yes

From version:

1.6.0

Values:
  • Plain text password.
  • Encrypted password using a one-way cryptographic hash function.
  • Disabled or empty field to disable the password.
Description:

This option specifies the password used for authenticating this account.

It can be stored as a plain text password or as an encrypted password using the cryptographic hash function SHA-256.

In order to make use of the secure hash algorithm, please check how to generate encrypted passwords using admin-commands.

When the password is set to Disabled or left blank, the account will not be able to authenticate, even if the enabled option is set to yes.

Note

The password is ignored for accounts of type os.

Note

When FTPS SSL certificate-based authentication or key-based SFTP / SSH authentication are enabled, the password value can be set to Disabled.

Warning

When using plain text passwords, make sure only authorized users have read access to the configuration file. It is important to change the permission for the configuration file to allow read and write access only for the account under which the server is running.

4.9.9.2. password_lifetime

Default value:

inherit

Optional:

Yes

From version:

3.46.0

Values:
  • Number of days.
  • Inherit
Description:

Number of days for which a password is valid.

Once a new password is set, it is valid for the configured number of days.

If the password is not changed for the configured number of days, the account is automatically disabled. To re-enable it, a new password needs to be set by an administrator.

Note

To allow users to change their own passwords, make sure allow_own_password_change is enabled in the associated group.

4.9.9.3. last_password_update

Default value:

0

Optional:

Yes

From version:

3.46.0

Values:
  • Unix timestamp
Description:

Unix timestamp for the time of the last password change.

Note

This value is automatically updated by SFTPPlus together with the main password value. You should only need to set this value when password expiration is enabled and password is set via an external process.

4.9.10. Configuration options available to operating system accounts

A few configuration options are only available for operating system accounts.

4.9.10.1. lock_in_home_folder

Default value:

Yes

Optional:

Yes

From version:

1.6

Values:
  • Yes
  • No
  • Inherit
Description:

Specify whether to restrict file system access to the account’s home folder. When accounts are locked inside the home folder, access to files and folders outside the home folder path will be denied, and the home folder path will be the root of the available file system.

4.9.10.2. create_home_folder_owner

Default value:

${DEFAULT_OS_USER}

Optional:

Yes

From version:

1.6.0

Values:
  • Name of an account defined inside the operating system.
  • ${DEFAULT_OS_USER}
  • Inherit
Description:

When the server is configured to automatically create missing home folders, this option specifies who should be the owner of the newly created folder.

When this option is set to ${DEFAULT_OS_USER}, the folder owner will be set to the default value specified by the operating system.

When this option is set to Inherit, the value defined for the account’s group will apply.

4.9.10.3. create_home_folder_group

Default value:

${DEFAULT_OS_GROUP}

Optional:

Yes

From version:

1.6.0

Values:
  • Name of a group defined by the operating system.
  • ${DEFAULT_OS_GROUP}
  • Inherit
Description:

When the server is configured to automatically create missing home folders, this option specifies what group should be associated with the newly created folder.

When this option is set to ${DEFAULT_OS_GROUP}, the folder group will be set to the default value specified by the operating system.

Note

On Windows operating system, ${DEFAULT_OS_GROUP} is defined as the Users group. Please contact us in the case that you need different behaviour.

When this option is set to Inherit, the value defined for the account’s group will apply.