A newer version of this documentation is available.

View Latest

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:

      securityView

      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:

      usersAndGroupsTab

      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 notification may appear in the upper area of the screen:

      externalAuthNotEnabled

      This indicates that no ability to support external authentication — by means of either saslauthd or LDAP — has yet been enabled. To enable LDAP, see the first step of the command-sequence provided in 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:

      addGroupTab2

      This brings up the Add New Group dialog:

      addNewGroupDialog71

      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 Administrative roles: these roles involve access to cluster-wide features.

        Below the first category, the Bucket, Data, and other categories appear: in most of these categories, roles can be applied to some or all buckets defined on the cluster. Additionally, within any given bucket, the assigned role can apply to all or to a subset of scopes and collections defined for that bucket (see Scopes and Collections, for an overview of scopes and collections).

      Create a Group with an Administrative Role

      To create a ClusterAdmin group, each of whose members is granted the Cluster Admin role, enter the following:

      addNewGroupDialogNoMapping70

      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.

      Create a Group with a Data-Access Role

      Within each bucket, Couchbase Server organizes data into scopes and collections. For an overview, see Scopes and Collections. Access to each bucket, each scope, and each collection is protected by Role-Based Access Control. Therefore, roles must be assigned accordingly.

      To create a group with a data-access role (for example, Data Reader), having entered a Group Name into the Add New Group dialog, access the Data category, in the Roles panel. This opens to reveal the available Data roles:

      dataCategoryOpen70

      Left-click on Data Reader, to reveal the selector for role-assignment options:

      dataReaderRoleAssignmentInitial

      The selector features three fields: each provides a pull-down menu, from which selections can be made. The field at the left allows a bucket to be specified; that in the center, a scope; that at the right, a collection. In each case, the default selection is a wild-card symbol (*), indicating that all are selected by default.

      Left-click in the left-hand field:

      selectBucketForRoleAssignment

      This indicates that three buckets are available for selection: demoBucket, exampleBucket, and testBucket. Select testBucket. The center field, which has until now been inactive, is activated. Left-click in the center field to reveal what scopes are available in testBucket for assigment:

      selectScopeForRoleAssignment

      This shows that the MyScope and _default scopes are available. Select MyScope. Now, left-click in the right-hand field:

      selectCollectionForRoleAssignment

      This shows that the MyCollection collection is available. Select MyCollection. Now, to add the assignment of Data Reader to all documents in the MyCollection collection, in the MyScope scope, in the testBucket bucket, left click on the Save button, at the bottom right of the dialog. The assigned role now appears immediately below the selector:

      addedRole

      To make additional assignments, to other buckets, scopes, and collections, repeat the procedure using the selector. For each role to be defined, an entry must be specified for each of the three fields — bucket, scope, and collection. Then, the role is displayed as a role-definition, underneath the selector. Should it be necessary, a displayed role-definition can be deleted, by left-clicking on the X, to the right.

      (Note that some roles apply to all data in the bucket; some to all collections in a specified scope, within a specified bucket; and some to all documents in a specified collection, within a specified scope and bucket. Consequently, the selector varies in appearance, role by role; based on how many fields are required for the a full specification of the role’s assignment.)

      When all required role-definitions have been made, left-click on Save, to save the group. The Security screen is now displayed. The edited group appears, and can always be made visible by means of the Groups button.

      addedGroupForDataReader

      To make additional changes to the group’s role-assignments, left click on the Edit button. The Edit Group <group-name> dialog appears: this is similar in appearance and behavior to the Add Group dialog, and thus allows new roles to be added, and existing to be deleted.

      Add a User

      To add a user, left-click on the Add User control, at the upper right.

      addUserTab3

      The Add New User dialog now appears:

      addNewUserDialogInitial72

      If either Native LDAP or saslauthd has been enabled, 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 and using selectors, in the Roles panel, which is displayed by default.

      For example, assign the Query Curl Access role:

      addQueryCurlAccessRole70

      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 at the upper right of the dialog:

      rolesAndGroupsToggle

      The content of the dialog’s right-hand pane now changes, to display available groups:

      groupsPanel2

      A user-group named ClusterAdmin, is thus shown to exist. To add the user to the group, check the corresponding checkbox:

      checkCllusterAdmin

      Now left-click on the Add User button, at the lower right:

      addUserButton

      The new user now appears on Security panel, as follows:

      securityScreenWithLocalUser

      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:

      userSecurityRowClicked

      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:

      resetPassword

      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:

      accessGroupsButton

      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:

      groupSecurityRow

      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:

      externalUserRadioButton

      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:

      usersSecurityRows

      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.

      External users can only be authenticated using the PLAIN method. By default, the Couchbase SDK will only default to PLAIN when connecting over TLS ports, therefore, external users should use the TLS ports.

      More details on authentication methods can be found in Understanding Authentication

      Role-Based Console Appearance

      Role-assignment determines which features of Couchbase Web Console are available to the administrator. Non-available features are not displayed: therefore, the console’s appearance changes, based on which roles have been assigned the current user.

      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.144.210.101 \
      --username Administrator \
      --password password \
      --list | jq

      A document is returned, containing an entry for each of the current users:

      [
        {
          "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"
        }
      ]

      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. For each non-global role, the bucket, scope, and collection to which the permissions are restricted are displayed, as appropriate.

      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": "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": "Administrators with limited Data Reader permission."
        }
      ]

      This shows that a single group, named DataReaderGroup, has been defined on the cluster; and that the data_reader role has been assigned to it for the specified collections.

      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.144.210.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:

      WARNING: Granting the query_external_access role permits execution of the N1QL function CURL() and may allow access to other network endpoints in the local network and the Internet.
      SUCCESS: User dgreen set

      The output thus includes the standard command-line warning on the significance of the query_external_access role.

      Create a Local User with the CLI, Directly Assigning a Per-Collection Role

      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.

      The following example creates a user whose role permits access to data within a specified collection:

      /opt/couchbase/bin/couchbase-cli user-manage \
      --cluster http://10.144.210.101 \
      --username Administrator \
      --password password \
      --set \
      --rbac-username dhiggins \
      --rbac-password d8&3hdli2 \
      --roles data_reader[testBucket:my_new_scope:my_new_collection] \
      --auth-domain local

      This grants the user dhiggins the data_reader role on data within the collection my_new_collection; which resides within the scope my_new_scope, in the testBucket bucket.

      If this call is successful, the following is displayed:

      SUCCESS: User dhiggins set

      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 \
      --set \
      --user-groups Admins

      This specifies the --set 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, Directly Assigning a Per-Collection Role

      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.

      The following example creates an external user whose role permits access to data within a specified collection:

      /opt/couchbase/bin/couchbase-cli user-manage --cluster http://10.144.210.101 \
      --username Administrator \
      --password password \
      --set \
      --rbac-username tcrawford \
      --roles data_writer[testBucket:my_new_scope:my_new_collection] \
      --auth-domain external

      If successful, the call returns the following:

      SUCCESS: User tcrawford set

      External user tcrawford is thus granted data_writer access to the collection my_new_collection; which resides in the scope my_new_scope, in the bucket testBucket.

      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 \
      --set \
      --rbac-username rjones \
      --rbac-name 'Richard Jones' \
      --auth-domain external \
      --user-groups Admins

      The --set 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 Control (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.

      Retrieve a Local User, with the REST API

      The GET /settings/rbac/users method and URI can be used to list current users:

      curl -v -X GET -u Administrator:password http://10.143.192.101:8091/settings/rbac/users | jq '.'

      If successful, the call returns the following:

      [
        {
          "id": "dgreen",
          "domain": "local",
          "roles": [
            {
              "role": "ro_admin",
              "origins": [
                {
                  "type": "user"
                }
              ]
            }
          ],
          "groups": [],
          "external_groups": [],
          "uuid": "aad6c6df-bf03-428b-8850-2e4171ec88f2",
          "password_change_date": "2023-07-24T07:39:09.000Z"
        }
      ]

      Create a Local User, Directly Assigning a Per-Collection Role

      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. The following example creates a user whose role permits access to data within a specified collection:

      curl -v -X  PUT -u Administrator:password \
      http://10.144.210.101:8091/settings/rbac/users/local/dwilliams \
      -d password=dGr3En238 \
      -d roles=data_reader[testBucket:my_new_scope:my_new_collection]

      The user dwilliams is thus granted data_reader privileges on the collection my_new_collection; which resides within the scope my_new_scope, in the testBucket bucket.

      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.

      Delete a Group with the REST API

      To delete a group with the REST API, use the DELETE /settings/rbac/groups/<group-name> method and URI. For example:

      curl -v -X DELETE -u Administrator:password \
      http://10.143.192.101:8091/settings/rbac/groups/roAdminGroup

      This deletes the group roAdminGroup.

      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, Directly Assigning a Per-Collection Role

      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. The following example creates an external user whose role permits access to data within a specified collection:

      /opt/couchbase/bin/couchbase-cli user-manage \
      --cluster http://10.144.210.101 \
      --username Administrator \
      --password password \
      --set \
      --rbac-username tcrawford \
      --roles data_writer[testBucket:my_new_scope:my_new_collection] \
      --auth-domain external

      If successful, the call returns the following:

      SUCCESS: User tcrawford set

      External user tcrawford is thus granted data_writer access to the collection my_new_collection; which resides in the scope my_new_scope, in the bucket testBucket.

      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.

      For more information on managing users, groups, and roles with the REST API, see Role Based Admin Control (RBAC).