For security reasons, we were occupied with bucket passwords and stumbled across the obviously undecided handling of cluster administration user name and password:
manager() also takes $username and $password as argument, but does something with them.
There is the undocumented method authenticate() which takes the undocumented class CouchbaseAuthenticator as argument, but does not check the type. If this authenticator is used, it is also obligatorily used for bucket passwords.
I have several questions in this context:
Why are there several ways to implement this relatively simple goal (two working and one not working)? What is the preferred way to handle the authentication?
What means “bucket-kv”? What are the “bucket-n1ql” credentials for?
Is it imaginable to evolve the CouchbaseAuthenticator to an interface with real methods instead of one big switch…case? We could elegantly code a wrapper around our own credentials mechanism with an interface. At least the magic string values should be defined as well documented constants.
At the moment we know the following documentation sources
The developer section in the “main documentation” is SDK switchable.
Especially the API reference is so fragmentary that it is hard to believe. At least there should be some text and types for parameters for every public method. The returned data also is essential. “@return mixed” without further explanation what to expect is e. g. a no-go for users of a public API. The translation is: “I don’t care what I return. Find out yourself. Subject to change without prior warning.”
Do we miss some important source for answering our questions? Are there any plans to improve the API documentation in the near future? In the best case, the API would even become a little bit type safe, but better documentation of parameters and return types would be a start for the smooth use.
Apologies for some of the confusion in there @kstorch.
Couchbase Server is in the process of transitioning from a model where there were some discontinuities between some of the different ways you might approach Couchbase. For instance, if you go back far enough in time there was only one administrative user for the cluster manager. Even in today’s releases, the KV service currently has no way to distinguish between the resource being accessed and who you are. Meanwhile, the Query service had specific functionality that required certain access levels.
The good news is we’re quickly changing this! And you’ve come across one of the building blocks for that change.
Couchbase Server 5.0 introduces a new way of being more fine grained about authentication and access privileges. In preparation for that and because some services (query and FTS) already needed a way to provide credentials for multiple buckets, we added the CouchbaseAuthenticator.
So, in effect, you see part of the new API and since it’s a step, we’ve not yet deprecated the old API. @avsej noted the same thing you did, and I’m sure we’ll be deprecating the older methods. I think some of this is planned for the 2.3 we’ve been working on and more will come into place in the next dot-minor releases as we get ready for 5.0.
Sorry about the API reference fragmentation. You’re absolutely right. I’ve filed PCBC-452 to look at this in general. I know improvements have been made in what we intend to ship in 2.3 If you have any specific questions, we can address them here in the forums.
My quick advise would be to, when doing bucket management, use the arguments on the manager(), and when otherwise working with a bucket use the arguments to openBucket() for the bucketname and password as covered in the Start Using section of the docs. The CouchbaseAuthenticator is not yet documented since it’ll be to cover new features (5.0’s RBAC and multi-bucket query).
For anything else, when you hit a question, please let us know. 2.3 will improve things, and we’ll improve further in that series.
Thanks a lot for the verbose answer which makes some things better understandable! We and future user of the API documentation will appreciate any improvement for the documentation because it means saved time every day.
Also at the moment we are discussing RFC-16, which is about new authentication mechanism which will be available in next Couchbase Server release: https://github.com/couchbaselabs/sdk-rfcs, so you are welcome to ask questions or provide feedback in the google doc linked from readme at RFC repository.