LDAP
ClusterControl supports integration with directory services like Active Directory, FreeIPA, and OpenLDAP authenticatio using lightweight directory access protocol (LDAP). This allows users to log into ClusterControl by using their corporate credentials instead of a separate password. LDAP groups can be mapped onto ClusterControl user groups to apply privileges to the entire group. This ensures that ClusterControl authorizes the logged-in user based on the group assigned. It supports up to the LDAPv3 protocol based on RFC2307.
To integrate with a directory service, one has to perform the following steps:
- Fill up the LDAP Settings configuration wizard. See LDAP Settings.
- Save the settings. At this point, LDAP is saved but not activated because no group mapping has been created yet.
- Create at least one group mapping entry by going to Map LDAP Group. See Map LDAP Group.
- Enable the LDAP authentication by toggling on the LDAP Settings → Enable LDAP Authentication.
- Log in to ClusterControl by using the value of LDAP Username Attributes with the respective password. The user will be authenticated and redirected to the ClusterControl dashboard page based on the assigned group.
- From this point, both ClusterControl native authentication and LDAP authentications are enabled.
Attention
The last entry of the group mapping can not be deleted while LDAP authentication is enabled and activated. See Delete mapping group.
LDAP settings
| Field | Description |
|---|---|
| General Settings | |
| Enable LDAP Authentication | Enables LDAP authentication. The native authentication in ClusterControl will also work. Refer to the steps mentioned above, on enabling LDAP authentication. |
| LDAP/LDAPS URI | Enter the LDAP or LDAPS Uniform Resource Identifier (URI), with the port number (if applicable). An example is ldaps://ad.s9s.com:636. For LDAPS, provide the certificates and key files under SSL/TLS Settings section. |
| Login DN | The Distinguished Name is used to bind the LDAP server. This user requires read access to all LDAP users and group entries to work correctly. ClusterControl must perform an LDAP search using the DN before any user can log in. This field is case-sensitive. An example is cn=Administrator,cn=Users,dc=s9s,dc=com. |
| Login DN Password | The password for Login DN. |
| User Base DN | The Distinguished Name (DN) to locate the users’ information. This field is case-sensitive. An example is cn=Users,dc=s9s,dc=com. |
| Group Base DN | The Distinguished Name (DN) to locate the group information. ClusterControl does not support LDAP users that do not belong to at least one LDAP group. An example is ou=Groups,dc=s9s,dc=com. |
| Advanced | |
| Pre-fill for | Fill up all required fields based on common settings for Active Directory or OpenLDAP. Clicking on Reset will clear all textfields. |
| User Base Filter | Filter the object class of the LDAP users. If empty, all object classes will be returned. |
| Username Attributes | The LDAP attributes which hold the username, separated by a comma (whitespace value is not allowed). For Active Directory, this is commonly sAMAccountName and uid for OpenLDAP. When authenticating with ClusterControl (via ClusterControl GUI login page, ClusterControl CLI or RPC API), use the value of this attribute. If more than one attribute is specified, ClusterControl will attempt to look up all of them with the first non-empty reply (in the particular order) used for the login username. |
| Real Name Attributes | The LDAP attributes which hold the full name of the user, separated by a comma. For Active Directory, this is commonly displayName and cn for OpenLDAP. This value of this attribute will be used as the first and last name of the user. If more than one attribute is specified, ClusterControl will attempt to look up all of them with the first non-empty reply (in the particular order) used for the user’s full name. |
| Email Attributes | The LDAP attributes which hold the email address of the user, separated by a comma. For Active Directory, this is commonly userPrincipalName and mail for OpenLDAP. This value of this attribute will be used as the email address of the user. If more than one attribute is specified, ClusterControl will attempt to look up all of them with the first non-empty reply (in the particular order) used for the user’s email address. |
| Group Base Filter | Filter the object class for the LDAP groups. If empty, all object classes will be returned. |
| Static Member Attributes | The LDAP attributes which represent the group’s members, separated by a comma. For Active Directory, this is commonly member. For OpenLDAP, posixGroup uses memberUid, while groupOfNames uses member. The value of these attributes will be used to create combinations with the value of Group Mapping Attributes when querying the LDAP server to retrieve the group’s information. |
| Group Mapping Attributes | The LDAP attributes of which name holds the group membership, separated by a comma. For Active Directory, this is commonly dn and uid for OpenLDAP. The value of these attributes will be used to create combinations with Static Member Attributes to query the LDAP server to retrieve the group. |
| Group Name Attributes | The LDAP attribute where the name represents the group’s name. This is commonly cn. The value of this attribute will be used in the group mapping with ClusterControl's Team for authorization purposes. |
| Network Timeout | The connection timeout in seconds if the LDAP server is unreachable or takes too long to respond. |
| Protocol Version | The current LDAP protocol version is used. |
| Time Limit | The limit in seconds for an LDAP query to finish, any query that takes longer will be aborted. |
| SSL/TLS | |
| CA Cert File | Only if specified ldaps:// in the LDAP URI. This is the location of the CA certificate file on the ClusterControl host. |
| Certificate File | Only if specified ldaps:// in the LDAP URI. This is the location of the certificate file on the ClusterControl host. |
| Key File | Only if specified ldaps:// in the LDAP URI. This is the location of the key file on the ClusterControl host. |
Map LDAP group
ClusterControl requires at least one LDAP group mapping entry to be defined before the LDAP authentication can be activated. Otherwise, ClusterControl would only save the LDAP settings without activating them.
To create a group mapping:
- Click on the Map LDAP Group button.
- Choose an existing team from the dropdown and specify the value of the LDAP’s Group Name Attributes that you want to be mapped with the ClusterControl team. For single-tier RDN, specify the attribute value for example "DBA". ClusterControl will prepend the Group name attribute configured under the LDAP Settings with the value specified, and append it with the Group base DN value. The final constructed DN will be
{Group name attribute}={value specified},{Group base DN}. For multi-tier RDNs, specify the attribute name and value (for multiple RDNs, delimited by a comma) for examplecn=DBA,cn=IT,ou=org1. ClusterControl will append the value specified with the Group base DN value under the LDAP Settings. The final constructed DN will be{value specified},{Group base DN}. - After creating the first entry, you may proceed to activate the LDAP authentication by going to LDAP Settings → Enable LDAP Authentication.
All LDAP configurations and mappings will be stored inside a configuration file at /etc/cmon-ldap.cnf. It is recommended to configure LDAP settings and group mappings via the ClusterControl GUI because any changes to this file will require a reload to the controller process, which is triggered automatically when configuring LDAP via the GUI.
Note
It is also possible to modify the configuration file directly, however, the cmon service must be reloaded manually by using the systemctl restart cmon command, or service cmon restart.
Delete mapping group
Click on Delete of the entry in the list to delete it. The last entry of the group mapping can not be deleted while LDAP authentication is enabled and activated (the button will be greyed out). To delete the last entry, set Enable LDAP Authentication to OFF and you will notice the Remove Group button is now clickable, allowing you to remove the last group mapping entry and effectively deactivating LDAP authentication for ClusterControl.