Authentication Methods

CompleteFTP supports multiple authentication methods beyond the built-in internal and OS user authentication. External authenticators allow users to be verified against SAML identity providers, LDAP directories, Active Directory domains, databases, and gateway servers. Two-factor authentication can be layered on top of any method for additional security.

Overview

CompleteFTP authentication includes:

• Built-in authentication - Internal users and OS users managed directly by CompleteFTP
• SAML SSO - Single sign-on via SAML 2.0 identity providers
• Database authentication - Verify credentials against an external database
• LDAP authentication - Authenticate against an LDAP directory server
• Active Directory - Integrate with Windows Active Directory domains
• Gateway authentication - Delegate authentication to a remote CompleteFTP or other gateway server
• Two-factor authentication (2FA) - TOTP-based second factor for any user
• Authenticator chaining - Multiple authenticators evaluated in sequence

All authenticator operations use the completeftp site auth command group. Two-factor authentication is managed via the completeftp user 2fa command group.

Authentication System Overview

Built-in vs External Authentication

CompleteFTP has two categories of authentication:

Built-in authentication is the default. Internal users have passwords stored in CompleteFTP's configuration database, and OS users are authenticated by the operating system. No additional configuration is required.

External authentication uses one of the five authenticator types (SAML, database, LDAP, Active Directory, gateway) to verify credentials against an external system. When an external authenticator is enabled, CompleteFTP checks incoming credentials against the external source. If the external system confirms the user, CompleteFTP logs them in using a template user account (see The logInAsUser Concept).

How Authentication Order Works

When a user attempts to log in, CompleteFTP evaluates authentication sources in this order:

1. Built-in users (internal and OS) are checked first
2. Enabled external authenticators are checked in sequence
3. The first successful match is used

If a built-in user exists with the given username, external authenticators are not consulted.

Listing and Viewing Authenticators

List All Authenticators

# List all authenticators and their status for the default site
completeftp site auth list default

# List authenticators for a named site
completeftp site auth list "Production Site"

Show Authenticator Properties

# Show all properties of an authenticator
completeftp site auth show default saml

# Show specific properties
completeftp site auth show default ldap enabled server port ssl

# Show properties of the database authenticator
completeftp site auth show default database providerName connectionString query

Authenticator Summary

Enabling and Disabling Authenticators

# Enable an authenticator
completeftp site auth set default ldap enabled=true

# Disable an authenticator
completeftp site auth set default ldap enabled=false

# Check the current state
completeftp site auth show default ldap enabled

SAML SSO

SAML (Security Assertion Markup Language) enables single sign-on through external identity providers such as Okta, Azure AD, or OneLogin. Users authenticate through the identity provider's login page and are redirected back to CompleteFTP.

Enabling SAML

# Enable the SAML authenticator
completeftp site auth set default saml enabled=true

# Set the site URL (required - the public URL of your CompleteFTP server)
completeftp site auth set default saml siteUrl=https://ftp.example.com

SAML Properties

Configuring SAML Properties

# Set the public site URL
completeftp site auth set default saml siteUrl=https://ftp.example.com

# Enable certificate validation
completeftp site auth set default saml validateCerts=true

# Configure attribute mappings
completeftp site auth set default saml \
  givenName=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname \
  surname=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname \
  emailAddress=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Managing SAML Identity Provider Profiles

Each SAML identity provider is configured as a profile:

# List existing SAML profiles
completeftp site auth profile list default saml

# Add a new identity provider profile (the configuration argument is the IdP metadata URL or XML)
completeftp site auth profile add default saml \
  "https://company.okta.com/app/abc123/sso/saml/metadata"

# Show profile details (use the profile name assigned after creation)
completeftp site auth profile show default saml "Okta"

# Remove a profile
completeftp site auth profile remove default saml "Okta"

Database Authentication

Database authentication verifies user credentials against an external database using a configurable SQL query.

Enabling Database Authentication

# Enable the database authenticator
completeftp site auth set default database enabled=true

Database Properties

Configuring Database Authentication

# Set the database provider
completeftp site auth set default database \
  providerName=Npgsql

# Set the connection string
completeftp site auth set default database \
  "connectionString=Host=db.example.com;Database=ftpusers;Username=ftpauth;Password=secret"

# Set the authentication query
# The query must use @username and @password parameters
completeftp site auth set default database \
  "query=SELECT username FROM users WHERE username=@username AND password=@password"

# Enable password hashing if passwords are stored hashed
completeftp site auth set default database isPasswordHashed=true

Full Database Setup Example

# 1. Enable the authenticator
completeftp site auth set default database enabled=true

# 2. Configure the connection
completeftp site auth set default database \
  providerName=Npgsql \
  "connectionString=Host=localhost;Database=ftpauth;Username=ftpapp;Password=dbpass"

# 3. Set the query
completeftp site auth set default database \
  "query=SELECT username FROM ftp_users WHERE username=@username AND password_hash=@password AND active=true"

# 4. Enable password hashing
completeftp site auth set default database isPasswordHashed=true

# 5. Verify the configuration
completeftp site auth show default database

LDAP Authentication

LDAP authentication verifies credentials against an LDAP directory server such as OpenLDAP.

Enabling LDAP Authentication

# Enable the LDAP authenticator
completeftp site auth set default ldap enabled=true

LDAP Properties

Configuring LDAP Authentication

# Set the LDAP server
completeftp site auth set default ldap server=ldap.example.com

# Set the port (636 is default for LDAPS)
completeftp site auth set default ldap port=636

# Enable SSL
completeftp site auth set default ldap ssl=true

# Enable certificate validation
completeftp site auth set default ldap validate=true

# Set the LDAP query
completeftp site auth set default ldap \
  "query=dc=example,dc=com??sub?(uid=@username)"

# Set the LDAP protocol version
completeftp site auth set default ldap version=3

Full LDAP Setup Example

# 1. Enable the authenticator
completeftp site auth set default ldap enabled=true

# 2. Configure the server connection
completeftp site auth set default ldap \
  server=ldap.example.com \
  port=636 \
  ssl=true \
  validate=true \
  version=3

# 3. Set the search query
completeftp site auth set default ldap \
  "query=ou=People,dc=example,dc=com??sub?(uid=@username)"

# 4. Verify the configuration
completeftp site auth show default ldap

Active Directory Integration

Active Directory authentication allows users to log in with their AD domain credentials.

Enabling Active Directory

# Enable the Active Directory authenticator
completeftp site auth set default activedirectory enabled=true

Active Directory Properties

Managing Active Directory Profiles

Active Directory profiles define which AD servers and groups to authenticate against:

# List existing AD profiles
completeftp site auth profile list default activedirectory

# Add a new AD profile
completeftp site auth profile add default activedirectory "Corporate AD"

# Show profile details
completeftp site auth profile show default activedirectory "Corporate AD"

# Configure an AD profile (map AD group to CompleteFTP groups and home folder)
completeftp site auth profile set default activedirectory "Corporate AD" \
  cftpGroups=staff homeFolder=/Home

# Remove a profile
completeftp site auth profile remove default activedirectory "Corporate AD"

Auto-Creating Home Directories

# Enable automatic home directory creation for AD users
completeftp site auth set default activedirectory autoCreateHomeOverrides=true

When enabled, CompleteFTP automatically creates a home directory for each AD user on first login.

Full Active Directory Setup Example

# 1. Enable the authenticator
completeftp site auth set default activedirectory enabled=true

# 2. Add an AD profile (the configuration string is the AD group name)
completeftp site auth profile add default activedirectory "Domain Users"

# 3. Configure the profile
completeftp site auth profile set default activedirectory "Domain Users" \
  cftpGroups=staff homeFolder=/Home

# 4. Enable automatic home directory creation
completeftp site auth set default activedirectory autoCreateHomeOverrides=true

# 5. Verify the configuration
completeftp site auth show default activedirectory
completeftp site auth profile list default activedirectory

Gateway Authentication

Gateway authentication delegates credential verification to a remote server. This is useful for centralized authentication across multiple CompleteFTP instances.

Enabling Gateway Authentication

# Enable the gateway authenticator
completeftp site auth set default gateway enabled=true

Gateway Properties

Managing Gateway Profiles

# List existing gateway profiles
completeftp site auth profile list default gateway

# Add a new gateway profile
completeftp site auth profile add default gateway "Central Auth Server"

# Show profile details
completeftp site auth profile show default gateway "Central Auth Server"

# Configure a gateway profile
completeftp site auth profile set default gateway "Central Auth Server" \
  host=auth.example.com \
  port=21

# Remove a profile
completeftp site auth profile remove default gateway "Central Auth Server"

Full Gateway Setup Example

# 1. Enable the authenticator
completeftp site auth set default gateway enabled=true

# 2. Add a gateway server profile
completeftp site auth profile add default gateway "Auth Gateway"

# 3. Configure the gateway
completeftp site auth profile set default gateway "Auth Gateway" \
  host=auth.example.com \
  port=21

# 4. Verify the configuration
completeftp site auth show default gateway
completeftp site auth profile list default gateway

Two-Factor Authentication

Two-factor authentication (2FA) adds a TOTP (Time-based One-Time Password) second factor to user logins. Users authenticate with their password and then provide a code from an authenticator app such as Google Authenticator, Authy, or Microsoft Authenticator.

Enabling 2FA Site-Wide

Two-factor authentication must first be enabled at the site level:

# Enable 2FA support on the site
completeftp site set default twoFactorAuthEnabled=true

# Verify the setting
completeftp site show default twoFactorAuthEnabled

Managing 2FA for Individual Users

# Enable 2FA for a user
completeftp user 2fa enable alice

# Check 2FA status for a user
completeftp user 2fa status alice

# Disable 2FA for a user
completeftp user 2fa disable alice

2FA Enrollment

When 2FA is enabled for a user, they will be prompted to enroll on their next login through the web interface. During enrollment, the user scans a QR code with their authenticator app.

Resetting 2FA Enrollment

If a user loses access to their authenticator app, an administrator can reset their enrollment:

# Reset 2FA enrollment (user must re-enroll on next login)
completeftp user 2fa reset alice

Backup PINs

Backup PINs provide emergency access when a user cannot use their authenticator app:

# Show backup PINs for a user
completeftp user 2fa backuppins alice

Backup PINs are single-use. Once a PIN is used, it cannot be used again. Store backup PINs securely and provide them to the user through a secure channel.

2FA Commands Reference

The logInAsUser Concept

When users authenticate through an external authenticator, CompleteFTP needs to know what permissions, protocols, and settings to apply. It does this through template users -- special user accounts whose settings are applied to all externally authenticated sessions.

How It Works

Each authenticator has a logInAsUser property that specifies the template user account. When an external user logs in successfully, they receive all the settings (protocol access, home directory, quotas, etc.) from the template user.

Default Template Users

Configuring Template Users

# 1. View the current template user for an authenticator
completeftp site auth show default ldap logInAsUser

# 2. Configure the template user with desired settings
completeftp user set defaultExtension \
  enabled=true \
  sftpEnabled=true \
  httpEnabled=true \
  homeDirIsRoot=true

# 3. Optionally change the template user for an authenticator
completeftp site auth set default ldap logInAsUser=myCustomTemplate

Custom Template User Example

# 1. Create a custom template user
completeftp user add ldapTemplate internal

# 2. Configure the template user
completeftp user set ldapTemplate \
  enabled=true \
  sftpEnabled=true \
  ftpEnabled=false \
  httpEnabled=true \
  httpsEnabled=true \
  homeDirIsRoot=true \
  readOnly=false \
  quotaStorage=5368709120

# 3. Assign it as the template for LDAP authentication
completeftp site auth set default ldap logInAsUser=ldapTemplate

# 4. Verify
completeftp site auth show default ldap logInAsUser

Multiple Authenticator Chaining

You can enable multiple authenticators simultaneously. CompleteFTP evaluates them in sequence after checking built-in users. This allows you to support multiple external authentication sources at the same time.

Example: LDAP and Database Together

# 1. Enable both authenticators
completeftp site auth set default ldap enabled=true
completeftp site auth set default database enabled=true

# 2. Configure LDAP for corporate users
completeftp site auth set default ldap \
  server=ldap.example.com \
  port=636 \
  ssl=true \
  "query=ou=People,dc=example,dc=com??sub?(uid=@username)"

# 3. Configure database for partner/external users
completeftp site auth set default database \
  providerName=Npgsql \
  "connectionString=Host=localhost;Database=partners;Username=ftpapp;Password=dbpass" \
  "query=SELECT username FROM partners WHERE username=@username AND password=@password"

# 4. Verify both are enabled
completeftp site auth list default

Considerations for Chaining

• Built-in users (internal and OS) are always checked first
• Each authenticator can use a different template user via logInAsUser
• If a username matches in multiple authenticators, the first enabled authenticator that succeeds is used
• Disable unused authenticators to avoid unnecessary lookups and improve login performance

Workflow Examples

Corporate LDAP with 2FA

Set up LDAP authentication for corporate users with two-factor authentication:

# 1. Enable and configure LDAP
completeftp site auth set default ldap \
  enabled=true \
  server=ldap.corp.example.com \
  port=636 \
  ssl=true \
  validate=true \
  "query=ou=Employees,dc=corp,dc=example,dc=com??sub?(uid=@username)"

# 2. Configure the template user
completeftp user set defaultExtension \
  enabled=true \
  sftpEnabled=true \
  httpsEnabled=true \
  homeDirIsRoot=true

# 3. Enable 2FA site-wide
completeftp site set default twoFactorAuthEnabled=true

# 4. Enable 2FA for specific users as they are provisioned
completeftp user 2fa enable alice
completeftp user 2fa enable bob

SAML SSO for Web Portal Users

Configure SAML SSO for users accessing CompleteFTP through the web interface:

# 1. Enable and configure SAML
completeftp site auth set default saml \
  enabled=true \
  siteUrl=https://ftp.example.com \
  validateCerts=true

# 2. Add the identity provider profile (pass the IdP metadata URL)
completeftp site auth profile add default saml \
  "https://login.microsoftonline.com/tenant-id/federationmetadata/2007-06/federationmetadata.xml"

# 3. Configure attribute mappings
completeftp site auth set default saml \
  givenName=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname \
  surname=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname \
  emailAddress=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

# 4. Verify the setup
completeftp site auth show default saml
completeftp site auth profile list default saml

Mixed Internal and External Users

Support both internal users and database-authenticated partner users:

# 1. Create internal users as normal
completeftp user add alice internal
completeftp user set alice enabled=true sftpEnabled=true
completeftp user set alice password

# 2. Enable database authentication for partners
completeftp site auth set default database \
  enabled=true \
  providerName=Npgsql \
  "connectionString=Host=localhost;Database=partners;Username=app;Password=secret" \
  "query=SELECT username FROM partner_users WHERE username=@username AND password_hash=@password" \
  isPasswordHashed=true

# 3. Configure the template user for partners
completeftp user set defaultDatabase \
  enabled=true \
  sftpEnabled=true \
  homeDirIsRoot=true \
  readOnly=true \
  quotaStorage=1073741824

# 4. Internal users (alice) log in with their CompleteFTP password
# 5. Partner users log in with credentials from the database

Migrating from One Authenticator to Another

# 1. Enable the new authenticator alongside the old one
completeftp site auth set default ldap enabled=true

# 2. Configure the new authenticator
completeftp site auth set default ldap \
  server=newldap.example.com \
  port=636 \
  ssl=true \
  "query=ou=Users,dc=example,dc=com??sub?(uid=@username)"

# 3. Test with a few users before disabling the old one

# 4. Disable the old authenticator
completeftp site auth set default database enabled=false

# 5. Verify
completeftp site auth list default

Troubleshooting

External Users Cannot Log In

# Check that the authenticator is enabled
completeftp site auth show default ldap enabled

# Verify the authenticator configuration
completeftp site auth show default ldap

# Check that the template user exists and is enabled
completeftp site auth show default ldap logInAsUser
completeftp user show defaultExtension enabled

# Verify protocol access on the template user
completeftp user show defaultExtension sftpEnabled ftpEnabled httpEnabled

SAML Login Fails

# Verify the site URL is correct and accessible
completeftp site auth show default saml siteUrl

# Check certificate validation settings
completeftp site auth show default saml validateCerts

# List SAML profiles to ensure an IdP is configured
completeftp site auth profile list default saml

# Try disabling certificate validation temporarily for debugging
completeftp site auth set default saml validateCerts=false

LDAP Connection Issues

# Verify server, port, and SSL settings
completeftp site auth show default ldap server port ssl validate

# Test network connectivity to the LDAP server
nc -zv ldap.example.com 636

# Check the LDAP query syntax
completeftp site auth show default ldap query

# Try without SSL for debugging (not recommended in production)
completeftp site auth set default ldap ssl=false port=389

Database Authentication Fails

# Verify the connection string
completeftp site auth show default database connectionString

# Check the query
completeftp site auth show default database query

# Verify the provider name is correct
completeftp site auth show default database providerName

# Check password hashing setting
completeftp site auth show default database isPasswordHashed

# Test database connectivity from the server
# (use appropriate database client tool)

2FA Issues

# Check if 2FA is enabled at the site level
completeftp site show default twoFactorAuthEnabled

# Check the user's 2FA status
completeftp user 2fa status alice

# Reset enrollment if user lost their authenticator app
completeftp user 2fa reset alice

# Retrieve backup PINs for emergency access
completeftp user 2fa backuppins alice

# Disable 2FA for a user if needed
completeftp user 2fa disable alice

Template User Problems

# Identify the template user for the authenticator
completeftp site auth show default ldap logInAsUser

# Verify the template user exists
completeftp user list userName | grep defaultExtension

# Check that the template user has appropriate settings
completeftp user show defaultExtension enabled sftpEnabled ftpEnabled httpEnabled homeDirIsRoot

# Verify the template user is enabled
completeftp user show defaultExtension enabled

Best Practices

Security

1. Use SSL/TLS for LDAP - Always enable SSL when connecting to LDAP or Active Directory servers
2. Validate certificates - Enable certificate validation for SAML and LDAP in production
3. Enable 2FA for sensitive accounts - Add two-factor authentication for users with elevated access
4. Store backup PINs securely - Treat backup PINs like passwords and deliver them through secure channels
5. Use strong database credentials - Protect the connection strings used for database authentication

Configuration

1. Configure template users carefully - The template user controls all settings for externally authenticated users
2. Test before production - Verify external authentication works with test accounts before rolling out
3. Disable unused authenticators - Only enable the authenticators you actively use
4. Use descriptive profile names - Name SAML, AD, and gateway profiles clearly (e.g., "Corporate AD", "Partner Gateway")
5. Document your authentication flow - Record which authenticators are enabled and their order of evaluation

Maintenance

1. Monitor authentication logs - Review logs for failed authentication attempts
2. Rotate database credentials - Periodically update connection strings for database authentication
3. Review template user settings - Audit template user permissions when changing access policies
4. Handle certificate renewals - Track SAML and LDAP certificate expiration dates
5. Test after upgrades - Verify external authentication continues to work after CompleteFTP updates

Quick Reference

Authenticator Management Commands

# List authenticators
completeftp site auth list <siteName>

# Show authenticator details
completeftp site auth show <siteName> <authName> [properties]

# Modify authenticator
completeftp site auth set <siteName> <authName> property=value

Profile Management Commands

# List profiles
completeftp site auth profile list <siteName> <authName>

# Show profile details
completeftp site auth profile show <siteName> <authName> <profileName> [properties]

# Add profile
completeftp site auth profile add <siteName> <authName> <configuration>

# Modify profile
completeftp site auth profile set <siteName> <authName> <profileName> property=value

# Remove profile
completeftp site auth profile remove <siteName> <authName> <profileName>

Two-Factor Authentication Commands

# Enable 2FA for a user
completeftp user 2fa enable <loginUserName>

# Disable 2FA for a user
completeftp user 2fa disable <loginUserName>

# Check 2FA status
completeftp user 2fa status <loginUserName>

# Reset 2FA enrollment
completeftp user 2fa reset <loginUserName>

# Show backup PINs
completeftp user 2fa backuppins <loginUserName>

# Enable 2FA at the site level
completeftp site set <siteName> twoFactorAuthEnabled=true

Authenticator Properties

# SAML
enabled=true/false
siteUrl=https://ftp.example.com
validateCerts=true/false
logInAsUser=templateUser

# Database
enabled=true/false
providerName=Npgsql
connectionString="Host=...;Database=...;Username=...;Password=..."
query="SELECT ... WHERE username=@username AND password=@password"
isPasswordHashed=true/false
logInAsUser=defaultDatabase

# LDAP
enabled=true/false
server=ldap.example.com
port=636
ssl=true/false
validate=true/false
query="dc=example,dc=com??sub?(uid=@username)"
version=3
logInAsUser=defaultExtension

# Active Directory
enabled=true/false
autoCreateHomeOverrides=true/false
logInAsUser=defaultWindows

# Gateway
enabled=true/false
logInAsUser=defaultExtension

Default Template Users

# Authenticator        Default logInAsUser
# database             defaultDatabase
# gateway              defaultExtension
# ldap                 defaultExtension
# activedirectory      defaultWindows