1.2.23. 身份验证¶

用于获取会话和授权数据的接口。

注意

我们还强烈建议您设置 SSL 以提高所有身份验证方法的安全性。

1.2.23.1. 基本身份验证¶

基本身份验证 (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"
    }
}

1.2.23.3. 代理身份验证¶

注意

要使用此身份验证方法，请确保将 {chttpd_auth, proxy_authentication_handler} 值添加到活动 chttpd/authentication_handlers 列表中。

[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 标头，则无需请求会话即可通过此方法进行身份验证。

1.2.23.4. JWT 身份验证¶

注意

要使用此身份验证方法，请确保已将 {chttpd_auth, jwt_authentication_handler} 值添加到活动 chttpd/authentication_handlers 列表中。

[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 配置为信任的密钥签名（不支持 JWT 的“NONE”算法）。

此外，可以配置 CouchDB 以拒绝缺少可配置声明集的 JWT 令牌（例如，CouchDB 管理员可以坚持使用 exp 声明）。

仅验证所需检查中列出的声明。其他声明将被忽略。

存在两个配置部分来配置 JWT 身份验证；

required_claims 配置设置是必须出现在任何提交的 JWT 令牌中的其他必需 JWT 声明的逗号分隔列表。如果缺少任何声明，则会发送 400 Bad Request。

alg 声明是强制性的，因为它用于查找用于验证签名的正确密钥。

sub 声明是强制性的，如果 JWT 令牌有效，则用作 CouchDB 用户的名称。

您可以通过配置设置 roles_claim_name 设置用户角色声明名称。如果您没有设置显式值，则 _couchdb.roles 将被设置为默认声明名称。如果存在，作为字符串的 JSON 数组，只要 JWT 令牌有效，它将用作 CouchDB 用户的角色列表。

警告

roles_claim_name 在 CouchDB 3.3 中已弃用，并将稍后删除。请使用 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

jwt_keys 部分列出了此 CouchDB 服务器信任的所有密钥。您应该确保集群的所有节点都具有相同的列表。

从 3.3 版开始，可以在参数名称中使用 =，但前提是参数和值之间用 = 分隔，即等号两侧至少有一个空格。这在 [jwt_keys] 部分可能很有用，因为 base64 编码的密钥可能包含 = 字符。

不包含 kid 声明的 JWT 令牌将针对 $alg:_default 密钥进行验证。

出于安全原因，必须为每个密钥指定关联的算法（特别是使用服务器信任的 RSA 或 EC 公钥呈现 HMAC 签名的令牌：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 标头，则无需请求 session 即可通过此方法进行身份验证。

1.2.23. 身份验证¶

1.2.23.1. 基本身份验证¶

1.2.23.2. Cookie 身份验证¶

1.2.23.2.1. /_session¶

1.2.23.3. 代理身份验证¶

1.2.23.4. JWT 身份验证¶

1.2.23.2.1. `/_session`¶