Couchbase Server 5.0 delivers some great new authentication features that require some minor changes to your client connection code.  The specific changes to the SDK are outlined in this post and also refer to changes made in the pre-release April Developer Build as well as upcoming Beta releases.
See Matthew’s Introduction to Role-Based Access Control: Part 1 & Part 2
In a nutshell, bucket-based passwords (and passwordless buckets) are now a thing of the past.  Instead, we’ve provided fine-grained role level access control to buckets, data and all services.  You are now able to create a user with specific roles and access rights, then connect as that user (with password) in your client.
There are three specific patterns to using these new features, I review each option in this post.
As this is based on pre-production server code, examples may change.  Please also note that you need to have the latest SDK libraries for your language, supported at the time of writing are Java, .NET, Node.js, PHP, Python, Go and C.
User Named Buckets
If you continue to use the basic URI connection string for a bucket without a username, there are some assumptions that the client now makes.
First, it will assume you have a user with the same name as your bucket.  Migrating users from earlier versions will appreciate this as all they have to do is provide a password with the connection string as shown in this Python example:
|
1 |
>>> db = Bucket("couchbase://localhost/tyler",password="tyler123") |
(This simplified usage is limited to Python, PHP and C libraries)
The above assumes not only that there is a bucket named tyler but also a user named tyler who has a bucket access role enabled.
Passwordless buckets are no longer allowed, but with one exception: migrated buckets.  It is impossible to create a new user without a password but the migration process will create users, without passwords, for buckets that formerly did not have one.
As above, the user will have the same name as the bucket and no password.  In that case you can pass an empty password string with the connection string.
After the migration, new buckets and users will all require passwords, so this is a good time to change your approach going forward.
Passing Username and Password With Bucket Name
The new authentication paradigm going forward has two ways of managing authenticated connections.  The simplest approach is to adjust the connection parameters to include both username and password, this is easily done in Python, :
|
1 |
>>> db = Bucket("couchbase://localhost/travel-sample", username="tyler", password="tyler123") |
However, this is a very simplistic approach. Â There is a more powerful option that uses the new Authenticator class to manage authentication against, potentially, multiple buckets.
Authenticator Class  for Handling Users and Buckets
The “proper” way to handle authentication is to de-couple it from the Bucket URI altogether and pass it to the Cluster connection when needed.
Here the Authenticator initialization takes a given Cluster and authenticates against it.  In these examples, you see that the pattern across languages is the same.  The Authenticator can then be passed to other Clusters as desired.
Python
|
1 2 3 4 5 6 7 8 |
from couchbase.cluster import Cluster from couchbase.cluster import PasswordAuthenticator cluster = Cluster('couchbase://localhost') authenticator = PasswordAuthenticator('username', 'password') cluster.authenticate(authenticator) bucket = cluster.open_bucket('bucket-name') |
Java
|
1 2 3 |
Cluster cluster = CouchbaseCluster.create(); cluster.authenticate("username", "password"); Bucket bucket = cluster.openBucket("bucket-name"); |
.NET
|
1 2 3 4 5 |
var cluster = new Cluster(new ClientConfiguration { Servers = new List<Uri> { new Uri("http://localhost") }}); var authenticator = new PasswordAuthenticator("username", "password"); cluster.Authenticate(authenticator); var bucket = cluster.OpenBucket("bucket-name"); |
PHP
|
1 2 3 4 5 |
$authenticator = new \Couchbase\PasswordAuthenticator(); $authenticator->username('username')->password('password'); $cluster = new \Couchbase\Cluster('couchbase://localhost'); $cluster->authenticate($authenticator); |
Node.js
|
1 2 3 4 |
var couchbase = require('couchbase'); var cluster = new couchbase.Cluster('couchbase://localhost/'); cluster.authenticate('username', 'password'); var bucket = cluster.openBucket('bucket-name'); |
Next Steps
Notice that the main design change in your applications is to not use a bucket specific password.  Instead, you need to have a user with an adequate role that has access to particular buckets.
With only a couple lines of code change you easily take advantage of the role-based access control features of Couchbase Server 5.0.
Upgrade to the latest developer build and upgrade your client libraries to start trying it out.
Join us in the forums with any questions!
[…] https://staging.couchbase.com/new-sdk-authentication/ […]
I need to establish an SSL connection. How would I specify the certpath in the new SDK? Specifically I’m using python. In the past I did something like this:
db = Bucket(“couchbase://localhost/tyler?certpath=/etc/ca-bundle.crt”,password=”tyler123″)
Hi, thanks for reading! Same way as usual, just be sure have the “s” at end of “couchbases://”… Let me know if you get stuck again.
Hi Tyler,
I should have clarified my question was specifically how and where to specify the cert path file? We use self-signed certs and without specifying this I get “RC=0x37[Client could not verify server’s certificate]”
In the past the certpath was passed as a url-style param in the connection string. I’m not sure how to specify this in the new sdk.