Configuring LDAP Authentication¶

This page explains how to configure a CML server to use LDAP for user authentication and authorization. By default, CML uses a local database for user accounts. To use LDAP for user authentication, a local user with administrator rights must change the authentication method for the CML server.

When the CML server is configured to use LDAP, the local user lookup is disabled. Users logging into the CML server will be authenticated and authorized with the external LDAP servers. CML still adds these users to its local user database because specific relationships, such as group memberships and lab ownership, must be associated with a user object. CML cannot modify user objects or add these attributes on the LDAP servers; it stores these relationships in its local database.

LDAP usernames that are added to CML’s local user database are specifically flagged as non-local and cannot be used to log into CML if the configured LDAP servers are unavailable. Similarly, if the CML server’s authentication method is switched back to Local, these non-local user accounts cannot be used to log into CML. The non-local users are still visible in the local user database, and their associated data will still be available when the CML server is switched back to the LDAP authentication method and the LDAP servers are available.

Procedure

Log into the CML UI as a user with administrator privileges.

Click the Tools ‣ System Administration menu item.

On the System Administration page, click User Authentication.

The User Authentication form is shown with the currently-configured Authentication Method.

Configuring the user authentication method¶

Select LDAP from the Authentication Method drop-down.

The page changes to show a form with the LDAP configuration settings.

Enter values for the LDAP configuration settings. The settings are described in detail below.

Use the Test Authentication button to verify that the LDAP configuration works. More details on Test Authentication are provided at the bottom of this page.

Warning

Saving the incorrect LDAP settings can leave you with no way to log into the CML server. Always use the Test Authentication button to test your LDAP configuration settings before saving the changes.

If you save incorrect LDAP settings, or if all LDAP logins are failing, see the section below on Recovering Access when LDAP is Broken.

Click Save to save your changes.

LDAP Configuration Settings¶

This section provides an explanation for each field in the LDAP configuration settings.

Resource Pool/Template¶

How does this field work again???

LDAP Servers¶

Required. Enter the URL for the LDAP server. You may enter multiple servers, separated by whitespace.

Similar to web URLs, an LDAP URL specifies the protocol, the hostname, and the port of the service to use. The complete specification can be found in RFC 4516.

We recommend using TLS encryption to connect to the server (i.e., ldaps:// URLs).

Examples

ldaps://ipam.corp.lab:636
ldaps://amer.corp.com:3269 ldap://emea.corp.com:3269

The second example specifies two servers with the port that is typically used by Active Directory for TLS LDAP access. The different LDAP servers could be hosted in different regions or on different networks to increase availability.

CML uses the LDAP servers in the order that they are listed. If the first server is not responding, then the next server in the list is used. A server that cannot be reached (e.g., because of a timeout or connectivity problem) will not be used again until some time has passed. This retry delay for unreachable servers cannot be modified and is currently set to 5 minutes.

If all of the configured LDAP servers are not responding or are unavailable, then and only then will the CML server fall back to local authentication. Once the LDAP server retry delay has passed, the CML server will again try to authenticate subsequent user logins with the LDAP server. Alternatively, if no LDAP servers are available, you can log into CML using a local user account with administrator privileges and disable LDAP.

Verify TLS¶

Recommended. Check the Verify TLS checkbox if you want CML to verify the X.509 certificates presented by the LDAP servers. If CML fails to verify the certificate, authentication will fail.

CML uses the built-in system certificates and the custom certificate chain (see below) to verify the LDAP servers’ certificates. If your LDAP servers use a private CA certificate, see the Certificate Chain field below.

Root DN¶

Required. The root DN specifies the top level search string to limit the scope of an LDAP query. It is typically something like dc=corp,dc=lab.

The root DN is specific to your LDAP environment, and a non-empty root DN is required.

User Search Base¶

Required. The user search base, when combined with the Root DN, defines the container where users are stored in the LDAP server.

User Filter¶

Recommended. CML uses the user filter to determine whether a user found in the LDAP query is permitted to access the CML server. With no user filter, all users found via the LDAP directory services would be allowed to log into the CML UI. The user filter enables you to restrict which users are allowed to access the CML server.

You would normally create a filter that only matches users who are members of a particular user group or who have a specific attribute. The filter can use logical operations, such as AND, NOT, and OR.

The user filter must include a placeholder for the user ID. The user ID is the string that the user enters in the username field on the CML login page. In the user filter, the user ID is represented by {} or {0}. If you use the {} form, the placeholder can occur exactly once in the user filter. If you use the {0} form, the placeholder can occur multiple times in the filter.

Search filters are specified in RFC 4515.

Examples

(&(uid={})(memberOf=CN=cmlusers,CN=groups,CN=accounts,dc=virl,dc=lab))

This example shows a filter that only permits users who are in a specific user group to log into CML. The filter uses a logical AND, specified by &, to combine two clauses. The first clause indicates that the uid attribute of the user object in the LDAP directory must equal the user ID that the user entered when trying to log into CML. The second clause requires the user to be a member of the specified group. The group is uniquely identified by its Distinguished Name (DN).
(&(uid={0})(|(uid=user1)(uid=user2)))

This example filter restricts access to the CML server to just these two users: user1 and user2. The filter matches the user ID with the uid attribute AND requires that the user ID is either user1 OR user2.

Admin Filter¶

Required. The admin filter is another user filter. If the user who is logging into the CML server matches the admin filter, then CML gives the user administrator privileges. A typical admin filter will require the user to be a member of a specific group.

Note that the user must match both the user filter and the admin filter to login as an admin user. That is, if the admin filter matches the user, but the user filter does not, the user will not be able to log into the CML UI.

Manager DN, Password and Use NTLM¶

To authenticate users and check whether the filters match, CML needs a separate set of credentials to authenticate itself with the LDAP servers. The specified manager user for LDAP does not need any specific privileges beyond looking up users. In particular, the management user does not have to be a directory admin or similar.

Use NTLM

Check this checkbox to enable NTLM. The Use NTLM setting only works with Active Directory and not with regular LDAP servers. When NTLM is enabled, CML communicates with the LDAP (Active Directory) server using NTLM as a protocol.

Manager DN

The full distinguished name (DN) of the manager user. If NTLM is enabled, then you can enter the username in the DOMAIN\username format instead of using the DN.

Manager Password

The password for the manager user. If NTLM is not enabled, CML stores the password itself using symmetric encryption. The actual password value is used when communicating with the LDAP servers. When NTLM is enabled, CML stores the manager password as a hash value, improving security.

Note that the password field is not automatically filled in when editing LDAP settings. If you return to the page to test or edit the LDAP settings, you must enter the password every time.

Depending on what kind of LDAP server is used, different authentication protocols can be used.

Active Directory.: With AD, we recommend using NTLM for authentication. You may specify the manager user in the form of DOMAIN\username instead of providing a DN. The password for the manager user will be stored as an NTLM hash.
All other LDAP servers.: NTLM must be disabled. With non-AD LDAP servers, the manager username must be provided as a distinguished name (DN). Since the SIMPLE authentication must be used in this case, CML stores the actual password for the manager user using symmetric encryption instead of storing a hash.

Important

Regardless of how the manager password is stored, it is always important to use TLS (encryption) to communicate with the LDAP to ensure that user’s passwords are never transmitted in the clear across the network.

Display Name LDAP Attribute¶

The Display Name is the LDAP user attribute that stores the user’s name. The attribute should be the one that is associated with the user’s full name, not the login ID or user ID. CML stores this information in the local user database, and the value may be displayed in the CML UI to help identify the user.

Email Address LDAP Attribute¶

The Email Address is the LDAP user attribute that stores the user’s email address. CML stores this information in the local user database, but it is currently not displayed anywhere in the product.

Certificate Chain¶

The Certificate Chain allows you to provide a private CA’s certificate chain for use with TLS. We recommend always using TLS (encryption) for communicating with the directory servers over LDAP. See the LDAP Servers setting above.

When using TLS, the best practice is to enable the Verify TLS setting. CML performs certificate verification using the CML server’s list of public certificates / anchors / CAs. However, directory services often use a private CA / PKI. If your directory services use a private CA, the certificate chain lets you provide the certificate chain for your private CA.

The certificates must be in PEM format and have the proper framing. Multiple certificates can be concatenated. If your certificate is provided in a binary format, like DER, then you can use openssl to convert the certificate to the required PEM format. For example,

openssl x509 -in cert.der -inform DER -text

Resource Pool¶

The Resource Pool field is an optional setting. If you are using resource limits in your CML instance, you can use this field to ensure that all users are assigned to a resource pool the first time that they log into the CML server. If you leave this field blank, the users will not be assigned to a resource pool automatically. If you

Note that this setting only affects users who log into CML for the first time after you set the Resource Pool field. If you are already using LDAP authentication on your CML instance without setting this field, and then you later set the Resource Pool field, your existing CML users will not be assigned to a resource pool. New users who log into your CML instance after that will be assigned to a resource pool.

If you set the Resource Pool field to a resource pool template, then when new users log in, CML will create a new individual resource pool from that template and assign the user to that new resource pool. If you set the Resource Pool field to a resource pool, new users who log into your CML server after that will simply be assigned to the selected resource pool.

Complete LDAP Example¶

The following example uses fictitious values but illustrates typical types of values for the LDAP settings:

LDAP Settings	Example Value
Server URLs	`ldaps://ipam1.virl.lab:636 ldaps://ipam2.virl.lab`
Verify TLS	`True`
Root DN	`dc=virl,dc=lab`
User Search Base	`CN=users,CN=accounts`
User Filter	`(&(uid={0})(memberOf=CN=cmlusers,CN=groups,CN=accounts,dc=virl,dc=lab))`
Admin Filter	`(&(uid={0})(memberOf=CN=cmladmins,CN=groups,CN=accounts,dc=virl,dc=lab))`
Use NTLM	`False`
Manager DN	`uid=ldapromgr,cn=users,cn=accounts,dc=virl,dc=lab`
Manager Password	`somepassword`
Display Name LDAP Attribute	`displayName`
Email Address LDAP Attribute	`email`
Certificate Chain	`-----BEGIN CERTIFICATE----- ...`

Using these example settings, suppose a user entered their username and their correct password on the CML login page. To authenticate the user, the CML server would contact one of the two LDAP servers, using TLS and verifying the LDAP server’s certificate. When verifying the certificate, the CML server would use the supplied certificate chain in addition to the server’s root certificates.

CML would search for users in a common name (cn) users in accounts inside of the virl / lab domain component (dc) in the LDAP directory services. The matching user object would be found, and the LDAP server would verify the password. After successful LDAP authentication, CML would check the user against the two filters.

The user and admin filters not only restrict which users are permitted to log into CML but also control the user’s privileges within CML. If the username matches the uid property of the user object, and the user is a member of the cmlusers group, CML logs the user into the CML UI. If the username matches the uid property of the user object in the LDAP directory services, and the user is a member of the cmladmin group with the specified DN, then CML will also grant the user administrator privileges.

When CML queries the LDAP servers, it connects to the LDAP server as the ldapromgr user. In this case, the LDAP server is a FreeIPA server. Therefore, it does not support NTLM, and the LDAP settings must provide the the manager’s full DN and password.

Testing LDAP Configuration¶

The LDAP configuration form provides a built-in test facility. After entering the LDAP configuration settings, but before saving the configuration, click the Test Authentication button to perform authentication tests and verify that the LDAP configuration is correct and returning the expected results. CML never pre-fills the Manager Password field. If you are editing the existing LDAP settings, remember to enter the Manager Password field before clicking the Test Authentication button.

Click the Test Authentication button. Then enter the Username and Password of a user in your LDAP servers. If the user is found in LDAP and the credentials match, the Test Authentication dialog will indicate Authenticated is true and the other fields will be displayed. If the the user is not found in the specified root DN + user search base, the user does not match the user filter, or the credentials do not match, then Authenticated is false, and all of the other fields will be empty.

In the example given above, the user jdoe with the provided password was successfully authenticated by the LDAP servers.

This means that the user ID matched the provided user filter, and this user would be able to log into the CML server.

The provided admin filter did NOT match, and the user would not have administrator privileges in CML.

In addition, the values for the display name and the email attributes are shown if matching fields were included in the data returned by the LDAP servers.

The Attributes field shows all the attributes returned by the LDAP query for the provided credentials. You may find this information useful when you are creating the filters for the LDAP settings. For example, you can see the user’s group memberships in the Attributes text area.

If you keep getting an authentication failure in the test dialog, click Close to close the dialog and then simplify the User Filter setting. Using a trivial filter to match exactly one user ID ensures that if the user is found in LDAP, the user object will match the user filter. For example, if you want to test with the user jdoe and the user ID attribute in your LDAP system is uid, then set the filter to:

(&(uid={0})(uid=jdoe))

Note that Microsoft ActiveDirectory normally uses the attribute sAMAccountName for the user’s login ID. In that case, try setting the User Filter to:

(&(sAMAccountName={0})(sAMAccountName=jdoe))

Now, click the Test Authentication button again and test the authentication for jdoe. If you entered the jdoe user’s password correctly, and the result still indicates Authenticated false, click Close to close the test dialog. Double-check the Root DN and User Search Base properties. Since the user filter should match the user object for jdoe, the most likely reason that a matching user is still not found is a typo or other mistake in one of those two fields. Once you fix any problems there, always verify the settings with Test Authentication before saving the changes.

Once you are able to get a test result where Authenticated is true, you have verified that your LDAP server, manager DN, manager password, root DN, and user search base are all working. Of course, only our test user, jdoe in this example, can log into CML. You still need to configure the user filter and admin filter. Click Close to close the test dialog and return to the page to adjust those filters and then Test Authentication again to verify that they work as expected. Since you know that the other settings are now correct, if your user filter test result is Authenticated false, you know that there’s a problem in the user filter itself. Repeat the same process with the admin filter and the Admin field in the Test Authentication dialog.

Recovering Access when LDAP is Broken¶

Note that if you configure CML to use LDAP, and the LDAP settings are incorrect, you may find that no one can log into the CML server. Once CML is configured to use the LDAP Authentication Method, all login attempts are authenticated via LDAP. Therefore, even the local admin user will be unable to log into the CML server. If CML can reach the LDAP servers over the network, it will not fall back to local authentication even if it fails to bind to the LDAP servers.

To restore access to CML when it is in this state, you must disconnect the CML server from the network or otherwise block its network access to the configured LDAP servers. For example, you can log into Cockpit (see Logging into the System Administration Cockpit), and click Terminal. In the Cockpit terminal, add a firewall rule to prevent the CML server from sending any traffic on the port that your LDAP server is using (normally port 389 or 636):

# Prevent traffic from this server to port 389
sudo ufw deny out to any port 389
# Enable the firewall
sudo ufw enable

Enabling this firewall rule prevents your CML server from connecting to the LDAP servers. If CML fails to reach all of the LDAP servers in its list, it will fall back to local authentication. You can use this approach to log into the CML UI as a local user with administrator privileges. Once you login as a local administrator, you can correct the LDAP settings or change the Authentication Method back to Local. Note that after you login as a local administrative user, you must disable the firewall in the Cockpit terminal before you attempt to correct the LDAP settings:

sudo ufw status numbered

# Output of ufw status numbered
#   Status: active
#
#     To                         Action      From
#     --                         ------      ----
#[ 1] 389                        ALLOW OUT   Anywhere                   (out)
#[ 2] 389 (v6)                   ALLOW OUT   Anywhere (v6)              (out)

# Delete the rules that we added above, using the numbers in the ufw status output.
sudo delete 2
sudo delete 1
# Disable the firewall.
sudo ufw disable