|
| 1 | +# couchdb-auth-proxy |
| 2 | + |
| 3 | +[](https://www.npmjs.com/package/couchdb-auth-proxy) [](https://david-dm.org/tyler-johnson/couchdb-auth-proxy) [](https://travis-ci.org/tyler-johnson/couchdb-auth-proxy) |
| 4 | + |
| 5 | +An HTTP reverse proxy server for easy CouchDB proxy authentication. |
| 6 | + |
| 7 | +## Install |
| 8 | + |
| 9 | +Install from NPM |
| 10 | + |
| 11 | +```bash |
| 12 | +npm install couchdb-auth-proxy -S |
| 13 | +``` |
| 14 | + |
| 15 | +And import into your project |
| 16 | + |
| 17 | +```js |
| 18 | +import couchdbProxy from "couchdb-auth-proxy"; |
| 19 | +``` |
| 20 | + |
| 21 | +```js |
| 22 | +const couchdbProxy = require("couchdb-auth-proxy"); |
| 23 | +``` |
| 24 | + |
| 25 | +## Usage |
| 26 | + |
| 27 | +To begin, ensure proxy authentication is enabled on your CouchDB server. This is as simple as adding `{couch_httpd_auth, proxy_authentication_handler}` to the list of active authentication handlers in your configuration. Your `local.ini` file should have a line that looks something like this: |
| 28 | + |
| 29 | +```ini |
| 30 | +[httpd] |
| 31 | +authentication_handlers = {couch_httpd_oauth, oauth_authentication_handler}, {couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, proxy_authentication_handler}, {couch_httpd_auth, default_authentication_handler} |
| 32 | +``` |
| 33 | + |
| 34 | +This library returns an Express/Connect middleware function. It accepts two arguments: a user context method and some options. |
| 35 | + |
| 36 | +```js |
| 37 | +const app = express(); |
| 38 | + |
| 39 | +app.use(couchdbProxy(function(req) { |
| 40 | + // admin party! |
| 41 | + return { |
| 42 | + name: null, |
| 43 | + roles: [ "_admin" ] |
| 44 | + }; |
| 45 | +})); |
| 46 | +``` |
| 47 | + |
| 48 | +In CouchDB, users are represented with a user context object. These are simply objects with `name` and `roles` fields. Usually this information comes from a document in the `_users` database, however we can also generate it from other means. |
| 49 | + |
| 50 | +This library allows you to complete asynchronous authentication lookup, return a promise or pass `next` as the third argument. If you do use the `next()` callback, you absolutely must call it, or the request will never complete. |
| 51 | + |
| 52 | +```js |
| 53 | +app.use(couchdbProxy(function(req, res, next) { |
| 54 | + const token = req.get("Authorization"); |
| 55 | + |
| 56 | + validateToken(token, function(err, user) { |
| 57 | + if (err) return next(err); |
| 58 | + |
| 59 | + return { |
| 60 | + name: user.name, |
| 61 | + roles: [] |
| 62 | + }; |
| 63 | + }); |
| 64 | +})); |
| 65 | +``` |
| 66 | + |
| 67 | +## API |
| 68 | + |
| 69 | +#### `couchdbProxy( userCtxFn [, options ] ) → Middleware` |
| 70 | + |
| 71 | +- `userCtxFn` (Function, *required*) - Method called on every request, with the request `req` and response `res` as arguments. This method should return a plain object with `name` and `roles` fields, representing the authenticated user. To run an async task, return a promise or pass a third argument `next` for a callback. |
| 72 | +- `options` (Object) - Options to configure the proxy. |
| 73 | + - `options.target` (String) - The URL of the CouchDB server to proxy to. This server must have [proxy authentication enabled](http://docs.couchdb.org/en/1.6.1/api/server/authn.html#proxy-authentication). |
| 74 | + - `options.secret` (String) - The [CouchDB secret](http://docs.couchdb.org/en/1.6.1/config/auth.html#couch_httpd_auth/secret) used to sign proxy tokens and cookies. This is very much an optional parameter and in general there is very little reason to use a secret. This is only absolutely required if `couch_httpd_auth/proxy_use_secret` is enabled on CouchDB. |
| 75 | + - `options.via` (String) - The name of the proxy to add to the `Via` header. This is so consumers of the HTTP API can tell that the request was directed through a proxy. This is optional and the `Via` header will be excluded when not provided. |
| 76 | + - `options.headerFields` (Object) - A map of custom header fields to use for the proxy. This should match what is declared in CouchDB `couch_httpd_auth` configuration, under `x_auth_roles`, `x_auth_token`, and `x_auth_username`. This is the default map: |
| 77 | + ```json |
| 78 | + { |
| 79 | + "username": "X-Auth-CouchDB-UserName", |
| 80 | + "roles": "X-Auth-CouchDB-Roles", |
| 81 | + "token": "X-Auth-CouchDB-Token" |
| 82 | + } |
| 83 | + ``` |
0 commit comments