客户端接入

客户端 SDK 用于让工作台内打开的网页应用获取一次性 code，再由应用后端完成免登。SDK 采用本地文件引入方式，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__;

    // 普通浏览器不申请工作台 code，改用业务系统自己的登录流程。
    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 函数​

常见问题​