User Management

Team and Users

A user belongs to one or more teams. Users created here will be able to log in and see specific cluster(s), depending on their team and the cluster they have been assigned to.

Teams group users. Each team may consist of zero or more users. A single user may be a part of one team. Teams may be assigned to zero or more clusters.

Access Control

ClusterControl uses access control to restrict access to clusters and their respective deployment, management, and monitoring features. Access control defines privileges and permissions for a specific team. This ensures that only authorized user requests are allowed.

The privileges are depending on the ClusterControl components as described below:

For the “clusters” component, only the owner’s team is allowed to delete the cluster. All clusters created by a specific user also belong to the same team.

LDAP Settings

ClusterControl supports integration with directory services like Active Directory, FreeIPA, and OpenLDAP authentication. 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 would ensure 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:

1. Fill up the LDAP Settings.
2. Save the settings. At this point, LDAP is saved but not activated because no group mapping has been created yet.
3. Create at least one group mapping entry by going to Map LDAP Group.
4. Enable the LDAP authentication by toggling ON the LDAP Settings → Enable LDAP Authentication.
5. Log in into ClusterControl by using the value of Username Attributes with the respective password. The user will be authenticated and redirected to the ClusterControl dashboard page based on the assigned group.
6. From this point, both ClusterControl and LDAP authentications would work.

The last entry of the group mapping can not be deleted while LDAP authentication is enabled and activated. To delete the last entry, set Enable LDAP Authentication to OFF and you will notice the Remove Group button is no longer greyed out, allowing you to remove the last group mapping entry.

LDAP Settings

Map LDAP Groups

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. Pick 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. 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 this configuration file, /etc/cmon-ldap.cnf. It is recommended to configure LDAP setting and group mappings via the ClusterControl UI because any changes to this file will require a reload to the controller process, which is triggered automatically when configuring LDAP via the UI. You may also make direct modifications to the file, however, you have to reload the cmon service manually by using the systemctl restart cmon command, or service cmon restart.

Enabling New User Management

If you are running old version of ClusterControl i.e. versions <=1.8.2, once you view any of your cluster dashboards, a prompt should be visible to enable new User Management. The example screenshot below (with the marked in red rectangular box) has to be clicked.

Once click, ClusterControl will transition a pop-up UI in the right side corner allowing you to create a New Admin User. Technically, ClusterControl will be able to detect if you have a current user that is already compatible to the New User Management. Which means, if you have been from versions < 1.8.2 and just upgraded to the latest version of ClusterControl (i.e. >= 1.8.2), your current users are not yet compatible to the New User Management. That’s why ClusterControl will let you create a New Admin User. Otherwise, if this prompt is click but you have a user that is already compatible for the “New” User Management, you will be redirected to the main User Management UI.

Creating New Admin User

Clicking on the link allows to create a new administrator account for the new system. Take note that the User name field is case sensitive. ClusterControl technically creates an admin user. In that case, you cannot re-use admin for User name, but Admin as your User name is allowed. The screenshot below allows ClusterControl to create an Admin user apart from its default admin user in this case.

Once the user is created, the following prompt will appear:

As stated, it is required to log out now and log in as a newly added user.

After this, new options will be accessible in the User Management screen:

From version 1.8.2,

Starting from version 1.9.0, we no longer have the old settings for User Management.

 

Creating a New Team

To create a new team, click on the Create Team button and give a name to the team:

Creating a New User

A user belongs to one team. Users created here will be able to log in and see specific cluster(s), depending on their team and the cluster they have been assigned to.

To create a user, click on the Create User button and specify the details:

Users may be deleted, edited, or have their password reset. Users can be active or disabled.

Assigning Privileges

Access control defines privileges and permissions for a specific team. There are up to three privileges:

Access privileges are granted to teams for the following resources:

• Clusters
• Cluster Deployment
• LDAP Configuration
• Controller Configuration

From version 1.8.2,

Since version 1.9.0, we no longer have the old settings for User Management. Access Control can be viewed then by just clicking other than Access Control tab as shown below,

It is also possible to use the “wildcard” team: “All Other Teams”. This privilege will be applied to users that are members of a team other than the team that created a given cluster and teams other than those explicitly listed. From the screenshot above, this means that for all the list of “Clusters“, only the owner that deployed the cluster have access (including the admins – which has all access of the clusters by default), while “All Other Teams” have “No Access” at all. For more details on the privileges, see Access Control.

LDAP Migration Procedure

In the previous versions (1.8.1 and older), LDAP authentication was handled by the frontend component through a number of tables (dcps.ldap_settings and dcps.ldap_group_roles). Starting from ClusterControl 1.8.2, the new LDAP authentication is handled by the backend component and all LDAP-related configuration will reside in /etc/cmon-ldap.cnf.

The older implementation (frontend LDAP) will be automatically disabled, therefore it is necessary to perform this migration for a working LDAP authentication in 1.8.2.

Migrating LDAP Configurations

1) Retrieve the old LDAP settings from the ClusterControl server:

$ mysql -uroot -p dpcs
MariaDB [dcps]> SELECT * FROM ldap_settings\G
*************************** 1. row***************************
              id: 1
enable_ldap_auth: 1
            host: ad.s9s.com
            port: 389
           login: CN=Administrator,CN=Users,DC=s9s,DC=com
        password: ¦Qiç¾÷É5žu
        base_dsn: DC=s9s,DC=com
         user_dn: CN=Users,DC=s9s,DC=com
        group_dn: OU=Groups,DC=s9s,DC=com

2) Based on the collected information above, we can configure the new LDAP Configuration Settings under ClusterControl → User Management → LDAP Settings, with the following details:

• General Settings
  • Enable LDAP Authentication: No
  • LDAP/LDAPS URI: {Construct the URI based on ldap(s)://{value of “host”}:{value of “port”}, as in the ldap_settings. If you use LDAPS, configure the TLS configuration under SSL/TLS Settings}
  • Login DN: {The value of login, as in the ldap_settings table}
  • Login DN password: {The password of Login DN. Do not take the value from ldap_settings table since the value is encrypted}
  • User Base DN: {The value of user_dn, as in the ldap_settings table}
  • Group Base DN: {The value of group_dn, as in the ldap_settings table}
• Advanced Settings
  • User base filter: {Set to empty, unless you want to filter specific objectclasses during LDAP user lookups}
  • Username attributes: {Set to sAMAccountName for Active Directory, or uid for OpenLDAP}
  • Real name attributes: {Set to displayName for Active Directory, or cn for OpenLDAP}
  • Email attributes: {Set to userPrincipalName, or mail for OpenLDAP}
  • Group base filter: {Set to empty, unless you want to filter specific objectclasses during LDAP group lookups}
  • Static member attributes: {Set to member for Active Directory. For OpenLDAP, posixGroup uses memberUid, while groupOfNames uses member}
  • Group mapping attributes: {Set to dn for Active Directory, or uid for OpenLDAP}
  • Group name attribute: {Set to cn for both Active Directory and OpenLDAP}
• SSL/TLS Settings
  • CA cert file: {Location of CA cert file on the ClusterControl server}
  • Certificate file: {Location of TLS certificate file on the ClusterControl server}
  • Key file: {Location of TLS key file on the ClusterControl server}

3) Click the Save Settings button to save the configuration. At this point, LDAP authentication is NOT activated since we specified “No” under Enable LDAP Authentication. ClusterControl does not allow enabling LDAP authentication without a group mapping. Therefore, we need to set this to “No” at the initial stage where ClusterControl will only save the LDAP Configurations without activating it.

Migrating Group Mappings

1) Retrieve the old group mapping from the dcps database on the ClusterControl server:

$ mysql -uroot -p dcps
MariaDB> SELECT lg.id, lg.ldap_group_name AS "LDAP Group", r.role_name AS "Role", c.name AS "Team" FROM ldap_group_roles lg, roles r, companies c WHERE lg.role_id=r.id AND lg.company_id=c.id;
+----+------------+-------------+-------+
| id | LDAP Group | Role        | Team  |
+----+------------+-------------+-------+
|  1 | CN=DBA     | Super Admin | Admin |
|  2 | CN=Dev     | Admin       | Dev   |
+----+------------+-------------+-------+

Based on the above output, pay attention to the following:

• LDAP Group: This mapping should be similar to the new LDAP Settings. However, in the new implementation, the attribute name (CN) should be specified as LDAP Settings → Advanced Settings → Group name attribute. When specifying the group mapping, just set the attribute value (DBA or Dev).
• Role: There will be no role in the new user management. Instead, it is equivalent to user permission in the new user management which is “No Access”, “Read” or “Admin”.
• Team: In the new user management, this term is corresponding to “group”. To check out the group, run s9s user --list-groups. A user must belong to a group, thus ClusterControl will automatically map the LDAP user with the mapped group. An LDAP group that is not mapped has no authorization to log into ClusterControl.

2) Now we need to create ClusterControl groups (or you can use any existing groups) for this purpose. Since we are going to have two LDAP groups to log into the ClusterControl system, we will create two ClusterControl groups called “DBA” and “Dev” to be mapped on. Go to ClusterControl → User Management → Teams and Users → Create Team and create the following groups:

• DBA
• Dev

3) Optionally, you can map a cluster to a group by going to ClusterControl → User Management → Access Control → Clusters. Click on the Add Team button for the corresponding cluster and specify the following:

• Team: DBA (select from the dropdown)
• Permissions: Admin

Repeat the same step to allow access for other groups to any cluster, as in this case is “Dev”.

4) Now we can perform the LDAP group mapping. Go to ClusterControl → User Management → LDAP Settings → Map LDAP Group, and specify the following for group DBA:

• ClusterControl Team: DBA
• LDAP Group: DBA (which basically translates to CN=DBA,OU=Groups,DC=s9s,DC=com)

5) Repeat step #4 for the other groups, like in this case Dev:

• ClusterControl Team: Dev
• LDAP Group: Dev (which basically translates to CN=Dev,OU=Groups,DC=s9s,DC=com)

6) We can then enable the LDAP authentication by toggling ON Enable LDAP Authentication under ClusterControl → User Management → LDAP Settings → General Settings. Note that you can not delete the last group mapping entry in the list until you disable again LDAP Authentication. In simple words, enabling LDAP authentication is only allowed if there is at least one group mapping entry.

At this point, the LDAP configuration is complete. You may open a new browser and try to authenticate as an LDAP user. The username to log in is the value of Username Attributes.

Troubleshooting

• ClusterControl Controller (cmon) will log all user authentication into /var/log/cmon.log. Observe this logfile when troubleshooting all LDAP authentication issues.
• All LDAP configurations will be stored inside this configuration file, /etc/cmon-ldap.cnf. It is recommended to configure LDAP via the ClusterControl UI because any changes to this file will require a reload to the controller process, which is triggered automatically when configuring LDAP via the UI. You may also make direct modifications to the file, however, you have to reload the cmon service manually by using the systemctl restart cmon command, or service cmon restart.
• For reference, a working LDAP authentication should have the configuration file, /etc/cmon-ldap.cnf looking something like this (example for Active Directory, without TLS):

  $ grep -v '^\s*$\|^\s*\#' /etc/cmon-ldap.cnf
  enabled = true
  ldapServerUri = "ldap://ad.s9s.com"
  ldapAdminUser = "cn=Administrator,cn=Users,dc=s9s,dc=com"
  ldapAdminPassword = "moyGp6pUwLZ"
  ldapUserSearchRoot = "cn=Users,dc=s9s,dc=com"
  ldapGroupSearchRoot = "ou=Groups,dc=s9s,dc=com"
  [ldap_settings]
  ldapUserClassName = ""
  ldapUsernameAttributes = "sAMAccountName"
  ldapRealnameAttributes = "displayName"
  ldapEmailAttributes = "userPrincipalName"
  ldapGroupClassName = ""
  ldapMemberAttributes = "member"
  ldapGroupIdAttributes = "dn"
  ldapGroupNameAttribute = "cn"
  [security]
  [mapping0]
  ldapGroupId   = "DBA"
  cmonGroupName = "DBA"
  [mapping1]
  ldapGroupId   = "Dev"
  cmonGroupName = "Dev"