Role-Based Access Control (RBAC)
Full and Security Administrators can manage the Couchbase Role-Based Access Control (RBAC) system, using the REST API.
Description
A Couchbase-Server role permits one or more resources to be accessed according to defined privileges. Roles can be assigned to individual users, and to groups, by means of the REST API.
For a complete list of roles, see Roles.
Note that most roles can be assigned only on the Enterprise Edition of Couchbase Server: on the Community Edition of Couchbase Server, only the bucket_full_access,
admin, and ro_admin roles can be assigned.
For more information, see Authorization.
Retrieve Information on Roles, Permissions, Users, and Groups
The REST API allows information to be retrieved on available roles and permissions; and on the cluster’s currently defined users and groups. Curl syntax, parameter-descriptions, examples, and call-specific responses are described in the subsections below. See the section Responses, for further descriptions of error and other notifications.
List Roles
To list roles, use the GET method with the /settings/rbac/roles URI.
The curl syntax is as follows:
curl -X GET http://<ip-address-or-domain-name>:8091/settings/rbac/roles -u <username:password>
If successful, this returns 200 OK, and an array that contains a description of every available role.
Example: List Roles
The following example lists the roles for the current cluster. Note that in this example (as in others, below) the output is piped to the jq command, to facilitate readability.
curl -v -X GET http://10.143.201.101:8091/settings/rbac/roles \ -u Administrator:password | jq
If successful, the call returns an array, containing information on every role:
[
{
"role": "admin",
"name": "Full Admin",
"desc": "Can manage all cluster features (including security). This user can access the web console. This user can read and write all data.",
"ce": true
},
{
"role": "ro_admin",
"name": "Read-Only Admin",
"desc": "Can view all cluster statistics. This user can access the web console. This user can read some data.",
"ce": true
},
{
"role": "security_admin",
"name": "Security Admin",
"desc": "Can view all cluster statistics and manage user roles, but not grant Full Admin or Security Admin roles to other users or alter their own role. This user can access the web console. This user cannot read data."
},
.
.
List Current Users and Their Roles
To list current users, use the GET method with the /settings/rbac/users URI.
The curl syntax is as follows:
curl -X GET http://<ip-address-or-domain-name>:8091/settings/rbac/users -u <username:password>
This returns an array, each of whose members is an object containing information on a currently defined user.
Example: List Current Users
The following example lists the users currently defined on the cluster:
curl -v -X GET http://10.144.210.101:8091/settings/rbac/users \ -u Administrator:password | jq
If successful, the call returns 200 OK, and an array such as the following:
[[
{
"id": "externalUser",
"domain": "local",
"roles": [
{
"role": "scope_admin",
"bucket_name": "demoBucket",
"scope_name": "demoScope",
"origins": [
{
"type": "user"
}
]
},
{
"role": "ro_admin",
"origins": [
{
"type": "user"
}
]
}
],
"groups": [],
"external_groups": [],
"name": "",
"password_change_date": "2021-02-01T09:46:04.000Z"
},
{
"id": "testUser",
"domain": "local",
"roles": [
{
"role": "data_reader",
"bucket_name": "testBucket",
"scope_name": "MyScope",
"collection_name": "MyCollection",
"origins": [
{
"type": "user"
}
]
}
],
"groups": [],
"external_groups": [],
"name": "",
"password_change_date": "2021-02-01T09:40:23.000Z"
},
{
"id": "dgreen",
"domain": "local",
"roles": [
{
"role": "data_reader",
"bucket_name": "testBucket",
"scope_name": "MyScope",
"collection_name": "MyCollection",
"origins": [
{
"type": "user"
}
]
},
{
"role": "query_external_access",
"origins": [
{
"type": "user"
}
]
},
{
"role": "analytics_reader",
"origins": [
{
"type": "user"
}
]
}
],
"groups": [],
"external_groups": [],
"password_change_date": "2021-02-01T09:56:29.000Z"
}
]
In this example, each array-member contains values that specify the domain, the role(s), the groups, the external_groups, the name, and the last password_change_date for a defined user.
Where roles are not global, the bucket, scope, and collection to which permissions are restricted are specified, as appropriate.
Check Permissions
The REST API allows the permissions of the authenticating administrator to be confirmed, by means of the POST method and the /pools/default/checkPermissions URI.
The curl syntax is as follows:
curl -X POST http://<ip-address-or-domain-name>:8091/pools/default/checkPermissions -u <username>:<password> -d <permissions-check-specification>
The permissions-check-specification must indicate whether the check is to be made at the level of the cluster (for permissions associated with global roles), or at the level of a bucket within the cluster (for permissions associated with bucket-specific roles); or at the level of a specific data-set associated with the buckets (such as stats or views); and must specify the permission (such as read or write) for which the check is to be made.
Cluster, bucket, and data-set, if specified, must be separated from one another with a period.
The permission to be checked for must be preceded by the ! character.
A successful call returns 200 OK, plus an object indicating whether the authenticating administrator’s possession of the specified permission is true or false.
For an alternative procedure whereby the authenticating administrator can retrieve information on their assigned roles, see Who Am I?.
Examples: Check Permissions
The following example checks whether the authenticating administrator has admin permissions on the cluster (which is to say, the permission associated with the cluster_admin role):
curl -v -X POST http://10.143.201.101:8091/pools/default/checkPermissions \ -u gsanderson:gsanderson \ -d 'cluster!admin'
If the call is successful, and the authenticating administrator does has the specified permission, the following object is returned:
{"cluster!admin":true}
The following example checks whether the authenticating administrator has read permission on stats for the travel-sample bucket, and write permission on travel-sample data:
curl -v -X POST http://10.143.201.101:8091/pools/default/checkPermissions \ -u Administrator:password \ -d 'cluster.bucket[travel-sample].stats!read,cluster.bucket[travel-sample]!write' | jq
An object such as the following is returned:
{
"cluster.bucket[travel-sample].stats!read": true,
"cluster.bucket[travel-sample]!write": true
}
List Currently Defined Groups
To list currently defined user-groups, use the GET method with the /settings/rbac/groups/
URI.
The curl syntax is as follows:
curl -X GET http://<ip-address-or-domain-name>:8091/settings/rbac/groups -u <username:password>
If successful, the call returns 200 OK, and an array each of whose members is an object containing information on one of the user-groups currently defined on the cluster.
Example: List Currently Defined Groups
The following example lists all user-groups currently defined on the cluster:
curl -v -X GET http://10.143.201.101:8091/settings/rbac/groups \ -u Administrator:password | jq
If successful, the call returns an array such as the following:
[
{
"id": "ClusterAdmins",
"roles": [
{
"role": "cluster_admin"
}
],
"ldap_group_ref": "uid=cbadmins,ou=groups,dc=example,dc=com",
"description": "Couchbase Server Cluster Administrators"
},
{
"id": "DataReaderGroup",
"roles": [
{
"role": "data_reader",
"bucket_name": "testBucket",
"scope_name": "MyScope",
"collection_name": "MyCollection"
},
{
"role": "data_reader",
"bucket_name": "demoBucket",
"scope_name": "demoScope",
"collection_name": "demoCollection"
}
],
"ldap_group_ref": "",
"description": ""
}
]
Thus, the array contains two members, which respectively contain information on the ClusterAdmins, and the DataReaderGroup groups.
Note that the ClusterAdmins group is shown to have an ldap_group_ref: meaning that it corresponds to an LDAP group, defined on the LDAP server.
For information, see Native LDAP Support.
Create Users and Groups
The REST API allows users and groups to be created, and roles thereby assigned. Curl syntax, parameter-descriptions, examples, and call-specific responses are described in the subsections below. See the section Responses, for further descriptions of error and other notifications.
Users can be either local or external. A local user may have the same username as an external user.
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, local users.
Groups can optionally be mapped to external groups, defined on an LDAP server. For information, see Authentication Domains.
Create a Local User, and Assign Roles
To create a local user, and assign them one or more roles, use the PUT method with the /settings/rbac/users/local URI.
The curl syntax is as follows:
curl -X PUT http://<ip-address-or-domain-name>:8091/settings/rbac/users/local/<new-username> -u <username>:<password> -d password=<password> -d roles=[ <role> ]*
The specified password must conform to the settings established as described in Setting Password Policy.
Either the roles flag or the groups flag may be specified.
If multiple instances of role are specified, these must be comma-separated.
Roles that permit data-access can be assigned with reference to a bucket, to a scope within a bucket, or to a collection within a scope.
Syntactically, the assignment should be specified in square brackets, immediately after the role-name; with the bucket-name preceding (if one is specified) the scope-name; and the scope-name preceding (if one is specified) the collection-name.
The names of bucket, scope, and collection must be separated by colons.
If successful, the call returns 200 OK.
No object is returned.
Note that in Couchbase Server 7.1.1+, if an existing user’s password is to be changed, and their existing role-assignments are to be kept unchanged, the /settings/rbac/users/local URI can be used with the PATCH method: this allows the password parameter to be used, specifying a new password; and the username and roles parameters to be omitted.
Examples: Create Local Users, Assigning Roles
The following example creates a local user, assigning a single role.
curl -v -X PUT http://10.143.201.101:8091/settings/rbac/users/local/dgreen \ -u Administrator:password \ -d password=pwdpwd \ -d roles=ro_admin
This assigns user dgreen the ro_admin role.
To change the password-assignment for dgreen, while leaving their role-assignment as ro_admin, use the /settings/rbac/users/local URI with the PATCH method, as follows:
curl -v -X PATCH http://localhost:8091/settings/rbac/users/local/dgreen \ -u Administrator:password \ -d password=pwdpwdpwd
Following this use of the PATCH, method, dgreen continues to have the same role-assignments as before, but has been assigned a new password.
Note that whenever a new user is to be assigned multiple roles, the roles must be comma-separated. If a role is to be limited to a specific bucket, the bucket-name must follow the name of the role, without a separator, enclosed in square-brackets. This is demonstrated by the following example:
curl -v -X PUT http://10.143.201.101:8091/settings/rbac/users/local/rbrown \ -u Administrator:password \ -d password=rbrownpassword \ -d roles=bucket_admin[travel-sample],data_reader[beer-sample:my_scope:my_collection]
Thus, the new user rbrown is assigned the bucket_admin role on the travel-sample bucket, and is assigned the data_reader role on the my_collection collection; which resides in the my_scope scope, in the beer-sample bucket.
The following example assigns one global role, and one bucket-specific:
curl -v -X PUT http://10.143.201.101:8091/settings/rbac/users/local/krichards \ -u Administrator:password \ -d password=krpassword \ -d roles=cluster_admin,bucket_admin[travel-sample]
Thus, the new user krichards is assigned the cluster_admin role (this being a global role), and the bucket_admin role for the travel-sample bucket only.
Create a Local User, and Assign to a Group
To create a local user, and assign them to a group — thereby ensuring that they inherit the role or roles already assigned to the specified group — again use the PUT method with the /settings/rbac/users/local/<new-username> URI; this time, using the groups flag, instead of the roles flag.
The curl syntax is as follows:
curl -X PUT http://<ip-address-or-domain-name>:8091/settings/rbac/users/local/<new-username> -u <username>:<password> -d password=<password> -d groups=[ <groupname> ]*
If multiple instances of groupname are specified, each should be separated from the next with a comma.
Each groupname must be the name of an existing group.
If successful, the call returns 200 OK.
Example: Create a Local User, and Assign to a Group
The following example creates a local user named sdavis, and assigns them to two existing groups:
curl -v -X PUT http://10.143.201.101:8091/settings/rbac/users/local/sdavis \ -u Administrator:password \ -d groups=ClusterAdmins,XDCRAdmins \ -d password=Sd4v1s938
If successful, the call creates local user sdavis and adds them to the ClusterAdmins group and to the XDCRAdmins group.
Create an External User, and Assign Roles
To create an external user, and assign them one or more roles, use the PUT method with the /settings/rbac/users/external/<new-username> URI.
The curl syntax is as follows:
curl -X PUT http://<ip-address-or-domain-name>:8091/settings/rbac/users/external/<new-username> -u <username:password> -d roles=[ <role> ]*
Note that no password need be specified, since this is expected to have been defined on an external server: the external server will be contacted by Couchbase Server, as part of the user-authentication procedure.
Roles that permit data-access can be assigned with reference to a bucket, to a scope within a bucket, or to a collection within a scope. Syntactically, the assignment should be specified in square brackets, immediately after the role-name; with the bucket-name preceding (if one is specified) the scope-name; and the scope-name preceding (if one is specified) the collection-name. The names of bucket, scope, and collection must be separated by colons.
If successful, the call returns 200 OK.
Example: Create an External User, Assigning Roles
The following example creates an external user named wgrey:
curl -v -X PUT -u Administrator:password \ http://10.143.201.101:8091/settings/rbac/users/external/wgrey \ -d roles=cluster_admin,data_reader[beer-sample:my_scope:my_collection]
The new, external user is thus assigned the cluster_admin role; and is assigned the data_reader role on the collection my_collection, which resides in the my_scope scope, in the beer-sample bucket.
Create an External User, and Assign to a Group
To create an external user, and assign them to one or more groups, use the PUT method with the /settings/rbac/users/external/<new-username> URI.
The curl syntax is as follows:
curl -X PUT http://<ip-address-or-domain-name>:8091/settings/rbac/users/external/<new-username> -u <username:password> -d groups=[ <group> ]*
Each specified group must be the name of a Couchbase-Server user-group, defined on the cluster.
The external user, when authenticated on the external server, will be granted the roles associated with each of the specified groups.
Note that if the external user has been defined on the LDAP server as belonging to a particular LDAP group, and this LDAP group has been previously mapped to an existing Couchbase-Server group, the user is granted the roles associated with the existing Couchbase-Server group, even if this Couchbase-Server group is not specified by means of the groups flag.
For information on mapping LDAP groups to Couchbase-Server groups, see Create a Group and Assign it Roles, below.
Example: Create an External User, Assigning to a Group
The following example creates an external user named rjones and assigns them to two groups:
curl -v -X PUT -u Administrator:password \ http://10.143.201.101:8091/settings/rbac/users/external/rjones \ -d groups=ClusterAdmins,XDCRAdmins
The new user rjones is thus assigned to the ClusterAdmins and XDCRAdmins groups.
The user, once authenticated on an external server, inherits the roles associated with these Couchbase-Server groups.
Create a Group, and Assign it Roles
Couchbase Server allows the creation of local user-groups, to which roles can be assigned. Each user, local or external, who is a member of such a group inherits the roles that have been assigned to the group. Optionally, a local group can be mapped to an external, LDAP group: this means that successfully authenticated external users who are a member of one or more LDAP groups can inherit, on Couchbase Server, the roles assigned to the corresponding local user-groups.
All these actions can be performed by means of the REST API, using the PUT method and the /settings/rbac/groups/<new-groupname> URI.
The curl syntax is as follows:
curl -X PUT http://<ip-address-or-domain-name>:8091/settings/rbac/groups/<new-groupname> -u <username>:<password> -d roles=[ <role> ]* -d description=<description> --data-urlencode ldap_group_ref=<ldap-group-reference>
Each specified role must be a Couchbase-Server role: each will be assigned to the new group, whose name is specified by new-groupname.
Multiple roles must be separated by commas.
The optional description can be multiple words, which must be separated from each other by the + character.
The optional ldap_group_ref, which must be specified as URL-encoded, specifies an existing LDAP group to which the new, local Couchbase-Server group will be mapped.
If successful, the call returns 200 OK.
Examples: Create Groups
The following example creates a local group, and assigns it roles:
curl -v -X PUT -u Administrator:password \ http://10.143.201.101:8091/settings/rbac/groups/roAdminGroup \ -d roles=ro_admin
The example thus creates a new group named roAdminGroup, assigning the group the ro_admin role.
All users who become members of roAdminGroup will thereby inherit the ro_admin role.
The following example creates a new local group, mapping it to an external, LDAP group.
curl -v -X PUT http://10.143.201.101:8091/settings/rbac/groups/admins \ -u Administrator:password \ -d roles=cluster_admin \ -d description=Couchbase+Server+Cluster+Administrators \ --data-urlencode ldap_group_ref='uid=cbadmins,ou=groups,dc=example,dc=com'
The new, local group admins is thus created, and is assigned the cluster_admin role.
The description Couchbase Server Cluster Administrators is provided.
The ldap_group_ref specifies that the new, local group be mapped to an existing LDAP group named cbadmins: therefore, users who successfully authenticate via LDAP, and are members of cbadmins, automatically inherit the roles assigned locally to the Couchbase-Server admins group.
(Note, in consequence, that the username of such users may not be registered at all on Couchbase Server: since their authentication occurs on the LDAP server; and the roles they require for Couchbase-Server-access may be acquired entirely through one or more mappings between Couchbase-Server and LDAP user-groups.)
Delete Users and Groups
Users and groups can be deleted by means of the DELETE method and appropriate URI.
The curl syntax is as follows:
curl -X DELETE http://<ip-address-or-hostname>:8091/settings/rbac/users/local/<local-username> -u <username>:<password> curl -X DELETE http://<ip-address-or-hostname>:8091/settings/rbac/users/external/<external-username> -u <username>:<password> curl -X DELETE http://<ip-address-or-hostname>:8091/settings/rbac/groups/<groupname> -u <username>:<password>
The DELETE method, used with the /settings/rbac/users/local/<local-username> URI, deletes a local user; used with the /settings/rbac/users/external/<external-username> URI, deletes and external user; and used with the /settings/rbac/groups/<groupname> URI, deletes a local group.
In each case, if the call is successful, 200 OK is returned.
Examples: Delete Users and Groups
The following example deletes a local user:
curl -X DELETE http://10.143.201.101:8091/settings/rbac/users/local/dgreen \ -u Administrator:password
The local user dgreen is thus deleted from the Couchbase-Server cluster.
The following example deletes an external user:
curl -X DELETE http://10.143.201.101:8091/settings/rbac/users/external/wgrey \ -u Administrator:password
The external user wgrey is thus deleted from the Couchbase-Server cluster.
The user continues to exist on the external server on which their authentication is performed.
The following example deletes a group:
curl -v -X DELETE http://10.143.201.101:8091/settings/rbac/groups/ClusterAdmins \ -u Administrator:password
The local group ClusterAdmins is thus deleted.
Users defined on the Couchbase-Server cluster as either local or external, whose roles were derived entirely from their membership of the ClusterAdmins group, henceforth continue to be registered as local users, but are assigned no roles; and therefore no longer have access to the Couchbase-Server cluster.
If the ClusterAdmins group was mapped to an LDAP group, LDAP-authenticated users whose Couchbase-Server roles were derived entirely from that mapping are henceforth assigned no roles; and therefore no longer have access to the Couchbase-Server cluster.
Responses
If successful, 200 OK is given.
A malformed URI gives 405 Method Not Allowed.
Failure to authenticate gives 401 Unauthorized.
An improperly specified role fails with 400 Bad Request and the message {"errors":{"roles":"Cannot assign roles to user because the following roles are unknown, malformed or role parameters are undefined: [ro_admine]"}}.
An attempt to delete an already deleted user or group fails with 404 Object not found, and a message such as "User was not found." or "Group was not found.".
An attempt to add a user to one or more non-existent groups fails with 400 Bad Request and an error notification such as "groups":"Groups do not exist: ClusterAdmins,XDCRAdmins".
The creation of an already existing group or local or external user succeeds with 200 OK: the user is recreated with the newly specified role-assignments and group-memberships; and the group is recreated with the newly specified role-assignments and, optionally, a newly specified mapping.
Audit the Management of Users and Roles
Couchbase Server allows the management of users and roles to be audited. For a conceptual overview of auditing, see Auditing. For instructions on the management and configuration of auditing, see Manage Auditing. Note that the auditing facility is off by default: therefore it must be explicitly enabled, in order to be used; and the scope of events to be audited may need to be explicitly specified.
Once auditing is enabled, the file audit.log is written to an audit log directory, whose location is configurable.
Details of actions taken in the management of users and groups are recorded in this file.
For example, if the following call is used to create a user:
curl -v -X PUT http://10.143.201.101:8091/settings/rbac/users/local/dgreen \ -u Administrator:password \ -d password=pwdpwd \ -d roles=ro_admin
The file audit.log might be examined as follows:
sudo more audit.log | grep dgreen | jq '.'
This produces output such as the following:
{
"description": "User was added or updated",
"groups": [],
"id": 8232,
"identity": {
"domain": "local",
"user": "dgreen"
},
"name": "set user",
"real_userid": {
"domain": "builtin",
"user": "Administrator"
},
"reason": "added",
"remote": {
"ip": "10.143.201.101",
"port": 36328
},
"roles": [
"ro_admin"
],
"timestamp": "2020-08-19T03:25:27.513-07:00"
}
This confirms that the user was created, with the specified roles; and provides additional contextual information.
Likewise, if the following statement is used to create a group:
curl -v -X PUT -u Administrator:password \ http://10.143.201.101:8091/settings/rbac/groups/roAdminGroup \ -d roles=ro_admin
The file audit.log might be examined as follows:
sudo more audit.log | grep roAdminGroup | jq '.'
This produces output such as the following:
{
"description": "User group was added or updated",
"group_name": "roAdminGroup",
"id": 8244,
"name": "set user group",
"real_userid": {
"domain": "builtin",
"user": "Administrator"
},
"reason": "updated",
"remote": {
"ip": "10.143.201.101",
"port": 36334
},
"roles": [
"ro_admin"
],
"timestamp": "2020-08-19T03:26:40.125-07:00"
}
This confirms that the group roAdminGroup was created, with the specified roles, and provides additional contextual information.
See Also
See Authentication Domains, for an overview of local and external domains, and how to define users. See Authorization, for an introduction to the principles of Couchbase authorization, including Role-Based Access Control. All roles defined by Couchbase Server are listed and explained in Roles.
Manage Users, Groups, and Roles provides step-by-step examples using the UI, CLI, and REST API. See Configure LDAP for information on all aspects of LDAP-authentication configuration, including the mapping of groups.
Information on configuring LDAP with the REST API is provided in Configure LDAP.
Comprehensive information on managing users, groups, and roles with the CLI is provided on the reference page for user-manage.
For a conceptual overview of auditing, see Auditing. For instructions on the management and configuration of auditing, see Manage Auditing.