跳至主要内容

免登流程

端內免登由客戶端 SDK 取得一次性 code，再由應用後端換取目前使用者身份。SDK 會處理客戶端授權請求，應用頁面不需要直接呼叫客戶端授權介面。

接入前設定​

在管理後臺「內部應用」中完成以下設定：

  1. 應用已啟用並發布版本，且已開啟客戶端顯示。
  2. 已設定桌面端或行動端的應用入口。
  3. 已將實際應用頁面加入端內免登地址白名單。
  4. 目前使用者在應用可見範圍內。

流程​

應用頁面
   │ 1. SDK 呼叫 requestWorkbenchAuthCode() 取得一次性 code
   │ 2. 透過 HTTPS 將 code 傳送給應用後端
   ▼
應用後端
   │ 3. POST /auth/v1/oauth/token 取得 access_token
   │ 4. POST /auth/v1/oauth/userinfo?access_token=... 提交 code
   ▼
應用後端取得 {userId, nickName, avatar}，建立自己的登入態

前端範例​

<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 { code } = await sdk.requestWorkbenchAuthCode();
    const response = await fetch("/api/workbench/login", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ code }),
    });

    if (!response.ok) {
      throw new Error("登入失敗，請重新申請授權碼");
    }
  }

  loginFromWorkbench();
</script>

前端只負責取得並提交 code，不得保存 client_secret、access_token 或使用者身份資料。

服務端介面呼叫​

1. 取得應用令牌​

應用後端使用服務端保存的 client_id 和 client_secret 呼叫 Token 介面：

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

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

成功響應：

{
  "access_token": "應用級令牌",
  "expires_in": 7200
}

2. 取得目前使用者資訊​

使用 Token 介面返回的 access_token 和前端提交的一次性 code 呼叫 UserInfo 介面：

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

code=<code>

成功響應：

{
  "userId": "10001",
  "nickName": "張三",
  "avatar": "https://cdn.example.com/avatar/10001.png"
}

code 只能使用一次，兌換成功後立即失效。client_secret 和 access_token 只能由應用後端保存和使用，不能下發到前端。

常見錯誤​

HTTP 狀態碼錯誤碼處理方式
400INVALID_REQUEST檢查 access_token、code 和請求格式。
400INVALID_GRANTcode 已過期、已使用或與應用不符，請重新取得 code。
401INVALID_TOKEN重新取得應用 access_token。
403USER_NOT_VISIBLE檢查使用者是否在應用可見範圍內。
500SERVER_ERROR稍後重試。