Skip to main content
這是由真人決定是否允許你的應用程式存取其 Fluz 帳戶的步驟。你將他們重新導向至 Fluz,他們核准後,Fluz 會帶著短效授權碼把他們重新導回你這裡。 此頁之前都是設定,此頁之後是權杖處理。這是你使用者唯一會看到的步驟。

位置與脈絡

請注意圖中 Fluz 在中間處理了什麼:帳戶建立、登入、雙重驗證,以及在使用者尚未完成時的身分驗證。你不需要建置這些,且你永遠不會看到任何憑證。

開始之前

1

你的應用程式已完成設定

Permissions 分頁設定範圍上限、在 OAuth 分頁註冊回呼 URI,並將 client_idclient_secret 放入你的密鑰儲存。請參考 設定 OAuth 應用程式
2

你的回呼路由已存在且可連到你的工作階段儲存

它需要讀取 state,並與你在重新導向前所持久化的值進行比對。
3

你知道此流程需要哪些範圍

完整清單請見 Authentication。請只要求最低需求——同意畫面是流失率最高的步驟,其長度來自此清單。

第 1 步 — 建立 authorize URL

使用以下查詢參數將使用者導向 /authorize 端點。
參數是 scopes(複數)——不是基礎 OAuth 2.0 規範中的 scope。如果你使用通用的 OAuth 用戶端函式庫,這就是你需要覆寫的欄位。

環境

編碼規則

範圍之間的空白必須編碼為 %20redirect_uri 值也要進行 URL 編碼;請使用程式語言內建的 URL 編碼器來建立查詢字串,而非字串串接,如此即可自動處理這些事項。 完整的 Staging 範例:

使用者會看到什麼

Sample OAuth permissions page 你的應用程式名稱、頭像與描述取自 Overview 分頁,而權限列為你所選的範圍,並以可讀標題分組。若此畫面看起來不正確,修正點在 設定 OAuth 應用程式,而非你的程式碼。

第 2 步 — 使用 state 來保護流程

參考表將 state 標示為選填。在基於重新導向的授權流程中,它是你唯一能防止他人將其授權碼植入你使用者工作階段的方法,因此請從第一個提交就內建它,而不是之後才補上。
1

產生不可猜測的值

至少 128 位元,且來自密碼學安全來源。不要用時間戳、使用者 ID 或計數器。
2

於伺服器端儲存,並繫結至瀏覽器工作階段

可用工作階段儲存、已簽章的 Cookie,或以工作階段為鍵的短 TTL 快取。不要用全域變數。
3

回來時進行比對,不符合就拒絕

缺少、無法識別、或已使用過的 state 都代表要放棄該請求——不要交換授權碼。請使用恆定時間比較。
4

消耗它

成功比對後將其刪除,避免同一個回呼被重放。
state 會經由使用者的瀏覽器傳遞。用它來攜帶查找鍵是可以的——是哪位使用者、哪個流程、要返回哪個頁面——但切勿在值本身放入任何敏感或可信任的內容。

第 3 步 — 處理回呼

當核准後,Fluz 會將使用者重新導向至你的 redirect_uri,並帶有: 若請求設定有誤,重新導向會帶有描述不相符處的錯誤訊息。
立刻、只一次、由你的伺服器端交換授權碼。它是一次性且短效。讓你的回呼路由具備冪等性——使用者重新整理頁面、連結預先擷取,或瀏覽器重試都會讓它被打兩次,而第二次不得破壞狀態或對已成功的使用者顯示錯誤。
下一步:交換 OAuth 授權碼

第 4 步 — 對齊你實際拿到的內容

交換的回應包含使用者所核准的範圍陣列。該陣列——而非你的請求——才是你的整合可以做什麼的事實依據。 你請求的某個範圍可能缺失,原因可能是使用者拒絕,或因為它未在你的應用程式 Permissions 分頁啟用——這種情況會被悄悄移除而非被拒絕。無論如何,流程會成功完成,而你的 API 呼叫之後才會失敗。 讀取回傳的範圍,將它與權杖一併持久化,並據此控管功能。若缺少必要的項目,請明確告知使用者,並提供重新執行流程的選項。

設計這個關鍵時刻

當使用者理解為何會看到同意畫面時,轉換率會更高。
  • 在重新導向前先解釋。 在你的頁面上一句話——「連結你的 Fluz 帳戶以便我們匯出你的款項」——遠勝過把人直接丟到權限畫面。
  • 在情境中觸發。 於第一次撥款或第一次使用卡片時,而不是埋在帳戶設定中。
  • 使用整頁重新導向而不是彈出視窗。 彈出視窗可能被封鎖,且流程包含 2FA 以及可能的身分驗證,這在小視窗中會很不舒適。若你需要留在頁面中,請改用 內嵌小工具,它正是為此打造。
  • 處理返回行程。 讓使用者回到原本所在位置,且他們想做的那件事現在可以運作。state 是你知道他們原本在哪裡的方法。
  • 準備重新授權路徑。 更新權杖會過期,使用者也可能撤銷存取。請在建立連線流程的同時就建好「重新連線」流程,而不是等到第一張支援單才處理。
  • 考慮直接略過。 若你的使用者尚未擁有 Fluz 帳戶,小工具可在單一託管流程中處理註冊、驗證與同意,且無需重新導向。請見 Embedded Widgets

疑難排解


後續步驟

交換授權碼

將授權碼換成 access token 與 refresh token。

重新整理 access token

保持連線而不讓使用者再次經過同意流程。

設定 OAuth 應用程式

修正同意畫面顯示的不正確之處。

內嵌小工具

使用託管的頁內流程,完全略過重新導向。