Configuring LDAP Authentication¶

This page explains how to configure a CML server to use LDAP for user authentication and authorization, and group management. By default, CML uses a local database for user accounts and groups. To use LDAP for user authentication and group management, 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 and group lookup is disabled. Users logging into the CML server will be authenticated and authorized with the external LDAP servers, and group memberships will be synchronized from LDAP. CML still adds these users and groups to its local database because specific relationships, such as group memberships and lab ownership, must be associated with user and group objects. CML cannot modify user or group 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.

LDAP groups are treated similarly. When you enable LDAP group management, you can no longer create local groups on the CML server. Instead, when you attempt to create a group, the CML server will search the LDAP server for a group with that name and, if found, will create that group in the local database with a non-local flag.

The CML server synchronizes group memberships from LDAP each time a user logs in to the CML instance, ensuring that users are automatically added to the appropriate groups in CML based on their LDAP group membership. You can configure this synchronization process to check either each user’s group membership attributes or to use a group membership filter to determine the list of users for each group. Note that you can disable LDAP group synchronization by not setting or by clearing the group search filter. If you enable LDAP authentication, but there is no group search filter, you can create and manage local groups in CML again just like when the CML server’s authentication method is set to local.

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.

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¶

Applicable when using ldaps://, not relevant with ldap://. 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. When enabled, it is expected to add a certificate chain (unless the LDAP server’s certificate was signed by a recognized CA root, like Verisign). On the other hand, if you disable Verify TLS, CML will not bother to verify the LDAP server’s certificate, which is less secure.

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¶

Recommended. The user search base, when combined with the root DN, defines the container where the CML server will look for users on the LDAP server. If the user search base is not set, the CML server will use the root DN on its own.

Note

The user search base should not contain any elements from root DN, because CML will concatenate the root DN and the user search base to query the LDAP Database. For example: If the root DN is dc=virl,dc=lab and the user search base is CN=users,CN=accounts, CML will use dc=virl,dc=lab,CN=users,CN=accounts for querying 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.

Group Search Base¶

Recommended if using LDAP groups. The group search base, when combined with the root DN, defines the container where the CML server will look for groups on the LDAP server. If the group search base is not set, the CML server will use the root DN on its own.

Note

The group search base should not contain any elements from the root DN, because CML will concatenate the root DN and the group search base to query the LDAP Database. For example: If the root DN is dc=virl,dc=lab and the group search base is CN=groups,CN=accounts, CML will use dc=virl,dc=lab,CN=groups,CN=accounts for querying the LDAP server.

Group Via User¶

Required if using LDAP groups. Determines how the CML server retrieves a user’s group memberships from the LDAP server.

If enabled, it uses the Group User Attribute. If disabled, uses the Group Membership Filter. See below for details.

Group User Attribute¶

Required if Group Via User is enabled. The attribute of the user that holds the group memberships. Each user must have an attribute with the name specified in the group user attribute. This attribute must contain a list of DNs of groups. When synchronizing memberships, the CML server will make the user a member of every group that is in the list and removes the user from groups that are not in the list.

Examples

memberOf

In this example, all user objects on the LDAP server must have a memberOf attribute. CML reads that attribute’s value when synchronizing group memberships for the user, and CML will ensure that the user is a member of any synchronized group that’s listed in that attribute.

Group Membership Filter¶

Required if Group Via User is disabled. The group membership filter is used when synchronizing group memberships. The CML server replaces the placeholder ({} or {0}) with the DN of a user, and executes an LDAP search. The CML server then makes the user a member of every group that is returned by the search and removes the user from groups that are not returned.

Please read the section User Filter above for details on how to write a filter.

Examples

(member={0})

In this example when synchronizing group memberships, for each user, CML will search the LDAP server for all groups that have the attribute member and said attribute contains the DN of the user in question. It will then make the user a member of each such group.

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 can be optionally displayed in the CML dashboard UI to help identify the owner of the labs.

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.

If the LDAP server’s certificate was issued by an internal or private CA, which is not publicly recognized, authentication testing may return an error indicating that the certificate validation failed, unable to get local issuer certificate. Then it is required to provide the internal CA Root certificate in the certificate field.

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))`
Group Search Base	`CN=groups,CN=accounts`
Group Search Filter	`(&(cn={0})(objectclass=posixgroup))`
Group Via User	`True`
Group User Attribute	`memberOf`
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.

Next, suppose an administrator attempted to create a group by entering the group name in the administrative section of the CML UI and clicking Create. To create the group, the CML server would contact one of the two LDAP servers with the same configuration as before. It would then search for groups in a common name (CN) groups in accounts inside of the virl / lab domain component (DC) in the LDAP directory services, while also filtering out groups that do not match the group search filter. The matching group object would be found, and a group would be created in the local database.

When a group is created and every time an LDAP user logs in afterwards, group memberships are refreshed. When refreshing memberships, the CML server contacts the LDAP servers the same way as before and retrieves the memberOf attribute of every user that has logged into CML before. The user is then added to every LDAP group that has been created in CML, if that group’s distinguished name (DN) is found in the memberOf attribute.

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 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 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 or there was a change in the LDAP server, 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, Login to Cockpit ‣ Click CML2 ‣ Factory Reset ‣ Authentication Reset (see Logging into the System Administration Cockpit).

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.

Local authentication fallback¶

In certain scenarios where LDAP authentication fails, CML will automatically fall back to local authentication for that authentication attempt. The following are all possible scenarios in which this fallback occurs.

Could not establish a valid connection to any LDAP server after 5 attempts, due to errors such as
- Could not bind user
- Failed to open socket
- Session was unexpectedly terminated by the server
- Unsolicited, malformed, or otherwise erroneous message received from server
- Error while sending message to server
- Certificate error
- Other unexpected errors
Invalid search filter, i.e.
- Invalid filter format
- More than one {} placeholder in filter
- Invalid base DN or root DN format
No manager password provided
Unknown authentication method
If using NTLM
- Missing username/domain or password
Any other unexpected LDAP error

The fallback will NOT trigger in the following circumstances:

Manager password is incorrect
User/admin filter failed to match
User authentication failed
Missing username/password (except for NTLM)

Configuring LDAP Authentication¶

LDAP Configuration Settings¶

LDAP Servers¶

Verify TLS¶

Root DN¶

User Search Base¶

User Filter¶

Admin Filter¶

Group Search Base¶

Group Search Filter¶

Group Via User¶

Group User Attribute¶

Group Membership Filter¶

Manager DN, Password and Use NTLM¶

Display Name LDAP Attribute¶

Email Address LDAP Attribute¶

Certificate Chain¶

Resource Pool¶

Complete LDAP Example¶

Testing LDAP Configuration¶

Recovering Access when LDAP is Broken¶

Local authentication fallback¶