Skip to main content

​
為什麼在這裡需要 OAuth

你的應用程式已能在你自己的帳戶上，執行 Fluz API 提供的一切功能。使用你的 API 金鑰產生權杖即可—請參見 Authentication 與 API credentials。 當帳戶不是你的時候，就需要 OAuth 應用程式。 當你想在客戶的錢包發卡、從他們連結的銀行帳戶扣款、讀取他們的交易或向他們撥款時，你需要該名使用者的明確授權——而且需要一種 Fluz 能驗證、限定範圍、設定到期並可撤銷的形式。這就是 OAuth 應用程式的意義：你軟體的已註冊身分，加上一個將使用者同意轉換為你的伺服器可用權杖的同意機制。
一旦你持有以客戶為範圍的權杖，API 便完全相同。用你自己的權杖呼叫 createVirtualCard 會在你的錢包建立卡片；用客戶權杖呼叫相同的 mutation 會在他們的錢包建立卡片。OAuth 改變的是_你正在操作誰的帳戶_，而不是你能做什麼。

​
你需要嗎？

你在你自己的 Fluz 帳戶內發卡、購買禮品卡或移轉資金：撥款引擎、大量發卡、內部消費工具、ERP 同步。使用你的應用程式 API 金鑰直接呼叫 generateUserAccessToken。不需要 OAuth 應用程式、沒有同意畫面、沒有重新導向。從 API credentials 開始。

​
三組憑證，各司其職

本章節最常見的困惑是：一個 Fluz 應用程式攜帶不只一組憑證，而且它們不能互換。
這裡的每個 secret 都能鑄造權限。洩漏 apiSecret 會讓他人能以你的平台名義簽署交易；洩漏 client_secret 會讓他人能以你的應用程式身分交換授權代碼。請將兩者都僅放在伺服器端，切勿出現在瀏覽器 bundle、行動裝置二進位檔或版本控制中。

​
權限模型

Fluz 在兩個層級強制執行權限，而應用程式的有效存取權是兩者的交集。
1

應用程式層級授與——天花板

設定於你的應用程式 Permissions 分頁。這是你的應用程式在任何使用者無關的情況下，所能請求的最大範圍。若你在 authorize URL 中放入未在此啟用的 scope，該 scope 將被靜默忽略——請求不會出錯，只是該 scope 不會被授與。有些 scopes 是由 Fluz 管控而非自行選取。PCI_COMPLIANCE 僅在應用層級授與，僅提供給已證明符合 PCI DSS 的開發者，且在產生權杖時不可請求。
2

使用者層級授與——地板

由最終使用者在同意畫面上設定。他們會看到你所請求的 scopes——以可讀的頂層標題群組呈現，而非原始列舉值——並同意它們。任何被拒絕的項目都不會被授與。
3

兩者都必須有效

在 generateUserAccessToken 時驗證，而非在呼叫時驗證。兩種授與都必須存在且未過期。因此，遭撤銷或失效的授與會表現為權杖產生失敗，而不是流程中途的權限錯誤——這通常是在先前運作正常的整合開始失效時，首先該檢查的地方。
依能力劃分的 scopes： 使用 getApplicationScopes 讀取目前已授與的內容。完整參考： Application Scopes。
請求更少。 較短的同意畫面轉換率更佳，而範圍更窄的權杖在外洩時能降低風險。只請求你眼前流程所需的內容，當需要更多時再產生新的權杖。

​
生命週期，從頭到尾

以下每個步驟在本章節中都有深入頁面。這裡是地圖；那些頁面是疆域。
1

建立應用程式

在開發者控制台選擇 Browse templates 並加入 OAuth Integration 範本。為它命名、副標、描述——這三個欄位會出現在使用者的同意畫面上，所以請用給人看的語氣撰寫，而非你的議題追蹤器用語。→ Create an OAuth App
2

進行設定

在 Permissions 分頁選擇你的 scope 天花板。在 OAuth 分頁設定 Redirect URIs（公開、不可含查詢參數、數量不拘）以及 Webhook URLs（可各自訂閱特定事件；未選事件的 URL 會成為全收）。在 Overview 加上頭像與標誌——沒有它們，同意畫面看起來不完整。→ Configure OAuth App
3

導引用戶進行授權

重新導向至 /authorize 並帶上 response_type=code、你的 client_id、一個已註冊的 redirect_uri、以空白分隔的 scopes 列表，以及可選擇性的 state 值（會原樣回傳給你）。→ Client-facing OAuth grant flow
4

接收授權代碼

在核准後，Fluz 會以 code 與你原先的 state 重新導向至你的 redirect_uri。若設定有誤，重新導向會帶有描述不匹配之處的錯誤訊息。
5

以授權代碼交換權杖

使用 code 與完全相同的 redirect_uri 呼叫 /token/exchange，並以 Authorization: Basic base64(client_id:client_secret) 驗證。你會拿回一個 accessToken、一個 refreshToken、到期時間戳，以及確認後的 scope 陣列。→ Exchanging an OAuth authorization code
6

刷新，不要重提同意

使用 refresh_token 與相同的 Basic auth 標頭呼叫 /token/refresh。存取權杖刻意設計為短效——大約十分鐘——而更新權杖約可維持一個月。請在背景靜默刷新；只有在更新權杖本身已過期或授與已被撤銷時，才再次將使用者帶回同意流程。→ Refreshing an OAuth accessToken
7

上線

測試與正式是分離的環境，擁有分離的應用程式與分離的憑證。沒有任何東西會沿用——你需要在正式主機上再次註冊應用程式、重新導向 URI 與 webhook 端點。→ Deploying to Production

​
會咬人的規則

在開始之前值得內化，因為以下每一條都可能靜默或令人困惑地失敗。
你送往 /authorize 的 redirect_uri 必須已在應用程式註冊，且你送往 /token/exchange 的必須與你在 /authorize 使用的那個位元級相同。結尾斜線、http 與 https、主機大小寫都算。不要在 URI 本身註冊查詢參數——請用 state 傳遞情境。
若請求一個你未在 Permissions 分頁勾選的 scope，authorize 請求仍會成功——該 scope 會被丟棄。請務必閱讀交換回應中的 scope 陣列，並以它（而非你的請求）作為你能做什麼的事實依據。
立刻在伺服器端交換，且僅一次。若你的重新導向處理器可能被重放——使用者重新整理回呼頁面、連結預先擷取——請確保第二次嘗試不會破壞狀態。
Authorization: Basic <base64(client_id + ":" + client_secret)>。請對連接後的字串進行編碼。交換步驟中多數的整合失敗都出在這裡。
重新導向是一次全新的瀏覽器導覽。若你需要知道是哪位使用者、哪個流程，或要回到哪個頁面，請在 state 放入簽章或可由伺服器查找的參照。不要在其中放入敏感資訊——它會經過使用者的瀏覽器。
若 generateUserAccessToken 對昨天還能用的使用者開始失敗，請先檢查應用層級授與或使用者層級授與是否過期或被撤銷，再去檢查你的程式碼。

​
OAuth 應用程式 vs. widgets

兩者都是應用程式，都使用上述的權限模型。差異在於誰負責打造同意介面。 你可以混搭：透過 API 完成使用者註冊與 KYC，然後只在同意與敏感資料收集時開啟 widget。混合模式請見 Embedded Widgets。

​
下一步

建立 OAuth 應用程式

從 OAuth Integration 範本註冊你的應用程式。

設定 OAuth 應用程式

Scopes、重新導向 URI、webhooks、品牌化。

用戶端授權流程

建立 authorize URL 並處理回呼。

交換授權代碼

將代碼轉換為 access token 與 refresh token。

刷新存取權杖

在不重新提示使用者的情況下維持授權。

部署到正式環境

針對正式主機重新註冊並上線。
正在打造一個平台，讓你的每位客戶都有一個 Fluz 帳戶嗎？Build a platform 端到端說明整個模式，而 API Features 上的每項能力在連接帳戶上都以相同方式運作。