How to setup LDAP Authentication (4290187)

This article describes how to set up the LDAP authentication feature on the KACE SMA and KACE SDA Appliances.

• System-level user accounts. Accounts that enable users to log in to the System Administration Console to manage appliance settings, such as the appliance host name and network settings. System-level user accounts include the default admin account for the appliance. These accounts also enable access to organization-level components (AdminUI) and the User Console.
• Organization user accounts. Accounts that enable users to log in to the Administrator Console Organization level (Administrator Console ) to manage organization-specific components. These components may include Inventory, Assets, Distribution, Scripting, Security, Service Desk, and User Console depending on the user's role.

*NOTE* Please reference the KSMA Admin Guide or search our other articles for more information regarding configuring and troubleshooting LDAP Authentication and LDAP Labels.

Step One: Collect Information from LDAP Server

1)    The following information is needed from the LDAP Server in order to set up the LDAP authentication on the KACE appliance
     a)    Server Hostname or IP ADDRESS of the LDAP Server. For LDAPs use ldaps:// Server Hostname or IP ADDRESS.
     b)    LDAP Port number default 389, LDAPs (secured) port number is 636
     c)    Search Base DN - The starting location of the LDAP Tree
     d)    LDAP Filter – This is the query that filters in users from your domain environment.
     e)    LDAP login and password that has permission to query the directory

*NOTE* In Active Directory every user has this privilege by default so it does not have to be an administrative account; however, we recommend an administrative account for testing.

If the customer is using port 636 and the appliance is unable to establish a communication link via this port but can connect through port 389, the issue is likely related to the local SSL certificate on the Domain Controller.

Please ensure that the specified Domain Controller has a valid SSL certificate, and that the certificate authority role on the server has not expired.

For further testing on this port, the user should use LDP.exe, pointing to the Domain Controller on port 636 for validation.

Step Two: Configure an LDAP Filter

1)    Navigate to the User Authentication page in the AdminUI of the Kace SMA.
     a)    In the KACE SMA: http://KaceSMA/adminui | Settings | User Authentication
     b)    In the KACE SDA: http://KaceSMA/adminui | Settings and Maintenance | Control Panel |  User Authentication | External LDAP Server Authentication
2)    Enable LDAP Authentication and click ‘NEW’ to create a new filter.
3)    Configure the LDAP filter with a Name, LDAP Server Information, Port, Base DN, LDAP Search Filter, Login name (domain\username), and password, and Role that you would like these users to get when their account is created in the SMA either by importing or by logging in for the first time.
     a)    Reference below for LDAP filter examples for targeting an OU or a Security Group.
4)    Verify that the user roles being assigned to each filter are appropriate for the users that are being targeted. The user role can be manually changed after the user account is imported, and it will not change back unless that user account is deleted and re-imported.

*NOTE* If the KACE SMA is using Orgs, LDAP filters need to be created in every Org.

LDAP authentication for Multi-ORG appliances with SystemUI (System User Interface) 
This feature is available on Kace SMA version 12.0.x or later.

1. Navigate to the User Authentication page in the AdminUI of the Kace SMA.
        a)    In the KACE SMA: http://KACESMA/systemui | Settings | User Authentication
2. Select "LDAP authentication".
3. Configure the LDAP filter with a Name, LDAP Server Information, Port, Base DN, LDAP Search Filter, Login name (domain\username), and password, and Role that you would like these users to get when their account is created in the SMA either by importing or by logging in for the first time.
4. Verify that the user roles being assigned to each filter are appropriate for the users that are being targeted. The user role can be manually changed after the user account is imported, and it will not change back unless that user account is deleted and re-imported.

NOTE: LDAP import is not available from the SystemUI. The users are created in the Kace SMA at their first logon if they match the LDAP query created under LDAP authentication.

Step Three: Configure LDAP Import

The LDAP User Import is used for importing all of the users targeted in the LDAP Filter into KACE SMA appliance. It is not necessary for users to be imported to the KACE before they can authenticate, but it does allow for user management prior to deployment.

1)    In User Authentication, after the LDAP filter is created | Click on the bell to the left of the LDAP filter.
2)    Most of the attributes can be left as is. | Click Next.
3)    Here is what should be put by default into the User/LDAP Attributes:
     a)    LDAP UID: ObjectGUID
     b)    User Name: SamAccountName
     c)    Full Name: Display Name
     d)    Email: Mail
4)    Choose the Role for the user import.

*NOTE* The role for the import can be set independently from the default role for this LDAP Filter. The difference is that when the user import is run it applies for this role, or if the user logs in without being imported that account will be given the role in the LDAP filter.

1)    LDAP Labels: It is generally best practice to de-select the labels in the import unless there is an express purpose for them. Generally, LDAP labels are best created from scratch. For more information about LDAP Labels, please reference the KACE Admin guide and this article: KCS Article 134040.
2)     Click Next.
3)    Review the list of users and attributes that are set to be imported and either save/schedule this LDAP import, or click the Import Now Button.

Step Four: Test the LDAP Filter

1)    Once the filter is created, click on LDAP Browser to verify that it is able to connect to the LDAP Server and correctly see the users being filtered in.
2)    To see test the LDAP filter against a single user, change the (KBOX_USER) variable to a specific user For Example: (samaccountname=Gerald)
     a)    Experiment with different Search Bases and Search Filters. If the filter can return results here then it will work in the authentication. If the LDAP filter cannot return results then it will not work there either.
3)    Once it is verified that the LDAP filter is working, please replace the username in the Search filter back to KBOX_USER before saving it. KBOX_USER is a variable that gets replaced when you authenticate.  For Example: (samaccountname=KBOX_USER)

*NOTE* Be sure to delete all LDAP authentication sources that are not used or put a valid LDAP Server IP address if not being used.

Security best practices

• Use read-only access service account for LDAP bindings (see note below).
• Enable 2FA on the appliance
  • Guide on how to enable 2FA on the SMA
  • Guide on how to enable 2FA on the SDA
• Users authenticate using strong passwords

NOTE: If using a read-only service account, the user used for Credentials must have read access to the OU in the base dn. This means either they are a member of the OU or they must be granted Read access to the OU you are running the query against.

LDAP Filter Examples:

*NOTE* There are two different ways to target users with an LDAP filter for authentication; a filter that targets a Security Group, or a filter that targets an OU.

LDAP Security Group Filter: An LDAP filter that targets a security group uses the Distinguished Name of that group for the Advanced Search, and the top of the domain tree for the Base DN. There is no limit to how many users can be targeted by this filter. It can be a little more cumbersome to setup if the domain users are not organized into security groups, but this filter allows for maximum manageability of your users.

LDAP OU Filter: An LDAP filter that targets an OU uses the Base DN of that OU with a basic search filter. LDAP filters that target an OU are limited to 1000 users.

1)    To authenticate users by OU, use this format:
Search Base DN: OU=Support,OU=Kace,DC=Corp,DC=Kace,DC=com Search Filter: samaccountname=KBOX_USER

2)    To authenticate users by security group, use this format:
Search Base DN: DC=Kace,DC=com
Search Filter: (&(memberOf=CN=Miami Office,OU=KACEGroups,DC=Copr,DC=Kace,DC=com)(samaccountname=KBOX_USER))

3)    This is an example of a filter looking for users only:  

Search Base DN: DC=Kace,DC=com
Search Filter: (&(samaccountname=KBOX_USER)(objectCategory=person))

4)    This is an example of a filter that targets a security group called Sales, but excludes inactive accounts:

Search Base DN: DC=Kace,DC=com
Search Filter: (&(!(msExchUserAccountControl=2))(&(memberOf=CN=Western,OU=Sales,DC=Copr,DC=Kace,DC=com)(samaccountname=KBOX_USER)))

5)    This is an example of a filter that includes only active accounts in a group called sales (note that there may be a difference):
Search Base DN: DC=Kace,DC=com
Search Filter: (&((msExchUserAccountControl=0))(&(memberOf=CN=Western,OU=Sales,DC=Copr,DC=Kace,DC=com)(samaccountname=KBOX_USER)))

6)    This is what a filter might look like in a Novell E-directory setup:
Search Base DN: DC=Kace,DC=com
Search Filter: (&(cn=KBOX_USER)(groupMembership=cn=GROUPNAME,ou=IT,o=Acme))

Troubleshooting Scenarios:

1)    Multiple users are getting locked out:
     a)    The reference account used in the authentication has failed too many times because the password was mistyped in one of the authentication sources. Fix the password and unlock the account.

2)    Only one person in the entire company can log in:
     a)    It is likely that the search filter is not set to (samaccountname=KBOX_USER).
     b)    There could be multiple authentication sources and only one of them is correct.
     c)    The reference account ("LDAP Login" field) that was used only has permissions on certain OUs.

3)    Only the admin account can log in:
     a)    The local KACE appliance has an admin account, (user=admin), that is reserved for bypassing the LDAP authentication in the event that authentication breaks. Make sure that this account password is known and kept safe.

4)    Logging in is really slow:
     a)    At least one of the authentication sources is failing and waiting to timeout before erroring. Typically this means one of the defaults OEM authentication sources and is pointing to a non-existent LDAP server. This should be deleted along with any other LDAP filters that are not in use.

5)    Users promoted to my AD "Admin" group that is assigned to an LDAP filter for the KACE appliance admin role still log in and connect as "Users":
     a)    Once a role is assigned to an account in the KACE appliance (which happens on first login or import) it will not be changed regardless of LDAP filter settings. The Role must manually be changed for that user to reflect the change on the KACE appliance.

6)    Admins that were demoted to my AD "User" group still connect as KACE appliance admins:
     a)    This is the same scenario as above. They are still able to authenticate via the LDAP filter defined for that user role, but their role does not dynamically change in the KACE appliance.

7)    My search results during testing are successful but return 0 rows:
     a)    This happens with the Search Base or the Correct LDAP Login account is incorrect.  Try an administrator or a different search base.

8)    The memberOf information has an asterisk in it so it doesn't work when I search on it. E.g. memberOf=CN=Sales,OU=*Distribution Lists,DC=company,DC=com:
     a)    According to Microsoft’s LDAP Search Filter Syntax, Special characters will need an ‘escape special characters’ to be used: E.g. memberOf=CN=ALL - CDN Sales,OU=\2aDistribution Lists,DC=company,DC=com