9.6.1. Introduction¶

Simple BIND operation is used for authenticating an account against the LDAP server in order to validate the credentials received from a file transfer client session.

When an authentication request is made for a transfer client session, SFTPPlus will use the provided credentials (username and password) and forward them to the configured LDAP server for validation.

Successfully authenticated accounts are associated to the default group, or to a specific group based on the group_mapping configuration.

9.6.2. name¶

Default value:

''

Optional:

Yes

From version:

2.10.0

Values:

• Any text.

Description:

Human-readable short text used to identify this method.

9.6.3. description¶

Default value:

''

Optional:

Yes

From version:

2.10.0

Values:

• Any text.

Description:

Human-readable text that describes the purpose of this authentication method.

9.6.4. type¶

Default value:

''

Optional:

No

From version:

2.10.0

Values:

• application - Application accounts.

• os - Accounts authenticated by the OS.

• http - HTTP (unsecured).

• ip-time-ban - Ban an IP address for a time interval.

• deny-username - Deny authentication based on usernames.

• anonymous - Anonymous account authentication.

• ldap - Authenticate against an LDAP server.

• local-file - Authenticate the accounts from a separate local file.

• radius - Authenticate via an RADIUS server.

• entra-id - Microsoft Entra ID

Description:

This option specifies the type of the method. Each type has a set of specific configuration options

9.6.5. address¶

Default value:

''

Optional:

No

Values:

• Host name.

• Fully qualified domain name resolving an IPv4 address.

• IPv4 address.

• IPv6 address.

From version:

3.13.0

Description:

Host name, domain name or IP address used to connect to the remote LDAP server.

9.6.6. port¶

Default value:

389

Optional:

Yes

Values:

• Port number.

From version:

3.13.0

Description:

Port number used by the remote LDAP server to receive client connections.

9.6.7. secure_connection¶

Default value:

No

Optional:

Yes

Values:

• Yes

• No

From version:

4.11.0

Description:

When set to yes the connection to the LDAP server will be protected by a TLS security wrapper. This will enabled LDAP over TLS/SSL communication method, also called LDAPS.

Warning

Without the ssl_certificate_authority configuration, the LDAPS connect will use TLS, but the identity of the remote server will not be validated. Use ssl_certificate_authority to define the certificate authorities allowed to issue a certificate for the remote server.

9.6.8. bind_dn_type¶

Default value:

parent

Optional:

No

Values:

• parent

• relative

• absolute

• direct-username

From version:

3.20.0

Description:

This field defines the method utilized to construct the LDAP DN that is administered for the LDAP authentication (BIND) request.

With bind_dn_type set to parent (or the 'Username generated from Bind DN` option in the Web Manager GUI), a distinguished name applied for the bind (authentication) operation is generated using the following method: cn=USERNAME,BIND_DN_VALUE.

Under this method, there is no need for file transfer users to consider the LDAP structure when providing the username. They can authenticate based on the usual username.

For example, if bind_dn is defined as ou=det,dc=example,dc=com and an authentication is requested for username John, the LDAP authentication (bind) operation is set for DN as: cn=John,ou=det,dc=example,dc=com.

With bind_dn_type set to absolute (or 'Absolute DN' option in the Web Manager GUI), the value from bind_dn is ignored.

When set to absolute, the end users will need to specify the full DN as part of the username.

When bind_dn_type is set to relative (or 'Append to bind DN' option in the Web Manager GUI), the provided username will be used together with the value configured for bind_dn to construct the final DN administered for the LDAP authentication operation.

With bind_dn_type set to direct-username, the username provided as part of the file transfer authentication process will be directly used for the LDAP BIND operation. Once authenticated, SFTPPlus will use the username_attribute to get the full DN associated with this username in order to obtain the configuration for the authenticated account.

9.6.9. bind_dn¶

Default value:

''

Optional:

No

Values:

• Base distinguished name.

• Multiple base DNs, one per line (Since 4.16.0)

From version:

3.13.0

Description:

Base DN used to generate the distinguished name associated with the account which needs to be authenticated.

The exact way in which the bind_dn is constructed will depend on the bind_dn_type configuration.

For more details, consult the documentation for bind_dn_type.

When bind_dn_type is set to direct-username, this is used as the base DN of the Active Directory group to which access is permitted.

Multiple base DNs can be defined, one per line. This can be used for authenticating account from multiple organizations inside the same LDAP tree or for a multi-tree / forest LDAP deployment. They will be checked from top to bottom and the authentication will succeed on the first base DN in which the account is found.

This is ignored when bind_dn_type is set to absolute.

9.6.10. username_attribute¶

Default value:

cn

Optional:

Yes

Values:

• Attribute name.

• Attribute name, @FQDN.DOMAIN.COM

From version:

3.17.0

Description:

The attribute name that LDAP uses to create the DN for performing the LDAP BIND (authentication) operation.

It is also used to create the DN from which the user configuration is retrieved.

Together with bind_dn, this is used to configure the full DN used for a specific username.

As an example, if bind_dn is defined as dc=example,dc=com, username_attribute is defined as uid, and the authentication is requested for username John, the LDAP authentication (bind) operation is set for DN as: uid=John,dc=example,dc=com.

When bind_dn_type is direct-username, this attribute is used to search the LDAP directory and retrieve the DN of the authenticated account.

Note

This option is ignored when bind_dn_type has any value other than parent or direct-username.

9.6.11. username_suffix¶

Default value:

Empty

Optional:

Yes

Values:

• Empty

• @FQDN.DOMAIN.COM

From version:

4.1.0

Description:

When bind_dn_type = direct-username you can use this configuration to define a default domain that is appended to the name of each use.

In this way, the file transfer users can login with just the username, and SFTPPlus will use the full UPN for the Active Directory authentication request.

The domain name should include the @ character. For example: username_suffix = @ad.example.com.

9.6.12. home_folder_attribute¶

Default value:

homeDirectory

Optional:

Yes

Values:

• Attribute name.

• Attribute name, home path template

• Empty value.

From version:

3.13.0

Description:

Name of the attribute used to retrieve the home folder path for the account which is authenticated.

When the LDAP entry associated with the authenticated account has no such attribute or the attribute's value is empty the authentication will fail.

Leave it empty to not retrieve the home folder path from the LDAP entry, but rather inherit the value from the associated group.

You can create the home folder path by combining a configurable template and the value stored in the LDAP attribute. For example to reuse the Internet Information Service (MS IIS) user path, you can use:

home_folder_attribute: msIIS-FTPDir, E:\SFTP-Files\{msIIS_FTPDir}

9.6.13. email_attribute¶

Default value:

empty

Optional:

Yes

Values:

• Attribute name.

• Empty value.

From version:

5.1.0

Description:

Name of the attribute used to retrieve the email associated with the authenticate account

When the LDAP entry associated with the authenticated account has no such attribute, no email is set.

Leave it empty to not retrieve the email from the LDAP entry.

9.6.14. extension_entry_point¶

Default value:

Empty

Optional:

Yes

Values:

• API extension expression.

• Empty.

From version:

4.16.0

Description:

The API entry point is defined in the format LANGUAGE:DOTTED.ENTRY.POINT,

LANGUAGE is the name of the language in which the extension is written.

DOTTED.ENTRY.POINT as an expression defining the package, module, and class name which will receive the event.

Note

At this moment, the event handler API supports the development of custom handlers based on the Python programming language.

As an example, for the file extension/auth_ldap_noop.py defining the AuthLDAPNoop class, the configuration will be:

extension_entry_point = python:auth_ldap_noop.AuthLDAPNoop

9.6.15. extension_configuration¶

Default value:

Empty

Optional:

Yes

Values:

• JSON

• Empty

From version:

4.16.0

Description:

A JSON value which is passed to the extension.

This is ignored when extension_entry_point is not defined.

9.6.16. search_filter¶

Default value:

''

Optional:

Yes

Values:

• LDAP search expression.

• Empty value.

From version:

3.33.0

Description:

The LDAP authentication method can also filter accepted LDAP entries, based on an LDAP search filter, to restrict access to the file transfer services.

For example, if you only want to allow access to members of the group file-transfer you can use the following search filter (memberOf=file-transfer)

Leave it empty to accept any LDAP entry, regardless of its attributes.

For more information about the search filters, check the documentation of your LDAP server in order to discover the search capabilities supported by the server.

9.6.17. manager_search_filter¶

Default value:

''

Optional:

Yes

Values:

• LDAP search expression.

• Empty value.

From version:

3.37.0

Description:

LDAP filter to select the LDAP entries allowed to act as administrators for the Web Manager service.

For example, if you only want to allow access to members of the group file-transfer-admins you can use the following search filter (memberOf=file-transfer-admins)

Leave it empty to deny any LDAP entry as administrator.

9.6.18. group_mapping¶

Default value:

''

Optional:

Yes

Values:

• Group UUID.

• Comma separated LDAP attribute name, matching value, and group UUID.

• Comma separated list of group UUIDs (Since 4.20.0)

• Empty value.

From version:

3.34.0

Description:

The LDAP group mapping configuration can be used to augment the LDAP data without updating the actual LDAP entries.

Setting to a single group UUID, or a list of UUIDs, will associate all the LDAP authenticated accounts to the SFTPPlus groups having that UUID. For more details, see the dedicated LDAP group mapping documentation.

You can create complex group mapping by specifying multiple groups which are selected based on targeted LDAP values.

The matching for LDAP attribute names is case insensitive.

Leave this configuration option empty to use the default SFTPPlus group configuration.

9.6.19. ssl_certificate_authority¶

Default value:

set-on-first-connection

Optional:

Yes

Values:

• PEM content of a CA chain (Since 3.40.0)

• PEM content of a pinned public key (Since 5.1.0)

• Absolute path to a local file

• set-on-first-connection (Since 5.0.0)

• pin-public-key (Since 5.1.0)

• ${MOZILLA_CA_ROOTS} (Since 5.0.0)

• ${LETS_ENCRYPT_X3_CA}

• ${MICROSOFT_IT_CA}

• ${GO_DADDY_G2_G1}

• disable-identity-security (Since 5.0.0)

From version:

1.6.0

Description:

This is used to validate the identity of the remote server.

Remote server identity can only be validated when the remote address or URL is configured using a fully-qualified domain name. IP-based validation would always fail as this is not a method accepted by Certificate Authorities (CAs).

Configured certificates need to be in PEM format.

Multiple Certificate Authorities can be configured, one after the other. They can be multiple root CAs or intermediate CAs.

Warning

When disable-identity-security is set, the identity of the remote server is not validated. All remote servers are accepted without validating their TLS/SSL certificates. Communication is encrypted and data is protected in transit. This can result in an encrypted connection to an unknown server.

When set-on-first-connection is used, the Certificate Authority of the remote server is configured automatically. The set-on-first-connection configuration value is automatically replaced by the actual CA chain of the remove server on the very first connection. For all subsequent connections, the server identity is validated against the automatically configured CA chain.

When pin-public-key is set, SFTPPlus accepts server certificates that have the same public key as the one discovered during the first connection to this server. This is used to implement certificate and public key pinning. SFTPPlus only pins the public key. This can be used for self-signed server certificates.

You can configure the client to validate the server's identity based on a fixed list of public keys. In this way, you can implement public key pinning. When public key validation is used, the public key infrastructure (PKI) certificate policies are not enforced. For example, the server certificate is accepted even if it's expired or issued for a different hostname.

This can be defined as an absolute path on the local filesystem to a file containing the certificates of the Certificate Authorities used to validate the remote peer.

A series of bundle CAs are distributed with SFTPPlus. They can be configured together and mixed with other CA certificates. The bundle CAs are available under the following names:

• ${MOZILLA_CA_ROOTS} - All the root certification authorities accepted by the Mozilla's CA Certificate Program

• ${LETS_ENCRYPT_X3_CA} - For Let's Encrypt X3 certificate authority.

• ${MICROSOFT_IT_CA} - For all Microsoft IT CA certificates, used by SharePoint Online and other services provided by Microsoft.

• ${GO_DADDY_G2_G1} - For all GoDaddy Certificate Bundles, G2 With Cross to G1.

Only servers using certificates signed by one of the configured Certificate Authorities are allowed to communicate with this client.

Leave it empty to disable checking the identity of the remote server.

9.6.20. ssl_domains¶

Default value:

Empty

Optional:

Yes

Values:

• Fully qualified domain name (FQDN)

• Comma separated list of fully qualified domain names

• Empty

From version:

3.42.0 This configuration option defines the domain for which SFTPPlus will request certificates from the Let's Encrypt server.

The same domain can be shared by multiple services.

The domain name is handled as a case-insensitive lower case value.

You can generate a certificate with multiple domain names (Subject Alternative Name - SAN), by defining a comma-separated list of domain names. The first name from the list is used as the common name of the certificate, while the remaining names are used for the SAN extension.

For this option to be used, you need to define a lets-encrypt resource.

9.6.21. ssl_certificate¶

Default value:

Empty

Optional:

Yes

Values:

• Absolute path on the local filesystem.

• Certificate in PEM text format (Since 3.40.0).

• Certificate in PKCS12 / PXF binary format (Since 4.0.0).

• Empty

From version:

1.6.0

Description:

This can be defined as an absolute path on the local filesystem to the file containing the SSL certificate or chain of certificates used by the component.

File content should be encoded in the Privacy-Enhanced Mail (PEM) or PKCS12 / PFX formats.

File extension should be .p12 or .pfx for the file to be recognized as a PCKS-12 certificate. The password for the PCKS12 / PFX certificate should be set in the ssl_key_password configuration option.

Note

The path should not be longer than 256 characters.

You can also define the content of the certificate as text in PEM format. In this case the configuration will look as in the following example. It's important to start each line with at least one space character and keep the number of leading spaces constant:

ssl_certificate = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

When the value contains both the certificate and the key, the configuration will look as in the following example:

ssl_certificate = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

This certificate is sent to the remote peer during the SSL/TLS handshake process.

The certificate file can contain both the certificate and the private key, in which case you don't need to set the path to the private key. Only supported for PEM encoding.

The certificate file can contain the full chain of certificates. The targeted certificate should be first in the file, followed by the chained certificates. It will advertise the certificate chain in the same order as listed in the file. Only supported for PEM encoding. (Since 3.22.0)

For server-side components using TLS/SSL secure communication, this configuration option is required. If no value is defined here, the global ssl_certificate value is used.

For the client-side component using TLS/SSL, you can disable sending the certificate as part of the handshake, by leaving this configuration option empty.

9.6.22. ssl_key¶

Default value:

Empty

Optional:

Yes

Values:

• Absolute path on the local filesystem.

• Key as PEM text format (Since 3.40.0).

• Empty

From version:

1.6.0

Description:

This can be defined as an absolute path on the local filesystem to the X.509 private key file used by this component.

File content should be encoded in the Privacy-Enhanced Mail (PEM) format.

Note

The path should not be longer than 256 characters.

When the value is defined as PEM text, the configuration will look as in the following example:

ssl_key = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----

If ssl_certificate is not defined, any value defined for this ssl_key configuration is ignored and the global ssl_key value is used.

If the value defined in ssl_certificate option already contains the private key, this option can be omitted by leaving it empty.

9.6.23. ssl_key_password¶

Default value:

Empty

Optional:

Yes

Values:

• Password as plain text.

• Empty

From version:

1.7.19

Description:

This is used to define the password of the private key, when the private X.509 key is stored as an encrypted file.

Leave it empty to not use a password for the private key file.

9.6.24. ssl_certificate_revocation_list¶

Default value:

Empty

Optional:

Yes

Values:

• Comma separated list of CRL paths or HTTP URLs.

• crl-distribution-points

• ${MICROSOFT_IT_CRL}

• Empty

From version:

1.6.0

Description:

It defines the locations from where one or more CRLs will be loaded.

Multiple CRLs are defined as a comma separated list.

It supports local files with absolute paths, in either of the following formats:

• file:///unix/absolute/test-ca.crl

• file://c:\\windows\\absolute\\test-ca.crl

Retrieving the CRL over HTTP is also supported. The HTTP request is done using non-persistent HTTP/1.1 connections. The URL will look as follows:

• http://example.com/some.crl

CRL distribution points (CDP) are supported by using the crl-distribution-points configuration value.

When CRL distribution points are configured, the local certificate defined at ssl_certificate needs to have the CDP extension. The CDP advertised in the local certificate is loaded at startup in order to validate the configuration.

The distribution points configuration is mutually exclusive with local file or HTTP url configurations. When the certificate revocation list is configured to use CDP, all other configured CRL location are ignored.

Warning

HTTP redirection is not yet supported for CRL URLs. You have to configure the exact URL for the CRL.

Leave it empty to disable certificate revocation checks.

The certificate revocation list can only be used when the component is configured with CA certificates stored in a single file in PEM format.

When multiple or chained CA certificates are configured the CRL is only checked for the peer's certificate and not for the CA certificate or for an intermediate CA.

Warning

CDP publishing Delta CRL are not supported.

Note

If the certificate defines multiple HTTP-based distribution points in the CDP extension, only the first HTTP URI is used. All non HTTP or the other HTTP URIs are ignored.

The CRL file should be stored in PEM or DER format.

Note

This option is ignored if ssl_certificate_authority is not enabled.

9.6.25. ssl_certificate_revocation_list_refresh¶

Default value:

0

Optional:

Yes

Values:

• Number of seconds

• 0

From version:

2.8.0

Description:

This defined the number of seconds after which a configured CRL is reloaded by this component.

When set to 0, the CRL file is initially loaded at startup and then loaded again after the Next Update field advertised in the CRL.

If the Next Publish extension is present in the CRL and this option is set to 0, the CRL will be loaded again at the date and time specified in the Next Publish extension.

If the CRL does not advertise the Next Update field you will have to configure a number of seconds after which the CRL should be reloaded, otherwise you will get a configuration error.

For example, a value of 86400 means that the CRL will be re-read after one day.

For more details about the CRL reloading see the documentation for CRL reloading rules

Note

This option is ignored if ssl_certificate_authority is not enabled.

9.6.26. ssl_cipher_list¶

Default value:

secure

Optional:

Yes

Values:

• List of SSL/TLS ciphers in OpenSSL format.

• secure

From version:

1.7.4

Description:

This defined the list of ciphers accepted by this component while communicating over the network.

The special keyword secure contains all the algorithms that we currently consider secure.

Connections are closed if the remote peer has no common cipher in its list of configured ciphers.

When left empty, it will default to the secure configuration.

More information about the accepted values can be found at the cryptography guide

The format for this value is the same as the one used for defining the OpenSSL cipher list. More information can be found on the OpenSSL site.

9.6.27. ssl_allowed_methods¶

Default value:

secure

Optional:

Yes

Values:

• secure

• all

• tlsv1.0

• tlsv1.1

• tlsv1.2

• tlsv1.3

From version:

1.7.4

Description:

This defines the comma-separated list of SSL and TLS methods that are accepted by this component during the secure communication handshake.

Set this to secure to allow only the TLS methods that are currently considered secure. For now, this is TLS 1.2 and TLS 1.3 but this might be changed in the future. Any other configured value is ignored.

Set this to all to allow any supported SSL or TLS method. Any other configured value is ignored.

Currently, the following methods are officially supported:

• tlsv1 or tlsv1.0, which is TLS 1.0.

• tlsv1.1, which is TLS 1.1.

• tlsv1.2, which is TLS 1.2.

• tlsv1.3, which is TLS 1.3.

Note

SSLv3 is still supported, but highly discouraged, due to the SSLv3 POODLE vulnerability. In the case that you need to interact with an old SSL implementation that only supports SSLv3, it is highly recommended to force the usage of the non-CBC cipher RC4-SHA by configuring as:

[services/681f5f5d-0502-4ebb-90d5-5d5c549fac6b]
ssl_cipher_list = RC4-SHA

Support for SSLv3 will be removed in future versions.

SSLv2 is no longer supported since it is not secure.

In version 2.8.0, the following new methods were added: tlsv1.0 (alias for tlsv1), tlsv1.1 and tlsv1.2

Support for tlsv1.3 was added in version 3.47.0.

Prior to version 4.17.0, this was configured as a space separated value.