重新導向 URL 的設定

OAuth 重新導向URI 應用程式登錄安全性

本文的對象
適用於在 ReceiptRoller 的開發者入口登錄應用程式的開發者。說明 OAuth 2.0 授權碼流程使用的重新導向 URI（回呼 URL）的設定方法與注意點。

重新導向 URI 是在 OAuth 授權流程中使用者於授權畫面「許可」後，用於接收授權碼的 URL。應用程式登錄時登錄的 URI，與實際對 /oauth/authorize 送請求時指定的 redirect_uri 需要完全一致。

重新導向 URI 的角色

在 OAuth 授權碼流程中，以下列順序傳遞值。

應用程式讓使用者轉移到 ReceiptRoller 的授權畫面（含 redirect_uri）
使用者按下「許可」
ReceiptRoller 對已登錄的重新導向 URI 附帶 code 參數重新導向
應用程式使用 code 取得存取權杖

將未登錄的 URI，或與登錄值僅差 1 個字的 URI 指定於 redirect_uri，ReceiptRoller 不會回傳授權碼而成 invalid_redirect_uri 錯誤。這是為了防止攻擊者竊取碼的機制。

登錄規則

項目	規則
Scheme	`https://` 必填（正式） `http://localhost` 以及 `http://127.0.0.1` 僅開發時許可
主機	完全修飾域名。萬用字元（`*.example.com`）不可
路徑	任意。建議 `/oauth/callback` 或 `/auth/rr/callback` 等慣例的路徑
查詢、片段	登錄 URI 不含。動態參數請以 `state` 傳遞
可登錄的件數	每 1 應用程式最多 10 件
大小寫	會被區別。`/Callback` 與 `/callback` 是不同物
末尾斜線	會被區別。`/callback` 與 `/callback/` 是不同物

開發、正式環境的分別使用

許多應用程式持有「開發」「預備」「正式」等多個環境。ReceiptRoller 中，可對 1 個應用程式登錄多個重新導向 URI，因此依環境追加 URI 為基本。

建議模式

https://app.example.com/oauth/callback           ← 正式
https://staging.example.com/oauth/callback       ← 預備
http://localhost:3000/oauth/callback             ← 開發（本機）

也可以依環境分開應用程式，但正式應用程式與開發應用程式務必分開強烈建議。理由如下。

不需要將正式的用戶端密鑰配布給全部開發者
可防止開發中的不相容誤將正式使用者的權杖失效的事故
User 系權限範圍的審查僅以正式應用程式就完成

注意：正式應用程式請勿登錄 http://localhost。密鑰外洩時，攻擊者可將授權碼誘導至手邊的假網站。

登錄步驟

開發者入口 → 應用程式一覽 → 開啟目標應用程式
點擊「重新導向 URI」區段的「＋追加」按鈕
輸入 URI 並「儲存」
需要的環境分反覆進行

登錄的 URI 會即時反映。不需要應用程式的重新建置或重新部署。

state 參數的活用

動態的資訊（轉移來源頁面的 URL、使用者 ID、CSRF 對策權杖等），請不要直接埋入重新導向 URI，而以 state 參數傳遞。state ReceiptRoller 授權後會原封不動回傳，因此可在回呼端還原。

// 授權請求
https://receiptroller.io/oauth/authorize
  ?client_id=xxx
  &redirect_uri=https://app.example.com/oauth/callback
  &state=eyJjc3JmIjoiYWJjMTIzIiwicmV0dXJuIjoiL2Rhc2hib2FyZCJ9
  &scope=store.read
  &response_type=code

// 回呼
https://app.example.com/oauth/callback
  ?code=...
  &state=eyJjc3JmIjoiYWJjMTIzIiwicmV0dXJuIjoiL2Rhc2hib2FyZCJ9

state 作為 CSRF 對策也是必須。請將請求時產生的隨機值保存到 session，回呼時確認一致。

常見錯誤

錯誤	原因	因應
`invalid_redirect_uri`	與已登錄 URI 不一致	大小寫、末尾斜線、埠號都含在內確認是否完全一致
`redirect_uri_required`	授權請求中沒含 `redirect_uri`	務必附加至查詢參數
`insecure_redirect_uri`	正式應用程式想登錄 `http://`（localhost 以外）	變更為 `https://`
授權後不回呼	登錄 URI 的主機有 DNS/憑證錯誤	以瀏覽器直接開該 URI 確認可到達

變更時的注意

要變更運作中應用程式的重新導向 URI 時，請遵守下列順序。

將新 URI 追加（舊 URI 保留原樣）
將應用程式的程式碼／環境變數切換為新 URI 並部署
以新 URI 確認運作
將舊 URI 刪除

將舊 URI 突然刪除的話，到部署完成為止之間發生的授權請求會全部失敗。