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";
lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_BUCKET_CRED, creds);

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_AUTHENTICATOR *	lcbauth_new (void)
lcb_STATUS	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_AUTHENTICATOR *	lcbauth_clone (const lcb_AUTHENTICATOR *src)
lcb_STATUS	lcbauth_set_mode (lcb_AUTHENTICATOR *src, lcbauth_MODE mode)

Typedefs
typedef struct lcbauth_CREDENTIALS_	lcbauth_CREDENTIALS

Enumerations
enum	lcbauth_ADDPASSFLAGS
	Flags to use when adding a new set of credentials to lcbauth_add_pass. More...
enum	lcbauth_RESULT
	Result could be used to notify the library that credentials cannot be resolved (e.g. More...
enum	lcbauth_SERVICE
enum	lcbauth_REASON
	Reason, why the library requests credentials.
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:

lcb_AUTHENTICATOR *auth = lcbauth_new();
lcbauth_set_mode(auth, LCBAUTH_MODE_RBAC);
lcbauth_add_pass(auth, "mark", "secret", LCBAUTH_F_CLUSTER);
 
lcb_INSTANCE 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_unref(auth);

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

lcb_AUTHENTICATOR *auth = lcbauth_new();
lcbauth_set_mode(auth, LCBAUTH_MODE_CLASSIC);
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_INSTANCE 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_unref(auth);

lcbauth_add_pass()

lcb_STATUS lcbauth_add_pass	(	lcb_AUTHENTICATOR *	auth,
		const char *	user,
		const char *	pass,
		int	flags
	)

Stability

Uncommitted:

Add a set of credentials

Parameters

auth
user	the username (or bucketname, if LCBAUTH_F_BUCKET is passed)
pass	the password. If the password is NULL, the credential is removed
flags	one 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_ERR_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

auth	The only time you would want to call this function is when sharing a single lcb_AUTHENTICATOR with multiple lcb_INSTANCE 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

src	the 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_STATUS lcbauth_set_mode	(	lcb_AUTHENTICATOR *	src,
		lcbauth_MODE	mode
	)

Stability

Uncommitted:

Set the mode of this authenticator.

Parameters

src	the authenticator
mode	the 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

enum 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_RESULT

enum lcbauth_RESULT

Result could be used to notify the library that credentials cannot be resolved (e.g.

3rd party provider is not available)

lcbauth_MODE

enum 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()