Couchbase C Client  2.10.7
Asynchronous C Client for Couchbase
Authentication

Detailed Description

The lcb_AUTHENTICATOR object is how the library stores credentials internally, and may be used in cases where you'd like to manage credentials in an object separate from the library. This interface also provides better clarification between 'old style' (Classic) and new style (RBAC) auth.

If you don't have a specific need to have credentials managed in their own. lcb_create_st3::username and lcb_create_st3::passwd fields (note that username is only valid on clusters 5.0 and higher):

crst.v.v3.username = "user"; // Only for newer clusters
crst.v.v3.passwd = "s3cr3t";
lcb_create(&instance, &crst);

If you are connecting to a cluster older than 5.0 and would like to issue N1QL queries against multiple password-protected buckets, you can use the LCB_CNTL_BUCKET_CRED setting to "add" more bucket:password pairs to the library. The library will then send these credentials whenever you issue a query with the LCB_CMD_F_MULTIAUTH flag set.

lcb_BUCKETCRED creds;
creds[0] = "secondBucket";
creds[1] = "secondPass";

Or if you have a JSON encoder handy (or are interfacing from a higher level language) you can use the lcb_cntl_string() variant:

JsonArray *arr = new_json_array();
json_array_push_string("secondBucket");
json_array_push_string("secondPass");
char *s = json_encode(arr);
lcb_cntl_string(instance, "bucket_cred", s);

The json functions in the above example are mockups of however you would actually create a JSON array.

Functions

lcb_AUTHENTICATORlcbauth_new (void)
 
lcb_error_t lcbauth_add_pass (lcb_AUTHENTICATOR *auth, const char *user, const char *pass, int flags)
 
void lcbauth_ref (lcb_AUTHENTICATOR *auth)
 
void lcbauth_unref (lcb_AUTHENTICATOR *auth)
 
lcb_AUTHENTICATORlcbauth_clone (const lcb_AUTHENTICATOR *src)
 
lcb_error_t lcbauth_set_mode (lcb_AUTHENTICATOR *src, lcbauth_MODE mode)
 

Enumerations

enum  lcbauth_ADDPASSFLAGS
 Flags to use when adding a new set of credentials to lcbauth_add_pass. More...
 
enum  lcbauth_MODE
 

Function Documentation

◆ lcbauth_new()

lcb_AUTHENTICATOR* lcbauth_new ( void  )
Stability
Uncommitted:

Creates a new authenticator object. You may destroy it using lcbauth_unref(). The returned object initially has a refcount of 1.

Returns
A new authenticator object.

You must set the mode on this object before adding credentials to it. See lcbauth_set_mode().

Once you have added all the credentials to the object, you may assign it (or a copy, see lcbauth_clone()) to a library handle via lcb_set_auth().

Setting RBAC Auth:

lcbauth_add_pass(auth, "mark", "secret", LCBAUTH_F_CLUSTER);
lcb_t instance;
lcb_create_st crst = { 0 };
crst.version = 3;
crst.v.v3.connstr = "couchbase://cbhost.com/myBucket";
lcb_create(&instance, &crst);
lcb_set_auth(instance, auth);

Setting multi-bucket classic auth, also with cluster administrative credentials:

lcbauth_add_pass(auth, "myBucket", "secret", LCBAUTH_F_BUCKET);
lcbauth_add_pass(auth, "otherBucket", "otherSecret", LCBAUTH_F_BUCKET);
lcbauth_add_pass(auth, "Administrator", "password", LCBAUTH_F_CLUSTER);
lcb_t instance;
lcb_create_st crst = { 0 };
crst.version = 3;
crst.v.v3.connstr = "couchbase://cbhost.com/myBucket";
lcb_create(&instance, &crst);
lcb_set_auth(instance, auth);

◆ lcbauth_add_pass()

lcb_error_t lcbauth_add_pass ( lcb_AUTHENTICATOR auth,
const char *  user,
const char *  pass,
int  flags 
)
Stability
Uncommitted:

Add a set of credentials

Parameters
auth
userthe username (or bucketname, if LCBAUTH_F_BUCKET is passed)
passthe password. If the password is NULL, the credential is removed
flagsone of LCBAUTH_F_CLUSTER or LCBAUTH_F_BUCKET. If both flags are combined then the credential will be used for both bucket-level and cluster-level administrative operations (using LCB_HTTP_TYPE_MANAGEMENT).
Returns
LCB_OPTIONS_CONFLICT if LCBAUTH_F_BUCKET is used in conjunction with LCBAUTH_MODE_RBAC.
Note
You must set the mode of the authenticator using lcbauth_set_mode() before calling this function
when using LCBAUTH_MODE_RBAC, only LCBAUTH_F_CLUSTER is supported.

◆ lcbauth_ref()

void lcbauth_ref ( lcb_AUTHENTICATOR auth)
Stability
Volatile:

Increments the refcount on the authenticator object

Parameters
authThe only time you would want to call this function is when sharing a single lcb_AUTHENTICATOR with multiple lcb_t instances. While doing so is theoretically possible, it is not supported or tested.

◆ lcbauth_unref()

void lcbauth_unref ( lcb_AUTHENTICATOR auth)
Stability
Uncommitted:

Decrements the refcount on the authenticator object, freeing it if there are no more owners.

Parameters
auth

◆ lcbauth_clone()

lcb_AUTHENTICATOR* lcbauth_clone ( const lcb_AUTHENTICATOR src)
Stability
Uncommitted:

Makes a copy of an existing lcb_AUTHENTICATOR object. The returned authenticator object has a reference count of 1.

Parameters
srcthe authenticator object to clone
Returns
the cloned authenticator.

This function is useful when you wish to copy an existing set of credentials for use with a new client.

◆ lcbauth_set_mode()

lcb_error_t lcbauth_set_mode ( lcb_AUTHENTICATOR src,
lcbauth_MODE  mode 
)
Stability
Uncommitted:

Set the mode of this authenticator.

Parameters
srcthe authenticator
modethe mode to use.
Returns
error if the authenticator already contains credentials.
Note
This function should be called as early as possible. It is not possible to change the mode after credentials have been added

Data Structure Documentation

◆ lcb_AUTHENTICATOR

class lcb_AUTHENTICATOR

Opaque pointer containing credentials for the library.

Enumeration Type Documentation

◆ lcbauth_ADDPASSFLAGS

Flags to use when adding a new set of credentials to lcbauth_add_pass.

Enumerator
LCBAUTH_F_CLUSTER 

User/Password is administrative; for cluster.

LCBAUTH_F_BUCKET 

User is bucket name.

Password is bucket password. This flag is only used for legacy authentication. Using it with RBAC authentication will return an error

◆ lcbauth_MODE

Enumerator
LCBAUTH_MODE_CLASSIC 

Use "bucket-specific" credentials when authenticating.

This is the only way of authenticating up to server version 5.0

LCBAUTH_MODE_RBAC 

Use role-based access control.

This allows the same user to have access to multiple buckets with a single set of credentials.

Note that if this option is selected, it becomes impossible to use LCBAUTH_F_BUCKET with lcbauth_add_pass()

LCB_CNTL_SET
#define LCB_CNTL_SET
Modify a setting.
Definition: cntl.h:124
lcb_set_auth
void lcb_set_auth(lcb_t instance, lcb_AUTHENTICATOR *auth)
Sets the authenticator object for the instance.
LCBAUTH_F_BUCKET
@ LCBAUTH_F_BUCKET
User is bucket name.
Definition: auth.h:155
lcb_AUTHENTICATOR
lcb_create_st3::connstr
const char * connstr
Connection string.
Definition: couchbase.h:282
LCBAUTH_F_CLUSTER
@ LCBAUTH_F_CLUSTER
User/Password is administrative; for cluster.
Definition: auth.h:148
lcbauth_add_pass
lcb_error_t lcbauth_add_pass(lcb_AUTHENTICATOR *auth, const char *user, const char *pass, int flags)
LCBAUTH_MODE_CLASSIC
@ LCBAUTH_MODE_CLASSIC
Use "bucket-specific" credentials when authenticating.
Definition: auth.h:256
lcbauth_new
lcb_AUTHENTICATOR * lcbauth_new(void)
LCBAUTH_MODE_RBAC
@ LCBAUTH_MODE_RBAC
Use role-based access control.
Definition: auth.h:265
lcb_create_st::lcb_CRST_u::v3
struct lcb_create_st3 v3
Use this field.
Definition: couchbase.h:338
lcb_create_st
Wrapper structure for lcb_create()
Definition: couchbase.h:328
lcb_t
struct lcb_st * lcb_t
Definition: couchbase.h:41
LCB_CNTL_BUCKET_CRED
#define LCB_CNTL_BUCKET_CRED
Set credentials for a bucket.
Definition: cntl.h:1045
lcb_create
lcb_error_t lcb_create(lcb_t *instance, const struct lcb_create_st *options)
Create an instance of lcb.
lcbauth_set_mode
lcb_error_t lcbauth_set_mode(lcb_AUTHENTICATOR *src, lcbauth_MODE mode)
lcbauth_unref
void lcbauth_unref(lcb_AUTHENTICATOR *auth)
lcb_create_st::version
int version
Indicates which field in the lcb_CRST_u union should be used.
Definition: couchbase.h:330
lcb_cntl_string
lcb_error_t lcb_cntl_string(lcb_t instance, const char *key, const char *value)
Alternatively one may change configuration settings by passing a string key and value.
lcb_cntl
lcb_error_t lcb_cntl(lcb_t instance, int mode, int cmd, void *arg)
This function exposes an ioctl/fcntl-like interface to read and write various configuration propertie...