After upgrading to ClusterControl 1.8.2, you should get the following notification banner:
What's up with that? It is a depreciation notice of the current user management system in favor of the new user management system handled by the ClusterControl controller service (cmon). When clicking on the banner, you will be redirected to the user creation page to create a new admin user, as described in this user guide.
In this blog post, we are going to look into the new user management system introduced in ClusterControl 1.8.2, and to see how it is different from the previous ones. Just for clarification, the old user management system will still work side-by-side with the new user authentication and management system until Q1 2022. From now on, all new installations for ClusterControl 1.8.2 and later will be configured with the new user management system.
User Management pre-1.8.2
ClusterControl 1.8.1 and older stores the user information and accounting inside a web UI database called "dcps". This database is independent of the cmon database that is used by the ClusterControl Controller service (cmon).
User Accounts and Authentication
A user account consists of the following information:
Name
Timezone
Email (used for authentication)
Password
Role
Team
One would use an email address to log in to the ClusterControl GUI, as shown in the following screenshot:
Once logged in, ClusterControl will look up for the organization the user belongs to and then assign the role-based access control (RBAC) to access a specific cluster and functionalities. A team can have zero or more clusters, while a user must belong to one or more teams. Creating a user requires a role and team created beforehand. ClusterControl comes with a default team called Admin, and 3 default roles - Super Admin, Admin and User.
Permission and Access Control
ClusterControl 1.8.1 and older used a UI-based access control based on role assignment. In another term, we called this role-based access control (RBAC). The administrator would create roles, and every role would be assigned a set of permissions to access certain features and pages. The role enforcement happens on the front-end side, where ClusterControl controller service (cmon) has no idea on whether the active user has the ability to access the functionality because the information is never been shared among these two authentication engines. This would make authentication and authorization more difficult to control in the future, especially when adding more features that compatible with both the GUI and CLI interfaces.
The following screenshot shows the available features that can be controlled via RBAC:
The administrator just needs to pick the relevant access level for specific features, and it will be stored inside the "dcps" database and then used by the ClusterControl GUI to permit UI resources to the GUI users. The access list created here has nothing to do with the CLI users.
LDAP
ClusterControl pre-1.8.1 used the PHP LDAP module for LDAP authentication. It supports Active Directory, OpenLDAP and FreeIPA directory services but only a limited number of LDAP attributes can be used for user identification such as uid, cn or sAMAccountName. The implementation is fairly straightforward and does not support advanced user/group base filtering, attributes mapping and TLS implementation.
The following are the information needed for LDAP settings:
Since this is a frontend service, the LDAP log file is stored under the web app directory, specifically at /var/www/html/clustercontrol/app/log/cc-ldap.log. An authenticated user will be mapped to a particular ClusterControl role and team, as defined in the LDAP group mapping page.
User Management post-1.8.2
In this new version, ClusterControl supports both authentication handlers, the frontend authentication (using email address) and backend authentication (using username). For the backend authentication, ClusterControl stores the user information and accounting inside the cmon database that is used by the ClusterControl Controller service (cmon).
User Accounts and Authentication
A user account consists of the following information:
Username (used for authentication)
Email address
Full name
Tags
Origin
Disabled
Suspend
Groups
Owner
ACL
Failed logins
CDT path
If compared to the old implementation, the new user management has more information for a user, which allows complex user account manipulation and better access control with enhanced security. A user authentication process is now protected against brute-force attacks and can be deactivated for maintenance or security reasons.
One would use an email address or username to log in to the ClusterControl GUI, as shown in the following screenshot (pay attention to the placeholder text for Username field):
If the user logs in using an email address, the user will be authenticated via the deprecating frontend user management service and if a username is supplied, ClusterControl will automatically use the new backend user management service handled by the controller service. Both authentications work with two different sets of user management interfaces.
Permission and Access Control
In the new user management, permissions and access controls are controlled by a set of Access Control List (ACL) text forms called read (r), write (w), and execute (x). All ClusterControl objects and functionalities are structured as part of a directory tree, we called this CMON Directory Tree (CDT) and each entry is owned by a user, a group, and an ACL. You can think of it as similar to Linux file and directory permissions. In fact, ClusterControl access control implementation follows the standard POSIX Access Control Lists.
To put into an example, consider the following commands. We retrieved the Cmon Directory Tree (CDT) value for our cluster by using "s9s tree" command line (imagine this as ls -al in UNIX). In this example, our cluster name is “PostgreSQL 12”, as shown below (indicated by the "c" at beginning of the line):
$ s9s tree --list --long
MODE SIZE OWNER GROUP NAME
crwxrwx---+ - system admins PostgreSQL 12
srwxrwxrwx - system admins localhost
drwxrwxr-- 1, 0 system admins groups
urwxr--r-- - admin admins admin
urwxr--r-- - dba admins dba
urwxr--r-- - nobody admins nobody
urwxr--r-- - readeruser admins readeruser
urwxr--r-- - s9s-error-reporter-vagrant admins s9s-error-reporter-vagrant
urwxr--r-- - system admins system
Total: 22 object(s) in 4 folder(s).Suppose we have a read-only user called readeruser, and this user belongs to a group called readergroup. To assign read permission for readeruser and readergroup, and our CDT path is “/PostgreSQL 12” (always start with a “/”, similar to UNIX), we would run:
$ s9s tree --add-acl --acl="group:readergroup:r--""/PostgreSQL 12"
Acl is added.
$ s9s tree --add-acl --acl="user:readeruser:r--""/PostgreSQL 12"
Acl is added.Now the readeruser can access the ClusterControl via GUI and CLI as a read-only user for a database cluster called "PostgreSQL 12". Note that the above ACL manipulation examples were taken from the ClusterControl CLI, as described in this article. If you connect through ClusterControl GUI, you would see the following new access control page:
ClusterControl GUI provides a more simple way of handling the access control. It provides a guided approach to configure the permissions, ownership and groupings. Similar to the older version, every cluster is owned by a team, and you can specify a different team to have a read, admin, or forbid another team from accessing the cluster from both ClusterControl GUI or CLI interfaces.
LDAP
In the previous versions (1.8.1 and older), LDAP authentication was handled by the frontend component through a set of tables (dcps.ldap_settings and dcps.ldap_group_roles). Starting from ClusterControl 1.8.2, 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 following commands:
$ systemctl restart cmon # or service cmon restartThe following screenshot shows the new LDAP Advanced Settings dialog:
If compared to the previous version, the new LDAP implementation is more customizable to support industry-standard directory services like Active Directory, OpenLDAP and FreeIPA. It also supports attribute mappings so you can set which attribute represents a value that can be imported into the ClusterControl user database like email, real name and username.
For more information, check out the LDAP Settings user guide.
Advantages of the New User Management
Note that the current user management is still working side-by-side with the new user management system. However, we highly recommend our users to migrate to the new system before Q1 2022. Only manual migration is supported at the moment. See Migration to the New User Management section below for details.
The new user management system will benefit ClusterControl users in the following ways:
Centralized user management for ClusterControl CLI and ClusterControl GUI. All authentication, authorization, and accounting will be handled by the ClusterControl Controller service (cmon).
Advanced and customizable LDAP configuration. The previous implementation only supports a number of username attributes and had to be configured in its own way to make it work properly.
The same user account can be used to authenticate to the ClusterControl API securely via TLS. Check out this article for example.
Secure user authentication methods. The new native user management supports user authentication using both private/public keys and passwords. For LDAP authentication, the LDAP bindings and lookups are supported via SSL and TLS.
A consistent view of time representation based on the user's timezone setting, especially when using both CLI and GUI interface for database cluster management and monitoring.
Protection against brute force attacks, where a user can be denied access to the system via suspension or disabled logins.
Migration to the New User Management
Since both user systems have different user account and structure, it is a very risky operation to automate the user migration from frontend to backend. Therefore, the user must perform the account migration manually after upgrading from 1.8.1 and older. Please refer to Enabling New User Management for details. For existing LDAP users, please refer to the LDAP Migration Procedure section.
We highly recommend users to migrate to this new system for the following reasons:
The UI user management system (where a user would log in using an email address) will be deprecated by the end of Q1 2022 (~1 year from now).
All upcoming features and improvements will be based on the new user management system, handled by the cmon backend process.
It is counter-intuitive to have two or more authentication handlers running on a single system.
If you are facing problems and required assistance on the migration and implementation of the new ClusterControl user management system, do not hesitate to reach us out via the support portal, community forum or Slack channel.
Final Thoughts
ClusterControl is evolving into a more sophisticated product over time. To support the growth, we have to introduce new major changes for a richer experience in a long run. Do expect more features and improvements to the new user management system in the upcoming versions!