Specify CLI 認證機制詳解auth.json 配置、GitHub / Azure DevOps 鑒權與憑證安全【免費下載鏈接】spec-kit Toolkit to help you get started with Spec-Driven Development項目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit本文基于 spec-kit 倉庫的認證參考文檔完整講解 Specify CLI 的 opt-in顯式啟用認證機制如何編寫~/.specify/auth.json、hosts/provider/auth等字段的取值與校驗規(guī)則、GitHub 與 Azure DevOps 各類認證方案bearer、basic-pat、azure-cli、azure-ad的配置示例以及憑證匹配、401/403 回退與重定向憑證剝離的底層實現(xiàn)。讀完后你可以為公共 GitHub、GitHub Enterprise Server 或 Azure DevOps 私有目錄catalog/擴展extension/預設preset下載正確配置憑據并理解其安全邊界。1. 設計原則不配置即不發(fā)送憑據Specify CLI 對目錄源 HTTP 請求、擴展下載和版本發(fā)布檢查均采用**可選認證opt-in authentication**模型只有當你顯式創(chuàng)建~/.specify/auth.json時CLI 才會向對應主機附加Authorization頭該文件不存在時所有 HTTP 請求均以未認證方式發(fā)出配置文件中“哪些主機 哪個 provider 哪種認證方案”由你聲明provider 類定義“如何認證”Bearer、Basic-PAT 等。這一模型在 src/specify_cli/authentication/init.py 的模塊 docstring 中被明確陳述其內置 provider 注冊表AUTH_REGISTRY通過_register_builtins()注冊了github與azure-devops兩個內置 provider。2. 配置文件結構認證配置全部集中在用戶主目錄下的單個 JSON 文件中mkdir -p ~/.specify # 將下文 JSON 寫入 ~/.specify/auth.json chmod 600 ~/.specify/auth.json最小可用的 GitHub 配置{ providers: [ { hosts: [github.com, api.github.com, raw.githubusercontent.com, codeload.github.com], provider: github, auth: bearer, token_env: GH_TOKEN } ] }安全提示建議將文件權限收緊為僅屬主可讀寫chmod 600。這一點并非只是文檔建議——從源碼看config.py 在加載配置時會檢查文件權限位若在 POSIX 系統(tǒng)上該文件對 group/others 可讀會發(fā)出UserWarning提醒執(zhí)行chmod 600但不會因此失敗。2.1 字段參考providers數組中每個條目的通用字段字段必填說明hosts是該條目適用的主機名數組。僅支持精確主機名或以*.開頭的子域通配如*.visualstudio.com。*.visualstudio.com匹配foo.visualstudio.com但不匹配visualstudio.com本身。*github.com、gith?b.com等其他 glob 模式不被支持會在加載時被拒絕。provider是內置 provider 鍵github或azure-devops。auth是認證方案見下節(jié)。token否內聯(lián) token 值?？赡軙r優(yōu)先使用token_env。token_env否存放 token 的環(huán)境變量名。azure-ad方案額外要求三個字段字段必填說明tenant_id是Azure AD 租戶 ID。client_id是服務主體service principal客戶端 ID。client_secret_env是存放 client secret 的環(huán)境變量名。bearer與basic-pat方案必須至少設置token或token_env之一。2.2 源碼中的校驗規(guī)則load_auth_config() 對配置的約束比文檔表格更具體了解它們可以避免配置不生效host 模式白名單_is_valid_host_pattern()只接受兩種形式——精確主機名和*.suffix。它顯式拒絕含?、[、]的模式以及*出現(xiàn)在其他位置的寫法。注釋中說明動機*github.com會匹配github.com.evil.com這類危險形式因此必須禁用。歸一化所有hosts值在存儲前會被strip().lower()token_env、tenant_id、client_id、client_secret_env等字符串引用字段經_norm()去除首尾空白防止“驗證通過但環(huán)境變量查不到”的靜默故障。provider/scheme 兼容性未知provider或該 provider 不支持的auth值會拋出ValueError錯誤信息會列出已注冊的 provider 或該 provider 支持的方案列表。schema 違規(guī)的容錯策略文件不存在返回空列表即全部未認證請求JSON 結構錯誤則拋ValueError而更高層的 HTTP 輔助函數會捕獲它、告警后繼續(xù)以未認證方式運行見 http.py 的_load_config()配置按進程緩存文件最多讀取一次。3. Provider 與認證方案3.1 GitHubgithub方案請求頭適用場景bearerAuthorization: Bearer tokenPAT、細粒度 PATfine-grained PAT、OAuth token、GitHub App tokenGitHubAuth 類只聲明了key github與supported_auth_schemes (bearer,)其auth_headers()對非bearer方案直接拋ValueErrortoken 解析則繼承基類默認邏輯優(yōu)先讀entry.token否則讀token_env指定的環(huán)境變量并對值做strip()。示例 — 通過環(huán)境變量注入 PAT{ hosts: [github.com, api.github.com, raw.githubusercontent.com, codeload.github.com], provider: github, auth: bearer, token_env: GH_TOKEN }3.2 GitHub Enterprise ServerGHES若目錄或擴展托管在自管的 GHES 實例上只需添加一條github條目列出該實例的主機名。同一條目既用于認證 catalog JSON 拉取也用于私有 release 資產下載——Specify 會識別這些主機為 GitHub Enterprise并將 release 下載解析到 GHES REST API/api/v3。{ providers: [ { hosts: [ghes.example.com, raw.ghes.example.com, codeload.ghes.example.com], provider: github, auth: bearer, token_env: GH_ENTERPRISE_TOKEN } ] }配置要點必須列出裸 web 主機如ghes.example.com因為 release 下載 URL 就掛在它下面若實例使用子域隔離還要把 catalog/擴展 URL 實際用到的raw.、codeload.子域一并列出*.ghes.example.com通配只匹配子域、不匹配裸主機因此裸主機必須顯式列出。源碼側可以印證這一機制http.py 的github_provider_hosts()會收集auth.json中所有githubprovider 條目的hosts供 resolve_github_release_asset_api_url() 使用。該函數把瀏覽器式下載 URLhttps://host/owner/repo/releases/download/tag/asset解析為 REST API 資產 URL主機是否按 GHES 處理正是由這份白名單決定——未列入的主機不會被當作 GHES從而阻止惡意 catalog 誘導向任意主機發(fā)起 API 請求。擴展、預設、workflow 的安裝路徑如 extensions/__init__.py、presets/__init__.py、commands/bundle/__init__.py都通過傳入github_provider_hosts()復用這一邏輯。3.3 Azure DevOpsazure-devopsAzureDevOpsAuth 支持四種方案方案請求頭適用場景basic-patAuthorization: Basic base64(:PAT)個人訪問令牌PATbearerAuthorization: Bearer token預先獲取的 OAuth / Azure AD tokenazure-cliAuthorization: Bearer token通過az account get-access-token獲取 tokenazure-adAuthorization: Bearer token通過 OAuth2 client credentials 流程獲取 token示例 — 環(huán)境變量注入 PAT{ hosts: [dev.azure.com], provider: azure-devops, auth: basic-pat, token_env: AZURE_DEVOPS_PAT }示例 — Azure CLI交互式登錄{ hosts: [dev.azure.com], provider: azure-devops, auth: azure-cli }要求此前已執(zhí)行az login。從源碼看_acquire_via_az_cli()會以 30 秒超時執(zhí)行az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --output json并解析accessToken字段它特意用shutil.which尊重 Windows 的PATHEXT解析出絕對路徑的az避免工作目錄中一個名為az.cmd的惡意文件被當成憑證操作執(zhí)行——任何失敗都會返回None并回退到下一個策略而不是拋出異常。示例 — Azure AD 服務主體CI/自動化{ hosts: [dev.azure.com], provider: azure-devops, auth: azure-ad, tenant_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, client_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, client_secret_env: AZURE_CLIENT_SECRET }_acquire_via_client_credentials()會向https://login.microsoftonline.com/tenant_id/oauth2/v2.0/token發(fā)起 POST請求client_credentials授權與499b84ac-1321-427f-aa17-267ca6975798/.default作用域。該請求有三層防護拒絕一切 307/308 重定向否則 POST 體中的client_secret會被原樣轉發(fā)到別處響應經read_response_limited按上限讀取超大響應視為失敗網絡故障、JSON 解析失敗等一律返回None落入回退。4. 多條目配置可以同時配置多個條目以覆蓋不同主機或組織條目按數組順序匹配{ providers: [ { hosts: [github.com, api.github.com, raw.githubusercontent.com, codeload.github.com], provider: github, auth: bearer, token_env: GH_TOKEN }, { hosts: [dev.azure.com], provider: azure-devops, auth: basic-pat, token_env: AZURE_DEVOPS_PAT } ] }5. 工作機制與源碼級實現(xiàn)文檔描述的運行時行為可概括為五步下面逐條對照 src/specify_cli/authentication/http.py 的實現(xiàn)主機匹配每個出站請求先用 find_entries_for_url() 解析 URL 的 hostname與auth.json中各條目的hosts模式比對*.前綴通配對hostname.endswith(pattern[1:])求值因此只匹配子域?；?authority如未閉合的 IPv6 方括號被視為無主機名返回空匹配而非拋異常。附加憑證命中后由對應 provider 的resolve_token()取 tokenauth_headers()構造Authorization頭。build_request()中有一個防繞過細節(jié)extra_headers里的Authorization鍵會被剝除認證頭最后合并外部無法覆蓋。401/403 回退open_url() 遍歷所有匹配條目某一輪收到 401/403 時關閉響應、嘗試下一條目其他錯誤404、500、網絡錯誤立即拋出。未認證兜底所有條目用盡或無匹配后以無認證請求作為最后回退。重定向憑證剝離每次嘗試都安裝隔離的 opener 并掛上_StripAuthOnRedirect處理器。重定向時它會校驗目標必須為帶主機名的 HTTPS僅允許環(huán)回地址之間使用 HTTP若新主機不在該條目的聲明主機內、或發(fā)生 HTTPS→HTTP 降級則從請求和unredirected_hdrs中同時移除Authorization防止憑據泄漏到 CDN 或第三方服務目標 URL 畸形則拋URLError交由上層下載錯誤處理。隔離 opener 的動機是代碼注釋中說明的open_url()每次自建 opener使得進程中若有全局urllib.request.install_opener也無法替換掉重定向守衛(wèi)。6. 與其他鑒權路徑的關系倉庫中另有一條獨立的輕量路徑build_github_request() 直接讀取GITHUB_TOKEN/GH_TOKEN環(huán)境變量但只針對內置的四個 GitHub 官方域名GITHUB_HOSTSgithub.com、api.github.com、raw.githubusercontent.com、codeload.github.com附加 Bearer 頭非 GitHub 主機一律不加避免向第三方主機泄漏憑據。從源碼結構看配置驅動的open_url()/build_request()是擴展、預設、bundle、workflow 安裝時下載資產的主通道tests/test_authentication.py及tests/http_helpers.py對其行為有測試覆蓋而build_github_request()服務于對 GitHub 官方域名的簡單請求場景。7. 快速上手模板一份預置 GitHub 配置的參考auth.json{ providers: [ { hosts: [ github.com, api.github.com, raw.githubusercontent.com, codeload.github.com ], provider: github, auth: bearer, token_env: GH_TOKEN } ] }啟用步驟mkdir -p ~/.specify # 將上方 JSON 復制到 ~/.specify/auth.json chmod 600 ~/.specify/auth.json # 使用前確保 GH_TOKEN 已導出小結spec-kit 的認證體系圍繞單一事實源~/.specify/auth.json展開以主機白名單控制憑據作用范圍以 provider/scheme 雙層鍵約束認證方式并在請求鏈路上實現(xiàn)了 401/403 逐條目回退、未認證兜底、重定向剝離與跨域防泄漏等安全行為。對使用公共 GitHub 的用戶最小配置即是一條bearertoken_env條目對 GHES 用戶額外列出裸主機即可同時打通 catalog 拉取與私有 release 下載對 Azure DevOps 用戶則可根據交互或 CI 場景在basic-pat、azure-cli、azure-ad三種動態(tài)/靜態(tài)方案中選擇?！久赓M下載鏈接】spec-kit Toolkit to help you get started with Spec-Driven Development項目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考