51CTO讀者成長計劃社群招募，咨詢小助手（微信號：CTOjishuzhan）

作者 | Robin Guldener

策劃 | 言征

OAuth 是一個標(biāo)準(zhǔn)協(xié)議?；旧夏憧梢韵胂蟮拿糠N編程語言都有 OAuth 2.0 的客戶端庫。

但有了客戶端庫，卻并不意味著萬事大吉，如果你能夠在大約 10 分鐘內(nèi)做到為任何 API 實施 OAuth?；蛘咧辽僭谝粋€小時內(nèi)，請給我們發(fā)電子郵件——我們想請你吃一頓美味的晚餐，并聽聽你是怎么做到的。

1、50 個 OAuth 實踐：結(jié)果一團糟

我們?yōu)?50 個最流行的 API 實現(xiàn)了 OAuth，例如 Google（Gmail、Calendar、Sheets 等）、HubSpot、Shopify、Salesforce、Stripe、Jira、Slack、Microsoft（Azure、Outlook、OneDrive）、LinkedIn、Facebook 和其他 OAuth API等。

我們的結(jié)論：現(xiàn)實世界的 OAuth 體驗可與 2008 年的 JavaScript 瀏覽器 API 相媲美。人們普遍認為應(yīng)該如何做事，但實際上每個 API 都有自己對標(biāo)準(zhǔn)、實現(xiàn)怪癖以及非標(biāo)準(zhǔn)行為和擴展的解釋. 結(jié)果：到處都是坑。

2、OAuth 標(biāo)準(zhǔn)太大太復(fù)雜

“這個 API 也使用 OAuth 2.0，我們幾周前就已經(jīng)這樣做了。我應(yīng)該在明天之前完成。”

——實習(xí)生的著名遺言

OAuth 是一個非常大的標(biāo)準(zhǔn)。OAuth 2.0 的官方網(wǎng)站目前列出了 17 個不同的 RFC（定義標(biāo)準(zhǔn)的文檔），它們共同定義了 OAuth 2 的工作方式。它們涵蓋了從 OAuth 框架和 Bearer 令牌到威脅模型和私鑰 JWT 的所有內(nèi)容。

“但是，”我聽到你說，“肯定不是所有這些 RFC 都與使用 API 的簡單第三方訪問令牌授權(quán)相關(guān)嗎？”

你說得對。讓我們只關(guān)注可能與典型的 API 第三方訪問用例相關(guān)的事情：

OAuth 標(biāo)準(zhǔn)：OAuth 2.0 現(xiàn)在是默認的，但是 OAuth 1.0a 仍然被一些人使用（2.1 即將到來）。一旦你知道你的 API 使用了哪一個，請繼續(xù)。

授予類型：你需要authorization_code、client_credentials還是device_code？它們的作用是什么，你應(yīng)該在什么時候使用它們？如有疑問，請嘗試authorization_code。

旁注：刷新令牌也是一種授權(quán)類型，但有點特殊。它們的工作方式是標(biāo)準(zhǔn)化的，但你最初要求它們的方式卻不是。稍后會詳細介紹。

現(xiàn)在你已準(zhǔn)備好處理你的請求，讓我們看看許多（準(zhǔn)確地說是 72 個）具有定義的含義和行為的官方 OAuth 參數(shù)。常見示例有prompt、scope、audience、resource、assertion和login_hint。然而，根據(jù)我們的經(jīng)驗，大多數(shù) API 提供者似乎都沒有注意到這個列表，就像你可能直到現(xiàn)在一樣，所以不要太擔(dān)心它。

如果你認為這仍然感覺太復(fù)雜并且需要學(xué)習(xí)很多東西，我們傾向于同意你的看法。

大多數(shù)構(gòu)建公共 API 的團隊似乎也同意這一點。他們沒有實現(xiàn)完整的 OAuth 2.0 子集，而是只實現(xiàn)了他們認為 API 用例所需的 OAuth 部分。這導(dǎo)致文檔中有相當(dāng)長的頁面概述了 OAuth 如何為這個特定的 API 工作。但是我們很難責(zé)怪他們；他們的 DX 只考慮最好的意圖。如果他們真的試圖實施完整的標(biāo)準(zhǔn)，你需要閱讀一本小書！

Salesforce authorization_code OAuth 流程。為什么不喜歡這個簡單的 10 步過程的清晰視覺效果？

問題在于每個人對于 OAuth 的哪個子集與他們相關(guān)的想法略有不同，因此你最終會得到許多不同的（子）實現(xiàn)。

3、每個人的 OAuth 都有細微差別

由于每個 API 都實現(xiàn)了不同的 OAuth 子集，你很快就會陷入被迫詳細閱讀 OAuth 文檔的長頁的情況：

他們在授權(quán)調(diào)用中需要哪些參數(shù)？

• 對于 Jira，audience參數(shù)是 key（并且必須設(shè)置為特定的固定值）。谷歌更喜歡通過不同的范圍來處理這個問題，但真正關(guān)心的是提示參數(shù)。同時，Microsoft 的某個人發(fā)現(xiàn)了response_mode參數(shù)并要求你始終將其設(shè)置為query。
• Notion API 采用了一種激進的方法，取消了無處不在的范圍參數(shù)。事實上，你甚至不會在他們的 API 文檔中找到“作用域”這個詞。Notion 將它們稱為“功能”，你可以在注冊應(yīng)用程序時設(shè)置它們。我們花了 30 分鐘才明白發(fā)生了什么。他們?yōu)槭裁匆匦掳l(fā)明這個輪子？
• 使用offline_access會變得更糟：現(xiàn)在大多數(shù) API 都會在短時間后過期訪問令牌。要獲得刷新令牌，你需要請求“offline_access”，這需要通過參數(shù)、范圍或你在注冊 OAuth 應(yīng)用程序時設(shè)置的內(nèi)容來完成。有關(guān)詳細信息，請咨詢你的 API 或 OAuth 醫(yī)生。

他們希望在令牌請求調(diào)用中看到什么？

• 某些 API，如 Fitbit，堅持在標(biāo)頭中獲取數(shù)據(jù)。大多數(shù)人真的希望它在正文中，編碼為x-www-url-form-encoded，除了少數(shù)，例如 Notion，它更喜歡將它作為 JSON 獲取。
• 有些人希望你使用基本身份驗證來驗證此請求。許多人對此并不在意。但要小心，他們明天可能會改變主意。

我應(yīng)該在哪里重定向我的用戶進行授權(quán)？

• Shopify 和 Zendesk 有一個模型，在該模型中，每個用戶都會獲得一個子域，例如 {subdomain}.myshopify.com。是的，它包括 OAuth 授權(quán)頁面，因此你最好將動態(tài) URL 構(gòu)建到你的模型和前端代碼中。
• Zoho Books 為不同地點的客戶提供不同的數(shù)據(jù)中心。希望他們記住他們的數(shù)據(jù)所在的位置：要授權(quán)你的應(yīng)用程序，你的美國客戶應(yīng)該訪問 https://accounts.zoho.com，歐洲人可以訪問 https://accounts.zoho.eu，歡迎印度人訪問 https：//賬戶.zoho.in. 清單還在繼續(xù)。

但至少我可以選擇我的回調(diào) URL，不是嗎？

如果你輸入http://localhost:3003/callback作為 Slack API 的回調(diào)，他們會友善地提醒你“請使用 https 確保安全”。是的，也適用于本地主機。幸運的是，在 localhost 上有 OAuth 重定向的解決方案。

我們可以繼續(xù)討論很長時間，但我們認為你現(xiàn)在可能明白了。

• OAuth 太復(fù)雜；讓我們制作一個更簡單的 OAuth 版本，它擁有我們需要的一切！XKCD

4、許多 API 向 OAuth 添加非標(biāo)準(zhǔn)擴展

盡管 OAuth 標(biāo)準(zhǔn)非常龐大，但許多 API 似乎仍然在其中尋找所需功能的差距。我們看到的一個常見問題是，除了access_token之外，你還需要一些數(shù)據(jù)才能使用 API。如果這些額外的數(shù)據(jù)可以與 OAuth 流中的 access_token 一起返回給你，那不是很好嗎？

我們實際上認為這是一個好主意——或者至少比強迫用戶在之后執(zhí)行古怪的額外 API 請求來獲取此信息（看看你，Jira）要好。但這確實意味著你特別需要為每個 API 實現(xiàn)更多非標(biāo)準(zhǔn)行為。

以下是我們見過的一小部分非標(biāo)準(zhǔn)擴展：

• Quickbooks 使用realmID，你需要在每個 API 請求中傳入它。他們唯一一次告訴你這個realmID是作為 OAuth 回調(diào)中的附加參數(shù)。最好將它存放在安全的地方！
• Braintree 對companyID做同樣的事情
• Salesforce 為每個客戶使用不同的 API 基本 URL；他們稱之為instance_url。值得慶幸的是，他們在令牌響應(yīng)中返回了用戶的instance_url和訪問令牌，但你確實需要從那里解析并存儲它。
• 不幸的是，Salesforce 還做了更煩人的事情：訪問令牌在預(yù)設(shè)時間后過期，這可以由用戶自定義。到目前為止還不錯，但出于某種原因，當(dāng)你剛收到的訪問令牌將過期時，他們不會在令牌響應(yīng)中告訴你（其他人都會這樣做）。相反，你需要查詢額外的令牌詳細信息端點以獲取令牌的（當(dāng)前）到期日期。為什么，Salesforce，為什么？
• Slack 有兩種不同類型的范圍：你作為 Slack 機器人擁有的范圍和允許你代表授權(quán)你的應(yīng)用程序的用戶采取行動的范圍。很聰明，但他們并沒有為每個范圍添加不同的范圍，而是實現(xiàn)了一個單獨的user_scopes參數(shù)，你需要在授權(quán)調(diào)用中傳遞該參數(shù)。你最好了解這一點，祝你好運，在你的 OAuth 庫中找到對此的支持。

為了簡潔起見，我們將跳過我們遇到的許多非真正標(biāo)準(zhǔn)的 OAuth 流程。

5、“invalid_request”調(diào)試 OAuth 流程很困難

調(diào)試分布式系統(tǒng)總是很困難。當(dāng)你使用的服務(wù)使用廣泛的、通用的錯誤消息時，這會變得更加困難。

OAuth2 有標(biāo)準(zhǔn)化的錯誤消息，但它們在告訴你正在發(fā)生的事情方面與上面標(biāo)題中的示例一樣有用（順便說一下，這是 OAuth 標(biāo)準(zhǔn)推薦的錯誤消息之一）。

你可能會爭辯說 OAuth 是一個標(biāo)準(zhǔn)并且每個 API 都有文檔，那么有什么可以調(diào)試的呢？

很多。我無法告訴你文檔出錯的頻率?；蛘呷鄙僖粋€細節(jié)?；蛘哌€沒有更新最新的變化?；蛘弋?dāng)你第一次看到它們時你錯過了什么。我們實施的 80% 的 OAuth 流程在首次實施時都存在一些問題，需要調(diào)試。

在我調(diào)試 OAuth 流程時 Randall 是如何觀察我的？XKCD

某些流程也會因看似隨機的原因而中斷：例如，如果你傳入 PKCE 參數(shù)，LinkedIn OAuth 就會中斷。你得到的錯誤？“客戶端錯誤 - 無效的 OAuth 請求。” 那是……告訴？我們花了一個小時才明白傳遞（可選，通常被忽略）PKCE 參數(shù)是中斷流程的原因。

另一個常見錯誤是發(fā)送的范圍與你在應(yīng)用程序中預(yù)注冊的范圍不匹配。（預(yù)注冊范圍？是的，現(xiàn)在很多 API 都需要這樣做。）這通常會導(dǎo)致出現(xiàn)有關(guān)范圍存在問題的一般錯誤消息。呃。

6、在 API 之上構(gòu)建的繁瑣審批

事實是，如果你通過使用他們的 API 構(gòu)建其他系統(tǒng)，你可能處于較弱的位置。你的客戶要求集成，因為他們已經(jīng)在使用其他系統(tǒng)?，F(xiàn)在你需要讓他們開心。

公平地說，許多 API 都是自由的，并為開發(fā)人員提供簡單的自助服務(wù)注冊流程來注冊他們的應(yīng)用程序并開始使用 OAuth。但是一些最流行的 API 在你的應(yīng)用程序公開并且可以被任何用戶使用之前需要進行審查。同樣，公平地說，大多數(shù)審核過程都很正常，可以在幾天內(nèi)完成。就最終用戶的安全性和質(zhì)量而言，它們可能是凈收益。

但一些臭名昭著的例子可能需要數(shù)月才能完成，有些甚至需要你簽訂收入分成協(xié)議：

• 如果你想訪問包含更敏感的用戶數(shù)據(jù)（例如電子郵件內(nèi)容）的范圍，Google 需要進行“安全審查”。我們聽說這些審核可能需要數(shù)天或數(shù)周才能通過，并且你需要付出大量的工作。
• 想要與 Rippling 集成？準(zhǔn)備好接受他們的 30 多個問題和安全預(yù)生產(chǎn)篩選。我們聽說訪問需要幾個月的時間（如果你獲得批準(zhǔn)）。
• HubSpot、Notion、Atlassian、Shopify 以及幾乎所有其他擁有集成市場或應(yīng)用程序商店的人都需要經(jīng)過審查才能在其中列出。有些評論很溫和，有些則要求你提供演示登錄、視頻演練、博客文章（是的！）等等。但是，在市場或商店中列出通常是可選的。
• Ramp、Brex、Twitter 和許多其他公司沒有面向開發(fā)人員的自助注冊流程，需要你填寫表格以進行手動訪問。許多人很快就能處理請求，但我們?nèi)栽诘却龜?shù)周后的回復(fù)。
• Xero 是貨幣化 API 的一個特別極端的例子：如果你想超過 25 個連接帳戶的限制，你必須成為 Xero 合作伙伴并將你的應(yīng)用程序列在他們的應(yīng)用程序商店中。然后，他們將從該商店產(chǎn)生的每條線索中（截至撰寫本文時）收取 15% 的收入。

7、OAuth 安全性很棘手并且是一個動態(tài)變化的目標(biāo)

隨著攻擊被發(fā)現(xiàn)，可用的 Web 技術(shù)不斷發(fā)展，OAuth 標(biāo)準(zhǔn)也發(fā)生了變化。如果你希望實施當(dāng)前的安全最佳實踐，OAuth 工作組為你提供了一份相當(dāng)冗長的指南。如果你使用的 API 目前仍在使用 OAuth 1.0a，你就會意識到向后兼容性是一場永無止境的斗爭。

幸運的是，安全性隨著每次迭代而變得更好，但這通常是以開發(fā)人員的更多工作為代價的。即將推出的 OAuth 2.1 標(biāo)準(zhǔn)將使一些當(dāng)前的最佳實踐成為強制性的，包括強制性的 PKCE（目前只有少數(shù) API 需要這個）和對刷新令牌的額外限制。

至少 OAuth 已經(jīng)實現(xiàn)了雙因素身份驗證模型。XKCD

隨著訪問令牌的過期和刷新令牌的興起，可能已經(jīng)迎來了最大的變化。從表面上看，這個過程似乎很簡單：每當(dāng)訪問令牌過期時，用刷新令牌刷新它并存儲新的訪問令牌和刷新令牌。

實際上，當(dāng)我們實現(xiàn)這個時，我們必須考慮：

• 競爭條件：我們?nèi)绾未_保在刷新當(dāng)前訪問令牌時沒有其他請求運行？
• 如果你在一定天數(shù)內(nèi)未使用刷新令牌（或者如果用戶已撤銷訪問權(quán)限），某些 API 也會使刷新令牌過期。預(yù)計一些刷新會失敗。
• 某些 API 會在每次刷新請求時向你發(fā)出一個新的刷新令牌……
• 但有些人也默默地假設(shè)你會保留舊的刷新令牌并繼續(xù)使用它。
• 一些 API 會以絕對值告訴你訪問令牌過期時間。其他人只是相對“從現(xiàn)在開始的幾秒鐘”。還有一些，例如 Salesforce，不會輕易泄露此類信息。

8、最后：還沒有談到的事情

遺憾的是，我們只是觸及了 OAuth 實施的皮毛而已?，F(xiàn)在，OAuth 流程已經(jīng)運行并且獲得了訪問令牌，這時候需要考慮：

• 如何安全地存儲這些訪問令牌和刷新令牌。它們就像你用戶帳戶的密碼。但是散列不是一種選擇；你需要安全、可逆的加密。
• 檢查授予的范圍是否與請求的范圍匹配（某些 API 允許用戶更改他們在授權(quán)流程中授予的范圍）。
• 刷新令牌時避免競爭條件。
• 在提供商端，檢測用戶撤銷的訪問令牌。
• 讓用戶知道訪問令牌已過期，以便他們可以在需要時重新授權(quán)你的應(yīng)用程序。
• 如何撤銷你不再需要的訪問令牌（或用戶要求你根據(jù) GDPR 刪除的訪問令牌）。
• 可用 OAuth 范圍的更改、提供程序錯誤、缺少文檔等。

原文鏈接：https://www.nango.dev/blog/why-is-oauth-still-hard