Cannot update _security document using Cloudant python

[mikerhodes]

You cannot update a _security document using python-cloudant. If you run the following script:

from cloudant.account import Cloudant

client = Cloudant(USERNAME, PASSWORD, account=ACCOUNT_NAME)
client.connect()
session = client.session()
database = client[DATABASE_NAME]
security_document = database[DOC_NAME]
print "Got security_document: ", security_document

# Update the security_document with the API key permissions
security_document[u'cloudant'][u'bouninamendouldnimendepa'] = [u'_reader']

security_document.save()

client.disconnect()

You get a problem because _security documents do not have _rev fields (they are not versioned in the same way):

Traceback (most recent call last):
  File "main.py", line 23, in <module>
    security_document.save()
  File "/Users/mike/scratch/python-cloudant/issue-49/lib/python2.7/site-packages/cloudant/document.py", line 172, in save
    super(Document, self).__setitem__('_rev', data['rev'])
KeyError: 'rev'

I should've spotted this issue; it's probably an issue elsewhere too.

[alfinkel]

@mikerhodes we are not wrapping _security documents as Document for that very reason. For now we are using the share_database and unshare_database methods to manage permissions for users and API keys. So the _security document would be updated that way. I suppose that I see your point in that you want to be able to handle the _security document as a Document so we can let this issue track that enhancement. As for the "rev" finding it should not be an issue other than in this case but again the _security document was not meant to be wrapped as a Document when this library was initially written.

[alfinkel]

@mikerhodes - I spoke to @evansde77 about setting permissions and the sharing databases. I've summarized the major points of our conversation below:

• Using the _api/v2/db/$db/_security endpoint (as is used in the share_database method of this library) accomplishes two things when sharing a database.
  1. Sets permissions in the database _security document for the user being granted "shared" access.
  2. Adds the database to the list of shared databases for the user to that user's user document (done via wilson). Note: We believe this to be the case. I will confirm and make a note here if this is NOT the case. Basically, this is how the user gets alerted to the fact that a database has been shared with them via the dashboard.
• Using the _security endpoint would only perform the setting of permissions in the _security document. This means a couple of things to us:
  1. We need to add an API that allows for the management of the _security document as already was pointed out in an earlier comment. But what has become more clear is that we need to be able to manage security for both CouchDB and Cloudant which we currently do not do at all for CouchDB in this library.
  2. While not ideal, the share_database method could possibly be used to set permissions for an API key since it would update the database security document, but it is unclear what would happen with the whole user document update piece. But since the API key is not technically a "user" then theoretically it should not be an issue. I will confirm that as well and make another note if necessary.
• The share_database method list of roles ('_reader', '_writer', '_admin') that can be set as part of the sharing process is not a complete list. The full list of roles needs to be added to that API to make it complete. Based on this, I think the best way to advise anyone interested in setting permissions on a database is to access the _security endpoint directly as is described in our endpoint access documentation for functionality that is still unavailable in this library.

[mikerhodes]

@alfinkel Seems clearer. For me, the naming of share/unshare is very use-case specific (to sharing databases) -- therefore editing the _security doc to add permissions is a separate thing.

[alfinkel]

I've opened #98 to split out the work involving the share_database missing roles. So this Issue is just for the direct management of the security document.