LDAP Authentication in Serv-U - KB Article #2143Related Articles -- 2141
By enabling LDAP authentication, users can log in to Serv-U using login credentials as 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.
To enable LDAP authentication, select Enable LDAP authentication under Users > LDAP Authentication.
LDAP User home folders are normally pulled from the "Home Directory" LDAP attribute 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.)
LDAP Login ID suffix
The LDAP Login ID suffix field is used to send fully qualified Login IDs to the LDAP server. (A typical value in an Active Directory environment might be @mydomain.com.) After changing this field, click Save to apply the change.
Use LDAP User Group home directory instead of account home directory
By default, Serv-U uses the LDAP account's home directory (that is, the value of the "Home Folder" attribute) when an LDAP User logs in. Enabling this option causes Serv-U to use the home directory specified in the Default LDAP User Group instead. 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.
Differences Between Windows Users and LDAP Users
Windows and LDAP Users are similar in many ways but there are a number of important differences that can help you decide which type of user is right for your environment.
Use Windows users if the following conditions apply:
- You only want to access one Windows machine or domain (per Serv-U domain)
- You want each end user to see that user's home folders and enjoy that user's NTFS permissions. Serv-U uses impersonation so that it respects the Windows directory access rules. The Windows directory access rules can be supplemented with directory access rules defined in Serv-U.
Use LDAP users if the following conditions apply:
- You want to deploy Serv-U on Linux
- You want to be able to access more than one Windows domain
- You want to be able to access different Windows domains
- You do not care about natively incorporating NTFS permissions. It is not possible to pull directory access rules from LDAP directly, but you can define Serv-U directory access rules for LDAP users.
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. Click Configure Default LDAP Group under Users > LDAP Authentication or under Groups > LDAP Groups to configure this group just like a normal Serv-U group.
LDAP Users can also be members of individual LDAP Groups. Click Configure LDAP Groups on the LDAP Authentication screen to configure these groups just like normal Serv-U groups.
LDAP Group membership
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. For example, in the Active Directory domain myoffice.local the tree must start with local -> myoffice before populating any OUs or Security Groups.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 LDAP Groups 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.
LDAP Server Configuration
Serv-U requires administrators to define one or more LDAP Servers before LDAP authentication will work. LDAP Servers are configured on the Domain Users > LDAP Authentication page in the Serv-U Management Console.
List of LDAP Servers
Administrators can define more than one LDAP Server if they want Serv-U to try a "backup" server in case the primary LDAP server is down, or if they want to try LDAP credentials against different LDAP servers with different sets of users.
Authentication is attempted against the list of LDAP servers from top to bottom. During log in, 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 log in against the first LDAP server, Serv-U will try each LDAP server in the list until it either encounters a successful log in, or it encounters an unsuccessful log in paired with an authoritative response from the LDAP server that the attempted LoginID exists on that LDAP server. (In other other words, the preceding LDAP servers need to have either been unresponsive or report that they had no knowledge of the LDAP User for login attempts to be made to LDAP servers lower on the list.) Serv-U tries each available LDAP server, even if the login credentials fail.
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 the move up, move down, move to top, and move to bottom ordering arrows on the right side of the dialog.
LDAP Server Configuration
The LDAP Server configuration dialog is displayed when you click Add, Edit, or Copy on the LDAP Servers list.
The LDAP Server Configuration dialog contains the following fields:
- Host: The hostname 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 often be 389.
- Server Name: This required field should contain a short description of this LDAP server. We recommend briefly describing the domain and type of LDAP server (for example, Tampa Office OpenLDAP).
- Connection Account: The username of the account that is used to execute queries against the LDAP server. 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 execute queries against the LDAP server.
Note: If the Connection Account credentials are not supplied, then the credentials that are being authenticated are used.
- Enable LDAP Server: Select this 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.
- Description: An optional field in which you can write more notes about your LDAP server.
- Base DN: Use this required field to provide the Base DN (or search DN) of the main node in your LDAP server. 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 myoffice.net domain, this value may be DC=myoffice,DC=net.
- 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. 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 will vary 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. Consult with your local LDAP administrator or use an LDAP client (for instance, Softerra LDAP Browser or Apache Directory Studio) to find and test the right value for your LDAP server before deploying into production.
- Attribute Mapping - Home Directory: This optional 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.
- Attribute Mapping - Full Name: This optional 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.
- Attribute Mapping - Email Address: This optional 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.
- Attribute Mapping - Login ID: This optional 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.
- Attribute Mapping - Group Membership: This optional field uses all the values found in the named LDAP attribute as additional LDAP Group membership assigments. For example, if this is configured as 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. A typical value on Active Directory is memberOf.
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.
Note: 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.
The possible error messages are the following:
- 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).
- 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.
- 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"