飞书登录怎么接：Web、桌面客户端、飞书内 H5 与移动端方案对比

给企业内部系统接入飞书登录时，最容易出现的误区是：看到“飞书免登”四个字，就以为所有客户端都能用同一套接口。

实际上，普通 Web 网站、独立桌面客户端、飞书客户端内嵌的 H5 应用，以及 Android、iOS
原生应用，运行环境完全不同。它们都可以完成飞书身份认证，但获取授权凭证、接收回调和保存登录状态的方式并不一样。

下面从应用形态出发，梳理几种常见方案的工作原理、适用场景、优缺点，以及开发时容易踩到的坑。

需要特别注意：在飞书 PC 客户端里打开的网页仍属于“飞书内 H5”，不能因为它运行在电脑上，就把它当作独立桌面客户端。

先明确一件事：客户端不负责“证明用户是谁”

无论采用哪种方式，授权码code都只能算一张短期凭证，不能直接当作业务系统的登录结果。不同场景中，code可能由前端 SDK 收到，也可能由用户浏览器直接送到后端redirect_uri。

完整的信任链应该是：

1. 应用把用户引导到飞书授权环境，或者在飞书客户端内调用免登 JSAPI。
2. 飞书签发临时授权码code，由前端提交给业务服务端，或由浏览器重定向到服务端。
3. 服务端使用 App ID、App Secret 和code换取飞书user_access_token，再获取用户身份信息。
4. 服务端在明确的应用和租户范围内匹配本地账号。
5. 服务端建立自己的登录会话，例如设置 HttpOnly Cookie，或者签发业务系统 Token。

这里最重要的原则是：App Secret 只能保存在服务端，不能打包到网页、Electron 或移动客户端中。

客户端负责发起授权，飞书负责证明身份，业务服务端负责建立“飞书用户”和“本地账号”的对应关系，并决定这个用户最终能不能进入系统。

账号映射不能只存一个含义模糊的“飞书用户 ID”。open_id是应用维度的用户标识；需要跨同一开发主体下的多个应用识别用户时，才考虑相应作用域下的union_id。多租户系统还要保存tenant_key或等价租户标识，并把它纳入唯一约束，不能把不同租户、不同应用的 ID 当成可互换主键。

方案一：系统浏览器 OAuth，适合独立桌面客户端

这是独立 Windows、macOS 或 Electron 客户端更符合 OAuth 原生应用安全实践的方案。RFC 8252 推荐原生应用使用系统浏览器等外部 User-Agent，而不是应用可控制的 WebView。

登录流程

桌面客户端请求业务服务端生成飞书授权地址 ↓ 客户端使用系统默认浏览器打开授权地址 ↓ 用户在飞书页面登录并确认授权 ↓ 飞书携带 code、state 回调业务服务端 ↓ 服务端用 code 换取飞书用户身份，并匹配本地账号 ↓ 服务端生成短时、一次性的登录 Ticket ↓ 浏览器跳转 com.example.desktop:/oauth/callback?ticket=xxx ↓ 操作系统唤起桌面客户端 ↓ 客户端用 Ticket 换取业务系统 Token

这里通常会注册一个自定义协议，例如：

com.example.desktop:/oauth/feishu/callback

飞书的重定向地址仍然配置成业务服务端的 HTTPS 地址，而不是直接配置自定义协议。服务端完成身份校验后，再跳转到自定义协议唤起客户端。

为什么要增加一次性 Ticket

服务端当然可以把业务系统的 Access Token 直接拼在com.example.desktop:/地址里，但不建议这样做。URL 可能出现在浏览器历史记录、系统日志、代理日志或者崩溃报告中。私有协议名最好使用自己持有域名的反向形式，降低与其他应用冲突的概率。

更安全的做法是签发一个高熵、有效期只有一两分钟、使用一次后立即失效的随机 Ticket。客户端拿到 Ticket 后，再通过 HTTPS 请求换取真正的业务 Token。服务端最好只保存 Ticket 哈希，并采用原子操作完成消费。

这样有几个好处：

• 飞书 Token 不会进入客户端。
• 业务 Access Token 不会暴露在浏览器地址栏。
• Ticket 即使泄露，也有很短的攻击窗口。
• 服务端可以原子消费 Ticket，防止重复兑换。

不过，“短时、一次性”并不能解决所有问题。私有协议可能被其他应用抢先注册，恶意应用如果截获 Ticket 后先完成兑换，真正的客户端仍然会失败。因此 Ticket 还应绑定登录发起端持有的随机verifier，使用类似 PKCE challenge 的方式证明“兑换者就是发起者”。操作系统支持且部署条件允许时，也可以优先考虑经过域名所有权验证的 HTTPS App Link/Universal Link。标准 OAuth 原生客户端流程如果支持 PKCE，应使用 S256。

优点

• 使用系统浏览器的现有登录状态，用户往往不需要再次输入飞书密码。
• 飞书登录页面运行在用户信任的浏览器中，客户端接触不到账号密码。
• 不要求电脑必须安装飞书客户端。
• 不限定 Chrome，Edge 或其他系统默认浏览器都可以。
• 同一套后端 OAuth 逻辑可以复用到 Windows、macOS 和 Linux。

缺点

• 登录时会短暂离开桌面客户端。
• 需要正确注册自定义协议，并处理应用未启动、已经启动和重复唤起等状态。
• Electron 应用通常还要实现单实例锁，否则回调可能启动第二个客户端进程。
• 回调 URL 必须登记在飞书开放平台，并且能被用户浏览器访问；生产环境通常使用 HTTPS。

如果产品形态是独立桌面客户端，我更推荐这一方案。它的交互不是最“无感”的，但身份页面和客户端处于不同安全上下文，兼容性也更好。这里的 Ticket Bridge 是业务系统自己的衔接设计，不是飞书提供的现成组件。

方案二：飞书客户端内 H5 免登

飞书 V6.9 及以上客户端应优先使用requestAccess获取免登授权码：

window.tt.requestAccess({appID:'your_app_id',scopeList:[],success(res){// 将 res.code 发送给业务服务端}})

scopeList为空时用于获取登录身份；需要增量授权时再按最小权限原则填写。requestAuthCode是 V6.9 之前使用的旧接口，目前已经停止维护，只应在确有旧客户端兼容要求时使用。两者返回的 code 有效期也不同，不能混用。

这类接口属于飞书客户端提供的 JSAPI，依赖飞书 H5 容器和正确引入的 JSSDK。开发时还要检查客户端最低版本、应用可见范围、网页应用能力和主页 URL 配置。

登录流程

用户从飞书工作台打开 H5 应用 ↓ H5 调用 tt.requestAccess ↓ 飞书客户端返回临时 code ↓ H5 将 code 提交给业务服务端 ↓ 服务端向飞书校验身份、匹配本地账号 ↓ 服务端签发业务系统 Token

飞书客户端本身已经知道当前登录用户是谁，所以不需要再次弹出完整的浏览器登录页。这也是它看起来更像“免登”的原因。

优点

• 用户从飞书工作台进入应用时，体验很顺畅。
• 通常不需要打开外部浏览器。
• 可以直接复用飞书客户端当前登录的企业身份。
• 适合审批、报表、内部管理系统等飞书工作台应用。

缺点

• 必须运行在飞书客户端环境中。
• 普通 Chrome 页面和独立 Electron 页面没有window.tt。
• 应用入口、JSAPI 权限和飞书客户端版本会影响实际行为。
• 系统与飞书客户端耦合较深，脱离飞书后不能独立完成登录。

判断环境时不要只看“页面是不是 Web 技术写的”。Electron 的页面也是 HTML、JavaScript，但它不是飞书提供的 H5 容器，因此不会凭空拥有tt.requestAuthCode。

方案三：普通 Web 网站的 OAuth 登录

普通 Web 网站同样适合使用标准 OAuth 授权码模式。它与桌面客户端方案的前半段基本一致，区别主要出现在授权完成之后。

Web 页面请求授权地址 ↓ 浏览器进入飞书授权页 ↓ 飞书回调业务服务端 ↓ 服务端校验用户并建立登录会话 ↓ 服务端重定向到 Web 首页

对于传统 Web 系统，登录状态可以放在安全的 HttpOnly Cookie 中；对于前后端分离系统，也可以让回调页携带一次性 Ticket，再由前端兑换 Token。

不建议把长期 Access Token 直接放在 URL 查询参数中。除了浏览器历史记录，页面引用的第三方资源还可能通过 Referer 等途径造成信息泄露。

优点

• OAuth 是标准流程，浏览器兼容性好。
• 不要求用户安装飞书客户端。
• 服务端用户匹配逻辑可以和桌面端共用。
• 适合后台管理系统、企业门户和 SaaS Web 应用。

缺点

• 需要处理重定向地址、Cookie、CSRF 和跨域问题。
• 登录完成后只建立当前浏览器会话，不能自动把结果交给另一个桌面应用。
• 前后端域名配置不一致时，容易出现回调成功但前端仍然未登录的情况。

方案四：在 Electron 内嵌授权页面

有些产品不希望登录时跳出客户端，于是考虑使用 ElectronBrowserWindow或 WebView 打开飞书授权页。

从协议上看，它仍然是标准 OAuth，只是把系统浏览器换成了应用内嵌浏览器。实现上没有解决服务端校验问题，App Secret 依旧必须放在后端。

优点

• 用户视觉上没有离开当前应用。
• 窗口样式和关闭逻辑可以由客户端控制。

缺点

• 内嵌浏览器通常不共享系统浏览器 Cookie，用户可能还要重新登录。
• 用户难以确认当前登录页面是否真的是飞书官方页面。
• WebView 的 Cookie、重定向、窗口生命周期和安全策略都需要额外处理。
• 身份平台可能限制或调整嵌入式浏览器的登录行为。
• 页面注入、导航劫持带来的风险高于系统浏览器。

除非产品有非常明确的交互要求，并且团队有能力长期维护嵌入式浏览器的安全，否则不建议把它作为默认登录方式。

方案五：Android、iOS 原生授权 SDK

原生移动应用可以在开放平台启用对应的移动应用登录能力，并接入飞书授权登录 SDK。应用调用 SDK 后拉起飞书，用户确认授权，SDK 再把临时凭证返回给移动应用。具体支持的平台版本、应用签名配置以及未安装飞书时的行为，应以接入时的官方 SDK 文档和实机测试为准。

移动 App 调用飞书授权 SDK ↓ 拉起飞书 App，由用户确认授权 ↓ SDK 返回临时 code ↓ 移动 App 将 code 交给业务服务端 ↓ 服务端校验身份并签发业务 Token

优点

• 符合移动端使用习惯，App 间跳转比浏览器跳转自然。
• 可以利用手机上已经登录的飞书账号。
• 授权交互由飞书 SDK 处理。

缺点

• Android 和 iOS 需要分别接入和测试。
• 通常要配置包名、应用签名、Universal Link 等平台信息。
• 如果产品要求覆盖未安装飞书的用户，需要根据 SDK 当前行为设计并验证网页授权等降级方案。
• 不能直接用于 Windows Electron 客户端。

方案六：二维码扫码登录

二维码登录适合公共电脑、大屏终端或者不方便在电脑上登录飞书的场景。

二维码本身不具备认证能力。可落地的方式一般有两类：使用飞书当前正式提供的 OAuth 二维码能力；或者让二维码指向一个登录落地页，扫码后仍然执行标准 OAuth。确认完成后，桌面端再通过轮询、WebSocket 或服务端推送取得与当前会话绑定的结果。

不能只生成一个自定义二维码，然后假设“用飞书扫码”就会自动得到飞书用户身份。接入前还要确认所参考的二维码 SDK 或接口不是已经废弃的历史版本。

优点

• 用户不需要在电脑上输入飞书密码。
• 适合共享设备和临时终端。
• 不依赖电脑浏览器中是否已经登录飞书。

缺点

• 必须额外使用手机。
• 要处理二维码过期、重复扫码、会话绑定、轮询和重放攻击。
• 整体实现复杂度明显高于浏览器 OAuth。
• 飞书相关接口存在版本演进，接入前要确认当前开放平台提供的正式能力，不要直接照搬旧版二维码登录示例。

它更适合作为补充入口，而不是企业桌面客户端的首选登录方式。

常见的几个坑

1. 把通讯录权限和登录权限混为一谈

通讯录同步、用户登录和事件回调是三套不同的能力。

• 通讯录同步通常使用应用身份访问部门和员工数据。
• 用户登录使用用户授权码确认当前操作人身份。
• 事件回调用于接收部门变更、员工变更等通知。

通讯录权限审批通过，不代表 OAuth 登录配置一定正确；OAuth 登录成功，也不代表应用可以读取整个组织通讯录。

2. App ID、App Secret 配好，不等于能读取整个组织

App ID 和 App Secret 只能证明“这是哪个应用”。应用究竟能读取哪些部门和员工，还取决于：

• 应用申请了哪些通讯录权限。
• 权限是否已经审批并发布生效。
• 应用的通讯录可见范围是不是整个组织。
• 当前企业管理员是否限制了部门访问范围。

出现no dept authority一类错误时，重点应检查通讯录可见范围，而不只是看 API 权限列表。

3. 重定向 URL 必须完全一致

协议、域名、端口、路径甚至结尾斜杠都可能影响校验。例如下面两个地址并不相同：

https://example.com/api/feishu/callback https://example.com/api/feishu/callback/

本地和生产环境应该分别登记准确的回调地址。OAuth 回调本质上是飞书让用户浏览器跳转到redirect_uri：本机开发时可以使用127.0.0.1，它指向正在操作浏览器的那台电脑；生产方案如果由后端处理回调，就应该配置用户浏览器可访问的 HTTPS 服务地址。

4.state不能省略

state不只是一个随便生成的字符串。它至少应该满足：

• 足够随机，不能被猜到。
• 有较短的有效期。
• 使用一次后失效。
• 能和发起登录的客户端、租户或登录上下文对应。

服务端收到回调时必须验证state，否则容易产生登录 CSRF 或账号串联问题。用户拒绝授权时还会返回失败结果，回调页和客户端都应给出可恢复的提示，而不是统一显示“系统异常”。

5. 授权码不能重复使用

OAuthcode通常有效期很短，而且只能兑换一次。刷新回调页面、浏览器重复提交或者服务端重试处理不当，都可能导致“第一次成功，第二次失败”。

回调接口应该做幂等和重放保护，同时避免前端反复加载同一个 callback URL。

6. 不要把飞书 Token 当成业务系统 Token

飞书 Token 用于访问飞书能力，业务 Token 用于访问自己的系统。二者用途和生命周期都不同。

客户端完成飞书认证后，应该拿到业务服务端签发的 Token，而不是长期持有飞书user_access_token。这样权限撤销、租户隔离和本地角色控制都更容易管理。

7. 本地端口被占用与服务端没有直接关系

Electron 客户端可能会启动一个本地 HTTP 服务，用来承载页面、代理接口或接收回调。如果提示某个127.0.0.1端口被占用，这是客户端本地进程或开发服务器的问题，不代表远程认证服务一定不可用。

排查时要分别确认：

• 本地客户端页面是否正常启动。
• 客户端实际请求的是本地 API，还是生产 API。
• 生产 HTTPS 服务是否可访问。
• 飞书回调地址是否指向了正确环境。

8. 浏览器回调成功，不代表客户端已经登录成功

对于桌面 OAuth，至少存在两个阶段：

1. 飞书成功回调业务服务端。
2. 浏览器成功通过自定义协议唤起客户端，客户端再兑换 Ticket。

如果浏览器已经显示成功，但客户端没有反应，应检查自定义协议注册、单实例处理和 Ticket 兑换，而不是继续修改飞书权限。

怎么选

选型时不要只盯着“能不能少弹一个窗口”。身份认证首先要保证凭证不落入不可信环境，其次才是交互体验。

对于独立桌面客户端，系统浏览器 OAuth 看起来多了一次跳转，但它使用成熟的浏览器登录环境，客户端不接触飞书密码，服务端也能完整控制账号绑定和业务 Token 签发。配合严格的state校验、PKCE 或等价的发起端绑定，以及短时一次性 Ticket，通常是安全性、开发成本和用户体验之间更均衡的选择。

如果未来还要提供飞书工作台入口，可以在同一个服务端账号体系上增加 H5 免登，但应把它视为另一种客户端入口，而不是用一套前端认证代码强行兼容所有运行环境。

参考资料

• 飞书网页应用免登概述
• 飞书 OAuth 授权码获取说明
• 飞书 H5 应用介绍
• 飞书客户端内网页应用免登流程
• 飞书 requestAccess API
• 飞书应用类型与能力介绍
• OAuth 2.0 for Native Apps（RFC 8252）