Authorization and authentication are important to Couchbase. In March, I blogged about some of the new Role Based Access Control (RBAC) that we are showing in the Couchbase Server 5.0 Developer Builds. This month, I’d like to go into a little more detail now that the April Couchbase Server 5.0 Developer Build is available (make sure to click the “Developer” tab).

Authentication and authorization

In past version of Couchbase, buckets were secured by a password. In 5.0, bucket passwords for authorization are gone. You can no longer create a “bucket password” for authorization. Instead, you must create one (or more) users that have varying levels of authorization for that bucket. Notice that there is no “password” field anymore (not even in the “Advance bucket settings”:

Create a new Couchbase bucket - no password for authorization

So now, you no longer have to hand out a password that gives complete access to a bucket. You can fine-tune bucket authorization, and give out multiple sets of credentials with varying levels of access. This will help you tighten up security, and reduce your exposure.

Note: The administrator user still exists, and has permission to do everything. So I can still run N1QL queries (for instance) on that bucket while logged in as an administrator account. However, this is not the account you should be using from your clients.

Creating an authorized user

To create a new user, you must be logged in as an administrator (or as a user that has an Admin role). Go to the “Security” tab, and you’ll be able to see a list of users, and be able to add new ones.

Create a new user by clicking “ADD USER”. Enter the information for the user. You may want to create a user for a person (e.g. “Matt”), or you may want to create a user for a service (e.g. “MyAspNetApplication”). Make sure to enter a strong password, and then select the appropriate roles for the user you want to create.

For example, let’s create a user “Matt” that only has access to run SELECT queries on the bucket I just created. In “Roles”, I expand “Query Roles”, then “Query Select”, and check the box for “mynewbucket”, and then “Save” to finalize the user.

Create a new user with authorization to run a select query

Authorization in action

When I log out of the administrator account, and log back in as “Matt”, I can see that the authorization level I have is severely restricted. Only “Dashboard”, “Servers”, “Settings”, and “Query” are visible. If I go to “Query” I can execute SELECT 1;

Execute SELECT query logged in with only Query authorization

If I try something more complex, like SELECT COUNT(1) FROM mynewbucket, I’ll get an error message like:

So, it looks like I have the correct authentication to log in, and I have the correct authorization to execute a SELECT, but I don’t have the correct authorization to actually read the data. I’ll go back in as admin, and add Data Reader authorization.

User now has authorization for two roles

At this point, when I login with “Matt”, SELECT COUNT(1) FROM mynewbucket; will work. If you are following along, try SELECT * FROM mynewbucket;. You’ll get an error message that no index is available. But, if you try to CREATE INDEX you’ll need another permission to do that. You get the idea.

New N1QL functionality

There’s some new N1QL functionality to go along with the new authentication and authorization features.

GRANT and REVOKE ROLE

You can grant and revoke roles with N1QL commands. You need Admin access to do this.

Here’s a quick example of granting SELECT query authorization to a user named “Matt” on a bucket called “mynewbucket”:

GRANT ROLE query_select(mynewbucket) TO Matt;

And likewise, you can REVOKE a role doing something similar:

REVOKE ROLE query_select(mynewbucket) FROM Matt;

Creating users with REST

There is no way (currently) to create users with N1QL, but you can use the REST API to do this. Full documentation is coming later, but here’s how you can create a user with the REST API:

  • PUT to the /settings/rbac/users/builtin/<username> endpoint.
  • Use admin credentials for this endpoint (e.g. Administrator:password with basic auth)
  • The body should contain:
    • roles=<role1,role2,…​,roleN>
    • password=<password>

Below is an example. You can use cURL, Postman, Fiddler, or whatever your favorite tool is to make the request.

Headers: Content-Type: application/x-www-form-urlencoded
Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==

Body: roles=query_select[mynewbucket],query_update[mynewbucket]&password=password

The above assumes that you have an admin user/password of Administrator/password (hence the basic auth token of QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==).

After executing that, you’ll see a new user named “restman” with the two specified permissions.

Create a new user with a REST command

Wait, there’s more!

The RBAC system is far too rich to cover in a single blog post, and full documentation is on its way. In the meantime, here are some details that might help you get started with the preview:

  • You may have noticed the all option in the screenshots above. You can give a user roles on a bucket-by-bucket basis, or you can give permission to all buckets (even buckets that haven’t been created yet).
  • I covered FTS permissions in the previous blog post, but there are permissions that cover just about everything: views, bucket administration, backup, monitoring, DCP, indexes, etc.
  • You can’t create buckets with a password anymore. The equivalent is to instead create a user with the name as the bucket, and give it authorization to a role called “Bucket Full Access”. This will be useful for upgrading and transitioning purposes.

We still want your feedback!

Stay tuned to the Couchbase Blog for information about what’s coming in the next developer build.

Interested in trying out some of these new features? Download Couchbase Server 5.0 April 2017 Developer Build today!

The 5.0 release is fast approaching, but we still want your feedback!

Bugs: If you find a bug (something that is broken or doesn’t work how you’d expect), please file an issue in our JIRA system at issues.couchbase.com or submit a question on the Couchbase Forums. Or, contact me with a description of the issue. I would be happy to help you or submit the bug for you (my Couchbase handlers let me take selfies on our cartoonishly big couch when I submit good bugs).

Feedback: Let me know what you think. Something you don’t like? Something you really like? Something missing? Now you can give feedback directly from within the Couchbase Web Console. Look for the feedback icon icon at the bottom right of the screen.

In some cases, it may be tricky to decide if your feedback is a bug or a suggestion. Use your best judgement, or again, feel free to contact me for help. I want to hear from you. The best way to contact me is either Twitter @mgroves or email me matthew.groves@couchbase.com.

Author

Posted by Matthew Groves

Matthew D. Groves is a guy who loves to code. It doesn't matter if it's C#, jQuery, or PHP: he'll submit pull requests for anything. He has been coding professionally ever since he wrote a QuickBASIC point-of-sale app for his parent's pizza shop back in the 90s. He currently works as a Senior Product Marketing Manager for Couchbase. His free time is spent with his family, watching the Reds, and getting involved in the developer community. He is the author of AOP in .NET, Pro Microservices in .NET, a Pluralsight author, and a Microsoft MVP.

5 Comments

  1. maybe you can post example roles sets for some frequently-used use case,such as the role of Sync Gateway connect Couchbase Server; the role to run FTS; the role to run prepared statement.

    1. Documentation is coming :)

      The FTS roles I covered in part 1: https://www.couchbase.com/authentication-authorization-rbac/

      I don’t think there’s a role specifically for Sync Gateway connectivity. It would probably be something like a Cluster Admin or Bucket Admin role or something like that.

      Prepared statements would probably be covered by query_* roles.

  2. […] See Matthew’s Introduction to Role-Based Access Control: Part 1 & Part 2 […]

  3. Tyler Mitchell May 4, 2017 at 1:35 pm

    To use the new features you have will need to upgrade your client applications. Here’s how: https://www.couchbase.com/new-sdk-authentication/

Leave a reply