IM 工作台免密登录

配置钉钉、企业微信、飞书工作台免密登录，让企业成员在 IM 客户端内一键访问 Knodo

IM 工作台免密登录

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

前提条件

拥有对应 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 凭证。

专属域名

钉钉

1. 进入应用管理

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

2. 配置网页应用地址

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

PC 端首页地址：https://acme.knodo.vip/bots?corpId=$CORPID$
移动端首页地址：https://acme.knodo.vip/workspaces?corpId=$CORPID$

将 acme.knodo.vip 替换为您的企业专属域名。 $CORPID$ 占位符由钉钉客户端自动替换为真实 corpId。

钉钉网页应用配置

3. 开通应用权限

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

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

以上权限为免密登录和用户同步的必要权限，缺少任一权限可能导致登录失败或用户信息不完整（如邮箱为空）。

4. 在 Knodo 中配置企业凭证

在 Knodo 的 组织设置 > 钉钉集成 中：

填写组织的专属域名（如 acme.knodo.vip）
关联钉钉企业并填写 AppKey 和 AppSecret
配置 DNS 解析，将专属域名指向 Knodo 服务

详见 IM 集成与用户同步。

5. 发布生效

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

企业微信

1. 进入应用管理

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

2. 配置应用主页

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

应用主页桌面端：https://acme.knodo.vip/workspaces?corpId=$CORPID$
应用主页移动端：https://acme.knodo.vip/bots?corpId=$CORPID$

将 acme.knodo.vip 替换为您的企业专属域名。 $CORPID$ 占位符由企业微信客户端自动替换为真实 corpId。

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

企业微信应用主页配置

专属域名解析到自有公网 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 的 组织设置 > 企业微信集成 中：

填写组织的专属域名（如 acme.knodo.vip）
关联企微企业并填写 CorpId、AgentId 和 Secret
配置 DNS 解析，将专属域名指向 Knodo 服务

详见 IM 集成与用户同步。

4. 保存生效

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

飞书

1. 进入应用管理

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

2. 配置网页应用地址

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

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

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

飞书网页应用配置

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_bot`	Bot 机器人主动推送消息
获取用户 userid	`contact:user.employee_id:readonly`	免密登录流程获取用户身份

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

4. 与钉钉/企微的区别

飞书不支持 $CORPID$ 占位符机制，也没有类似 dd.corpId 的客户端属性。飞书的租户标识（tenant_key）通过 OAuth 服务端流程获取：

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

因此飞书的应用首页地址无需添加 $CORPID$ 参数。

5. 在 Knodo 中配置企业凭证

在 Knodo 的 组织设置 > 飞书集成 中：

填写组织的专属域名（如 acme.knodo.vip）
关联飞书企业并填写 App ID 和 App Secret
配置 DNS 解析，将专属域名指向 Knodo 服务

详见 IM 集成与用户同步。

6. 发布生效

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

配置汇总

IM 平台	首页地址格式	corpId 获取方式	需要 $CORPID$	域名反查兜底
钉钉	`https://acme.knodo.vip/workspaces?corpId=$CORPID$`	`dd.corpId` + URL 参数 + 域名反查	是	是
企业微信	`https://acme.knodo.vip/workspaces?corpId=$CORPID$`	URL 参数 + sessionStorage + 域名反查	是	是
飞书	`https://acme.knodo.vip/workspaces`	服务端 OAuth 获取 `tenant_key` + 域名反查	否	是

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

用户体验

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

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

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

常见问题

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

A：请检查：

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

Q：配置 $CORPID$ 后打开应用报错「无法获取企业ID」？

A：请检查：

URL 参数名是否为 corpId（注意大小写）
占位符是否为 $CORPID$ （注意是美元符号包裹、全大写）
是否已发布新版本（钉钉和飞书需要发布后生效）

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

A：请确认：

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

Q：飞书为什么不需要 $CORPID$ ？

A：飞书的设计理念不同，租户标识通过服务端 OAuth 流程获取，不依赖客户端 URL 参数。Knodo 后端会在免登流程中自动获取 tenant_key。

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. 发布生效

配置汇总

用户体验

常见问题

相关文档