企业专属域名与 IM 集成

配置企业专属域名，以及钉钉、企业微信、飞书的免密登录、企业关联、用户同步和通知渠道

企业专属域名与 IM 集成

企业成员在钉钉、企业微信、飞书的工作台中打开 Knodo 时，可以自动完成身份认证，无需手动输入账号密码或扫码。本文介绍如何在各 IM 平台的开放平台中配置应用，并在 Knodo 中完成企业关联、凭证配置和通讯录用户同步。

Knodo 的 IM SSO 集成同时承担四类能力：工作台免密登录、企业关联、通讯录用户同步、各 IM 通知渠道。

能力钉钉飞书企业微信
企业关联支持支持支持
工作台免密登录支持支持支持
组织级应用凭证支持支持支持
通讯录主动拉取支持支持支持
平台 ID / 邮箱 / 手机号用户匹配支持支持支持
通知渠道支持支持支持

前提条件

  • 拥有对应 IM 平台的企业管理员权限
  • 已在 IM 开放平台创建企业自建应用
  • Knodo 实例已部署并可从公网访问
  • 已在 Knodo 中为组织配置了企业专属域名（见下方说明）

核心原理

工作台免密登录的核心在于企业专属域名 + IM 集成凭证：

  1. 管理员在 Knodo 中为组织配置一个企业专属域名（如 acme.knodo.vip），并将该域名的 DNS 解析指向 Knodo 服务
  2. 同时在组织设置中配置对应 IM 平台的集成凭证（AppKey/AppSecret 等）
  3. 当企业成员通过 IM 工作台打开应用，或通过专属域名访问 Knodo 时，系统根据请求域名自动识别所属组织，并使用该组织配置的 IM 凭证完成身份认证
  4. 登录完成后，系统自动将用户加入对应的企业组织

为什么需要专属域名？

Knodo 是多租户 SaaS 平台，不同企业使用不同的 IM 凭证（不同的 AppKey、CorpId、Secret 等）。系统通过请求域名来判断当前用户属于哪个企业，从而选择正确的凭证进行认证。

如果没有配置专属域名，系统将无法区分不同企业的用户，可能导致登录失败或用户被分配到错误的组织。

域名配置方式

在 Knodo 的 组织设置 中，填写组织的专属域名（如 acme.knodo.vip），然后将该域名的 DNS CNAME 记录指向 Knodo 服务地址。配置完成后，所有通过该域名的请求都会自动路由到对应组织的 IM 凭证。

专属域名

用户匹配策略

配置应用凭证后，用户用某种 IM 方式登录（如扫码或工作台登录）时，系统会尝试拉取该用户在对应 IM 系统下的用户信息（需要对应权限），再比对 Knodo 系统下的用户信息，并按以下优先级短路匹配系统用户：

  1. 平台 ID 匹配：已通过该 IM 登录过的用户，例如 unionId、userid 或 tenant_key 关联用户
  2. 邮箱匹配：通过邮箱注册的存量用户，自动补全 IM 身份信息
  3. 手机号匹配：平台 ID 和邮箱均未命中时，使用平台返回的可用手机号匹配已有用户
  4. 未匹配：自动创建新账号

如果平台 ID 或邮箱已命中用户，系统不会继续用手机号改变账号归属。手机号仅在更高优先级标识均未命中时参与匹配。中国大陆 11 位手机号会按 +86 前缀规范化后保存和匹配，E.164 国际号码按原格式保存；手机号为空或格式不可用时，不影响既有平台 ID 和邮箱匹配逻辑。

钉钉、飞书、企业微信等 IM 登录在可获得手机号时，会像处理邮箱一样尝试保存到用户资料，但不得覆盖其他用户已占用的手机号。手机号无法获取、为空或已被其他用户占用时，系统保留当前登录结果，不会自动迁移、抢占或合并账号。

无论匹配或不匹配都会将该用户自动加入到该组织，如果组织打开了”允许 SSO 用户自动加入“，那就自动加入不需要审批，如果是关闭，那就需要管理员审批

允许 SSO 用户自动加入

关闭自动加入后，管理员可以在成员列表中选择待处理成员，将其设为已通过或设为已禁用。

SSO 用户审批

钉钉

1. 进入应用管理

登录 钉钉开放平台，进入您的企业自建应用。

2. 配置网页应用地址

在左侧菜单选择 应用能力 > 网页应用，编辑网页应用配置：

  • PC 端首页地址：https://acme.knodo.vip/workspaces
  • 移动端首页地址：https://acme.knodo.vip/workspaces

将 acme.knodo.vip 替换为您的企业专属域名。

钉钉网页应用配置

在左侧菜单选择 开发配置 > 安全设置，将企业专属域名加入 重定向 URL（回调域名），否则钉钉扫码二维码可能无法加载，或扫码后提示应用/回调地址异常。

钉钉安全设置回调域名

3. 开通应用权限

如果需要通过钉钉向用户发送通知调试消息、任务提醒或 Bot 主动推送消息，还需要在同一个钉钉应用中添加 机器人 能力。Knodo 会将该应用的 AppKey 作为钉钉 OpenAPI 的 robotCode 使用；如果 AppKey 对应的应用没有机器人能力，发送单聊消息时会出现 robotCode.notExsit。

在左侧菜单选择 应用能力 > 添加应用能力 > 机器人，点击「配置」并启用机器人能力。

钉钉添加机器人能力

在左侧菜单选择 权限管理，确保以下权限已申请并授权：

权限名称用途
通讯录个人信息读权限读取用户姓名、头像等基本信息
邮箱等个人信息读取用户个人邮箱和企业邮箱
通讯录部门信息读权限获取部门列表用于用户同步
成员信息读权限读取部门成员列表
通讯录部门成员读权限读取部门下的用户信息
通讯录组织基础信息读权限获取企业基本信息
企业内机器人发消息权限（企业内机器人发送消息权限）Bot 机器人推送消息
获取钉钉开放接口用户访问凭证的基础权限OAuth 登录流程
企业微应用后台免登接口的访问权限JSAPI 免密登录

以上权限为免密登录、用户同步和机器人消息推送的必要权限。缺少通讯录权限可能导致登录失败或用户信息不完整（如邮箱为空）；缺少机器人能力或机器人发消息权限会导致通知调试、任务提醒等主动推送失败。

4. 在 Knodo 中配置企业凭证

在 Knodo 的 组织设置 > SSO 集成 中填写专属域名，切换到 钉钉 标签页，填写企业 ID、企业名称、AppKey 和 AppSecret 后关联钉钉企业。

Knodo 钉钉 SSO 集成配置

如果还需要让 AI 助手在钉钉群聊或单聊中回复用户，请继续参考 IM 机器人集成。

5. 发布生效

配置完成后需要发布新版本，修改才能生效。

企业微信

1. 进入应用管理

登录 企业微信管理后台，进入 应用管理 > 自建应用。

2. 配置应用主页

点击应用主页旁的「设置」，配置从工作台点击进入的网页地址：

  • 应用主页桌面端：https://acme.knodo.vip/workspaces
  • 应用主页移动端：https://acme.knodo.vip/workspaces

将 acme.knodo.vip 替换为您的企业专属域名。

注意：企业微信对应用主页域名有严格限制，要求必须与企业在企微后台备案的域名保持一致。请确保将以下截图中的所有域名替换为您的企业专属域名。：

企业微信应用主页配置

设置开发者接口，确保 网页授权及 JS-SDK、企业微信授权登录 已启用，并按实际部署情况配置 企业可信 IP。

企业微信开发者接口

企业微信应用主页配置

企业微信应用主页配置

企业微信企业可信 IP

专属域名解析到自有公网 IP，由 Web 代理（如 Nginx）反向代理到 knodo.vip

location / { proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; proxy_set_header Connection ""; proxy_read_timeout 1800s; proxy_connect_timeout 30s; proxy_send_timeout 1800s; proxy_buffering off; proxy_cache off; proxy_pass https://knodo.vip; }

3. 在 Knodo 中配置企业凭证

在 Knodo 的 组织设置 > SSO 集成 中填写专属域名，切换到 企业微信 标签页，填写企业 ID、企业名称、AgentId 和 Secret 后关联企业微信。

Knodo 企业微信 SSO 集成配置

关联完成后，可在同一页面执行通讯录同步。

4. 保存生效

配置保存后即时生效，无需额外发布。

飞书

1. 进入应用管理

登录 飞书开放平台，进入您的企业自建应用。

2. 配置网页应用地址

在左侧菜单选择 应用能力 > 网页应用，编辑网页应用配置：

  • 桌面端主页：https://acme.knodo.vip/workspaces
  • 移动端主页：https://acme.knodo.vip/workspaces

将 acme.knodo.vip 替换为您的企业专属域名。

飞书网页应用配置

在左侧菜单选择 开发配置 > 安全设置，补充以下域名安全配置，否则飞书免登授权码可能无法回跳，或 JSAPI 在工作台内无法正常调用：

  • 重定向 URL：添加 https://acme.knodo.vip/login 和 https://acme.knodo.vip/api/v1/auth/feishu/callback
  • H5 可信域名：添加 https://acme.knodo.vip

将 acme.knodo.vip 替换为您的企业专属域名。如果使用 Knodo 默认域名，也需要把对应默认域名加入同一配置。

飞书安全设置

3. 开通应用权限

在左侧菜单选择 权限管理，确保以下权限已申请并授权：

权限名称权限标识用途
获取用户基本信息contact:user.base:readonly免密登录获取用户姓名、头像等
获取用户邮箱contact:user.email:readonly读取用户邮箱用于账号匹配
获取部门列表contact:department.base:readonly获取部门列表用于用户同步
获取部门成员列表contact:department.member:readonly读取部门下的用户信息
获取通讯录基本信息contact:department.base:readonly获取企业组织基本信息
获取与发送单聊、群组消息im:message机器人发送和回复消息
以应用的身份发消息im:message:send_as_botBot 机器人主动推送消息
获取用户 useridcontact:user.employee_id:readonly免密登录流程获取用户身份

以上权限为免密登录、用户同步和机器人消息的必要权限，缺少任一权限可能导致登录失败或功能异常。

4. 飞书免登流程

飞书的租户标识（tenant_key）通过 OAuth 服务端流程获取：

  1. 飞书客户端自动调用 JS-SDK 获取免登授权码
  2. Knodo 后端用授权码换取 user_access_token，响应中包含 tenant_key
  3. 后端根据 tenant_key 自动关联企业组织

5. 在 Knodo 中配置企业凭证

在 Knodo 的 组织设置 > SSO 集成 中填写专属域名，切换到 飞书 标签页，填写企业 Tenant Key、企业名称、App ID 和 App Secret 后关联飞书企业。

Knodo 飞书 SSO 集成配置

关联完成后，可在同一页面执行通讯录同步。

6. 发布生效

配置完成后需要创建新版本并发布，修改才能生效。

配置汇总

IM 平台首页地址格式组织识别方式域名反查兜底
钉钉https://acme.knodo.vip/workspaces企业专属域名 + IM 集成凭证是
企业微信https://acme.knodo.vip/workspaces企业专属域名 + IM 集成凭证是
飞书https://acme.knodo.vip/workspaces服务端 OAuth 获取 tenant_key + 域名反查是

所有 IM 平台均支持通过企业专属域名自动识别组织并查找对应凭证，确保多租户场景下的登录正确性。

用户体验

配置完成后，企业成员的登录体验：

  1. 在 IM 工作台点击 Knodo 应用图标
  2. 系统通过请求域名自动识别企业身份
  3. 自动完成身份认证（无需手动操作）
  4. 若平台 ID、邮箱和手机号均未命中，首次登录自动创建账号并加入企业组织
  5. 直接进入工作空间页面

整个过程对用户完全透明，实现真正的「一键直达」。

常见问题

Q：免密登录报错「当前域名未关联企微组织」？

A：请检查：

  • 组织是否已配置专属域名
  • DNS 解析是否正确指向 Knodo 服务
  • 域名是否与组织设置中填写的一致（不含端口号）

Q：免密登录后没有自动加入企业组织？

A：请确认：

  • Knodo 组织设置中已配置专属域名
  • Knodo 组织设置中已配置对应 IM 平台的集成凭证
  • 专属域名已正确解析到 Knodo 服务

Q：多个企业共用一个 Knodo 实例，如何区分？

A：每个企业配置独立的专属域名（如 acme.knodo.vip、beta.knodo.vip），系统根据请求域名自动路由到对应组织的 IM 凭证。

相关文档