WorkOS釋出auth.md：基於OAuth標準的開放智慧體註冊協議

長期以來，Web認證一直基於一個設計假設：使用者坐在瀏覽器前，點選按鈕、填寫表單、驗證郵箱、複製API金鑰並貼上到其他地方。然而，當使用者將工作委託給智慧體時，這個模型不再適用。智慧體已經在編寫程式碼、發起拉取請求、分類工單、查詢系統和更新記錄，但大多數產品仍然沒有真正的方式讓智慧體註冊。目前的變通方案——給智慧體一個原始的API金鑰或會話令牌——會產生無作用域、難以按會話審計且無法選擇性撤銷的憑證。WorkOS提議了一種結構化的替代方案：auth.md，一個開放的智慧體註冊協議。

什麼是auth.md？ auth.md是一個小型Markdown檔案，應用程式將其釋出在眾所周知的路徑下，通常是https://service.com/auth.md。該檔案告訴智慧體如何註冊該服務：支援的流程、存在的作用域，以及憑證的發放、審計和撤銷方式。由於是純文本Markdown，同一檔案既可作為人類開發者的文件，也可作為智慧體程式設計讀取的執行時產物。智慧體獲取檔案，讀取結構化部分，選擇合適的流程，然後註冊——無需人類填寫表單。

發現機制分兩步進行。機器可讀的事實來源位於/.well-known/oauth-protected-resource（受保護資源後設資料，PRM），它推廣資源並指向授權伺服器。位於/.well-known/oauth-authorization-server的授權伺服器後設資料包含agent_auth塊——一個結構化物件，告訴智慧體哪些流程受支援，以及register_uri、claim_uri、revocation_uri和identity_types_supported的值。auth.md檔案是散文形式的伴侶，引導智慧體走向這一發現路徑。在API返回任何401時，服務應返回WWW-Authenticate: Bearer resource_metadata="..."頭，以便智慧體無需先閱讀文件即可啟動發現。

兩種註冊流程 auth.md定義了兩個主要流程，應用程式可以支援其中之一或兩者。

智慧體驗證流程：智慧體的身份提供商（OpenAI、Anthropic、Cursor或任何可信平臺）在註冊時證明使用者身份。智慧體從其提供商請求特定受眾的ID-JAG，然後將其POST到應用的/agent/auth端點。應用解碼ID-JAG頭以獲取kid和alg，在其可信提供商列表中查詢issuer，獲取提供商的JWKS，驗證簽名，驗證宣告（aud、exp、iat、jti、client_id），並同步返回憑證。無需OTP、無需電子郵件往返、無需人工互動。結果是每個(iss, sub, aud)的委派記錄，提供商可隨時透過向服務的revocation_uri POST登出令牌來撤銷。已經透過OIDC或SAML即時配置使用者的應用程式會識別這種模式——它與不同的issuer形狀相同。一個重要約束：從ID-JAG驗證簽發的訪問令牌不得包含重新整理令牌。智慧體必須提供新的ID-JAG以延長訪問許可權。

使用者認領流程：這是一個基於OTP的路徑，無需智慧體提供商參與。智慧體嚮應用註冊，使用者透過將電子郵件中的一次性程式碼讀回給智慧體來繫結註冊。兩個認領端點是/agent/auth/claim（觸發OTP電子郵件）和/agent/auth/claim/complete（提交程式碼）。此流程有兩種起始形態：在匿名啟動變體中，智慧體自行註冊無身份，並立即獲得憑證，作用域限於應用定義的預認領許可權。在註冊過期前的任何時刻，智慧體執行OTP儀式以將憑證繫結到真實使用者並升級作用域。API金鑰在認領時不輪換——作用域原地升級。在需要電子郵件變體中，智慧體在註冊時提供使用者郵箱，憑證完全扣留直至OTP儀式完成。當任何預認領使用不可接受時使用此變體。

使用者匹配與審計 發放憑證時，服務需要將註冊匹配到現有使用者或配置新使用者。推薦的解析順序是：首先根據同一(iss, sub)對的先前委派記錄匹配；然後根據已驗證的郵箱匹配；最後根據應用策略即時配置新使用者——如果產品需要手動入職則拒絕。為了可觀察性和事件響應，建議記錄一組標準審計事件：registration.created、claim.requested、otp.generated、claim.confirmed、registration.expired和registration.revoked。對於ID-JAG流程，包括iss、sub和agent_platform，以便操作員與提供商端日誌關聯。

Marktechpost的視覺解說 （此處省略了原文中的視覺解說部分，因為它們主要是圖解，但我們在重寫中應保留關鍵資訊。）

關鍵要點 auth.md是一個開放協議：應用在service.com/auth.md託管一個Markdown檔案，描述智慧體如何註冊和獲取有作用域的憑證。支援兩種流程：智慧體驗證（基於ID-JAG，同步，無人工互動）和使用者認領（基於OTP，無需提供商整合）。發現機制是兩跳：PRM指向授權伺服器，後者後設資料包含agent_auth塊。該協議複用現有OAuth標準（RFC 9728、ID-JAG），不繫結WorkOS基礎設施。

更多詳情請檢視倉庫和技術文件。