制揭秘：5種認(rèn)證方式與API Token作用域完整解析)
Jelu安全機(jī)制揭秘5種認(rèn)證方式與API Token作用域完整解析【免費(fèi)下載鏈接】jeluSelf hosted read and to-read list book tracker項(xiàng)目地址: https://gitcode.com/gh_mirrors/je/jeluJelu 是一款自托管的讀書(shū)與待讀清單追蹤工具self-hosted book tracker。很多用戶在部署后最關(guān)心的就是Jelu 的認(rèn)證登錄到底有幾種方式API Token 的作用域scope如何控制權(quán)限本文帶你完整解析 Jelu 的 5 種認(rèn)證方式、Token 生成與存儲(chǔ)機(jī)制以及 10 個(gè) API Token 作用域的實(shí)際用途。Jelu 的 5 種認(rèn)證方式一覽認(rèn)證方式適用場(chǎng)景是否默認(rèn)開(kāi)啟核心配置用戶名密碼表單/Basic個(gè)人與小團(tuán)隊(duì)? 是無(wú)API TokenBearer腳本、自動(dòng)化、第三方集成? 是按需創(chuàng)建無(wú)OAuth2 / OIDC 登錄用 GitHub 等第三方賬號(hào)登錄按需spring.security.oauth2LDAP 認(rèn)證企業(yè)內(nèi)網(wǎng)統(tǒng)一身份按需jelu.auth.ldap.*代理頭認(rèn)證Proxy反向代理已認(rèn)證場(chǎng)景按需jelu.auth.proxy.*所有認(rèn)證邏輯集中在安全過(guò)濾器鏈中配置核心文件是 SecurityConfig.kt。方式一用戶名密碼登錄Session 會(huì)話最基礎(chǔ)的登錄方式輸入用戶名和密碼服務(wù)端驗(yàn)證通過(guò)后簽發(fā)一個(gè)JDBC 會(huì)話Session 直接存儲(chǔ)在數(shù)據(jù)庫(kù)中而非內(nèi)存并下發(fā)名為SESSION的 Cookie。會(huì)話時(shí)長(zhǎng)由jelu.session.duration控制見(jiàn) SessionConfig.kt登出接口/api/v1/logout會(huì)主動(dòng)銷(xiāo)毀會(huì)話同時(shí)兼容 HTTP Basic 認(rèn)證頭方便 curl 等命令行工具方式二API TokenBearer Token——最實(shí)用的方式這是自動(dòng)化集成 Jelu 的首選方式也是本文的重點(diǎn)。Token 是如何生成的查看 ApiTokenService.kt 可以發(fā)現(xiàn)幾個(gè)值得稱(chēng)贊的安全設(shè)計(jì)格式固定jelu_前綴 32 位十六進(jìn)制字符16 字節(jié)SecureRandom強(qiáng)隨機(jī)數(shù)數(shù)據(jù)庫(kù)只存哈希原始 Token 用SHA-256哈希后入庫(kù)明文只在創(chuàng)建時(shí)顯示一次之后無(wú)法再查看?支持過(guò)期時(shí)間可設(shè)置expiresAt過(guò)期自動(dòng)失效每用戶最多 20 個(gè) Token并記錄lastUsedAt與usageCount便于審計(jì)隨時(shí)可吊銷(xiāo)非管理員只能管理自己的 Token管理員可以吊銷(xiāo)任意 Token使用方式就是在請(qǐng)求頭中攜帶Authorization: Bearer jelu_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx驗(yàn)證邏輯由 BearerTokenAuthenticationFilter.kt 完成格式校驗(yàn) → 哈希查庫(kù) → 檢查激活狀態(tài)與過(guò)期時(shí)間 → 構(gòu)建權(quán)限集合。方式三OAuth2 / OIDC 登錄在配置了 OAuth2 客戶端后登錄頁(yè)會(huì)出現(xiàn)使用第三方賬號(hào)登錄入口典型場(chǎng)景是用 GitHub 賬號(hào)登錄。支持標(biāo)準(zhǔn) OAuth2 與 OIDC 兩種模式見(jiàn) AppOAuth2AuthorizationServerConfiguration.ktGitHub 場(chǎng)景下會(huì)額外拉取已驗(yàn)證的主郵箱來(lái)匹配用戶見(jiàn) GithubOAuth2UserService.kt可配置jelu.auth.oidc-email-verification強(qiáng)制校驗(yàn)郵箱真實(shí)性防止用未驗(yàn)證郵箱注冊(cè)方式四LDAP 認(rèn)證企業(yè)級(jí)如果你的公司已有 AD/LDAP 域賬號(hào)可以讓 Jelu 直接復(fù)用。只需在配置中開(kāi)啟jelu.auth.ldap.enabledtrue并填入 LDAP 服務(wù)器地址、用戶搜索過(guò)濾器等參數(shù)所有參數(shù)定義在 JeluProperties.kt 的Ldap類(lèi)中具體實(shí)現(xiàn)見(jiàn) LdapConfig.kt。方式五代理頭認(rèn)證Proxy Authentication當(dāng)你把 Jelu 部署在 Traefik、Authelia、OAuth2-Proxy 等已經(jīng)完成認(rèn)證的反向代理之后可以開(kāi)啟代理認(rèn)證開(kāi)啟jelu.auth.proxy.enabledtrue后Jelu 會(huì)讀取請(qǐng)求頭默認(rèn)X-Authenticated-User可自定義中的用戶名首次請(qǐng)求時(shí)自動(dòng)創(chuàng)建用戶若該用戶名等于jelu.auth.proxy.admin-name則直接賦予管理員角色實(shí)現(xiàn)見(jiàn) AuthHeaderFilter.kt 注意這種方式要求 Jelu 只能被反向代理訪問(wèn)否則任何人都可以偽造請(qǐng)求頭登錄。API Token 作用域Scope完整清單Jelu 借鑒了 GitHub 式的作用域設(shè)計(jì)創(chuàng)建 Token 時(shí)只授予必要的最小權(quán)限。全部 10 個(gè)作用域定義在 TokenScope.kt按 6 大類(lèi)分組前端創(chuàng)建頁(yè) ApiTokens.vue 也按此分組展示分類(lèi)作用域說(shuō)明圖書(shū)與元數(shù)據(jù)books:read查看圖書(shū)、作者、標(biāo)簽、系列、出版社圖書(shū)與元數(shù)據(jù)books:write創(chuàng)建/修改/刪除圖書(shū)及元數(shù)據(jù)閱讀事件reading:read查看閱讀事件與統(tǒng)計(jì)閱讀事件reading:write創(chuàng)建/修改/刪除閱讀事件書(shū)評(píng)reviews:read查看書(shū)評(píng)書(shū)評(píng)reviews:write創(chuàng)建/修改/刪除書(shū)評(píng)清單與書(shū)架lists:read查看自定義清單、書(shū)架、引文清單與書(shū)架lists:write創(chuàng)建/修改/刪除清單、書(shū)架、引文導(dǎo)入導(dǎo)出import:write導(dǎo)入/導(dǎo)出數(shù)據(jù)、瀏覽文件系統(tǒng)外部元數(shù)據(jù)metadata:read從元數(shù)據(jù)提供方抓取外部數(shù)據(jù)作用域如何與 API 路徑綁定ScopePathMatcher同樣位于 TokenScope.kt維護(hù)了一張路徑 HTTP 方法 → 所需作用域的映射表例如GET /api/v1/books→ 需要books:readPOST /api/v1/reading-events→ 需要reading:writePOST /api/v1/imports→ 需要import:write一個(gè)非常關(guān)鍵的安全細(xì)節(jié)未列入映射表的路徑默認(rèn)拒絕deny by default。這意味著即使 Token 擁有所有作用域也無(wú)法訪問(wèn) Token 機(jī)制不支持的端點(diǎn)如用戶管理、其他 Token 管理等——新端點(diǎn)上線前必須顯式授權(quán)。權(quán)限不足時(shí)Jelu 會(huì)返回清晰的錯(cuò)誤碼401 UnauthorizedToken 無(wú)效、格式錯(cuò)誤或已過(guò)期403 ForbiddenToken 有效但缺少所需作用域Insufficient scope for this operation哪些接口無(wú)需認(rèn)證為支持嵌入與公開(kāi)分享SecurityConfig.kt 對(duì)以下只讀接口開(kāi)放了permitAllGET /api/v1/books/**—— 圖書(shū)詳情可匿名訪問(wèn)GET /api/v1/reviews/**—— 書(shū)評(píng)可匿名訪問(wèn)GET /api/v1/custom-lists/**—— 自定義清單支持匿名嵌入展示/api/v1/token、/api/v1/setup/status—— Token 查詢與初始化狀態(tài)檢查安全最佳實(shí)踐清單 ?最小權(quán)限原則給爬蟲(chóng)腳本只發(fā)books:read給同步工具發(fā)books:writereading:write給 Token 設(shè)過(guò)期時(shí)間尤其是臨時(shí)調(diào)試用途及時(shí)吊銷(xiāo)閑置 Token頁(yè)面會(huì)顯示lastUsedAt和usageCount輔助判斷生產(chǎn)部署建議放在反向代理之后用 Proxy 認(rèn)證或 OAuth2 統(tǒng)一管理入口記住Token 明文只顯示一次請(qǐng)立即妥善保存Jelu 用數(shù)據(jù)庫(kù)會(huì)話 哈希 Token 最小作用域 默認(rèn)拒絕的組合在保持輕量自托管的同時(shí)提供了企業(yè)級(jí)的安全縱深。無(wú)論是個(gè)人書(shū)單還是團(tuán)隊(duì)共用你都可以按需組合上面 5 種認(rèn)證方式打造最適合自己的部署方案?！久赓M(fèi)下載鏈接】jeluSelf hosted read and to-read list book tracker項(xiàng)目地址: https://gitcode.com/gh_mirrors/je/jelu創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Jelu安全機(jī)制揭秘：5種認(rèn)證方式與API Token作用域完整解析
Jelu安全機(jī)制揭秘5種認(rèn)證方式與API Token作用域完整解析【免費(fèi)下載鏈接】jeluSelf hosted read and to-read list book tracker項(xiàng)目地址: https://gitcode.com/gh_mirrors/je/jeluJelu 是一款自托管的讀書(shū)與待讀清單追蹤工具self-hosted book tracker。很多用戶在部署后最關(guān)心的就是Jelu 的認(rèn)證登錄到底有幾種方式API Token 的作用域scope如何控制權(quán)限本文帶你完整解析 Jelu 的 5 種認(rèn)證方式、Token 生成與存儲(chǔ)機(jī)制以及 10 個(gè) API Token 作用域的實(shí)際用途。Jelu 的 5 種認(rèn)證方式一覽認(rèn)證方式適用場(chǎng)景是否默認(rèn)開(kāi)啟核心配置用戶名密碼表單/Basic個(gè)人與小團(tuán)隊(duì)? 是無(wú)API TokenBearer腳本、自動(dòng)化、第三方集成? 是按需創(chuàng)建無(wú)OAuth2 / OIDC 登錄用 GitHub 等第三方賬號(hào)登錄按需spring.security.oauth2LDAP 認(rèn)證企業(yè)內(nèi)網(wǎng)統(tǒng)一身份按需jelu.auth.ldap.*代理頭認(rèn)證Proxy反向代理已認(rèn)證場(chǎng)景按需jelu.auth.proxy.*所有認(rèn)證邏輯集中在安全過(guò)濾器鏈中配置核心文件是 SecurityConfig.kt。方式一用戶名密碼登錄Session 會(huì)話最基礎(chǔ)的登錄方式輸入用戶名和密碼服務(wù)端驗(yàn)證通過(guò)后簽發(fā)一個(gè)JDBC 會(huì)話Session 直接存儲(chǔ)在數(shù)據(jù)庫(kù)中而非內(nèi)存并下發(fā)名為SESSION的 Cookie。會(huì)話時(shí)長(zhǎng)由jelu.session.duration控制見(jiàn) SessionConfig.kt登出接口/api/v1/logout會(huì)主動(dòng)銷(xiāo)毀會(huì)話同時(shí)兼容 HTTP Basic 認(rèn)證頭方便 curl 等命令行工具方式二API TokenBearer Token——最實(shí)用的方式這是自動(dòng)化集成 Jelu 的首選方式也是本文的重點(diǎn)。Token 是如何生成的查看 ApiTokenService.kt 可以發(fā)現(xiàn)幾個(gè)值得稱(chēng)贊的安全設(shè)計(jì)格式固定jelu_前綴 32 位十六進(jìn)制字符16 字節(jié)SecureRandom強(qiáng)隨機(jī)數(shù)數(shù)據(jù)庫(kù)只存哈希原始 Token 用SHA-256哈希后入庫(kù)明文只在創(chuàng)建時(shí)顯示一次之后無(wú)法再查看?支持過(guò)期時(shí)間可設(shè)置expiresAt過(guò)期自動(dòng)失效每用戶最多 20 個(gè) Token并記錄lastUsedAt與usageCount便于審計(jì)隨時(shí)可吊銷(xiāo)非管理員只能管理自己的 Token管理員可以吊銷(xiāo)任意 Token使用方式就是在請(qǐng)求頭中攜帶Authorization: Bearer jelu_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx驗(yàn)證邏輯由 BearerTokenAuthenticationFilter.kt 完成格式校驗(yàn) → 哈希查庫(kù) → 檢查激活狀態(tài)與過(guò)期時(shí)間 → 構(gòu)建權(quán)限集合。方式三OAuth2 / OIDC 登錄在配置了 OAuth2 客戶端后登錄頁(yè)會(huì)出現(xiàn)使用第三方賬號(hào)登錄入口典型場(chǎng)景是用 GitHub 賬號(hào)登錄。支持標(biāo)準(zhǔn) OAuth2 與 OIDC 兩種模式見(jiàn) AppOAuth2AuthorizationServerConfiguration.ktGitHub 場(chǎng)景下會(huì)額外拉取已驗(yàn)證的主郵箱來(lái)匹配用戶見(jiàn) GithubOAuth2UserService.kt可配置jelu.auth.oidc-email-verification強(qiáng)制校驗(yàn)郵箱真實(shí)性防止用未驗(yàn)證郵箱注冊(cè)方式四LDAP 認(rèn)證企業(yè)級(jí)如果你的公司已有 AD/LDAP 域賬號(hào)可以讓 Jelu 直接復(fù)用。只需在配置中開(kāi)啟jelu.auth.ldap.enabledtrue并填入 LDAP 服務(wù)器地址、用戶搜索過(guò)濾器等參數(shù)所有參數(shù)定義在 JeluProperties.kt 的Ldap類(lèi)中具體實(shí)現(xiàn)見(jiàn) LdapConfig.kt。方式五代理頭認(rèn)證Proxy Authentication當(dāng)你把 Jelu 部署在 Traefik、Authelia、OAuth2-Proxy 等已經(jīng)完成認(rèn)證的反向代理之后可以開(kāi)啟代理認(rèn)證開(kāi)啟jelu.auth.proxy.enabledtrue后Jelu 會(huì)讀取請(qǐng)求頭默認(rèn)X-Authenticated-User可自定義中的用戶名首次請(qǐng)求時(shí)自動(dòng)創(chuàng)建用戶若該用戶名等于jelu.auth.proxy.admin-name則直接賦予管理員角色實(shí)現(xiàn)見(jiàn) AuthHeaderFilter.kt 注意這種方式要求 Jelu 只能被反向代理訪問(wèn)否則任何人都可以偽造請(qǐng)求頭登錄。API Token 作用域Scope完整清單Jelu 借鑒了 GitHub 式的作用域設(shè)計(jì)創(chuàng)建 Token 時(shí)只授予必要的最小權(quán)限。全部 10 個(gè)作用域定義在 TokenScope.kt按 6 大類(lèi)分組前端創(chuàng)建頁(yè) ApiTokens.vue 也按此分組展示分類(lèi)作用域說(shuō)明圖書(shū)與元數(shù)據(jù)books:read查看圖書(shū)、作者、標(biāo)簽、系列、出版社圖書(shū)與元數(shù)據(jù)books:write創(chuàng)建/修改/刪除圖書(shū)及元數(shù)據(jù)閱讀事件reading:read查看閱讀事件與統(tǒng)計(jì)閱讀事件reading:write創(chuàng)建/修改/刪除閱讀事件書(shū)評(píng)reviews:read查看書(shū)評(píng)書(shū)評(píng)reviews:write創(chuàng)建/修改/刪除書(shū)評(píng)清單與書(shū)架lists:read查看自定義清單、書(shū)架、引文清單與書(shū)架lists:write創(chuàng)建/修改/刪除清單、書(shū)架、引文導(dǎo)入導(dǎo)出import:write導(dǎo)入/導(dǎo)出數(shù)據(jù)、瀏覽文件系統(tǒng)外部元數(shù)據(jù)metadata:read從元數(shù)據(jù)提供方抓取外部數(shù)據(jù)作用域如何與 API 路徑綁定ScopePathMatcher同樣位于 TokenScope.kt維護(hù)了一張路徑 HTTP 方法 → 所需作用域的映射表例如GET /api/v1/books→ 需要books:readPOST /api/v1/reading-events→ 需要reading:writePOST /api/v1/imports→ 需要import:write一個(gè)非常關(guān)鍵的安全細(xì)節(jié)未列入映射表的路徑默認(rèn)拒絕deny by default。這意味著即使 Token 擁有所有作用域也無(wú)法訪問(wèn) Token 機(jī)制不支持的端點(diǎn)如用戶管理、其他 Token 管理等——新端點(diǎn)上線前必須顯式授權(quán)。權(quán)限不足時(shí)Jelu 會(huì)返回清晰的錯(cuò)誤碼401 UnauthorizedToken 無(wú)效、格式錯(cuò)誤或已過(guò)期403 ForbiddenToken 有效但缺少所需作用域Insufficient scope for this operation哪些接口無(wú)需認(rèn)證為支持嵌入與公開(kāi)分享SecurityConfig.kt 對(duì)以下只讀接口開(kāi)放了permitAllGET /api/v1/books/**—— 圖書(shū)詳情可匿名訪問(wèn)GET /api/v1/reviews/**—— 書(shū)評(píng)可匿名訪問(wèn)GET /api/v1/custom-lists/**—— 自定義清單支持匿名嵌入展示/api/v1/token、/api/v1/setup/status—— Token 查詢與初始化狀態(tài)檢查安全最佳實(shí)踐清單 ?最小權(quán)限原則給爬蟲(chóng)腳本只發(fā)books:read給同步工具發(fā)books:writereading:write給 Token 設(shè)過(guò)期時(shí)間尤其是臨時(shí)調(diào)試用途及時(shí)吊銷(xiāo)閑置 Token頁(yè)面會(huì)顯示lastUsedAt和usageCount輔助判斷生產(chǎn)部署建議放在反向代理之后用 Proxy 認(rèn)證或 OAuth2 統(tǒng)一管理入口記住Token 明文只顯示一次請(qǐng)立即妥善保存Jelu 用數(shù)據(jù)庫(kù)會(huì)話 哈希 Token 最小作用域 默認(rèn)拒絕的組合在保持輕量自托管的同時(shí)提供了企業(yè)級(jí)的安全縱深。無(wú)論是個(gè)人書(shū)單還是團(tuán)隊(duì)共用你都可以按需組合上面 5 種認(rèn)證方式打造最適合自己的部署方案?！久赓M(fèi)下載鏈接】jeluSelf hosted read and to-read list book tracker項(xiàng)目地址: https://gitcode.com/gh_mirrors/je/jelu創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考