飞书登录与 SSO 接入 接入手册ai.njwl.ai/guide/auth/ · 维护者 ben22

新应用接入 SSO，默认增加身份水印

后续开发的新网站、新应用，接入 SSO 时同时接入统一身份水印，无需逐个询问。每页只保留一层，沿用电芯平台的公司名、登录姓名与时间样式。

身份水印接入规范、模板与验收清单

SSO 登记本身不会自动安装水印；开发时须完成组件、页面路径和已验证身份接口的适配，并核验登录、换号、移动端和弹窗。

2026-09-11：CRM（njwl.ai/crm/）已将登录授权与身份兑换切换到 auth.any-g.cn；已验证匿名访问拒绝、SSO 跳转及回调参数，真实用户重新登录和业务资料验收待本人完成。既有 CRM 会话保留；其他业务站未切换。管理台当前不提供大陆 CRM 的新登录开关。

大陆飞书认证进度 · 2026-09-11

auth.any-g.cn 已启用飞书登录，沿用香港现有飞书应用；凭证接口验证通过，授权跳转回调确认为 https://auth.any-g.cn/auth/callback。已登记现有 8 个 SSO 客户端的精确回调。

登录页及 AI 接入设置页保留闽ICP备2026033672号、闽公网安备35020602003907号与官方链接。未迁移香港会话、用户数据库或管理员名单，未切换各业务站的认证地址。真实用户扫码、身份核对与逐站授权链路仍需验收；管理台新登录开关当前仍作用于香港认证中心。

登录管理表格 · 视图与权限编辑

统一登录管理中的应用清单、人员、认证会话、登录历史、访问记录与操作记录，按 表格交互模组 使用紧凑单行、内容适配列宽、细线分隔和工业红选中状态。窄屏仅表格横向滚动，双击或键盘 Enter 可查看截断字段的完整内容。

支持搜索、按列多选筛选与未设置、多重排序、自定义值顺序、列拖拽和上下移动。排序条与列位置独立；启用分组时，前两项适合分类的排序字段形成最多两级分组，姓名和时间等字段不生成无意义分组。计数仅代表本次载入及筛选的记录范围。

只有人员权限字段可双击编辑；Enter 保存、Escape 取消，也可通过管理权限按钮打开完整表单。保存调用原有后台权限接口并检查版本；失败保留草稿。权限限制仅影响新登录，业务会话不自动退出。历史和访问记录保持只读，不提供新增、修改或删除记录入口。

页面和标签页、搜索筛选、排序及自定义顺序、列位置、横向滚动位置，按已登录账号保存在管理服务受保护的视图文件中；不将姓名和 IP 筛选值明文写入浏览器公共缓存。恢复默认只重置视图，不修改业务数据。应用清单导出采用当前筛选和排序结果。

按应用管理登录人员与记录

打开 统一登录管理台 → 应用接入 → 管理，可查看登录人员、登录历史、访问记录和接入配置。人员来自当前认证中心的已知用户；没有本应用成功授权记录的人员会明确标注。允许、禁止或恢复默认仅修改选中应用的新登录规则，不能覆盖认证中心停用、应用暂停或业务内部权限，也不结束已有业务会话。

最近授权时间和授权次数表示认证活动。中心会话有效不等于用户正在浏览应用，业务会话和实时在线状态尚未汇总。新授权记录保存浏览器发起授权时的 IP 和固定的授权目标页面；旧记录缺失字段不补填。

访问记录从 2026-09-11 起采集已接入香港网关的应用根页面与 index.html 页面加载，包括时间、IP、路径和响应状态。仅 GET/HEAD 且接受 HTML 的请求进入独立日志；不采集查询参数、Cookie、认证码、客户内容、API 或页内路由。日志按日或 5 MB 轮换，最多保留 14 份；页面只显示当前日志末尾 2 MB 中所选应用最近 200 条。请求暂未关联用户身份，不能按 IP 猜测人员。cell.njwl.ai 的独立大陆入口尚未接入该采集。

后台管理员校验保留；移除页面上的指定姓名管理提示不会扩大权限。独立飞书或账号密码应用的人员权限仍由应用自身管理。

登录用户、认证会话与人员权限

在 统一登录管理台 打开“登录与人员”，选择大陆或香港认证中心。仅指定管理员可查看登录用户、有效认证会话和新记录，保存人员的新登录状态及按 SSO 应用的允许/禁止规则。

规则按认证中心分别保存，未配置规则沿用原访问范围。限制在认证登录、SSO 授权和令牌兑换处检查；允许不绕过业务网站的权限或应用暂停设置。不能停用唯一管理员的管理台访问。独立飞书/账号密码旧应用尚不受该规则控制。

撤销单条或某人全部认证会话，只撤销所选认证中心的会话，不退出业务网站已有会话。旧记录未保存的登录时间显示“未记录”，不推算补填。自 2026-09-11 功能上线后开始记录新登录、应用授权与管理操作，保留最近90天且最多5000条，页面展示最近200条。管理凭证只保存在服务器，不返回给浏览器。

CRM 大陆登录已由本人确认正常；CRM 业务会话的即时撤销未接入。

可视化管理台

打开统一登录管理台（仅限平台管理员）。查看已登记 SSO 应用与已核对独立登录入口，保存负责人和迁移记录，暂停或恢复指定 SSO 应用的新登录。

新登录开关实时作用于香港认证中心，不撤销业务站已有会话。迁移阶段仅为协作记录，不会自动把认证中心切换到 auth.any-g.cn。管理数据在独立服务中保存，发布业务网站时应保留现有认证入口。

更新：2026-09-11。

先选对接入方式

截至 2026-09-10，不能只将现有业务站的认证地址改为 auth.any-g.cn 就视为迁移完成。大陆与香港的数据库、会话和配置独立，迁移需先完成身份关联与全链路验证。

飞书应用后台如何配置

这一节供维护认证中心时使用。普通业务网站只需完成下一节的 SSO 接入。

1. 在飞书开发者后台创建或进入专用的企业自建认证应用，添加网页应用能力。
2. 网页主页填写认证中心地址。当前桌面端与移动端可填 https://auth.njwl.ai/。
3. 安全设置 → 重定向 URL：填写 https://auth.njwl.ai/auth/callback。这必须与服务端生成的完整地址一致；不逐个填写业务页面。
4. 核对用户身份权限。当前授权请求使用 auth:user.id:read；按平台当前权限管理项核对，不为纯认证额外开放多维表格或消息权限。
5. 设置应用可用范围，创建版本并发布；先用指定测试账号验证，再扩大范围。
6. 将 App ID、App Secret 写入认证服务器 .env，禁止放进前端、URL、Git 或交接文档。

现有香港服务配置位置：/home/ubuntu/njwl-auth/.env；修改后在该目录运行 sudo docker compose up -d 让配置生效。

FEISHU_APP_ID=实际应用ID
FEISHU_APP_SECRET=实际密钥
FEISHU_LOGIN_ENABLED=true
PUBLIC_BASE_URL=https://auth.njwl.ai
SESSION_SECRET=服务器生成并保留的独立随机密钥

原湿度应用 /home/ubuntu/shidu/.env 是另一份配置，不要改错。App Secret 不能当作网站登录 Cookie 或 Agent 凭证使用。

未来启用大陆飞书入口时，需要新增 https://auth.any-g.cn/auth/callback，配置大陆服务对应凭证和身份映射。大陆目录为 /home/ubuntu/apps/anyg-auth，服务为 anyg-auth；2026-09-11 已启用，后续需完成真实扫码和业务站迁移验收。

飞书官方授权码接口 · 飞书官方 Web 应用接入指南

业务网站接入 SSO

1. 登记业务网站

先向认证中心登记唯一 client_id 与完整 HTTPS 回调地址。当前登记表在香港服务 /home/ubuntu/njwl-auth/sso.py 的 CLIENTS 中；修改前读取最新文件，追加客户端，不覆盖其他登记项，完成后重建认证服务。

# 示例，按实际网站替换；此示例未登记
'example': 'https://你的业务域名/auth/callback'

回调必须精确匹配已登记值。不使用任意域名、通配符或用户传入的任意 URL。

2. 在业务后端创建登录事务

生成随机 state 和 PKCE code_verifier，保存在业务后端的短期登录事务中，并绑定当前浏览器。保存原页面的站内相对路径；禁止直接信任外部 returnTo。

• state：当前实现接受 32–128 位 URL 安全字符。
• code_verifier：43–128 位随机字符，保留在业务后端。
• code_challenge：对 code_verifier 求 SHA-256，再作不带等号填充的 Base64URL 编码；长度43。

3. 跳转或弹窗打开认证中心

GET https://auth.njwl.ai/sso/authorize
  ?client_id=已登记的客户端ID
  &redirect_uri=URL编码后的完整业务回调地址
  &state=本次随机值
  &code_challenge=本次PKCE摘要
  &code_challenge_method=S256

认证中心已有有效会话时可直接继续；没有会话时进入飞书登录。完成后回到业务回调，携带 code 和原 state。当前代码登录事务有效期10分钟，授权码有效期60秒且只能使用一次。

4. 业务后端验证并兑换授权码

先检查回调 state 与原登录事务一致、事务未过期，再由后端调用以下接口。不要让前端自行认定授权成功。

POST https://auth.njwl.ai/sso/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "client_id": "已登记的客户端ID",
  "redirect_uri": "已登记的完整回调地址",
  "code": "回调收到的短期授权码",
  "code_verifier": "业务后端保存的原始随机值"
}

成功返回用户身份及 expires_in；目前身份字段包含 open_id、user_id、name、tenant_key。使用稳定的身份标识映射本站用户，不能按相同姓名合并账号。失败时显示重新登录入口，不循环兑换同一个授权码。

5. 建立本站会话并回原页面

业务后端创建独立会话，Cookie 使用 Secure、HttpOnly、适当的 SameSite 与路径范围；检查用户访问权限后回到原先保存的站内页面。当前认证中心会话为8小时，业务站应明确自己的有效期与撤销策略。

各域名不能直接共享 Cookie。一次性授权码只是交接身份的票据，不代表用户每打开一页就要重新扫码。

毛玻璃和登录弹窗怎么接

1. 未登录时只返回公开预览、骨架或模糊背景，不提前下发完整正文。
2. 由用户点击登录按钮打开认证窗口，减少浏览器拦截；手机或弹窗受限时降级为整页跳转。
3. 业务回调后端先完成授权码兑换并建立本站会话，再由本站回调页面通知 opener。
4. 通知必须指定精确 targetOrigin；原页面检查 event.origin、event.source 和本次事务标记，不传递飞书访问令牌。
5. 原页面再次向本站后端检查会话，确认成功后加载正文并关闭弹窗；取消授权时保持预览。

这是各业务网站需要实现的交互。仅添加登录按钮或 CSS 模糊不能保护数据；页面、接口和文件下载都必须校验权限。

退出 权限和机器访问

• 本站退出须撤销本站后端会话，不能只清除前端显示；全站退出需要单独实现跨站撤销，不是当前认证接口自动提供的能力。
• 飞书登录成功不等于管理员权限。限定企业与人员范围；成员停用后的访问撤销需另行接入与验证。
• AI Agent 使用专用凭证，见 AI 接入设置。不要共享人的登录 Cookie，也不要按 User-Agent 字符串无条件放行。
• 网站接入网关后仍须限制直接访问源站，避免绕过认证。

大陆部署必须保留双备案信息

any-g.cn 本次备案覆盖的大陆页面均保留 闽ICP备2026033672号 和 闽公网安备35020602003907号，各自链接官方查询页，登录前可见。部署地址和可复制页脚见 大陆部署与备案标注。其他独立域名使用其对应备案信息。

上线验收与常见问题

• 未登录直接访问正文、API和下载地址均不能获取受保护数据。
• 真实飞书扫码成功，返回原页面；姓名和身份映射正确。
• 已有认证会话进入新站，仍要建立该站会话，不需要重复扫码。
• 错误 state、错误 PKCE、过期或重复授权码、未登记回调均被拒绝。
• 验证拒绝授权、弹窗关闭、移动端跳转、退出后再访问。
• 授权后403：检查业务权限、企业限制与管理员资格；不要直接取消权限检查。
• 回调报错或循环登录：核对完整回调地址、Cookie 域/路径、HTTPS与反向代理 Host。
• 修改 .env 后没变化：确认目标服务器与服务正确，并重建/重启相应服务。