客戶端接入

客戶端 SDK 用於讓工作臺內開啟的網頁應用取得一次性 code，再由應用後端完成免登。SDK 採用本地檔案引入方式，不負責 Token 兌換、使用者資訊查詢或業務登入。

下載並引入 SDK

SDK 不透過 npm 安裝，請下載 UMD 檔案並儲存到業務系統的靜態資源目錄。

下載地址：twt-link-universal.umd.min.js

<script src="/assets/sdk/twt-link-universal.umd.min.js"></script>

SDK 載入後，透過 window.__TWT_LINK__ 使用公開函式。

接入流程

在管理後臺建立並發布企業內部應用，設定端內免登地址。
下載 SDK 並放入業務系統的靜態資源目錄。
使用 <script> 標籤引入本地 SDK 檔案。
在工作臺容器內呼叫 requestWorkbenchAuthCode() 取得一次性 code。
透過 HTTPS 將 code 提交給應用後端。
後端使用應用憑證呼叫 Token 和 UserInfo 介面，取得目前使用者資訊並建立業務登入態。

前端示例

以下示例展示如何引入本地 SDK、判斷工作臺環境、取得 code 並提交給業務後端：

<script src="/assets/sdk/twt-link-universal.umd.min.js"></script>
<script>
  async function loginFromWorkbench() {
    const sdk = window.__TWT_LINK__;

    // 普通瀏覽器使用業務系統自己的登入流程。
    if (!sdk || !sdk.isTwtLinkPlateform()) {
      window.location.href = "/login";
      return;
    }

    const environment = sdk.getWorkbenchEnvironment();
    console.info("目前工作臺環境", environment.platform);

    try {
      // code 只能使用一次，取得後立即透過 HTTPS 交給業務後端。
      const { code } = await sdk.requestWorkbenchAuthCode({ timeoutMs: 5000 });
      const response = await fetch("/api/workbench/login", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ code }),
      });

      if (!response.ok) {
        throw new Error("業務登入失敗，請重新申請 code");
      }

      window.location.replace("/app");
    } catch (error) {
      // 不要重複提交舊 code；重試時應重新呼叫 requestWorkbenchAuthCode。
      console.error("工作臺免登失敗", error);
    }
  }

  loginFromWorkbench();
</script>

SDK 返回的資料結構為：

{ code: "一次性 code" }

不要將 code 寫入 URL、日誌、Cookie、Local Storage 或其他持久化儲存。普通瀏覽器不支援工作臺免登時，應使用業務系統自己的登入流程。

服務端處理

業務後端收到前端提交的 code 後：

使用服務端保存的 client_id 和 client_secret 呼叫 POST /auth/v1/oauth/token，取得應用級 access_token。
使用 access_token 和一次性 code 呼叫 POST /auth/v1/oauth/userinfo，取得目前使用者資訊。
根據使用者資訊建立業務系統自己的登入態，後續業務請求使用業務系統登入態。

取得應用級 access_token：

POST /auth/v1/oauth/token
Content-Type: application/json

{
  "client_id": "應用 ID",
  "client_secret": "應用密鑰",
  "grant_type": "client_credentials"
}

查詢目前使用者資訊：

POST /auth/v1/oauth/userinfo?access_token=<access_token>
Content-Type: application/x-www-form-urlencoded

code=<code>

client_secret、access_token 和 code 都不能下發到前端。client_secret 只能保存在業務後端，code 兌換成功後應立即丟棄。

SDK 函式

isTwtLinkPlateform()：判斷目前頁面是否執行在支援 TWT Link 的工作臺客戶端中。
getWorkbenchEnvironment()：取得目前客戶端環境，需要區分 PC 端和行動端時使用。
requestWorkbenchAuthCode()：取得一次性 code，可傳入 timeoutMs 和 AbortSignal，取得後立即提交給應用後端。

常見問題

SDK 錯誤會透過 AuthError.code 返回。下表列出 SDK 目前定義的錯誤碼和處理方式。業務程式碼應按錯誤碼分支處理，如果遇到下表未提及的錯誤，請聯絡我們。

錯誤碼	常見原因	處理方式
`SDK_ENVIRONMENT_UNSUPPORTED`	目前頁面不是受支援的工作臺客戶端，或執行環境資訊不完整。	確認頁面從受支援的工作臺客戶端開啟；普通瀏覽器應使用業務系統自己的登入流程。
`AUTH_REQUEST_TIMEOUT`	目前客戶端或授權鏈路在 `timeoutMs` 時限內沒有返回。	檢查網路和工作臺狀態，重新呼叫 SDK 取得新的 `code`；不要提交已逾時的 `code`。
`AUTH_REQUEST_ABORTED`	呼叫方主動取消請求，或目前授權請求已被新的請求取代。	不需要按服務端故障處理；避免重複點擊，確認請求狀態後重新申請 `code`。
`AUTH_REQUEST_PAGE_CHANGED`	申請授權期間頁面地址發生變化，或授權上下文已失效。	在最終頁面地址穩定後重新呼叫 SDK，不要在跳轉、重新整理過程中申請 `code`。
`AUTH_REQUEST_IN_PROGRESS`	同一頁面已有一個正在進行的授權請求。	複用或等待現有請求，避免並行呼叫 `requestWorkbenchAuthCode()`。
`AUTH_RESPONSE_INVALID`	目前客戶端返回的資料缺少必要欄位，或回應結構校驗失敗。	確認 SDK 與工作臺客戶端版本相符；保留錯誤碼和請求時間，必要時聯絡我們。
`INVALID_REQUEST`	目前客戶端或服務端認為請求參數不合法，例如請求體、應用標識或目前頁面地址缺失或格式錯誤。	檢查應用設定、端內免登地址和目前頁面地址；不要修改 SDK 內部請求參數。
`INVALID_CLIENT`	應用不可用、目前頁面不在免登地址範圍內、來源不匹配，或使用者不在應用可見範圍內。	檢查應用是否已發布、免登地址和來源設定、應用可見範圍及應用憑證。
`INVALID_TOKEN`	閘道或目前客戶端注入的目前使用者憑證無效。	引導使用者重新登入工作臺，再重新申請 `code`。
`SERVER_ERROR`	服務端資料庫、快取等依賴異常，或發生未識別的服務端錯誤。	稍後重試；持續失敗時記錄錯誤碼、時間和請求標識，聯絡服務端維護人員。
`HOST_AUTH_REJECTED`	目前客戶端拒絕授權，但沒有返回更具體的錯誤碼。	檢查客戶端登入狀態、應用設定和可見範圍；仍無法定位時聯絡我們。

code 是一次性憑證。除排查問題所需的錯誤碼、請求時間和請求標識外，不要記錄 code、access_token 或 client_secret。

服務端免登介面詳細說明請參閱免登流程。

下載並引入 SDK​

接入流程​

前端示例​

服務端處理​

SDK 函式​

常見問題​