金鑰管理

一、何謂金鑰管理¶

透過「金鑰管理」，你可以控管 API 使用者的權限、查詢範圍與功能模組，目的是讓使用者可以安全地將系統資料、功能，授權給特定應用程式或外部系統存取，有效降低系統被濫用或資料外洩的風險。

目前支援四種金鑰類型：
- 應用程式開發金鑰（SDK）：授權第三方應用程式透過 UOFX SDK 呼叫 API，例如：API起單、取得組織部門資料、寫入文件庫等。
- 資料查詢金鑰 (OData)：提供報表工具 (如 Power BI) 以 OData 協定查詢組織人員、部門與表單資料。
- Open API 金鑰：授權外部系統呼叫符合 OpenAPI 標準的介面，此方式不限開發語言，開發者可透過標準 HTTP 請求 (RESTful API) 直接進行系統整合與資料交換，適用於跨平台或輕量級的開發情境。
- 開放授權金鑰(OAuth)：用於驗證應用程式身分並實作 OAuth授權流程，此機制允許外部應用程式在「不揭露密碼」的前提下，經使用者同意後，以「使用者個人身分」存取UOF X的個人相關資料。

路徑：管理者首頁>系統管理>金鑰管理

在 UOF X 中，若有以下任一情境需求，就建議啟用「金鑰管理」功能來保障系統安全，並進行有效的 API 存取權限控管。

串接第三方系統，透過API起單或讀取表單資料
- 當外部系統 (如 ERP、HR 系統) 需要與 UOF X 整合，並執行以下自動化操作時
  - 採購系統自動發送採購需求單至 UOF X，進行內部審核與流程追蹤。
  - CRM 系統送出客戶服務表單，供內部追蹤處理進度。
提供資料查詢 API 給外部報表工具 (如 Power BI)
- 為了方便管理者進行數據分析與統計，UOFX 支援透過 API 提供資料查詢介面
  - 透過 Power BI 連結器撈取 UOFX 的組織人員資料，建立人事報表。
  - 透過報表工具撈取單據資料，抓取流程進度、核決結果等資訊。
限制 API 存取範圍，保護系統資料安全
- 若希望確保只有特定系統或網段能夠存取 API，避免非授權設備惡意存取
  - 設定僅允許特定 IP 或 IP 區段可使用此金鑰。
  - 控制金鑰對 UOFX 系統內特定功能模組 (如：工作流程的表單、組織部門的資料) 的存取權限。
  - 針對每一個系統建立獨立金鑰，清楚劃分存取範圍與責任單位。

在建立金鑰之前，若你計畫讓金鑰串接表單或文件庫資料 (如讀取單據內容、API 起單)，請先確認相關表單與文件庫已開啟授權設定，否則即使金鑰功能已啟用，也無法成功存取資料。

針對表單與文件庫，UOF X 採用「雙向授權」原則，需同時設定「表單 / 文件庫的串接授權設定」與「金鑰可使用功能」，才能完成安全的串接設定。

表單授權設定（適用 SDK 與 OData 金鑰）
- 表單負責人可以前往 [表單設定] 的外部整合設定頁，根據組織需求，決定是否允許應用程式讀寫表單。
- 僅開啟授權的表單，才能被 SDK 金鑰串接與使用。
- 取消勾選時，該表單將自動從金鑰的授權清單中移除，立即生效。
文件庫授權設定（僅適用 SDK 金鑰）
- 文件中心管理員可以前往 [文件庫管理]，據組織需求，決定是否允許應用程式讀寫文件庫。
- 僅開啟授權的文件庫，才能被 SDK 金鑰串接與使用。
- 取消勾選時，該表單將自動從金鑰的授權清單中移除，立即生效。

完成授權準備後，你可以前往 [管理者首頁 > 系統管理 > 金鑰管理] 建立金鑰，此功能協助公司管理者控管外部應用程式串接權限，管理所有金鑰的存取狀態與功能範圍。

金鑰資訊的欄位資訊：由於各種金鑰類型在用途、授權方式與安全需求上皆不相同，因此在建立金鑰時，系統會依照金鑰的功能特性要求填寫不同的欄位，以下為欄位資訊的說明。

欄位名稱	說明
Client ID	系統自動產生的金鑰識別代號，便於系統間串接辨識使用，限OAuth金鑰才會需要使用欄位資訊。
Client 名稱	使用者自訂的金鑰識別名稱，便於後續維護與辨識金鑰用途，例如：「人資系統讀取」、「採購流程整合」等。
金鑰類型	選擇金鑰用途類型： • 應用程式開發金鑰 (SDK)：供系統整合開發用，支援送單、查詢等操作。 • 資料查詢金鑰 (OData)：提供外部工具（如 Power BI）讀取統計資料。
IP 來源	限制允許使用金鑰的來源 IP： • 不限制：任何裝置皆可存取 • 限制特定範圍：支援 CIDR 格式，例如 `127.0.0.1/32`, `192.168.1.7/32`
狀態	顯示金鑰是否啟用，支援手動啟用/停用。
金鑰	系統自動產生
重新導向URL	授權後系統將使用者導回的指定位置，用來確保授權結果只會送到可信任的應用程式端點，限OAuth金鑰才會需要此欄位值。
可使用的功能	根據金鑰類型提供不同的授權模組選項： • SDK：表單 / 文件中心 / 組織 / 打卡 • OData：組織 / 表單 • Open API：表單 / 文件中心 / 組織 / 打卡 • OAuth：表單 / 文件中心 / 讀取個人資料設定時需勾選至少一項，部分功能模組（如 BPM / DMS）還需指定授權的表單或文件庫清單。