企业专属域名与 IM 集成

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

企业专属域名与 IM 集成

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

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

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

前提条件

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

核心原理

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

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

为什么需要专属域名？

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

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

域名配置方式

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

专属域名

用户匹配策略

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

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

如果平台 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

重要：企业专属域名必须使用 https。平台注入的 cookie 带有 secure: true，如果使用 http 访问，浏览器不会写入该 cookie，扫码登录后会再次回到当前登录页。

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;

    client_max_body_size 1g;

    proxy_pass https://knodo.vip;
}

3. 在 Knodo 中配置企业凭证

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

Knodo 企业微信 SSO 集成配置

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

企业微信同步用户配置提示

同步用户前置条件：企业微信应用的可见范围必须设置为 全部成员，否则在 Knodo 中点击「同步用户」时，会报 企微通讯录权限不足，无法读取通讯录成员。

企业微信同步用户权限不足

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:contact.base:readonly`	读取通讯录组织结构，部门同步必需
获取与发送单聊、群组消息	`im:message`	飞书机器人接收用户消息并回复
以应用的身份发消息	`im:message:send_as_bot`	Knodo 机器人主动发送单聊通知，配置通知时必需
获取用户 userid	`contact:user.employee_id:readonly`	免密登录流程获取用户身份

本次飞书通知新增 im:message:send_as_bot，原有 im:message 仍用于机器人对话，必须保留。完整使用 Knodo 飞书集成时需要同时配置这两项权限。

4. 飞书免登流程

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

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

5. 在 Knodo 中配置企业凭证

在 Knodo 的 组织设置 > SSO 集成 中填写专属域名，切换到飞书标签页，填写企业自建应用的 App ID 和 App Secret 后关联飞书企业。Knodo 会通过飞书接口自动识别企业 Tenant Key 和企业名称，无需手工填写。

同时，请将当前 Knodo 环境的 OAuth 重定向 URL 配置到同一个飞书应用的 安全设置 > 重定向 URL 中：

https://<Knodo访问域名>/api/v1/auth/feishu/callback

组织配置页面会展示当前访问环境生成的完整地址。个人信息绑定飞书账号和通知配置中的“授权关联飞书通知”共用此回调地址；测试、生产或其他域名需要分别配置，且协议、端口和路径必须完全一致。

Knodo 飞书 SSO 集成配置

关联完成后，可在同一页面执行通讯录同步。Knodo 会先读取应用的通讯录授权范围，再同步其中单独授权的成员，以及授权部门和其可见子部门中的成员；应用可用范围只需覆盖希望同步的部门或成员，无需开放给全部员工。

6. 发布生效

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

7. 配置飞书通知

飞书通知复用上述组织企业自建应用，不需要额外配置 notification.feishu.enabled 开关。配置流程如下：

在飞书开放平台进入企业自建应用，在 应用能力 中启用 机器人。
在 权限管理 中开通 以应用的身份发消息（im:message:send_as_bot）。
在应用可用范围中加入需要接收 Knodo 通知的部门或成员，无需开放给全部员工。
创建并发布新的应用版本；如需管理员审批，等待审批通过。
在 Knodo 组织设置 > SSO 集成 > 飞书 中填写 App ID 和 App Secret，完成企业关联。
点击 同步成员。Knodo 会按 union_id、邮箱匹配已有用户，并自动补全 feishuUserId、feishuOpenId、feishuUnionId 和 feishuTenantKey。
用户进入 个人设置 > 通知配置，在聊天通知或任务通知中选择飞书。
点击 发送测试信息。飞书客户端收到测试消息后，配置完成。

飞书通知可用需要同时满足：

当前组织已关联飞书企业，并保存有效的 App ID、App Secret 和 Tenant Key。
应用已启用机器人能力并具备 im:message:send_as_bot 权限。
当前用户已经通过组织成员同步或个人账号绑定获得飞书身份，且用户 Tenant Key 与组织一致。
当前用户已在通知配置中选择飞书渠道。

如果测试发送返回 99991672 Access denied，表示应用尚未获得消息发送权限。请确认已开通 im:message:send_as_bot，并且包含该权限的新版本已经发布和审批生效。

配置汇总

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

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

用户体验

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

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

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

常见问题

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

A：请检查：

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

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

A：请确认：

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

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

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

企业专属域名与 IM 集成

企业专属域名与 IM 集成

前提条件

核心原理

为什么需要专属域名？

域名配置方式

用户匹配策略

钉钉

1. 进入应用管理

2. 配置网页应用地址

3. 开通应用权限

4. 在 Knodo 中配置企业凭证

5. 发布生效

企业微信

1. 进入应用管理

2. 配置应用主页

3. 在 Knodo 中配置企业凭证

4. 保存生效

飞书

1. 进入应用管理

2. 配置网页应用地址

3. 开通应用权限

4. 飞书免登流程

5. 在 Knodo 中配置企业凭证

6. 发布生效

7. 配置飞书通知

配置汇总

用户体验

常见问题

相关文档