couchdb_auth

Authentication helpers for the Apache CouchDB REST API, written in Elixir.

• Tested with:
  • Elixir 1.18.x / Erlang OTP 27
  • CouchDB 3.x

Overview

Apache CouchDB REST API client for Elixir.

Small, focused API surface that builds pre-configured Tesla.Clients for the main CouchDB interfaces.

Features

• HTTP REST client
• HTTP Authentication:
  • Basic Auth
  • Cookie Auth
  • OAuth 1.0a
  • Bearer / JWT tokens
  • Proxy authentication headers
• Cluster/admin helpers for _nodes endpoints
• Local document helpers for _local/<doc_id>

Installation

Add to mix.exs

  def deps do
    [{:couchdb_auth, "~> 0.2.4"}]
  end

Configuration

Project settings live in config/*.exs and can be overridden with environment variables prefixed with COUCHDB_. A minimal configuration looks like:

config :couchdb_auth,
  protocol: "http",
  hostname: "localhost",
  port: "5984",
  backend_port: "5986",
  database: "couchdb_test",
  auth_type: :admin_party

Authentication Modes

Choose an auth_type that matches your CouchDB deployment. The library accepts :admin_party, :basic, :cookie, :oauth, :bearer, and :proxy. Each mode reuses the same CouchDB.client/2 API; only the configuration changes.

Basic authentication

config :couchdb_auth,
  auth_type: :basic,
  username: "admin",
  password: "supersecret"

CouchDB.get("/_up")

The middleware adds an Authorization: Basic <base64> header to every request.

Cookie (session) authentication

config :couchdb_auth,
  auth_type: :cookie,
  username: "cookie",
  password: "monster"

CouchDB.get("/_users")

The middleware logs in via /_session, caches the Set-Cookie value, and reuses it on subsequent calls.

OAuth 1.0a

config :couchdb_auth,
  auth_type: :oauth,
  consumer_key: "...",
  consumer_secret: "...",
  token: "...",
  token_secret: "..."

CouchDB.get("/_membership")

The middleware signs each request and injects the Authorization: OAuth ... header. See the detailed setup guide below for provisioning CouchDB credentials.

Bearer / JWT

config :couchdb_auth,
  auth_type: :bearer,
  bearer_token: "eyJhbGciOi..."

CouchDB.get("/_up")

A static Authorization: Bearer <token> header is attached to each call.

Proxy authentication

config :couchdb_auth,
  auth_type: :proxy,
  proxy_user: "carol",
  proxy_roles: ["_admin", "developers"],
  proxy_secret: "shared-secret"

CouchDB.get("/_all_dbs")

Requests carry the X-Auth-CouchDB-* headers expected by CouchDB’s proxy authentication. Provide proxy_secret to let the middleware derive the token, or set proxy_token yourself when a precomputed value is required.

Admin & Cluster Helpers

Use the admin interface for _nodes configuration endpoints. When clustering is enabled (cluster: true), the client automatically prefixes /_nodes/<node>:

CouchDB.admin_get("/_config")

Local Documents

Local documents live under /_local/<id> and never replicate. The convenience helpers wrap the correct routing:

CouchDB.LocalDocs.get("cache")
CouchDB.LocalDocs.put("cache", %{rev: "1-abc"})

OAuth 1.0a CouchDB setup

Provisioning OAuth credentials requires a few one-time changes on the CouchDB node (defaults assume Docker networking with the host at 172.17.0.1):

1. Expose the backend interface: open http://localhost:5986/_utils, locate the httpd section, and set the bind_address (or bind) value to 0.0.0.0. Save the change.

2. Create an admin user to close admin party:

   curl -X PUT http://172.17.0.1:5986/_config/admins/admin -d '"supersecret"'

3. Generate four random secrets (consumer key, consumer secret, token, token secret). Repeat the command four times and record each digest:

   < /dev/urandom tr -dc _A-Za-z0-9 | head -c ${1:-2048} | sha256sum

4. Register the consumer credentials:

   curl -X PUT \
     http://admin:supersecret@172.17.0.1:5986/_config/oauth_consumer_secrets/<consumer_key> \
     -d '"<consumer_secret>"'

5. Register the token credentials:

   curl -X PUT \
     http://admin:supersecret@172.17.0.1:5986/_config/oauth_token_secrets/<token> \
     -d '"<token_secret>"'

6. Map the token to the admin user:

   curl -X PUT \
     http://admin:supersecret@172.17.0.1:5986/_config/oauth_token_users/<token> \
     -d '"admin"'

Each successful write returns an empty JSON string (""). Once the configuration is in place, copy the four values into config/*.exs (or COUCHDB_* environment variables) as shown in the OAuth example above.

Contributing

Authenticate GitHub CLI before using the automated PR command:

gh auth login
gh pr create --base master --head <your-branch> --title "feat: expand auth coverage for couchdb" --body "## Summary\n..."