Hey Couchers,
I'd like to add OAuth support to CouchDB. In thinking about how to make
a oauth_authentication_handler much like Jason's
cookie_authentication_handler
I went a little further and see how this would fit into a more fine
grained
authentication and authorization system for CouchDB.
I'd like to get my work in progress out here to get your feedback and
guidance.
I'm not married to any of the nomenclature, so feel free to suggest
alternatives
along the way.
OAuth won't need all of that is outlined here, but it would use the
foundations of
this system, and I'd like to get that right from the get go.
Your input is highly appreciated, thanks!
--
# CouchDB Authentication and Authorization
This document describes a potential CouchDB authentication and
authorization system.
## Authentication
An HTTP request can contain credentials that identify a user in
numerous ways. The authentication mechanism should treat HTTP basic
authentication, cookie authentication, OAuth or any other future
system transparently.
## The Authentication Database
CouchDB will use a `users` database (the authentication database) to
authenticate users. User credentials must identify a user uniquely. A
username / password combination must point to a single user. An OAuth
token must identify a single user.
The authentication database contains documents identified by UUIDs.
Authentication handlers (see below) create views on the authentication
database to look up a user for a given credential.
The request record that gets passed around the CouchDB internals
carries the user's id after the user successfully authenticated.
## Authentication Handlers
An authentication handler is an Erlang module that takes authenticates
a user given handler-specific authentication data. A handler installs
a view in the authentication database to look up user ids by login
credentials that come in with a request.
A an example authentication client request
| client | ---> | http request with credentials | ---> |
authentication handler | ---> | lookup in authentication handler
specific view in `users` database | ---> | grant or deny access, set
role |
### The Default Authentication Handler
The default authentication handler creates a view `_design/default/
_view/by-credential` to to look up `login` for a given request.
### The Cookie Authentication Handler
The cookie authentication handler creates a view `_design/cooie/_view/
by-credential` to to look up `request_token` for a given request.
### The OAuth Authentication Handler
The OAuth authentication handler creates a view `_design/cooie/_view/
by-credential` to to look up `request_token` for a given request.
## Authorization
Each database contains a set of `_user/userid` documents. Roles
documents include an array of roles for a given user:
{
_id: "_user/123ccadd254",
_rev: "1-74474398",
roles: ["owner"]
}
The `roles` array can include `"owner"`, `"writer"` and `"reader"`.
### Database Owners
Database owners can create, edit and delete `_design/` and `_user/`
docs as well as creating, reading, updating and deleting regular
documents.
### Database Writers
Database writers can only create, read, update and delete regular
documents.
### Database Readers
Database readers can only read documents.
### Anonymous Users
An anonymous user gets identified with the id `_anonymous`. If the
`_user/_anonymous` document includes the role `"guest"`, anonymous
users can create, read, update and delete regular documents.
If the `_user/_anonymous` document includes the role `"owner"`,
anonymous users can create, read, update and delete `_design`
documents as well as regular documents.
### `_user/` Document and Replication
`_user/` documents do not replicate by default. A replication trigger
option replicates them:
POST /_replication HTTP/1.1
{"source":"db","target":"db-replica":"include_role_docs":true}
## Recommendations
User specific data like an avatar picture should live in the
authentication database.
Application-specific user-data should live in regular documents
managed by the application and *not* `_user/` documents.
--
Cheers
Jan
--
