1.2.25. Authentication¶
Interfaces for obtaining session and authorization data.
Note
We also strongly recommend you set up SSL to improve all authentication methods’ security.
1.2.25.1. Basic Authentication¶
Changed in version 3.4: In order to aid transition to stronger password hashing without causing a performance penalty, CouchDB will send a Set-Cookie header when a request authenticates successfully with Basic authentication. All browsers and many http libraries will automatically send this cookie on subsequent requests. The cost of verifying the cookie is significantly less than PBKDF2 with a high iteration count, for example.
Basic authentication (RFC 2617) is a quick and simple way to authenticate with CouchDB. The main drawback is the need to send user credentials with each request which may be insecure and could hurt operation performance (since CouchDB must compute the password hash with every request):
Request:
GET / HTTP/1.1
Accept: application/json
Authorization: Basic cm9vdDpyZWxheA==
Host: localhost:5984
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 177
Content-Type: application/json
Date: Mon, 03 Dec 2012 00:44:47 GMT
Server: CouchDB (Erlang/OTP)
{
"couchdb":"Welcome",
"uuid":"0a959b9b8227188afc2ac26ccdf345a6",
"version":"1.3.0",
"vendor": {
"version":"1.3.0",
"name":"The Apache Software Foundation"
}
}
1.2.25.3. Proxy Authentication¶
Note
To use this authentication method make sure that the
{chttpd_auth, proxy_authentication_handler}
value is added to the
list of the active chttpd/authentication_handlers
:
[chttpd]
authentication_handlers = {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, proxy_authentication_handler}, {chttpd_auth, default_authentication_handler}
Proxy authentication is very useful in case your application already uses some external authentication service and you don’t want to duplicate users and their roles in CouchDB.
This authentication method allows creation of a User Context Object for remotely authenticated user. By default, the client just needs to pass specific headers to CouchDB with related requests:
X-Auth-CouchDB-UserName
: usernameX-Auth-CouchDB-Roles
: comma-separated (,
) list of user rolesX-Auth-CouchDB-Token
: authentication token. Whenproxy_use_secret
is set (which is strongly recommended!), this header provides an HMAC of the username to authenticate and the secret token to prevent requests from untrusted sources. (Use one of the configured hash algorithms inchttpd_auth/hash_algorithms
and sign the username with the secret)
Creating the token (example with openssl):
echo -n "foo" | openssl dgst -sha256 -hmac "the_secret"
# (stdin)= 3f0786e96b20b0102b77f1a49c041be6977cfb3bf78c41a12adc121cd9b4e68a
Request:
GET /_session HTTP/1.1
Host: localhost:5984
Accept: application/json
Content-Type: application/json; charset=utf-8
X-Auth-CouchDB-Roles: users,blogger
X-Auth-CouchDB-UserName: foo
X-Auth-CouchDB-Token: 3f0786e96b20b0102b77f1a49c041be6977cfb3bf78c41a12adc121cd9b4e68a
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 190
Content-Type: application/json
Date: Fri, 14 Jun 2013 10:16:03 GMT
Server: CouchDB (Erlang/OTP)
{
"info": {
"authenticated": "proxy",
"authentication_db": "_users",
"authentication_handlers": [
"cookie",
"proxy",
"default"
]
},
"ok": true,
"userCtx": {
"name": "foo",
"roles": [
"users",
"blogger"
]
}
}
Note that you don’t need to request a session to be authenticated by this method if all required HTTP headers are provided.
1.2.25.4. JWT Authentication¶
Note
To use this authentication method, make sure that the
{chttpd_auth, jwt_authentication_handler}
value is added to the
list of the active chttpd/authentication_handlers
:
[chttpd]
authentication_handlers = {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, jwt_authentication_handler}, {chttpd_auth, default_authentication_handler}
JWT authentication
enables CouchDB to use externally-generated JWT tokens
instead of defining users or roles in the _users
database.
The JWT authentication handler requires that all JWT tokens are signed by a key that CouchDB has been configured to trust (there is no support for JWT’s “NONE” algorithm).
Additionally, CouchDB can be configured to reject JWT tokens that are
missing a configurable set of claims (e.g, a CouchDB administrator
could insist on the exp
claim).
Only claims listed in required checks are validated. Additional claims will be ignored.
Two sections of config exist to configure JWT authentication;
The required_claims
config
setting is a comma-separated list of additional mandatory JWT claims
that must be present in any presented JWT token. A 400 Bad Request
is sent if any are missing.
The alg
claim is mandatory as it used to lookup the correct key for verifying the
signature.
The sub
claim is mandatory and is used as the CouchDB user’s name if the JWT token
is valid.
You can set the user roles claim name through the config setting
roles_claim_name
. If you don’t set
an explicit value, then _couchdb.roles
will be set as the default claim name.
If presented, it is used as the CouchDB user’s roles
list as long as the JWT token is valid.
Note
Before CouchDB v3.3.2 it was only possible to define roles as a JSON array of strings. Now you can also use a comma-seperated list to define the user roles in your JWT token. The following declarations are equal:
JSON array of strings:
{
"_couchdb.roles": ["accounting-role", "view-role"]
}
JSON comma-seperated strings:
{
"_couchdb.roles": "accounting-role, view-role"
}
Warning
roles_claim_name
is deprecated in CouchDB 3.3, and will be removed later.
Please use roles_claim_path
.
; [jwt_keys]
; Configure at least one key here if using the JWT auth handler.
; If your JWT tokens do not include a "kid" attribute, use "_default"
; as the config key, otherwise use the kid as the config key.
; Examples
; hmac:_default = aGVsbG8=
; hmac:foo = aGVsbG8=
; The config values can represent symmetric and asymmetric keys.
; For symmetric keys, the value is base64 encoded;
; hmac:_default = aGVsbG8= # base64-encoded form of "hello"
; For asymmetric keys, the value is the PEM encoding of the public
; key with newlines replaced with the escape sequence \n.
; rsa:foo = -----BEGIN PUBLIC KEY-----\nMIIBIjAN...IDAQAB\n-----END PUBLIC KEY-----\n
; ec:bar = -----BEGIN PUBLIC KEY-----\nMHYwEAYHK...AzztRs\n-----END PUBLIC KEY-----\n
The jwt_keys
section lists all the keys that this CouchDB server trusts. You
should ensure that all nodes of your cluster have the same list.
Since version 3.3 it’s possible to use =
in parameter names, but only when
the parameter and value are separated =
, i.e. the equal sign is
surrounded by at least one space on each side. This might be useful in the
[jwt_keys]
section where base64 encoded keys may contain the =
character.
JWT tokens that do not include a kid
claim will be validated against the
{alg}:_default
key.
It is mandatory to specify the algorithm associated with every key for security reasons (notably presenting a HMAC-signed token using an RSA or EC public key that the server trusts: https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/).
Request:
GET /_session HTTP/1.1
Host: localhost:5984
Accept: application/json
Content-Type: application/json; charset=utf-8
Authorization: Bearer <JWT token>
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 188
Content-Type: application/json
Date: Sun, 19 Apr 2020 08:29:15 GMT
Server: CouchDB (Erlang/OTP)
{
"info": {
"authenticated": "jwt",
"authentication_db": "_users",
"authentication_handlers": [
"cookie",
"proxy",
"default"
]
},
"ok": true,
"userCtx": {
"name": "foo",
"roles": [
"users",
"blogger"
]
}
}
Note that you don’t need to request session to be authenticated by this method if the required HTTP header is provided.