后端文檔【免費下載鏈接】readthedocs.orgThe source code that powers readthedocs.org項目地址https://gitcode.com/gh_mirrors/re/readthedocs.org點擊查看免費下載Read the Docs本項目為 readthedocs.org 的開源源碼為賬戶注冊與登錄提供了多種認證方式郵箱密碼、GitHub/GitLab/Bitbucket 等 VCS 提供商 OAuth、面向組織級用戶的 Google 與 SAML 單點登錄SSO以及疊加在所有方式之上的雙因素認證2FA。本文以官方文檔 docs/user/intro/accounts.rst 為核心骨架結(jié)合倉庫內(nèi) settings、OAuth 客戶端、SSO 模型 等源碼實現(xiàn)完整講解每種認證方式的能力邊界、適用場景、底層原理與配置要點幫助你在部署或使用 Read the Docs 時正確選擇與組合認證方案。認證體系總覽多種方式并存且互不排斥Read the Docs 支持以下幾種賬戶認證方法郵箱 密碼最基礎(chǔ)的注冊與登錄方式適合個人用戶和小團隊但可用的功能有限。VCS 提供商認證通過 GitHub、GitLab 或 Bitbucket 的 OAuth 登錄更安全便捷并能解鎖倉庫自動同步、webhook 自動創(chuàng)建、Pull Request 預(yù)覽等進階能力。Google 認證面向組織的單點登錄方式僅 Read the Docs Business商業(yè)版可用。SAML 認證面向企業(yè)的單點登錄方式僅 Enterprise 計劃可用且需要開啟自定義集成。雙因素認證2FA疊加在上述所有認證方式之上的額外安全層登錄時需要額外輸入驗證碼。原文特別強調(diào)這些認證方式并不互斥你可以同時使用多種方式訪問同一個賬戶。例如先通過郵箱注冊賬戶再連接一個或多個 Git 提供商或是在組織內(nèi)啟用 SSO 的同時為成員保留其他登錄入口。從源碼看這一設(shè)計體現(xiàn)在 readthedocs/settings/base.py 中的_SOCIALACCOUNT_PROVIDERS配置里——github、githubapp、gitlab、bitbucket_oauth2等 provider 被同時注冊每個 provider 還帶有priority字段GitHub App 為 10、GitHub OAuth 為 20、GitLab 為 30、Bitbucket 為 40用于控制登錄頁展示順序印證了多 provider 共存是項目的默認設(shè)計。郵箱與密碼認證基礎(chǔ)但功能受限創(chuàng)建 Read the Docs 賬戶最簡單的方式就是使用郵箱地址和密碼注冊。這種方式的優(yōu)點是對單個用戶和小團隊足夠輕量缺點在于它限制了賬戶可用的功能——例如無法自動同步遠端倉庫、無法在創(chuàng)建項目時自動配置 webhook也無法使用 Pull Request 構(gòu)建等功能這些都需要 VCS 提供商認證。從源碼看郵箱注冊行為由 django-allauth 驅(qū)動并在 readthedocs/settings/base.py 中做了明確配置SOCIALACCOUNT_ADAPTER readthedocs.core.adapters.SocialAccountAdapter ACCOUNT_SIGNUP_FIELDS [username*, email*, password1*, password2*] # 關(guān)閉用戶枚舉防護即使郵箱未注冊也會發(fā)送郵件 ACCOUNT_PREVENT_ENUMERATION False # 強制郵箱驗證未驗證郵箱的用戶無法登錄 ACCOUNT_EMAIL_VERIFICATION mandatory ACCOUNT_LOGIN_ON_EMAIL_CONFIRMATION True ACCOUNT_LOGIN_METHODS [username, email] ACCOUNT_EMAIL_CONFIRMATION_EXPIRE_DAYS 7 SOCIALACCOUNT_AUTO_SIGNUP False SOCIALACCOUNT_STORE_TOKENS True其中幾個關(guān)鍵點值得注意ACCOUNT_EMAIL_VERIFICATION mandatory注冊后必須點擊郵件中的驗證鏈接完成郵箱驗證否則無法登錄這保證了賬戶郵箱的真實性。ACCOUNT_LOGIN_METHODS [username, email]登錄時既可用用戶名也可用郵箱。ACCOUNT_PREVENT_ENUMERATION False即使郵箱未注冊也會發(fā)出郵件避免攻擊者借此探測已注冊郵箱源碼注釋明確說明這是有意為之。ACCOUNT_FORMS中注冊表單被替換為 readthedocs.forms.SignupFormWithNewsletter即注冊時還會收集訂閱偏好。此外readthedocs/core/adapters.py 中的AccountAdapter.save_user重寫了默認注冊流程如果用戶通過邀請鏈接session 中存在invitation:pk完成注冊會在注冊成功時自動兌換該邀請并將其加入對應(yīng)組織/項目把邀請制加入與郵箱注冊無縫銜接。VCS 提供商認證GitHub / GitLab / Bitbucket能力與優(yōu)勢通過 GitHub、GitLab 或 Bitbucket 的 VCS 提供商認證注冊或登錄比郵箱密碼方式更安全、更便捷并能解鎖多項關(guān)鍵功能。原文檔明確列出以下功能必須使用 VCS 提供商認證Pull Request 預(yù)覽參見 docs/user/pull-requests.rst——每當(dāng)倉庫有新的 Pull Request 時自動構(gòu)建文檔預(yù)覽版本并把構(gòu)建狀態(tài)回寫到 PR 的 checks 中通過 GitHub App 連接的項目還能在 PR 評論中附帶文檔預(yù)覽鏈接與 變更文件視覺對比。自動倉庫同步登錄后自動從 Git 提供商拉取你的倉庫與組織列表創(chuàng)建項目時一鍵導(dǎo)入。創(chuàng)建項目時自動創(chuàng)建 webhook項目創(chuàng)建后Read the Docs 會自動在其 Git 倉庫中配置 incoming webhook倉庫每次變更都會觸發(fā)文檔構(gòu)建。連接的完整流程見 docs/user/guides/connecting-git-account.rst從主登錄菜單進入用戶名下拉菜單 → Settings → Connected Services點擊連接后跳轉(zhuǎn)到 Git 提供商完成 OAuth 授權(quán)授權(quán)成功即回到 Read the Docs并可在服務(wù)列表中看到新連接。底層原理OAuth 與 Token 生命周期VCS 認證的底層是標(biāo)準(zhǔn)OAuth2 授權(quán)碼流程。Git 提供商作為身份提供商IdP完成身份驗證并向 Read the Docs 簽發(fā)訪問令牌access token。Read the Docs 隨后用該令牌以你的名義調(diào)用提供商 API——例如在項目創(chuàng)建時自動配置 webhook、把構(gòu)建狀態(tài)寫回 PR、同步倉庫列表。由于配置了SOCIALACCOUNT_STORE_TOKENS True這些 token 會被持久化存儲。Token 的刷新邏輯集中在 readthedocs/oauth/clients.pydef _get_token_updater(token): Update token given data from OAuth response. def _updater(data): token.token data[access_token] token.token_secret data.get(refresh_token, ) token.expires_at timezone.make_aware( datetime.fromtimestamp(data[expires_at]), ) token.save() log.info(Updated token., token_idtoken.pk) return _updater def get_oauth2_client(account): Get an OAuth2 client for the given social account. token account.socialtoken_set.first() if token is None: return None ... session OAuth2Session( client_idsocial_app.client_id, tokentoken_config, auto_refresh_kwargs{ client_id: social_app.client_id, client_secret: social_app.secret, }, auto_refresh_urloauth2_adapter.access_token_url, token_updater_get_token_updater(token), ) return session可以看到Read the Docs 使用requests_oauthlib.OAuth2Session維護會話配置了auto_refresh_url即各 provider 的 token 刷新端點與token_updater回調(diào)——當(dāng) access token 過期時自動用 refresh token 換取新 token并回寫數(shù)據(jù)庫。這解釋了為什么即使 token 過期已連接賬戶通常仍能持續(xù)工作無需用戶反復(fù)重新授權(quán)。各提供商的 OAuth Scope 配置不同提供商申請的權(quán)限范圍Scope在 readthedocs/settings/base.py 中集中定義Provider優(yōu)先級Scope / 說明githubGitHub OAuth App20user:email、read:org、admin:repo_hook、repo:statusgithubappGitHub App10Scope 由 GitHub App 自身權(quán)限決定不再額外申請gitlab30api、read_userVERIFIED_EMAILTrue信任其返回的主郵箱已通過驗證bitbucket_oauth240權(quán)限范圍由 bitbucket.org 上的 OAuth consumer 設(shè)置決定值得注意 GitHub 同時存在兩個 provider傳統(tǒng)GitHub OAuth Appgithub與較新的GitHub Appgithubapp。后者在 readthedocs/allauth/providers/githubapp/provider.py 中實現(xiàn)通過子類化GitHubProvider并指定獨立的 OAuth2 Adapter 來區(qū)分兩者。使用 GitHub App 時不需要在倉庫上手動創(chuàng)建 webhookRead the Docs 會自動訂閱所需事件參見 docs/user/reference/git-integration.rst其 webhook 載荷由 readthedocs/oauth/views.py 中的GitHubAppWebhookView接收通過 HMAC 簽名校驗GITHUB_APP_WEBHOOK_SECRET確保安全性再交給后臺任務(wù) readthedocs/oauth/tasks.py 異步處理。舊 GitHub OAuth 與新 GitHub App 的平滑遷移readthedocs/core/adapters.py 中的SocialAccountAdapter.pre_social_login體現(xiàn)了兩種 GitHub provider 之間的智能銜接邏輯_connect_github_app_to_existing_github_account用戶首次用 GitHub App 登錄時若檢測到已存在同 UID 的舊 GitHub OAuth 賬戶且屬于同一用戶會自動將兩者連接而不是創(chuàng)建重復(fù)賬戶。_block_use_of_old_github_oauth_app若用戶已遷移到 GitHub App再次嘗試用舊 GitHub OAuth App 登錄時會被攔截并提示改用 GitHub App 登錄這是項目逐步切換到新 GitHub App 的過渡措施。此外_filter_email_addresses只保留社交賬戶的主郵箱便于將主郵箱可靠標(biāo)記為已驗證尤其針對 GitLab 這類不返回郵箱驗證狀態(tài)的提供商。Google 認證面向組織的 SSOBusiness 版?? 該功能僅限 Read the Docs Business 版參見 docs/user/shared/admonition-rtd-business.rst。Google 認證適合已經(jīng)在使用 Google 服務(wù)的團隊可以無縫融入既有工作流。原文檔特別指出一個重要邊界Google 只提供認證authentication不提供授權(quán)authorization。這意味著用戶可以用 Google 身份登錄 Read the Docs但系統(tǒng)無法自動判斷該用戶有權(quán)訪問哪些項目——項目權(quán)限仍需由 Read the Docs 內(nèi)部的 Teams 授權(quán)體系管理。對應(yīng)的組織級 SSO 方案詳見 docs/user/commercial/single-sign-on.rstGoogle Workspace SSO 允許組織基于特定郵箱域名如employeecompany.com其中company.com為已注冊的 Google Workspace 域名管理訪問由于該 IdP 不提供項目級授權(quán)信息權(quán)限依然交給內(nèi)部 Teams 系統(tǒng)。該方案要求Pro 計劃及以上。配置方法見 setup-single-sign-on-google-email 指南。SAML 認證企業(yè)級 SSOEnterprise 版?? 該功能同樣僅限 Read the Docs Business 版且僅 Enterprise 計劃可用需要開啟自定義集成參見 docs/user/shared/admonition-rtd-business.rst。SAML 認證是企業(yè)環(huán)境中安全認證用戶并管理組織項目訪問的通行做法。與 Google 認證一樣SAML 也只提供認證、不提供授權(quán)用戶可以完成登錄但 Read the Docs 無法自動推斷其對項目的訪問權(quán)限授權(quán)仍需依賴組織內(nèi)部的 Teams 體系詳見 docs/user/commercial/single-sign-on.rst。需要留意的現(xiàn)狀約束該功能目前處于beta 階段且目前僅支持 Okta 作為 SAML 身份提供商如需啟用需聯(lián)系 支持團隊。配置方法見 set-up-single-sign-on-saml 指南。從源碼角度SSO 的能力抽象體現(xiàn)在 readthedocs/sso/models.py 的SSOIntegration模型中其provider字段枚舉了allauthGit 提供商 SSO、email郵箱域名與saml三種模式saml_app通過 OneToOne 關(guān)聯(lián)到 django-allauth 的SocialApp而domains關(guān)聯(lián)到SSODomain即允許的郵箱域名使用 readthedocs/projects/validators.py 的域名校驗器。在 readthedocs/sso/admin.py 中還提供了重新同步所有 SSO 用戶賬戶的管理操作會為組織所有成員觸發(fā)遠端倉庫重新同步任務(wù)確保權(quán)限變更及時生效。雙因素認證2FA所有認證方式之上的安全層無論采用上述哪種認證方式Read the Docs 都支持為其疊加雙因素認證2FA。開啟后登錄時除密碼/第三方憑證外還需輸入由認證器應(yīng)用生成的動態(tài)驗證碼提供額外一層賬戶保護。完整的啟用/停用操作流程參見 docs/user/guides/management/2fa.rst啟用 2FA進入賬戶設(shè)置Account settings點擊Two-factor authentication點擊Activate用認證器應(yīng)用如 Google Authenticator、1Password 等支持 TOTP 的應(yīng)用掃描二維碼輸入認證器應(yīng)用顯示的驗證碼再次點擊Activate完成激活妥善保存恢復(fù)碼recovery codes。停用 2FA進入賬戶設(shè)置 → Two-factor authentication → 點擊Deactivate即可。管理恢復(fù)碼進入賬戶設(shè)置 → Two-factor authentication →Manage recovery codes可下載當(dāng)前恢復(fù)碼或生成新的一組。?? 警告如果丟失認證器應(yīng)用恢復(fù)碼是找回賬戶的唯一途徑。請務(wù)必將其保存在安全位置否則將無法訪問賬戶。組合建議如何選擇你的認證方案基于以上分析可參考如下選擇邏輯使用場景推薦方案個人用戶、小團隊、只讀文檔郵箱 密碼最輕量需要自動同步倉庫、PR 預(yù)覽、自動 webhook 的項目維護者郵箱注冊后連接 Git 提供商或直接用 VCS 提供商注冊已在用 Google 生態(tài)的組織Business 版Google Workspace SSO 內(nèi)部 Teams 管理授權(quán)有統(tǒng)一身份管理要求的企業(yè)Enterprise 版SAML目前支持 Okta 內(nèi)部 Teams 管理授權(quán)任何場景疊加 2FA 提升賬戶安全需要說明的實踐要點一個 Read the Docs 賬戶可以連接多個 Git 提供商GitHub、GitLab、Bitbucket 同時連接實現(xiàn)一個登錄入口管理所有身份參見 docs/user/reference/git-integration.rstGit 提供商連接隨時可以在 Read the Docs 側(cè)刪除同時也應(yīng)在提供商側(cè)撤銷 Read the Docs 的 OAuth 授權(quán)GitHub 的 Authorized OAuth Apps、Bitbucket 的 Application Authorizations、GitLab 的 Applications。對于組織用戶Git 提供商 SSO 模式下認證與授權(quán)都由 IdP 統(tǒng)一管理組織 Teams 將不再參與鑒權(quán)而 Google/SAML 模式則必須依賴內(nèi)部 Teams 授權(quán)詳見 docs/user/commercial/single-sign-on.rst。延伸閱讀與源碼索引賬戶認證方法文檔docs/user/intro/accounts.rst連接 Git 賬戶操作指南docs/user/guides/connecting-git-account.rstGit 集成工作原理與權(quán)限說明docs/user/reference/git-integration.rst組織級 SSOGit 提供商 / Google / SAMLdocs/user/commercial/single-sign-on.rst2FA 配置指南docs/user/guides/management/2fa.rstPull Request 預(yù)覽功能docs/user/pull-requests.rst認證相關(guān)配置源碼readthedocs/settings/base.pyAllauth 適配與舊/新 GitHub 遷移邏輯readthedocs/core/adapters.pyOAuth2 客戶端與 Token 刷新readthedocs/oauth/clients.pyGitHub App Webhook 接收與驗簽readthedocs/oauth/views.pySSO 數(shù)據(jù)模型與管理員同步操作readthedocs/sso/models.py、readthedocs/sso/admin.py贊分享后端文檔【免費下載鏈接】readthedocs.orgThe source code that powers readthedocs.org項目地址https://gitcode.com/gh_mirrors/re/readthedocs.org點擊查看免費下載相關(guān)推薦通過 Rube MCP 自動化 Exa 搜索awesome-codex-skills 中 Exa Automation 技能的完整實戰(zhàn)指南通過 Rube MCP 自動化 Exa 搜索awesome codex skills 中 Exa Automation 技能的完整實戰(zhàn)指南 本指南講解 awe后端文檔django-allauth 常規(guī)賬戶Regular Accounts完全指南認證、注冊、郵箱管理與密碼流程解析django allauth 常規(guī)賬戶Regular Accounts完全指南認證、注冊、郵箱管理與密碼流程解析 本指南基于 django allauth后端認證鑒權(quán)身份認證Meteor 用戶與賬戶系統(tǒng)完全指南密碼登錄、無密碼登錄、2FA 與 OAuth 集成實戰(zhàn)Meteor 用戶與賬戶系統(tǒng)完全指南密碼登錄、無密碼登錄、2FA 與 OAuth 集成實戰(zhàn) 導(dǎo)讀 本文以 Meteor 官方教程 Users and Acc后端前端開發(fā)工具移動開發(fā)上一篇ComfyUI-KJNodes5大核心功能解析與進階工作流優(yōu)化指南下一篇DSH Desktop 插件開發(fā)實戰(zhàn)desktopProfiles 與 desktopPnpm 服務(wù)契約、雙環(huán)境適配與外部開發(fā)沙箱創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考