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），僅供參考 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），僅供參考