A newer version of this documentation is available.

View Latest

User Management

The SDK now lets you create users, assign them roles and associated privileges, and remove them from the system.

Users, Resources, Roles, and Privileges

Couchbase Server 5.0 Enterprise Edition introduces Role-Based Access Control for applications. This means that resources on a Couchbase cluster can only be accessed by an identified user.

Each user who attempts resource-access is identified by means of the credentials they pass to Couchbase Server, for purposes of authentication: these consist of a username and (typically) a password. Once the user is authenticated, an authorization process checks the roles with which the user is associated. If one or more of these roles correspond to privileges that permit the user-requested level of resource-access, access is duly granted; otherwise, it is denied.

Users who have been assigned the Admin role for the cluster are able to create, edit, and remove users. The SDK provides APIs to support these activities.

Creating a User

The syntax required for creating a user varies according to language. The basic form is as follows:

booleanupsertUser (String userid, UserSettings settings)

The method upsertUser creates a user and adds the user to the Couchbase Cluster. The user will subsequently be visible in the Security panel of the Couchbase Web Console. Note that successful user-addition results in a user locally defined, with username and password stored on Couchbase Server: external users (whose credentials reside on a network-available server, possibly accessed by means of LDAP) cannot be created by this SDK method. If the local user created by upsertUser already exists, the previous definition is overwritten.

The method takes two arguments. The first, a String is the user ID of the user to be created: for example, johnsmith0325, or user734. This must be specified.

The second is a UserSettings object. This takes the following form:

UserSettings {
    String password;
    String name;
    Role[] roles;
}

The object contains three data-members. The first is a String that specifies the user’s password: this must be provided. The second is a String that specifies the user’s name (for example, John Smith): this is optional, and so may be omitted. The third is an array of Role objects: this must be specified. Each Role object takes the following form:

Role {
    String role;
    String bucket_name;
}

The object’s two data-members are both Strings, and must both be specified. The String specified as the role must correspond to a role supported by Couchbase Server. The String specified as the bucket_name must either correspond to a bucket currently defined on Couchbase Server; or be the asterisk character (*), meaning all buckets.

The method returns a boolean, which is true if the operation is successful, otherwise false.

Listing Users

The basic form of the method used to return currently defined users is as follows:

List<User>getUsers()

The method returns a list of User objects, each of which takes the following form:

User {
    String name;
    String id;
    String domain;
    Role[] roles;
}

The name is the full name of the user. The id is the user’s ID. The domain is either local or external. Each Role object in the Role-array has the form already described above, in Creating a User.

Getting a User

The basic form of the method used to return an already defined user is as follows:

User getUser (String userid)

The method returns a User object, which takes the following form:

User {
    String name;
    String id;
    String domain;
    Role[] roles;
}

The name is the full name of the user. The id is the user’s ID. The domain is either local or external. Each Role object in the Role-array has the form described above, in Creating a User.

Removing a User

The basic form of the method used to remove users is as follows:

booleanremoveUser (String userid)

The method’s sole argument is the id of the user to be removed from the system, specified as a String. The method returns a boolean, whose value is true if the operation is successful, otherwise false.

Language-Specific Variations

Each language supported by the Couchbase SDK implements the above methods in a slightly different way. For Java examples, see Sample Code.

Further Information on RBAC

All aspects of the Couchbase RBAC system are covered in the section Authorization. Specifically, for information on: