LDAP authentication (MFT only)

If LDAP authentication is enabled, users can log in to Serv-U using credentials provided by a remote LDAP server, such as Active Directory or OpenLDAP. LDAP users can use a home directory from their LDAP account, eliminating the need to manually specify a home directory.

Before you begin

Before you begin the configuration of LDAP authentication:

• Check the logs of your LDAP server to identify the correct group membership.
• Log in to your LDAP server to verify the correct directory structure.
• Configure the default LDAP group in Serv-U. For information, see Use LDAP user groups.

Active Directory and OpenLDAP users are configured in the same way. In the case of OpenLDAP, the user account must have permission to connect to the OpenLDAP database.

To help decide between whether you should use LDAP authentication or Windows authentication, see Compare Windows and LDAP authentication.

The examples and illustrations in this topic show a Serv-U instance configured to use authentication through Active Directory.

To enable LDAP authentication:

1. Navigate to the required domain > Users.
2. Click the LDAP Authentication tab.

   

The current LDAP servers are listed.

Configure an LDAP server

The LDAP Server configuration dialog is displayed when you click Add, Edit, or Copy on the LDAP Servers list.

1. Provide the following information to configure your LDAP server:

   Enable this LDAP Server	Select this option to enable the LDAP server. Disabled LDAP servers will be skipped over during LDAP authentication if you have configured multiple LDAP servers. LDAP authentication will stop working if you disable all your configured LDAP servers.
   Use Secure LDAP	Check to use Secure LDAP (LDAPS). LDAPS uses TLS (Transport Layer Security) to encrypt and authenticate the data exchanged between Serv-U and the LDAP server. All interactions are performed through a secure channel, which prevents unauthorized parties from intercepting or modifying the data.
   Host	The host name or IP address of the LDAP server. This may be IPv4 or IPv6, but it is always required.
   Port	The TCP port on which the LDAP server is listening. This will usually be 389, or 636 for secure LDAPS.
   Connection Account	The user name of the account that is used to connect to the LDAP server and execute queries against it. Provide the account name complete with the UPN suffix. Serv-U does not automatically apply the UPN suffix for the name you provide here.
   Connection Account Password	The password belonging to the account that is used to connect to the LDAP server and execute queries against the LDAP server. If the Connection Account credentials are not supplied, then the credentials that are being authenticated are used.
   CA root certificate	This field is shown only if Serv-U is installed on a Linux server and you selected the Use secure LDAP option. Select one of the following: Default OS certificate location To use this option, you must import the CA root certificate to the trusted section of the Serv-U host before you set up the LDAPS connection in Serv-U. The required configuration depends on the Linux distribution. It usually requires editing the ldap.conf file to specify the CA path and file name. When the configuration is complete, restart the Serv-U server. The Host field must contain the fully qualified domain name of the server used for TLS certificate creation on the LDAP server. Browse CA certificate Select this option to browse for the CA root certificate. Click Browse, and select the CA certificate file in the local file system. Serv-U parses the selected file and displays certificate details (such as the issuer, subject, and serial number). Review the details and click Yes if they are valid. Pick CA certificate from LDAPS server Select this option to attempt to retrieve the CA root certificate from the LDAP server and save it to the specified location on the local file system. The LDAP server must include the CA root certificate in its certificate chain when it connects to Serv-U. Click the Pick button, and then specify where to store the certificate on the local file system. CA attempts to get the certificate during the initial TLS handshake with the LDAP server specified in the Host field. If the operation succeeds, Serv-U parses the file and displays certificate details. Review the details and click Yes if they are valid.
   Description	An optional field in which you can write more notes about your LDAP server.

2. If you need to configure any of the following settings, click Show Advanced LDAP Options.

   Base Distinguished Name (DN)	Use this field to provide the Base DN (or search DN) of the main node in your LDAP server. The Base DN determines the structure in your LDAP server where the search filter will be applied. This is usually similar to the domain name over which your LDAP server has authority. For example, if your LDAP server provides information about your solar domain, this value can be DC=solar,DC=local. To determine the correct Base DN, hover over the main node of the LDAP server, and look for the highlighted information.
   Search Filter	This required field is used to tell Serv-U how to match incoming LoginIDs ("usernames") to specific LDAP Server entries. $LoginID must be included somewhere in this field. The search filter is used to search in the Users tree of the LDAP server. During authentication Serv-U will replace this variable with the LDAP User's LoginID (and LDAP Login ID suffix, if specified). The value of the search filter varies between different types of LDAP servers, and may even vary between different LDAP servers of the same type (depending on the specific schema your LDAP administrator has implemented). For Active Directory LDAP servers, a value of (&(objectClass=user)(userPrincipalName=$LoginID)) is recommended. This value is provided by default in Serv-U. Consult with your local LDAP administrator or use an LDAP client (for example, Softerra LDAP Browser or Apache Directory Studio) to find and test the right value for your LDAP server before deploying into production, and then modify the default search filter according to your specific setup. For example, if your LDAP server configuration contains subfolders, modify the search filter by adding a wildcard value (*) to match the whole folder structure. The search filter must be configured in a way that it only returns one user. To test your search filters against Active Directory, use the Ldp tool. The default location of the tool is C:\Windows\System32\ldp.exe. For more information about the location and usage of the Ldp tool, search for Ldp on the Microsoft Technet or on the Microsoft Support website.
   Group Membership	This field uses all the values found in the named LDAP attribute as additional LDAP Group membership assignments. For example, if this is configured as grp and an LDAP user record has both grp=Green and grp=Red attributes, Serv-U associates that LDAP User with both the "Red" and "Green" LDAP Groups. A typical value on Active Directory is memberOf.
   Home Directory	This field assigns the value of the named LDAP user entry attribute as your LDAP Users' home directory. A typical value on Active Directory is homeDirectory.
   Login ID	This field assigns the value of the named LDAP user entry attribute as your LDAP Users' login ID (username). A typical value on Active Directory is userPrincipalName. This value will almost always match the value paired with $LoginID in your Search Filter. In other words, this is your login ID in Serv-U, and it is compared to the userPrincipalName in the search filter.
   Full Name	This field assigns the value of the named LDAP user entry attribute as your LDAP Users' full name. A typical value on Active Directory is "name".
   Email Address	This field assigns the value of the named LDAP user entry attribute as your LDAP Users' email address. A typical value on Active Directory is "mail".

Specify the LDAP login ID suffix

After configuring the LDAP server, specify the LDAP login ID suffix. The LDAP login ID suffix is necessary to send fully qualified login IDs to the LDAP server. The suffix you specify here is placed at the end of the user name when a user logs in.

A typical value in an Active Directory environment might be @mydomain.com. After changing this field, click Save to apply the change.

LDAP group membership

You can use LDAP groups to specify which LDAP users can access Serv-U. For details, see Allow only selected LDAP users to access Serv-U.

In order for Serv-U to match users up to the appropriate user groups, the entire hierarchy, including the Distinguished Name (DN) must be recreated in the user group hierarchy.

LDAP Users are also added to any LDAP Groups whose names appear in "Group Membership" attributes defined on the LDAP Authentication page. For example, if the Group Membership field is configured to be grp and an LDAP user record has both grp=Green and grp=Red attributes, Serv-U will associate that LDAP User with both the "Red" and "Green" LDAP Groups.

Membership in one or more LDAP groups is required if the "Require fully-qualified group membership for login" option is selected on the Users > LDAP Authentication page. If this option is selected, and LDAP Users cannot be matched up to at least one LDAP Group, they will not be allowed to sign on. In this case it is possible that Serv-U successfully authenticates to the LDAP server, and then rejects the user login because the user is not a member of any group.

For more information about group permissions and settings, see LDAP Groups.

Use LDAP user groups

LDAP user accounts are not visible or configurable on an individual basis in Serv-U, but LDAP group membership can be used to apply common permissions and settings such as IP restrictions and bandwidth throttles.

All LDAP users are members of a special default LDAP group. To configure the default LDAP group in Serv-U:

1. Navigate either to Users > LDAP Authentication, or Groups > LDAP Authentication.
2. Click Configure Default LDAP Group.

LDAP Users can also be members of individual LDAP Groups. To configure LDAP groups in Serv-U:

1. Navigate to Users > LDAP Authentication.
2. Click Configure LDAP Groups.

LDAP groups have the same configuration options as other Serv-U groups. For information about the configuration options available at the group level, see Groups.

When you configure LDAP groups, recreate the same structure as the group structure in Active Directory, and use the same names as the group names in Active Directory.

The following image illustrates the group structure in Active Directory. By hovering over a user or group in Active Directory, the group structure is displayed. This information is highlighted in yellow.

The following image illustrates how the group structure of Active Directory is recreated in Serv-U.

Use a list of LDAP servers

Serv-U requires administrators to define one or more LDAP Servers before LDAP authentication will work. LDAP Servers are configured on the Users > LDAP Authentication page in the Serv-U Management Console.

You can define more than one LDAP Server if you want Serv-U to try a backup server in case the primary LDAP server is down, or if you want to try LDAP credentials against different LDAP servers with different sets of users.

Serv-U attempts authentication against the list of LDAP servers from top to bottom. During login, the first LDAP server that approves a set of credentials will be the server from which the associated LDAP user will draw its full name, email address and other attributes.

After attempting a login against the first LDAP server, Serv-U tries each LDAP server in the list until it either encounters a successful login, or it encounters an unsuccessful login paired with an authoritative response from the LDAP server that the attempted Login ID exists on that LDAP server.

In other words, Serv-U makes login attempts on LDAP servers that are lower on the list if the preceding LDAP servers are unresponsive, or if they report that they have no knowledge of the LDAP user.

Serv-U tries each available LDAP server, even if the login credentials fail. The error log provides detailed information of any possible connection failure. For information about the error messages, see LDAP error messages.

The error log contains information about the last LDAP server Serv-U contacted.

Use the Add, Edit, Delete, and Copy buttons to work with individual LDAP server entries. When there are multiple LDAP server entries in the list, selecting any entry will reveal move up, move down, move to top, and move to bottom ordering arrows on the right of the window.

Test the connection to the LDAP server

To test the connection to the LDAP server, log in with an LDAP user. If the connection fails, the log files of Serv-U will provide detailed information about the reason for the failure.

The following images show what a successful HTTP login looks like for the user and for the Serv-U administrator. Note that LDAP and Windows authentication looks identical in the log files.

The following image shows the login page for the user named LDAP.

The log entries for both a successful and a failed login are displayed under Domain > Domain Activity > Log.

The following image shows the log entries for a successful login and logout.

LDAP error messages

An unknown LDAP authentication error has occurred. Please double-check your LDAP configuration.	This message signifies a generic issue when the LDAP server does not return any specific error.
An unknown LDAP authentication error has occurred. The error code returned by the LDAP server was %d.	This message signifies a specific LDAP error. The error code returned by the LDAP server can be used to find the specific LDAP error.
LDAP server returned zero or multiple user records matching the account credentials.	This message either indicates that the provided user name is wrong (if zero accounts are returned), or it indicates a problem with the search filter (if multiple accounts are returned). The search filter must be configured in a way that it only returns a single user account. For information about configuring the search filter, see above.

Other error messages:

• Authenticated external user "%s" rejected because group membership is required and no matching Serv-U group was found. A list of all known groups for this user follows.
• No group memberships found. If group membership is expected, double-check the "Group Membership" attribute map for your LDAP configuration in Serv-U.
• No LDAP servers are defined or enabled.
• Unable to initialize LDAP server.
• The connection credentials in the LDAP server configuration have been rejected by the LDAP server.
• The user credentials were rejected by the LDAP server.
• The LDAP server is unavailable to Serv-U.
• The connection credentials in the LDAP server configuration do not have permission to run queries.
• The search filter string in the LDAP server configuration was rejected by the LDAP server.
• Unable to open CA certificate file. Please make sure the path is correct.
• LDAP connection error: Fingerprint verification error, CA certificate was changed outside Serv-U.
• Unable to get CA root certificate. Server does not include it to the certificate chain.

The following error messages relate to issues with accessing an account's home directory, and are not LDAP specific:

• Error logging in user "%s", permission denied by Serv-U access rules to access home dir "%s".
• Error logging in user "%s", the device for home dir "%s" is not ready.
• Error logging in user "%s", could not access home dir "%s"; the error returned by the operating system was %d.
• Error logging in user "%s", permission denied by the operating system to access home dir "%s".

Additionally, when Serv-U returns unknown LDAP authentication errors, search for the LDAP error codes in the documentation of your LDAP server.

Enable LDAP authentication

To enable LDAP authentication:

1. In the Serv-U Management Console, navigate to Users > LDAP Authentication.
2. Select Enable LDAP Authentication.

User home folders

The home folders of LDAP users are pulled from the "Home Directory" LDAP attribute that is specified in your LDAP server configuration. The service account Serv-U runs as should have full permission to the root folder of all LDAP User folders. For example, if your LDAP user home folders are similar to \\usernas\homefolders\username and Serv-U is running as a service on Windows as servu, then the Windows servu user should have full permissions to \\usernas\homefolders.

Use the LDAP user group home directory instead of the account home directory

By default, Serv-U uses the LDAP account's home directory when an LDAP user logs in. This is the value of the Home Folder LDAP attribute that is specified in the LDAP server configuration, as highlighted in the following image.

For information about configuring the LDAP account's home directory, see Configure the LDAP server above.

If you select the Use LDAP Group home directory instead of account home directory option under Users > LDAP Authentication in the Serv-U Management Console, Serv-U will use the home directory that you specify in the Default LDAP User Group instead of the LDAP account's home directory.

The home directory of the Default LDAP User Group is specified on the Group Properties window of the Default LDAP User Group, as highlighted in the following image.

For information about configuring the Default LDAP User Group, see Use LDAP user groups above.

If no home directory is specified at the group level, then the LDAP account's home directory is still used. However, if no home directory is defined at the user, group, domain, or system level, and none is available from the LDAP server, the user will not be allowed to sign on.

The interaction between domain home directories with Default LDAP User Group home directories

If a domain home directory is defined on the Domain Details > Settings page, this directory would be used by Serv-U as the default directory for LDAP authentication, resulting in errors.

To avoid possible issues in this case, make sure that you select the Use LDAP Group home directory instead of the account home directory option under Users > LDAP Authentication, and configure the LDAP group home directory as described in Use LDAP user groups.