Аутентификация

Базовая аутентификация

Базовая аутентификация (RFC 2617) — быстрый и простой способ аутентификации в CouchDB. Главный недостаток заключается в необходимости отправлять учётные данные пользователя с каждым запросом: это может быть небезопасно и снижать производительность (поскольку CouchDB должна вычислять хеш пароля при каждом запросе):

Запрос:

GET / HTTP/1.1
Accept: application/json
Authorization: Basic cm9vdDpyZWxheA==
Host: localhost:5984

Ответ:

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"
    }
}

Аутентификация с помощью cookie

При аутентификации с помощью cookie (RFC 2109) CouchDB создаёт токен, который клиент может использовать в следующих запросах к CouchDB. Срок действия токенов ограничен. Если CouchDB получает действительный токен в последующем запросе, пользователь проходит аутентификацию по этому токену без повторного запроса пароля. По умолчанию cookie действительны в течение 10 минут, но это значение можно изменить с помощью timeout. Кроме того, можно сделать cookie persistent.

Чтобы получить первый токен и впервые аутентифицировать пользователя, необходимо отправить username и password в API _session.

Аутентификация через прокси

[chttpd]
authentication_handlers = {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, proxy_authentication_handler}, {chttpd_auth, default_authentication_handler}

Аутентификация через прокси очень полезна, если ваше приложение уже использует внешнюю службу аутентификации и вы не хотите дублировать пользователей и их роли в CouchDB.

Этот метод аутентификации позволяет создать объект контекста пользователя для пользователя, прошедшего удалённую аутентификацию. По умолчанию клиенту достаточно передавать CouchDB специальные заголовки в соответствующих запросах:

• X-Auth-CouchDB-UserName: имя пользователя

• X-Auth-CouchDB-Roles: разделённый запятыми (,) список ролей пользователя

• X-Auth-CouchDB-Token: токен аутентификации. Если задан параметр proxy_use_secret (что настоятельно рекомендуется!), этот заголовок содержит HMAC имени пользователя, проходящего аутентификацию, и секретного токена, чтобы предотвратить запросы из ненадёжных источников. (Используйте один из настроенных алгоритмов хеширования в chttpd_auth/hash_algorithms и подпишите имя пользователя секретом.)

Создание токена (пример с openssl):

echo -n "foo" | openssl dgst -sha256 -hmac "the_secret"
# (stdin)= 3f0786e96b20b0102b77f1a49c041be6977cfb3bf78c41a12adc121cd9b4e68a

Запрос:

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

Ответ:

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"
        ]
    }
}

Обратите внимание: для аутентификации этим методом не нужно запрашивать сеанс, если указаны все необходимые HTTP-заголовки.

Аутентификация JWT

[chttpd]
authentication_handlers = {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, jwt_authentication_handler}, {chttpd_auth, default_authentication_handler}

JWT authentication позволяет CouchDB использовать созданные внешними средствами токены JWT вместо определения пользователей или ролей в базе данных _users.

Обработчик аутентификации JWT требует, чтобы все токены JWT были подписаны ключом, которому CouchDB настроена доверять (алгоритм «NONE» для JWT не поддерживается).

Кроме того, CouchDB можно настроить на отклонение токенов JWT, в которых отсутствует заданный набор утверждений (например, администратор CouchDB может потребовать наличие утверждения exp).

Проверяются только утверждения, перечисленные в обязательных проверках. Дополнительные утверждения игнорируются.

Для настройки аутентификации JWT предусмотрены два раздела конфигурации;

Параметр конфигурации required_claims представляет собой разделённый запятыми список дополнительных обязательных утверждений JWT, которые должны присутствовать в любом переданном токене JWT. Если какое-либо из них отсутствует, возвращается ответ 400 Bad Request.

Утверждение alg является обязательным, поскольку с его помощью определяется правильный ключ для проверки подписи.

Утверждение sub является обязательным и используется в качестве имени пользователя CouchDB, если токен JWT действителен.

Имя утверждения для ролей пользователя можно задать с помощью параметра конфигурации roles_claim_name. Если явно не указать значение, в качестве имени утверждения по умолчанию будет использоваться _couchdb.roles. Если оно присутствует, то при действительном токене JWT используется как список ролей пользователя CouchDB.

{
    "_couchdb.roles": ["accounting-role", "view-role"]
}

{
    "_couchdb.roles": "accounting-role, view-role"
}

; [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

Раздел jwt_keys содержит список всех ключей, которым доверяет этот сервер CouchDB. Убедитесь, что на всех узлах кластера используется одинаковый список.

Начиная с версии 3.3 в именах параметров можно использовать =, но только если параметр и значение разделены  = , то есть знак равенства окружён как минимум одним пробелом с каждой стороны. Это может быть полезно в разделе [jwt_keys], где ключи в кодировке base64 могут содержать символ =.

Токены JWT, не содержащие утверждения kid, будут проверяться с помощью ключа {alg}:_default.

В целях безопасности для каждого ключа необходимо указать соответствующий алгоритм (в частности, чтобы предотвратить предъявление токена с подписью HMAC с использованием открытого ключа RSA или EC, которому доверяет сервер: https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/).

Запрос:

GET /_session HTTP/1.1
Host: localhost:5984
Accept: application/json
Content-Type: application/json; charset=utf-8
Authorization: Bearer <JWT token>

Ответ:

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"
        ]
    }
}

Обратите внимание: для аутентификации этим методом не нужно запрашивать сеанс, если указан необходимый HTTP-заголовок.

Двухфакторная аутентификация (2FA)

CouchDB поддерживает встроенную аутентификацию на основе временных одноразовых паролей (TOTP), поэтому двухфакторную аутентификацию можно включить для любого пользователя без дополнительных плагинов или инструментов. Ниже описана настройка.

LC_ALL=C tr -dc 'A-Z2-7' </dev/urandom | head -c 32; echo

curl -X PUT http://admin:password@localhost:5984/_users/org.couchdb.user:USERNAME \
-H "Content-Type: application/json" \
-d '{
    "name": "USERNAME",
    "password": "PASSWORD",
    "roles": [],
    "type": "user",
    "totp": { "key": "YOURTOKEN" }
}'

POST /_session HTTP/1.1
Host: localhost:5984
Accept: application/json
Content-Type: application/json; charset=utf-8

{
    "name": "USERNAME",
    "password": "PASSWORD",
    "token": "123456"
}

{"ok": true, "name": "USERNAME", "roles": []}

curl -c cookie.txt -X POST http://localhost:5984/_session \
    -H "Content-Type: application/json" \
    -d '{"name": "USERNAME", "password": "PASSWORD", "token": "123456"}'

# Example using the cookie.txt
curl -b cookie.txt http://localhost:5984/DB_NAME/DOC_NAME

# Example passing AuthSession directly
curl -H "Cookie: AuthSession=AUTH_SESSION_COOKIE" http://localhost:5984/DB_NAME/DOC_NAME