位置與脈絡
請注意圖中 Fluz 在中間處理了什麼:帳戶建立、登入、雙重驗證,以及在使用者尚未完成時的身分驗證。你不需要建置這些,且你永遠不會看到任何憑證。
開始之前
1
你的應用程式已完成設定
在 Permissions 分頁設定範圍上限、在 OAuth 分頁註冊回呼 URI,並將
client_id 與 client_secret 放入你的密鑰儲存。請參考 設定 OAuth 應用程式。2
你的回呼路由已存在且可連到你的工作階段儲存
它需要讀取
state,並與你在重新導向前所持久化的值進行比對。3
你知道此流程需要哪些範圍
完整清單請見 Authentication。請只要求最低需求——同意畫面是流失率最高的步驟,其長度來自此清單。
第 1 步 — 建立 authorize URL
使用以下查詢參數將使用者導向/authorize 端點。
環境
編碼規則
範圍之間的空白必須編碼為%20。redirect_uri 值也要進行 URL 編碼;請使用程式語言內建的 URL 編碼器來建立查詢字串,而非字串串接,如此即可自動處理這些事項。
完整的 Staging 範例:
使用者會看到什麼
你的應用程式名稱、頭像與描述取自 Overview 分頁,而權限列為你所選的範圍,並以可讀標題分組。若此畫面看起來不正確,修正點在 設定 OAuth 應用程式,而非你的程式碼。
第 2 步 — 使用 state 來保護流程
參考表將 state 標示為選填。在基於重新導向的授權流程中,它是你唯一能防止他人將其授權碼植入你使用者工作階段的方法,因此請從第一個提交就內建它,而不是之後才補上。
1
產生不可猜測的值
至少 128 位元,且來自密碼學安全來源。不要用時間戳、使用者 ID 或計數器。
2
於伺服器端儲存,並繫結至瀏覽器工作階段
可用工作階段儲存、已簽章的 Cookie,或以工作階段為鍵的短 TTL 快取。不要用全域變數。
3
回來時進行比對,不符合就拒絕
缺少、無法識別、或已使用過的
state 都代表要放棄該請求——不要交換授權碼。請使用恆定時間比較。4
消耗它
成功比對後將其刪除,避免同一個回呼被重放。
state 會經由使用者的瀏覽器傳遞。用它來攜帶查找鍵是可以的——是哪位使用者、哪個流程、要返回哪個頁面——但切勿在值本身放入任何敏感或可信任的內容。第 3 步 — 處理回呼
當核准後,Fluz 會將使用者重新導向至你的redirect_uri,並帶有:
若請求設定有誤,重新導向會帶有描述不相符處的錯誤訊息。
第 4 步 — 對齊你實際拿到的內容
交換的回應包含使用者所核准的範圍陣列。該陣列——而非你的請求——才是你的整合可以做什麼的事實依據。 你請求的某個範圍可能缺失,原因可能是使用者拒絕,或因為它未在你的應用程式 Permissions 分頁啟用——這種情況會被悄悄移除而非被拒絕。無論如何,流程會成功完成,而你的 API 呼叫之後才會失敗。 讀取回傳的範圍,將它與權杖一併持久化,並據此控管功能。若缺少必要的項目,請明確告知使用者,並提供重新執行流程的選項。設計這個關鍵時刻
當使用者理解為何會看到同意畫面時,轉換率會更高。- 在重新導向前先解釋。 在你的頁面上一句話——「連結你的 Fluz 帳戶以便我們匯出你的款項」——遠勝過把人直接丟到權限畫面。
- 在情境中觸發。 於第一次撥款或第一次使用卡片時,而不是埋在帳戶設定中。
- 使用整頁重新導向而不是彈出視窗。 彈出視窗可能被封鎖,且流程包含 2FA 以及可能的身分驗證,這在小視窗中會很不舒適。若你需要留在頁面中,請改用 內嵌小工具,它正是為此打造。
- 處理返回行程。 讓使用者回到原本所在位置,且他們想做的那件事現在可以運作。
state是你知道他們原本在哪裡的方法。 - 準備重新授權路徑。 更新權杖會過期,使用者也可能撤銷存取。請在建立連線流程的同時就建好「重新連線」流程,而不是等到第一張支援單才處理。
- 考慮直接略過。 若你的使用者尚未擁有 Fluz 帳戶,小工具可在單一託管流程中處理註冊、驗證與同意,且無需重新導向。請見 Embedded Widgets。
疑難排解
後續步驟
交換授權碼
將授權碼換成 access token 與 refresh token。
重新整理 access token
保持連線而不讓使用者再次經過同意流程。
設定 OAuth 應用程式
修正同意畫面顯示的不正確之處。
內嵌小工具
使用託管的頁內流程,完全略過重新導向。