How does CouchDB implement authentication — cookie auth, JWT, and proxy auth?

CouchDB supports four authentication mechanisms, configurable simultaneously. Each request is checked against the enabled handlers in order.

1. Basic Authentication — HTTP Basic Auth over HTTPS. Credentials are sent with every request. Simple to implement but requires HTTPS in production to avoid credential exposure.

curl -u admin:password http://localhost:5984/_session

2. Cookie (Session) Authentication — the most common for web apps. POST credentials to /_session to receive a session cookie, then use that cookie for subsequent requests. The cookie has a configurable timeout.

# Login and get a session cookie
curl -X POST http://localhost:5984/_session \
  -H "Content-Type: application/json" \
  -d '{"name":"alice","password":"s3cret"}'
# Set-Cookie: AuthSession=abc123...; Version=1; Secure; HttpOnly

# Use the session
curl -b "AuthSession=abc123..." http://localhost:5984/mydb/_all_docs

# Logout
curl -X DELETE http://localhost:5984/_session -b "AuthSession=abc123..."

3. JWT Authentication (CouchDB 3.3+) — validates a JSON Web Token in the Authorization: Bearer {token} header. The JWT must contain a sub claim (the username) and optionally _couchdb.roles. CouchDB verifies the signature using a configured HMAC secret or RSA public key — it does not issue JWTs, only validates them.

[jwt_auth]
required_claims = exp
[jwt_keys]
hmac:default = aGVsbG93b3JsZA==

4. Proxy Authentication — for reverse-proxy setups (nginx, HAProxy). The proxy authenticates the user externally and forwards the identity in headers (X-Auth-CouchDB-UserName, X-Auth-CouchDB-Roles, X-Auth-CouchDB-Token). CouchDB trusts the headers if the correct HMAC token is present.