• 简体中文

      • 认证:飞书 / Lark

      飞书 / Lark专业版+

      介绍

      飞书 / Lark 插件支持用户使用飞书或 Lark 账号登录 NocoBase,并可开启免密自动登录。

      激活插件

      飞书 / Lark 为商业插件,需要在插件管理器中安装并启用,同时需要启用 用户认证 插件。

      在飞书开放平台创建应用

      进入飞书开放平台开发者后台,创建一个 企业自建应用(Lark 海外版请使用 Lark 开放平台),记录 App ID 和 App Secret。

      登录无需额外开通接口权限;如需通讯录同步,参考从飞书同步用户数据。

      配置重定向 URL

      在应用的 安全设置 → 重定向 URL 中,添加 NocoBase 显示的回调地址。地址格式:

      https://你的域名/api/feishu:redirect

      最简单的方式:在 NocoBase 认证器配置页复制 重定向 URL 字段显示的完整地址填入,避免手写出错。

      Warning

      如果 NocoBase 部署在子路径下(如配置了 APP_PUBLIC_PATH=/nocobase/),回调地址会带上前缀,如 https://你的域名/nocobase/api/feishu:redirect。飞书开放平台白名单中的地址必须与实际地址完全一致,升级部署方式后记得同步更新。

      在 NocoBase 上添加飞书认证

      进入 用户认证 管理页面,添加 飞书 / Lark 认证器,配置以下字段:

      字段说明
      自动注册用户首次登录不存在时自动创建账号,默认开启。
      区域飞书中国 或 Lark Global,与实际使用的开放平台一致。
      App ID飞书应用的 App ID,支持使用环境变量和密钥。
      App Secret飞书应用的 App Secret,支持使用环境变量和密钥。
      Origin站点对外访问地址,如 https://example.com。只填协议和域名,不要带路径(末尾斜杠可带可不带);留空时自动使用当前请求地址。
      用户唯一标识字段用户身份的唯一标识,见下文说明。
      自动登录在飞书内打开应用时免密登录,见下文说明。

      选择用户唯一标识字段

      字段说明
      union_id推荐。同一开发者账号下所有应用共享且稳定,后续扩展新应用时用户身份不变。
      open_id每个应用独立,更换应用后标识会变。
      user_id企业租户内唯一,多租户场景可能冲突。
      mobile / email用户可修改、可为空,不适合作为唯一标识。

      首次登录产生用户后,应保持该选项稳定;如同时使用用户数据同步,同步来源中请选择相同字段。

      登录与自动注册

      用户在登录页点击 飞书 / Lark 按钮,跳转飞书授权页完成登录。开启自动注册时:

      • 按 用户唯一标识字段 查找或创建用户;
      • 手机号、邮箱、昵称仅在用户资料为空时补写,不会覆盖已有资料。

      自动登录(免密)

      开启 自动登录 后,用户在飞书客户端内打开应用时自动发起 OAuth 登录,无需手动点击登录按钮。同一时刻只允许一个飞书认证器开启自动登录。

      使用条件:

      • 飞书开放平台 重定向 URL 白名单已包含回调地址;
      • 应用已发布,且用户在应用的可用范围内;
      • 从飞书客户端内打开应用。

      首次使用会出现一次飞书授权确认页,确认后后续进入均为静默免密。在系统浏览器中打开不会触发自动登录,属于预期行为。

      飞书工作台入口(可选)

      在飞书开放平台 应用功能 → 网页 中配置桌面端 / 移动端主页地址,用户即可从飞书工作台直接进入 NocoBase。地址需与 NocoBase 实际访问地址一致(子路径部署时包含前缀)。