Using Active Directory, Entra ID (Azure AD), SAML and LDAP groups to control who can log in to CompleteFTP

You cannot add a directory group to CompleteFTP's user list. Searching a domain from the Add Windows Users dialog returns individual accounts and never groups, and there is no group entry to select, because the user list holds users only. Group-based access is done somewhere else entirely, and which mechanism you get depends on where your accounts live: an on-premises Active Directory domain, Microsoft Entra ID (Azure AD), or some other LDAP directory. Those three are separate features in CompleteFTP with different capabilities, different editions and different protocol coverage.

Throughout, your CompleteFTP server is the machine running the CompleteFTP service, your directory is Active Directory, Entra ID, an LDAP server or the CompleteFTP host's own Windows account database as the case may be, and the connecting user is the person authenticating to CompleteFTP with an account held in one of those.

Which situation are you in?

Answer this before configuring anything. Each case names one section, and the other two are skippable unless you have accounts in two places, in which case work through both cases in turn: the authenticators coexist on one server, and running Active Directory for SFTP alongside a cloud identity provider for the web is a normal arrangement.

Two discriminators, because the boundary between A and C is where people go wrong:

• The test for Case A is a Windows logon, not network reachability. CompleteFTP authenticates an Active Directory user by asking Windows to log that account on locally on the CompleteFTP host, first as an interactive logon and then, if that is refused, as a network logon. Being able to reach a domain controller on port 389 is not sufficient. If your host sits in a DMZ workgroup and is not joined to the domain, its domain accounts are Case C. Its own local Windows accounts and local groups remain Case A, and the two can be configured on the same server.
• If you run Entra ID with directory synchronisation and your CompleteFTP host is joined to the synchronised on-premises domain, you are in Case A. The accounts are ordinary domain accounts with ordinary Windows passwords. Case B is for accounts that exist only in the cloud.

The short version

Common to all three cases: every directory integration in CompleteFTP is an authenticator, configured per site, and none of them are enabled out of the box. In CompleteFTP Manager they are the rows in the AUTHENTICATORS section of the Users panel, each with an Enabled checkbox, a Log in as user and a Configure... link. Adding directory accounts to the user list one by one is a different feature that does not use groups at all.

CompleteFTP Manager is a Windows application, but the server it manages need not be. It runs on the CompleteFTP host or on any Windows machine that can reach one, including a CompleteFTP server running on Linux, so a Linux deployment is still administered through the manager from a Windows desktop. Where the text below says the manager shows or does something, it is acting on the server it is connected to, not on the machine you are sitting at. What Linux has no local copy of is the manager application itself; on the server the same authenticator rows are completeftp site auth list. Before you can run any completeftp command the admin command line has to be reachable: on Windows it is off until --enable-admin-cli is added to the service binary path, and on Linux it must be run as root or the completeftp account, which owns the socket it connects over.

Then:

• Case A. Enable Windows/AD Group Authenticator, click Configure..., add each permitted group by name, click APPLY CHANGES. See Case A.
• Case B. Enable Single sign-on / SAML and register Entra ID as an identity provider. This covers the web interface only, and requires Enterprise MFT. See Case B.
• Case C. Enable LDAP Authenticator and give it a server address and a user DN template. Requires Enterprise MFT, and it has no group filtering. See Case C.

What each mechanism can and cannot do

Two consequences that are worth reading twice:

• SAML never applies to SFTP or FTPS. A SAML assertion only ever reaches CompleteFTP through the web login page. An SFTP client has nowhere to put one. If you need Entra ID or ADFS credentials on SFTP, the answer is directory synchronisation plus Case A, not SAML.
• The LDAP authenticator does not check group membership. It binds to your directory as the connecting user and accepts them if the bind succeeds. Any account that can bind can log in. If you need group restriction on a non-domain-joined host, no shipped authenticator provides it.

Case A: Active Directory or local Windows groups

The Windows/AD Group Authenticator admits any Windows or Active Directory account that can log on to your CompleteFTP host, optionally restricted to a list of groups you name. Members do not need entries in CompleteFTP's user list, and adding them there is not merely unnecessary, it changes their behaviour (see failure mode 4).

Prerequisites

• Your CompleteFTP server runs on Windows. For domain accounts it must also be joined to the domain, or to a domain that trusts it. For local Windows accounts and groups on that host, no domain membership is needed.
• Professional or Enterprise MFT, if you want the group list to be enforced. On Free and Standard the group restriction is silently ignored (failure mode 1).
• A group you can name. A distinguished name will not work (failure mode 3).

In CompleteFTP Manager

1. Open the Users panel and find the AUTHENTICATORS section below the user list. Check the For site: selector above the grid, because the setting applies to the selected site only.
2. Tick Enabled on the Windows/AD Group Authenticator row.
3. Leave Log in as set to defaultWindows unless you have a reason to change it. Everyone admitted by this authenticator inherits that user's settings: enabled protocols, home folder, access-control type and CompleteFTP group memberships.
4. Click Configure... on the same row.
5. Click Add allowed AD or Windows group and type the group name into the AD or Windows Group column. Repeat for each group.
6. Fill in the other columns as needed (see the table below), then click OK.
7. Click APPLY CHANGES at the top of the window. Nothing reaches the server until you do.

An empty group list is permissive, not restrictive. With no groups listed, every account that can log on to the host is admitted, local accounts included. Add at least one group before you enable the authenticator on a production site.

The four columns in the configuration dialog

There is also a checkbox, Automatically create overridden home folders if they don't already exist, which is on by default and creates the directory named by Home Folder Path Override at first login.

To grant folder permissions by AD group, use the Log-In-As User column, not the CompleteFTP Groups column. Create one CompleteFTP user per AD group (a non-Windows user is fine, its password is never used on this path), put that user in the CompleteFTP groups that carry the folder permissions you want, and name it in Log-In-As User on the matching row. Give it the home folder those members should get. The CompleteFTP Groups column is present in the dialog and is saved correctly, but the group names it holds are not applied to the session, so a row that relies on it alone grants nothing.

From the command line

Run these from an elevated prompt on the CompleteFTP host, with the admin command line enabled as described in the short version. Use PowerShell rather than the command prompt, because the command prompt expands %UserName% to the name of the account you are logged in as before CompleteFTP ever sees it.

completeftp site auth list "Default Site"
completeftp site auth set "Default Site" activedirectory enabled=true logInAsUser=defaultWindows
completeftp site auth profile add "Default Site" activedirectory "MYDOMAIN\SFTP_Users"
completeftp site auth profile set "Default Site" activedirectory "MYDOMAIN\SFTP_Users" logInAsUser=sftpUsersTemplate homeFolder=C:\FTP\SFTP_Users\%UserName%
completeftp site auth profile list "Default Site" activedirectory
completeftp site auth show "Default Site" activedirectory

A profile is one row of the configuration dialog, and its name is the group name. site auth set and site auth profile set apply their changes immediately; there is no separate apply step on the command line. The remaining profile property is cftpGroups, which takes a comma-separated list and is subject to the same limitation as the CompleteFTP Groups column above. The authenticator-level property autoCreateHomeOverrides corresponds to the checkbox.

Note that the command line does not validate the group name the way the dialog does, so a malformed name is accepted and simply never matches.

Letting domain accounts log in without typing the domain

Set Default Windows domain in General user settings on the Users panel, or completeftp site set "Default Site" defaultDomain=MYDOMAIN. A connecting user who supplies no domain is then treated as belonging to that domain.

One consequence catches people out: once a default domain is set, a bare user name will never reach a local account on the CompleteFTP host. Anyone logging in with a local account must type .\username.

If you list more than one default domain (the field accepts a comma-separated list), see failure mode 7 before relying on it.

Making a domain account a CompleteFTP administrator

There is no way to grant administrator rights to a whole AD group. Administrator access is per user and requires Enterprise MFT:

1. Add the Windows user to CompleteFTP individually, from Add user in the Users panel.
2. Turn on Show system users/folders/sites in the Options menu at the bottom left, so the Admin site becomes visible.
3. Set that user's home directory on the Admin site to /Admin.
4. Add the user to the admins group.

Because these users are in the user list, they are matched before any authenticator runs, so the group restrictions in the Windows/AD Group configuration do not apply to them.

Case B: Entra ID (Azure AD)

CompleteFTP has no Entra ID or Azure AD authenticator. The supported route is SAML: CompleteFTP acts as a SAML service provider and delegates authentication to Entra ID as the identity provider. It cannot act as an identity provider itself. The same applies to ADFS, Okta, OneLogin and any other SAML identity provider.

Requires Enterprise MFT, and covers the web interface only. Users authenticated this way reach CompleteFTP through a browser. SFTP, FTP and FTPS sessions cannot carry a SAML assertion and are unaffected by anything you configure here.

In CompleteFTP Manager

1. In the AUTHENTICATORS section of the Users panel, check the For site: selector, then tick Enabled on the Single sign-on / SAML row and click Configure.... Log in as starts at defaultExtension, and everyone who signs in this way inherits that user's settings unless user matching finds a better one at step 5.
2. Add your identity provider by importing its metadata, either from a file or by download. Each identity provider you add becomes a button on the CompleteFTP login page.
3. Give it a name (this is the button caption), and set the User attribute if the user name should come from a specific SAML attribute rather than the default name identifier.
4. Optionally set a User prefix, which is prepended to the name the identity provider returns.
5. Optionally turn on User matching, which looks for a CompleteFTP user whose name equals the prefixed name and uses that user in place of defaultExtension for the session. Without it, everyone signing in through this identity provider shares one set of settings and one home folder.
6. Click APPLY CHANGES.

From the command line

On Linux there is no manager, so this is the only interface. Prefix with sudo. The identity provider is added as a profile whose configuration string is the metadata XML itself, and whose name is taken from the entityID in that metadata.

completeftp site auth set "Default Site" saml enabled=true siteUrl=https://files.example.com validateCerts=true
completeftp site auth profile add "Default Site" saml - < idp-metadata.xml
completeftp site auth profile list "Default Site" saml
completeftp site auth profile set "Default Site" saml <entity-id> userNamePrefix=entra- userMatching=true

A single - in place of the configuration reads the metadata from standard input, which is the only practical way to pass an XML document as an argument.

Getting Entra ID groups to control access

CompleteFTP reads group memberships from the SAML assertion and adds them to the connecting user's CompleteFTP group membership for that session. It looks in exactly two places:

• any attribute whose name contains schemas.xmlsoap.org/claims/group, taking each value as one group name; and
• an attribute named exactly group (matched case-insensitively), whose value may be a single name or a comma-separated or semicolon-separated list.

Nothing else is read. In particular, the claim Entra ID emits by default for group membership is not one of these two names, so you must add a claim on the CompleteFTP enterprise application that uses one of them. The values must be the names of CompleteFTP groups you have already created, so the claim has to emit group names rather than the directory object identifiers Entra ID emits by default.

Once the names arrive, they behave like any other CompleteFTP group membership: create the groups under Manage groups on the Users panel and grant them folder permissions in the virtual file system.

There is no synchronisation in either direction. CompleteFTP does not read your directory, does not import Entra ID groups into its own group list, and does not create accounts. Everything comes from the assertion presented at login.

If you need SFTP for Entra ID accounts

Synchronise the accounts to an on-premises Active Directory domain, join your CompleteFTP host to that domain, and use Case A. Cloud-only accounts, including guest accounts, cannot be given SFTP access this way, because there is no Windows password for CompleteFTP to validate.

Case C: an LDAP directory

The LDAP Authenticator requires Enterprise MFT and works on both Windows and Linux. Use it when your CompleteFTP host cannot perform a Windows logon for the accounts you want to admit: a non-Microsoft directory, or an Active Directory reachable only over LDAP.

It performs no group filtering. It authenticates by binding to your directory as the connecting user, and admits anyone whose bind succeeds. There is no group setting in its configuration, and the group restriction available in Case A has no counterpart here. If group restriction is a requirement, this authenticator does not meet it, and the only routes that do are Case A and Case B.

In CompleteFTP Manager

1. In the AUTHENTICATORS section of the Users panel, check the For site: selector, then tick Enabled on the LDAP Authenticator row and click Configure.... Log in as starts at defaultExtension, and everyone who signs in this way inherits that user's settings unless user matching finds a better one at step 5.
2. LDAP server takes a host name or IP address, not a URL. Set Port to 636 with Use SSL/TLS ticked, or 389 without. Protocol version is normally 3.
3. Validate certificate checks the directory server's certificate against the certificate store of the CompleteFTP server, not of the machine running the manager. The test login runs there too. Leave validation off only while testing.
4. User Distinguished Name (DN) query is a DN template containing a placeholder for the user name, for example uid=%UserName%,dc=example,dc=com. The label insists on %UserName%, but %u, %s, {username}, ${username} and {{username}} are also accepted, all case-insensitively. Special characters in the supplied name are escaped, not rejected.
5. Enable user matching (user-name is prefixed with 'ldap-') makes CompleteFTP look for a local user named ldap-<username> and use that user in place of defaultExtension for the session. Without it, everyone who binds successfully shares one set of settings and one home folder.
6. Fill in User-name and Password under Test login and click Test login to check the configuration, then click APPLY CHANGES.

From the command line

One line, on Windows or Linux. On Linux prefix it with sudo: the command line reaches the server over a socket that ordinary users cannot open.

completeftp site auth set "Default Site" ldap enabled=true server=dir.example.com port=636 ssl=true validate=true version=3 query=uid=%UserName%,dc=example,dc=com userMatching=true

Bind credentials are not part of the configuration. Earlier releases had a bind DN and password; those fields have been removed from the dialog and are ignored if present in a stored configuration, because the authenticator binds only as the connecting user. The product guide still documents them.

When it doesn't work

Ordered by how often each appears in support tickets. Each is tagged with the cases it applies to.

1. The group list is ignored, and everyone in the domain gets in (Case A)

The group restriction requires Professional or Enterprise MFT. On Free and Standard the configuration is read but not applied, and the authenticator admits every account that can log on to the host. There is no error; the only sign is a warning in the log at startup:

WARN AWUAuthenticator Automatic Window user filtering by AD group is not available in editions lower than Professional

If someone can still log in after you removed them from the permitted group, check the edition first, then failure mode 4.

2. The permitted group is named, but members are refused (Case A)

The connecting user's password was accepted and the group check then failed. Have them try again and look for this line, which is written at Information level, so the default logging level is enough:

INFO AWUAuthenticator [Session.14:Default Site:MYDOMAIN\alice:10.20.0.31] User MYDOMAIN\alice is not a member of any allowed AD groups.  This user is a member of mydomain\domain users,builtin\users,mydomain\finance

The second half of that line is the complete list of groups CompleteFTP saw on the account, in the exact form it compares against. Copy the one you want out of it and paste it into the AD or Windows Group column. This is by far the fastest way to get the name right, and it is the only way to discover names that differ from what the Active Directory Users and Computers console shows.

If the user is refused before that line appears, the failure is the Windows logon, not the group check. A successful logon logs:

INFO WindowsImpersonation Windows Interactive logon succeeded for MYDOMAIN\alice

Nested groups are worth checking too. The comparison is against the groups present on the Windows logon token, which includes groups inherited through nesting, so a nested group should appear in that list. If it does not, the nesting has not replicated to the domain controller that served the logon.

3. A distinguished name is rejected, or accepted and never matches (Case A)

CompleteFTP wants a Windows-style group name, MYDOMAIN\GroupName or a bare GroupName. It does not accept a distinguished name. Typing one into the dialog produces:

AD/Windows group names may not contain the following characters:  # , + " \ < > ;

which is the comma in CN=SFTP_Users,OU=Groups,DC=example,DC=com being rejected. The command line performs no such check, so a distinguished name added with site auth profile add is stored happily and then never matches anything. If you configured groups from the command line and nobody can log in, list them back with site auth profile list and check their form.

4. Adding group members individually as Windows users defeats the group check (Case A)

CompleteFTP resolves a login by looking for an exact match in the user list first, and only then tries the authenticators. An account present in the user list therefore never reaches the Windows/AD Group authenticator, and none of its group restrictions, home-folder overrides or log-in-as mappings apply to it. Its password is still validated against Windows, so it keeps working after you remove the account from the permitted group.

You do not need to add group members to the user list. Add someone individually only when they need settings that differ from everyone else's, and remember that doing so takes them out of the group mechanism entirely.

The matching is on the full name as stored, so a user list entry of MYDOMAIN\alice is matched when they connect as MYDOMAIN\alice, and also when they connect as alice or alice@MYDOMAIN if a default domain is set.

5. All members land in the same folder and can see each other's files (Case A)

Everyone admitted by the authenticator inherits the home folder of the log-in-as user, which is defaultWindows unless you changed it, so by default they all share one home folder. Give each group its own home folder with Home Folder Path Override on that group's row, and include %UserName% in the path if each member should get their own directory, for example C:\FTP\SFTP_Users\%UserName%.

Whether the folder permissions you set in the virtual file system apply at all depends on the log-in-as user's Access control setting. With Non-Windows, CompleteFTP's own folder permissions and group memberships govern access. With Windows, CompleteFTP impersonates the connecting Windows account and the underlying NTFS permissions govern instead, which means the CompleteFTP groups have no effect on what the user can read or write.

6. Public-key logins are not filtered by group (Case A)

The group check runs on the password step, because the group list comes from the Windows logon token and there is no token without a password. On a public-key login the authenticator verifies the key and stops there.

The keys it verifies are the ones installed on the log-in-as user, not on any individual directory account, so every user admitted by this authenticator shares one set of keys and any of them will authenticate any of the others. If two members of the same group behave differently with their own keys, that is why.

For public-key access to directory accounts, set Methods (SSH) on the log-in-as user so that only the combined public-key-and-password method is enabled. The password step then runs, which restores both the Windows logon and the group check. Where individual users need individual keys, add those users to the user list and give each their own key, accepting the consequence in failure mode 4.

7. A comma-separated default domain breaks bare user names (Case A)

The Default Windows domain field accepts a comma-separated list, and CompleteFTP tries each entry in turn when resolving a name against the user list. The Windows/AD Group authenticator does not: it uses the field's whole contents as a single domain name, so a connecting user who supplies no domain is authenticated against a domain called MYDOMAIN,MYDOMAIN.COM, which does not exist.

If you need more than one default domain, tell users admitted by the authenticator to log in with the domain included, either as MYDOMAIN\alice or in user-principal-name form as alice@MYDOMAIN. Both forms are handled correctly, and a name containing an at sign is tried as a user principal name first.

8. Listing domain users fails, or returns no groups (Case A)

Two different things.

No groups in the results is correct behaviour. The List domain users button queries your directory for accounts, filtering on user objects that are people. Groups are excluded by construction and no filter you type will bring them back. Group-based access does not go through this dialog at all, it goes through the authenticator configuration described above.

An error means the query failed, and the query runs on your CompleteFTP server under the service account, not on the machine running CompleteFTP Manager. The dialog reports:

An error occurred while getting the list of Windows users from the server.

with the underlying exception in the details. The two common ones:

• System.Runtime.InteropServices.COMException: The server is not operational. The domain name could not be resolved to a domain controller from your CompleteFTP server, or the ports it needs are blocked. Check DNS and connectivity from that host, not from your desktop.
• System.DirectoryServices.DirectoryServicesCOMException: An operations error occurred. The bind was anonymous or the account used has no rights to read the directory. Tick Login when querying domain and supply a domain account that can read user objects.

The dialog also only offers the domain option on Professional and Enterprise MFT with a Windows server. On Free and Standard it goes straight to the host's local accounts with no domain fields shown.

9. Group claims arrive but nothing changes (Case B)

The claim name has to match. CompleteFTP reads only an attribute whose name contains schemas.xmlsoap.org/claims/group, or one named exactly group. Raise the logging level to Debug (see the next section) and log in: every attribute in the assertion is written to the log as a name and value pair, so you can see exactly what your identity provider sent and under what name.

Then check the values. They must be the names of groups that already exist in CompleteFTP. A group identifier that has no matching CompleteFTP group is added to the session's group list and matches no folder permission, which looks identical to nothing having happened.

10. The authenticator throws and the login falls through (Cases A and C)

When an authenticator raises an exception, CompleteFTP logs it and tries the next one:

ERROR UserManager Plugin Windows/AD Group Authenticator failed - trying next plugin

The stack trace on that line is the real error. In Case A the message is close to terminal: the Windows/AD Group authenticator is forced to the end of the list, so there is rarely another authenticator after it. In Case C another authenticator may well follow, and a login can still succeed after this line. Two configuration errors from the LDAP authenticator surface the same way, both at startup rather than at login: No LDAP configuration found if the authenticator is enabled but never configured, and LDAP query pattern must contain a username placeholder. if the user DN query has no %UserName% or equivalent in it.

11. An administrator cannot open the Admin site (Case A)

Login failed: User MYDOMAIN\alice does not have permission to change into home directory: /Admin

Administrator access is not something a directory group can confer, and naming the admins group in the CompleteFTP Groups column of the authenticator will not do it either, for the reason given in Case A under the four configuration columns. The account needs an entry in the user list, membership of the admins group, and a home directory of /Admin on the Admin site, as set out at the end of that section. Enterprise MFT is required for any administrator other than the built-in one.

The message above comes from the SFTP path, so it is what a Case A administrator sees. Case B and Case C readers should note that the same three requirements apply, and that all three are properties of a CompleteFTP user rather than of anything the identity provider or directory asserts.

Reading the log

Raise the server logging level to Debug before reproducing a failed login, either on the Log Files tab of the Monitoring panel in CompleteFTP Manager, or with completeftp monitor set logging.level=Debug on Linux. The level is not retroactive: raising it adds no detail to lines already written, so raise it first and then reproduce.

The log tag identifies which mechanism produced a line, which matters when more than one authenticator is enabled:

The order of events for a successful Case A login is: UserManager fails to find the name in the user list, WindowsImpersonation reports the logon, then AWUAuthenticator reports the group decision. If the WindowsImpersonation line is absent, the problem is the credential or the domain trust and not the group configuration.

If you are on an older release

• The LDAP authenticator does not exist before 24.0.0.
• LDAP authentication accepted empty passwords. A bind that supplies a DN but no password is an unauthenticated bind, and Active Directory answers it as an anonymous bind with a success code rather than rejecting it, so an empty password read back as a valid login. Affected 24.0.0 to 25.0.6, fixed in 25.0.7. Upgrade.
• A per-group log-in-as user's access-control setting was ignored. Fixed in 24.0.0.
• Sorting the group grid and then removing a row removed the wrong row. Fixed in 22.2.0.

Related

• Product guide: Configuring Windows/AD group users, Allow all users from a Windows group to log in, Adding a Windows user, Setting a default Windows domain, Managing groups, Adding extra administrators, Configuring LDAP users, Configuring SAML single sign-on, CLI reference.
• KB: Turning on debug logging in CompleteFTP, for raising the logging level and finding the log files on Windows and Linux.
• Background: SFTP server with Active Directory, which compares the ways an SFTP server can integrate with a domain and where CompleteFTP sits among them.

Other technical articles

• CompleteFTP service fails to start after an upgrade: how to find the cause and fix it
• CompleteFTP: System.OutOfMemoryException during SFTP, or a service that stops responding
• Does edtFTPnet/PRO support .NET 8? Which assembly to reference for .NET Framework, .NET Core and .NET 5+
• How to disable weak ciphers and encryption algorithms in CompleteFTP
• How to enable Debug logging in CompleteFTP for troubleshooting
• How to export and import CompleteFTP configuration between servers and versions
• IP filtering and whitelisting in CompleteFTP: what it supports and how to configure it
• Passive FTP and FTPS data connection failures in CompleteFTP: login works, the directory listing times out
• SFTP login fails with "No supported authentication methods available (server sent: publickey)" or "Permission denied (publickey)"
• Why SFTP transfers fail with "ConsumeWindowSpace timed out", and how to fix it
• Why an SSL certificate won't import into CompleteFTP, and how to fix it

Download Free Trial