Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tyler-johnson/couchdb-auth-proxy
An HTTP reverse proxy server for easy Couchdb proxy authentication
https://github.com/tyler-johnson/couchdb-auth-proxy
Last synced: 5 days ago
JSON representation
An HTTP reverse proxy server for easy Couchdb proxy authentication
- Host: GitHub
- URL: https://github.com/tyler-johnson/couchdb-auth-proxy
- Owner: tyler-johnson
- License: mit
- Created: 2016-08-03T17:54:12.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2018-03-21T12:50:48.000Z (over 6 years ago)
- Last Synced: 2024-08-10T04:19:56.577Z (3 months ago)
- Language: JavaScript
- Size: 15.6 KB
- Stars: 28
- Watchers: 4
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-starred - tyler-johnson/couchdb-auth-proxy - An HTTP reverse proxy server for easy Couchdb proxy authentication (others)
README
# CouchDB Auth Proxy
[](https://www.npmjs.com/package/couchdb-auth-proxy) [](https://travis-ci.org/tyler-johnson/couchdb-auth-proxy)
A Node.js HTTP reverse proxy library for quick and dirty CouchDB proxy authentication.
## Install
Install from NPM
```bash
npm install couchdb-auth-proxy -S
```
And import into your project
```js
import couchdbProxy from "couchdb-auth-proxy";
```
```js
const couchdbProxy = require("couchdb-auth-proxy");
```
## Usage
> Note: 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. See the [CouchDB Docs](http://docs.couchdb.org/en/1.6.1/api/server/authn.html#proxy-authentication) for more info.
This library generates an HTTP server request function from two arguments: a user context method and some options. This method will work with Express/Connect apps as well as the plain Node.js HTTP server.
Here is an example proxy that authenticates every request as a super admin:
```js
const server = http.createServer(couchdbProxy(function(req) {
// admin party!
return {
name: null,
roles: [ "_admin" ]
};
}));
```
In CouchDB, users are represented with a user context object. These are 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.
Your proxy can complete asynchronous tasks, great for authenticating against other databases or services. You can return a promise, or provide a third argument for a callback.
```js
const server = http.createServer(couchdbProxy(function(req, res, next) {
const token = req.get("Authorization");
db.authenticateToken(token, (err, user) => {
if (err) return next(err);
next(null, {
name: user.name,
roles: []
});
});
}));
```
## API
#### `couchdbProxy( userCtxFn [, options ] ) → Middleware`
- `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.
- `options` (Object) - Options to configure the proxy.
- `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). Defaults to `http://localhost:5984`.
- `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 only required if `couch_httpd_auth/proxy_use_secret` is enabled on CouchDB (which is recommended).
- `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.
- `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:
```json
{
"username": "X-Auth-CouchDB-UserName",
"roles": "X-Auth-CouchDB-Roles",
"token": "X-Auth-CouchDB-Token"
}
```
- `options.info` (Object) - Some JSON serializable value that will be injected into the CouchDB's root info document response.