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.