Jelu安全机制揭秘：5种认证方式与API Token作用域完整解析

Jelu安全机制揭秘5种认证方式与API Token作用域完整解析【免费下载链接】jeluSelf hosted read and to-read list book tracker项目地址: https://gitcode.com/gh_mirrors/je/jeluJelu 是一款自托管的读书与待读清单追踪工具self-hosted book tracker。很多用户在部署后最关心的就是Jelu 的认证登录到底有几种方式API Token 的作用域scope如何控制权限本文带你完整解析 Jelu 的 5 种认证方式、Token 生成与存储机制以及 10 个 API Token 作用域的实际用途。Jelu 的 5 种认证方式一览认证方式适用场景是否默认开启核心配置用户名密码表单/Basic个人与小团队✅ 是无API TokenBearer脚本、自动化、第三方集成✅ 是按需创建无OAuth2 / OIDC 登录用 GitHub 等第三方账号登录按需spring.security.oauth2LDAP 认证企业内网统一身份按需jelu.auth.ldap.*代理头认证Proxy反向代理已认证场景按需jelu.auth.proxy.*所有认证逻辑集中在安全过滤器链中配置核心文件是 SecurityConfig.kt。方式一用户名密码登录Session 会话最基础的登录方式输入用户名和密码服务端验证通过后签发一个JDBC 会话Session 直接存储在数据库中而非内存并下发名为SESSION的 Cookie。会话时长由jelu.session.duration控制见 SessionConfig.kt登出接口/api/v1/logout会主动销毁会话同时兼容 HTTP Basic 认证头方便 curl 等命令行工具方式二API TokenBearer Token——最实用的方式这是自动化集成 Jelu 的首选方式也是本文的重点。Token 是如何生成的查看 ApiTokenService.kt 可以发现几个值得称赞的安全设计格式固定jelu_前缀 32 位十六进制字符16 字节SecureRandom强随机数数据库只存哈希原始 Token 用SHA-256哈希后入库明文只在创建时显示一次之后无法再查看⏳支持过期时间可设置expiresAt过期自动失效每用户最多 20 个 Token并记录lastUsedAt与usageCount便于审计随时可吊销非管理员只能管理自己的 Token管理员可以吊销任意 Token使用方式就是在请求头中携带Authorization: Bearer jelu_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx验证逻辑由 BearerTokenAuthenticationFilter.kt 完成格式校验 → 哈希查库 → 检查激活状态与过期时间 → 构建权限集合。方式三OAuth2 / OIDC 登录在配置了 OAuth2 客户端后登录页会出现使用第三方账号登录入口典型场景是用 GitHub 账号登录。支持标准 OAuth2 与 OIDC 两种模式见 AppOAuth2AuthorizationServerConfiguration.ktGitHub 场景下会额外拉取已验证的主邮箱来匹配用户见 GithubOAuth2UserService.kt可配置jelu.auth.oidc-email-verification强制校验邮箱真实性防止用未验证邮箱注册方式四LDAP 认证企业级如果你的公司已有 AD/LDAP 域账号可以让 Jelu 直接复用。只需在配置中开启jelu.auth.ldap.enabledtrue并填入 LDAP 服务器地址、用户搜索过滤器等参数所有参数定义在 JeluProperties.kt 的Ldap类中具体实现见 LdapConfig.kt。方式五代理头认证Proxy Authentication当你把 Jelu 部署在 Traefik、Authelia、OAuth2-Proxy 等已经完成认证的反向代理之后可以开启代理认证开启jelu.auth.proxy.enabledtrue后Jelu 会读取请求头默认X-Authenticated-User可自定义中的用户名首次请求时自动创建用户若该用户名等于jelu.auth.proxy.admin-name则直接赋予管理员角色实现见 AuthHeaderFilter.kt 注意这种方式要求 Jelu 只能被反向代理访问否则任何人都可以伪造请求头登录。API Token 作用域Scope完整清单Jelu 借鉴了 GitHub 式的作用域设计创建 Token 时只授予必要的最小权限。全部 10 个作用域定义在 TokenScope.kt按 6 大类分组前端创建页 ApiTokens.vue 也按此分组展示分类作用域说明图书与元数据books:read查看图书、作者、标签、系列、出版社图书与元数据books:write创建/修改/删除图书及元数据阅读事件reading:read查看阅读事件与统计阅读事件reading:write创建/修改/删除阅读事件书评reviews:read查看书评书评reviews:write创建/修改/删除书评清单与书架lists:read查看自定义清单、书架、引文清单与书架lists:write创建/修改/删除清单、书架、引文导入导出import:write导入/导出数据、浏览文件系统外部元数据metadata:read从元数据提供方抓取外部数据作用域如何与 API 路径绑定ScopePathMatcher同样位于 TokenScope.kt维护了一张路径 HTTP 方法 → 所需作用域的映射表例如GET /api/v1/books→ 需要books:readPOST /api/v1/reading-events→ 需要reading:writePOST /api/v1/imports→ 需要import:write一个非常关键的安全细节未列入映射表的路径默认拒绝deny by default。这意味着即使 Token 拥有所有作用域也无法访问 Token 机制不支持的端点如用户管理、其他 Token 管理等——新端点上线前必须显式授权。权限不足时Jelu 会返回清晰的错误码401 UnauthorizedToken 无效、格式错误或已过期403 ForbiddenToken 有效但缺少所需作用域Insufficient scope for this operation哪些接口无需认证为支持嵌入与公开分享SecurityConfig.kt 对以下只读接口开放了permitAllGET /api/v1/books/**—— 图书详情可匿名访问GET /api/v1/reviews/**—— 书评可匿名访问GET /api/v1/custom-lists/**—— 自定义清单支持匿名嵌入展示/api/v1/token、/api/v1/setup/status—— Token 查询与初始化状态检查安全最佳实践清单 ✅最小权限原则给爬虫脚本只发books:read给同步工具发books:writereading:write给 Token 设过期时间尤其是临时调试用途及时吊销闲置 Token页面会显示lastUsedAt和usageCount辅助判断生产部署建议放在反向代理之后用 Proxy 认证或 OAuth2 统一管理入口记住Token 明文只显示一次请立即妥善保存Jelu 用数据库会话 哈希 Token 最小作用域 默认拒绝的组合在保持轻量自托管的同时提供了企业级的安全纵深。无论是个人书单还是团队共用你都可以按需组合上面 5 种认证方式打造最适合自己的部署方案。【免费下载链接】jeluSelf hosted read and to-read list book tracker项目地址: https://gitcode.com/gh_mirrors/je/jelu创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考