如何为CouchDB配置JWT auth实现现有API tokens鉴权

核心问题对应说明 #

JWT Payload 必填字段 #

• sub：必填，值为CouchDB中的用户名，必须和_users库内用户文档_id去掉org.couchdb.user:前缀后的值完全匹配，例如用户文档id为org.couchdb.user:api_client_01时，sub值必须为api_client_01
• exp：必填，值为JWT过期时间的Unix时间戳，CouchDB默认强制校验该字段，过期token会直接返回401
• 可选高频使用字段：
  • _couchdb.roles：字符串数组类型，配置后会直接给当前请求授予对应CouchDB权限角色，优先级高于_users库内预配置的角色
  • iat：JWT签发时间Unix时间戳，建议携带，可减少时钟偏移导致的校验失败问题

JWT Secret 配置规则 #

CouchDB JWT认证默认使用HS256对称加密算法，不需要生成非对称密钥对，直接在配置文件中填写和现有API Token签发端完全一致的签名密钥即可，支持配置多组密钥做无感知密钥轮转。如果需要使用RS256/ES256非对称算法，额外配置公钥文件路径即可，绝大多数对接现有API Token的场景用HS256即可满足需求。

最简可落地配置步骤 #

1. 修改CouchDB配置文件
   默认配置文件路径通常为/opt/couchdb/etc/local.ini或/etc/couchdb/local.ini，追加以下配置段：

[jwt_auth]
required_claims = sub,exp
secret = 替换为你现有服务签发JWT用的实际签名密钥
username_claim = sub
roles_claim = _couchdb.roles
; 不需要提前手动创建用户时可设为true，会自动根据token信息生成用户记录
create_user = false

[chttpd]
; 将JWT认证处理器追加到认证链末尾，不要删除原有cookie、默认认证配置，避免影响原有管理员登录、网页端控制台使用
authentication_handlers = {couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, default_authentication_handler}, {jwt_auth, jwt_authentication_handler}

2. 重启CouchDB服务加载配置
   根据部署环境执行对应重启命令，常规系统级部署执行：
   systemctl restart couchdb
3. 配置有效性验证
   先用现有JWT签发逻辑生成测试token，参考payload如下：

{
  "sub": "test_jwt_user",
  "exp": 1999999999,
  "_couchdb.roles": ["db_reader"],
  "iat": 1700000000
}

携带该token发起请求校验：

curl http://127.0.0.1:5984/_session -H "Authorization: Bearer 替换为生成的测试token"

返回结果中userCtx.name为test_jwt_user、roles包含db_reader即代表配置生效。

常见踩坑说明 #

• 不要把JWT认证处理器放在authentication_handlers列表最前，会拦截原有管理员账号、Cookie登录的正常请求
• 出现无理由401时先检查CouchDB服务与JWT签发服务的系统时间差，时间差超过5分钟会触发exp校验失败
• secret配置值不要携带多余的空格、换行符，HS256为字节级精确匹配，和签发端密钥不一致会直接校验失败

内容的提问来源于stack exchange，提问作者EKnot