Manage Users, Groups, and Roles
Couchbase Server allows defined users to be assigned roles, which permit access to resources. Additionally, groups of users can be established, and roles assigned to each group; so that each user is granted the roles of each group of which they are a member.
Creating and Managing Users and Groups
The administrator who initially performs installation and configuration of Couchbase Server is granted the role of Full Administrator, with complete access to the entire system, including read and write privileges. Once basic system configuration has been completed, the Full Administrator is free to add other users to the system, and assign them roles; thereby specifying their privileges.
Note that a cluster running Couchbase Server Enterprise Edition can have any number of users. A cluster running Community Edition can have a maximum of twenty users.
As Full Administrator, to add users (each of which might be either an administrator or an application) and groups to Couchbase Server, use Couchbase Web Console, the CLI, or the REST API, as described in the sections below.
For a general overview of Couchbase-Server authorization, see Authorization. For a list of available roles and corresponding privileges, see Roles.
Manage Users and Groups with the UI
Access the Dashboard of Couchbase Web Console, and left-click on the Security tab, on the vertical navigation-bar, at the left. This brings up the Security view, as follows:
The Users & Groups panel, which is visible by default on the Security screen, allows users and groups to be defined. It also allows roles to be assigned to users and groups. If at any time the Users & Groups panel is not currently visible, access it by left-clicking on the Users & Groups tab, which is located at the left-hand side of the upper, horizontal navigation-bar:
Initially, the panel shows that no users have yet been defined. (The Full Administrator who established the cluster is never included on the list; which contains only administrators subsequently defined.)
Note that the following notifications may appear in the upper area of the screen:
This indicates that no ability to support external authentication — by means of either saslauthd or LDAP — has yet been enabled.
To enable LDAP, see Configure LDAP: this is the recommended way of handling external authentication.
To enable saslauthd, see Getting Started with saslauthd and LDAP.
For a general overview of external authentication, see
Authentication Domains.
Add a Group
A group can be defined, and roles assigned to it, by means of Couchbase Web Console. Users can then be defined, and assigned to each group; each user thus being granted the group’s roles. Groups may provide the most efficient way of managing role-assignments, when user-numbers are high.
To define a group, left-click on the Add Group tab, near the upper right of the Security screen:
This brings up the Add New Group dialog:
The fields are as follows:
-
Group Name. The name of the new Couchbase-Server group to be created.
-
Description. An optional description of the new Couchbase-Server group.
-
Map to LDAP Group. The name of an existing LDAP group to which the new Couchbase-Server group is to be mapped. For details, see Map LDAP Groups to Couchbase Server Roles.
-
Roles. The roles to be associated with the new Couchbase-Server group. The display lists role-categories: to see roles, open each category by left-clicking on its right-pointing arrowhead, and scrolling down as appropriate.
The first category, which appears at the top of the panel, is for Administration & Global Roles: these roles are either administrative, or involve access to cluster-wide features.
Below the first category, the All Buckets (*) category appears: roles in this category apply to all buckets defined on the cluster. Below All Buckets (*), additional categories are displayed, one for each individual bucket currently defined on the cluster. Thus, the new group can be assigned roles that apply either to all buckets defined on the cluster, or to one or more particular buckets:
To display roles at lower levels of the All Buckets (*) hierarchy, again, left-click on the right-pointing arrowheads. To assign roles to the new group, simply check the appropriate checkboxes. (Note that some roles are considered to be subsets of others. In such cases, manually checking one checkbox may trigger the automated checking of others — indicating that the corresponding roles are also assigned to the new group.)
To create a ClusterAdmin group, each of whose members is granted the Cluster Admin role, enter the following:
As this indicates, no LDAP group mapping is required to define a group intended for the support only of users who are defined on Couchbase Server as local or external. For an explanation of LDAP group mappings, see Map LDAP Groups to Couchbase Server Roles.
Save the group by left-clicking on the Save button.
Add a User
To add a user, left-click on the Add User control, at the upper right.
The Add New User dialog now appears:
Towards the upper left of the dialog, the Authentication Domain panel is visible. This features two checkboxes: one specifying Couchbase, the other External. By default, Couchbase is checked: this means that the user will be defined locally, and that a password for the user must therefore be created, using the Password fields displayed on the dialog.
Add a Locally Authenticated User
Add a locally authenticated user, by adding appropriate entries into the Username and Password fields. See Usernames and Passwords for character-related requirements. The Full Name field may be left blank.
The user may now either be assigned one or more specific roles, or be assigned to one or more groups (so as to inherit each group’s assigned roles), or both.
Assign Roles to a User
Roles can be assigned as described above in Add a Group — by checking checkboxes in the Roles panel, which is displayed by default.
For example, assign the Query Curl Access role:
Now, to add this user, left-click on the Add User button, at the lower right of the dialog. Alternatively, continue the user-definition process, by assigning the user to a group.
Assign a User to a Group
To assign a user to a group, left-click on the Groups tab:
The content of the dialog’s right-hand pane now changes, to display available groups:
A single user-group, called ClusterAdmin, is thus shown to have been created.
To add the user to the group, check the corresponding checkbox:
Now left-click on the Add User button, at the lower right:
The Security panel now appears as follows:
The single, displayed row indicates that user localUser has been defined, and has been granted the Query CURL Access role (which was assigned directly) and the Cluster Admin role (which has been derived from the user’s assigned membership of the ClusterAdmin group).
Note also that the auth domain for the user is Couchbase, indicating that this user is locally defined.
Editing Users and Groups
Once created, users and groups can be edited. Left-click on the currently defined user’s row:
The row expands vertically, displaying control-buttons at the lower right. By left-clicking on Delete, you delete the user. By left-clicking on Edit, you bring up the Edit <username> dialog, which provides options for redefining full name, roles, and groups. (The content of this dialog is similar to that of the Add New User dialog, examined above.) The Reset Password button only appears when the selected user is locally defined: left-clicking on this brings up a dialog that allows redefinition of the user’s password:
Note that the Users & Groups panel, subsequent to the definition of a user, displays two buttons towards the upper right, whereby Users and Groups views can be accessed in turn. To inspect and make changes to the currently defined group, left-click on the Groups button:
The Groups view is now displayed:
As with the Users view, left-clicking on a group’s row displays controls that include Delete and Edit options. Left-click on the Edit button to display the Edit Group <group-name> dialog, which is similar to the Add New Group dialog examined above, and allows all the group’s attributes, except the name, to be modified.
Adding an Externally Authenticated User
An externally authenticated user is not authenticated on Couchbase Server. Instead, they are authenticated on a server external to the cluster. This means that the user’s password is defined and maintained externally.
The addition of a user as externally authenticated must be supported by Native LDAP, saslauthd, or PAM. Appropriate set-up procedures must have been completed prior to the addition of externally authenticated users.
For the detailed steps required to establish external authentication by means of Native LDAP (which is the recommended mechanism), see Configure LDAP.
To add an externally authenticated user, on the Add New User dialog, select the External option:
This removes the password-related fields from the dialog, since they are not required for the creation of an externally authenticated user. The fields for the user’s names remain, and can be used.
From this point, the externally authenticated user can be defined exactly as was the locally authenticated user, above.
For example, the Query System Catalog role can be assigned to the user; and the user then assigned to the ClusterAdmin group, whereby the Cluster Admin role is granted.
When the definition-process is complete, the Users view of the Users & Groups panel appears as follows:
The externally authenticated user is now shown to have the username externalUser, and the Query System Catalog and Cluster Admin roles.
Their auth domain is specified as External, indicating that they are authenticated on an external server.
Manage Users with the CLI
Users can be managed with the user-manage command. This allows the creation and deletion of users and groups, the assignment of roles, and the listing of current status.
Get User Information with the CLI
To list the cluster’s current users, enter the following. Note that the command is piped to the jq program, to optimize output-readability.
/opt/couchbase/bin/couchbase-cli user-manage --cluster http://10.143.192.101 \ --username Administrator \ --password password \ --list | jq
A document is returned, containing an entry for each of the current users:
[
{
"id": "externalUserIndividual",
"domain": "external",
"roles": [
{
"role": "cluster_admin",
"origins": [
{
"type": "user"
}
]
}
],
"groups": [],
"external_groups": [],
"name": "John Smith"
},
{
"id": "localUser",
"domain": "local",
"roles": [
{
"role": "data_writer",
"bucket_name": "travel-sample",
"origins": [
{
"type": "user"
}
]
},
{
"role": "data_reader",
"bucket_name": "travel-sample",
"origins": [
{
"type": "user"
}
]
}
],
"groups": [],
"external_groups": [],
"name": "",
"password_change_date": "2019-05-31T03:59:49.000Z"
},
{
"id": "externalUserGroup",
"domain": "external",
"roles": [
{
"role": "admin",
"origins": [
{
"type": "group",
"name": "Admins"
},
{
"type": "user"
}
]
}
],
"groups": [
"Admins"
],
"external_groups": [],
"name": "David Brown"
}
]
The entries include information on the id and roles of the user, their authentication domain, their name if one was specified, and on the local and external groups to which the user belongs.
Get Group Information with the CLI
Information on currently defined groups can similarly be returned:
/opt/couchbase/bin/couchbase-cli user-manage --cluster http://10.143.192.101 \ --username Administrator \ --password password \ --list-groups
An example of the output is as follows:
{
"id": "Admins",
"roles": [
{
"role": "admin"
}
],
"ldap_group_ref": "uid=cbadmins,ou=groups,dc=example,dc=com",
"description": "Couchbase Server Administrators"
}
This shows that a single group, named Admins, has been defined on the cluster; and that the admin role has been assigned to it.
The group’s LDAP reference and description are also provided.
Manage Local Users with the CLI
The username and password of a local user is stored and maintained on Couchbase Server. Roles can be allocated to the user either directly or by means of group membership.
Create a Local User, Using Direct Role-Assignment, with the CLI
To create a user who is to be locally authenticated, directly assigning a role, enter the following:
/opt/couchbase/bin/couchbase-cli user-manage \ --cluster http://10.143.192.101 \ --username Administrator \ --password password \ --set \ --rbac-username dgreen \ --rbac-password dGr3En239 \ --roles query_external_access,analytics_reader \ --auth-domain local
This uses the --set flag, to indicate that the RBAC profile for the cluster is being updated.
The username and password for the user are defined.
The value of the --auth-domain flag indicates that this is indeed to be a local user.
The query_external_access and analytics_reader roles are assigned by means of the --roles flag: to change direct role assignments, the user must be recreated, with all the new roles specified as the arguments to the --roles flag.
If the call is successful, the following is displayed:
SUCCESS: User dgreen was created
Create a Local User, Using Group-Based Role-Assignment, with the CLI
To create a user who is to be locally authenticated, assigning a role by means of group membership, enter the following:
/opt/couchbase/bin/couchbase-cli user-manage --cluster http://10.143.192.101 \ --username Administrator \ --password password \ --rbac-username cbrown \ --rbac-password cBr403n438 \ --auth-domain local \ --edit-users-groups \ --user-groups Admins
This specifies the --edit-users-groups flag, to indicate that group-editing is to occur.
The --user-groups flag is given the value Admins, to indicate that the Admins group is that which will be edited.
Flags are provided to indicate the username and password of a new user, who will be added to the system, and given membership of the specified group, so as to inherit its assigned roles.
If successful, the call returns the following:
SUCCESS: User 'cbrown' group memberships were updated
Delete a Local User with the CLI
To delete a local user, specify the --delete flag, with the username and authentication domain:
/opt/couchbase/bin/couchbase-cli user-manage --cluster http://10.143.192.101 \ --username Administrator \ --password password \ --rbac-username dgreen \ --auth-domain local \ --delete
The output is as follows:
SUCCESS: User 'dgreen' was removed
Create a Group with the CLI
Using the CLI, create a group as follows:
/opt/couchbase/bin/couchbase-cli user-manage \ --cluster http://10.143.192.101 \ --username Administrator \ --password password \ --set-group \ --group-name xdcrAdmin \ --roles replication_admin
This uses the --set-group flag to indicate that a group is to be created or edited.
The --group-name flag specifies the name of a new group named xdcrAdmin, and the --roles flag is used to assign the replication_admin role to the new group.
Note that to change the group’s role-assignments, the group must be recreated, with all the new role-assignments specified as the arguments to the --roles flag: user-memberships go unchanged.
If the call is successful, the following is displayed.
SUCCESS: Group 'xdcrAdmin' was created
For information on how to use the CLI to create a mapping between a Couchbase-Server user-group and an LDAP group, see Map Groups with the CLI.
Delete a Group with the CLI
To delete a group with the CLI, use the user-manage command as follows:
/opt/couchbase/bin/couchbase-cli user-manage \ --cluster http://10.143.192.101 \ --username Administrator \ --password password \ --delete-group \ --group-name xdcrAdmin
This deletes the group xdcrGroup.
If the command is successful, the following output is provided:
SUCCESS: Group 'xdcrAdmin' was deleted
Manage External Users with the CLI
Users can be defined as externally authenticated, by means of the CLI. This requires external authentication to have been configured prior to user-creation. For recommended procedures, see Configure LDAP.
Create an External User, Using Direct Role-Assignment, with the CLI
To create an externally authenticated user with direct role-assignment, use the user-manage command as follows:
/opt/couchbase/bin/couchbase-cli user-manage --cluster http://10.143.192.101 \ --username Administrator \ --password password \ --set \ --rbac-username wgrey \ --roles cluster_admin \ --auth-domain external
The --auth-domain is specified as external.
The --set flag establishes that the cluster’s RBAC profile is to be updated.
No password is specified, since none is to be saved on Couchbase Server — authentication occurring on the LDAP server.
The role to be assigned to the user is specified by means of the --roles flag as cluster_admin
If the command is successful, the following is returned:
SUCCESS: User wgrey was created
Create an External User, Using Group-Based Role-Assignment, with the CLI
To create an external user with a group-based role-assignment, use the user-manage command as follows:
/opt/couchbase/bin/couchbase-cli user-manage --cluster http://10.143.192.101 \ --username Administrator \ --password password \ --edit-users-groups \ --rbac-username rjones \ --rbac-name 'Richard Jones' \ --auth-domain external \ --user-groups Admins
The --edit-users-groups flag specifies that a group is to be updated.
The existing Couchbase-Server user-group Admins is passed as the value of --user-groups: this specifies that Admins is indeed the group of which the external user, rjones is to be a member.
All roles assigned to Admins are now to be inherited by rjones.
If successful, the command returns the following:
SUCCESS: User 'rjones' group memberships were updated
For information on how to use the CLI to create a mapping between a Couchbase-Server user-group and an LDAP group, see Map Groups with the CLI.
Delete an External User with the CLI
To delete an external user, use the --delete-user flag, specifying external as the value of the --auth-domain flag:
/opt/couchbase/bin/couchbase-cli user-manage --cluster http://10.143.192.101 \ --username Administrator \ --password password \ --rbac-username wgrey \ --auth-domain external \ --delete
If successful, the command returns the following:
SUCCESS: User 'wgrey' was removed
Manage Users with the REST API
Users can be managed with the GET /settings/rbac/users method and URI.
This allows the creation and deletion of users and groups, the assignment of roles, and the listing of current status.
For corresponding reference information, see Role Based Admin Access (RBAC).
Each user can be defined as either locally or externally. The creation of external users requires external authentication to have been configured prior to user-creation. For recommended procedures, see Configure LDAP.
Get User Information with the REST API
To list the cluster’s current users, use the GET /settings/rbac/users method and URI as follows:
curl -v -X GET -u Administrator:password \ http://10.143.192.101:8091/settings/rbac/users
If successful, the command provides as its output a document containing an entry for each of the current users. This output is identical in form to that shown above, in Get User Information with the CLI.
Get Group Information with the REST API
To list the cluster’s current groups, use the GET /settings/rbac/groups method and URI as follows:
curl -v -X GET -u Administrator:password \ http://10.143.192.101:8091/settings/rbac/groups
If successful, the command provides as its output a document containing an entry for each of the current groups. This output is identical in form to that shown above, in Get Group Information with the CLI.
Manage Local Users with the REST API
The username and password of a local user is stored and maintained on Couchbase Server. Roles can be allocated to the user either directly or by means of group membership.
Create a Local User, Using Direct Role-Assignment, with the REST API
To create a local user, use the PUT /settings/rbac/users/local/<username> method and URI.
For example:
curl -v -X PUT -u Administrator:password \ http://10.143.192.101:8091/settings/rbac/users/local/dgreen \ -d password=dGr3En238 \ -d roles=ro_admin
This specifies that the user dgreen should be locally established, with the given password and the ro_admin role.
If required, the GET /settings/rbac/users method and URI (described above) can now be used to verify that the specified user has been added.
Create a Local User, Using Group-Based Role-Assignment, with the REST API
Use the PUT /settings/rbac/users/local/sdavis method and URI, as follows:
curl -v -X PUT -u Administrator:password \ http://10.143.192.101:8091/settings/rbac/users/local/sdavis \ -d groups=Admins,xdcrAdmin \ -d password=Sd4v1s938
The value of the --groups flag specifies that the user, specified in the endpoint as sdavis, should be added to the Admins and xdcrAdmin groups.
To modify group membership subsequently, run the command again, specifying all of the groups whose membership is required as the arguments to the groups parameter.
Delete a Local User with the REST API
Local users can be deleted by means of the DELETE /settings/rbac/users/local/<username> method and URI:
curl -v -X DELETE -u Administrator:password \ http://10.143.192.101:8091/settings/rbac/users/local/dgreen
Create a Group with the REST API
To create a group with the REST API, use the PUT /settings/rbac/groups/<group-name> method and URI.
For example:
curl -v -X PUT -u Administrator:password \ http://10.143.192.101:8091/settings/rbac/groups/roAdminGroup \ -d roles=ro_admin
This establishes a new group named roAdminGroup.
By means of the roles parameter, the ro_admin role is assigned to the group.
This role will be inherited by all of the group’s future members.
Manage External Users with the REST API
Users can be defined as externally authenticated, by means of the REST API. This requires external authentication to have been configured prior to user-creation. For recommended procedures, see Configure LDAP.
Create an External User, Using Direct Role-Assignment, with the REST API
To create an external user and assign roles to them directly, use the PUT /settings/rbac/users/external/<username> method and URI.
For example:
curl -v -X PUT -u Administrator:password \ http://10.143.192.101:8091/settings/rbac/users/external/wgrey \ -d roles=cluster_admin
This creates the externally authenticated user wgrey, and assigns them the cluster_admin role.
Create an External User, Using Group-Based Role-Assignment, with the REST API
Use the PUT /settings/rbac/users/<name> method and URI, as follows:
curl -v -X PUT -u Administrator:password \ http://10.143.192.101:8091/settings/rbac/users/rjones \ -d groups=Admins,xdcrAdmin
This adds the externally authenticated user rjones to the cluster’s Admins and xdcrAdmins groups.
The user now inherits the roles that have been assigned to each of the groups.
Delete an External User with the REST API
External users can be deleted by means of the DELETE /settings/rbac/users/external/<username> method and URI:
curl -v -X DELETE -u Administrator:password \ http://10.143.192.101:8091/settings/rbac/users/external/wgrey
This deletes the external user wgrey from the cluster.