企业登录、身份与 IM 集成

配置组织专属入口、企业 IM SSO、登录方式和组织成员身份同步

企业登录、身份与 IM 集成

“登录与身份”用于管理一个组织如何通过专属入口登录，以及钉钉、企业微信、飞书中的企业成员如何与 Knodo 组织成员建立身份关联。

完整的接入顺序如下：

配置组织专属登录地址。
接入至少一个企业 IM 平台并配置完整凭证。
按需开启自定义登录方式，选择可用方式并调整展示顺序。
在对应 IM 平台配置应用主页、回调地址、可信域名和权限。
同步组织成员和部门，批量建立组织成员身份。

一、配置组织专属入口

企业 IM SSO 必须绑定组织专属入口。系统根据用户访问的完整 Origin 确定组织，再使用该组织的钉钉、企业微信或飞书凭证发起认证。

进入 组织设置 > 登录与身份，在“组织入口设置”中填写专属登录地址并保存。

未开启自定义登录的组织入口设置

专属登录地址必须满足以下要求：

使用完整的 HTTPS Origin，例如 https://acme.knodo.vip 或 https://knodo.example.com:9000。
只能包含协议、域名和可选端口，不能包含路径、查询参数或片段。
每个专属地址只能属于一个有效组织。
默认端口会被自动规范化，例如 https://example.com:443 等同于 https://example.com；其他端口会保留并参与组织匹配。

两类专属地址

Knodo 支持两类企业专属地址：

Knodo 泛域名：例如 https://acme.knodo.vip。域名解析和泛域名证书由平台统一维护，通常使用 443 端口。
企业自有备案域名：例如 https://knodo.example.com:9000。企业微信要求应用域名与企业备案域名一致；企业可以使用自有公网入口和非默认端口，再通过 Nginx 代理到 Knodo。

企业自有域名的 Nginx 配置

如果组织使用 Knodo 泛域名（例如 https://acme.knodo.vip），域名解析和泛域名证书由平台统一维护，本节可以跳过，无需自行配置 Nginx。只有使用企业自有备案域名时才需要完成以下配置。

使用企业自有备案域名前，请先联系 Knodo 支持人员，对企业专属域名进行加白。配置完成后，请在浏览器打开企业域名，确认可以通过企业专属域名直接访问 Knodo 官网。

将企业专属域名解析到自有公网 IP，并通过 Nginx 反向代理到 knodo.vip：

以下配置仅为示例，请根据企业自身的域名、端口、证书路径和企微校验文件等实际情况修改。

server {
    listen 80;
    listen [::]:80;
    server_name your-company-domain.com;

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 9000 ssl http2;
    listen [::]:9000 ssl http2;
    server_name your-company-domain.com;

    ssl_certificate     /root/ssl/your-company-domain.com.pem;
    ssl_certificate_key /root/ssl/your-company-domain.com.key;

    # SSL hardening
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # 企微的校验，在企微新建应用的时候那边会提示"配置可信域名需完成域名归属认证"，请点击下载。
    # 将文件名替换下面的your-wework-verify.txt
    # 然后打开获得文件里面的code，替换your-wework-verify-code
    location = /your-wework-verify.txt {
        return 200 "your-wework-verify-code";
        add_header Content-Type text/plain;
    }

    resolver 127.0.0.53 valid=300s;
    resolver_timeout 10s;

    location / {
        # Host 用于兼容现有的专属域名代理链路
        proxy_set_header Host $host;
        # 必须使用 $http_host，保留 :9000 等非默认外部端口
        proxy_set_header X-Forwarded-Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        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;
    }
}

X-Forwarded-Proto 和 X-Forwarded-Host 共同向 Knodo 传递用户实际访问的完整 Origin。不要把 X-Forwarded-Host 配置为 $host，因为 $host 不包含非默认端口；$http_host 会保留客户端请求中的端口。

二、配置专属入口的登录方式

保存专属入口并完成企业平台凭证配置后，可以在“专属入口登录方式”中开启 自定义登录方式。

已开启自定义登录方式和顺序

开启后可以：

启用或隐藏账号、微信、Google、钉钉、飞书和企业微信登录。
调整登录方式的展示顺序。
隐藏部分平台内置登录方式，只保留企业需要的入口。

钉钉、飞书或企业微信只有在该组织已经配置对应平台凭证且当前可用时，才能加入登录方式。至少需要保留一种可用的登录方式，避免组织成员无法登录。

配置的生效范围

组织自定义登录方式只对该组织的专属地址生效：

访问组织专属地址时，登录页完全采用该组织启用的方式和顺序。
访问 knodo.vip 等平台默认地址时，不应用任何组织的自定义策略，只展示平台统一登录方式。
平台默认登录方式通常为账号、微信、Google 和飞书，最终以平台当前启用配置为准。
公共入口的飞书登录使用平台 ISV 应用；组织专属入口的飞书登录使用该组织配置的应用，不会在两者之间回退。

“允许 SSO 用户自动加入”用于控制首次通过企业 SSO 登录的成员是否需要审批：

开启后，验证成功的企业成员会自动加入组织。
关闭后，新成员进入待审批状态，需要管理员在成员列表中处理。

允许 SSO 用户自动加入

SSO 用户审批

三、配置企业 IM 平台

专属入口决定用户属于哪个组织，企业平台凭证决定系统如何完成认证。钉钉、企业微信和飞书需要分别接入，某个平台配置不完整时，该平台不能作为组织登录方式。

钉钉

配置应用地址

登录钉钉开放平台，进入企业自建应用，在 应用能力 > 网页应用 中配置：

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

将示例地址替换为组织的完整专属地址。在 开发配置 > 安全设置 中，将专属地址加入重定向 URL，否则二维码可能无法加载，或扫码后提示回调地址异常。

钉钉工作台打开应用时会把 $CORPID$ 替换为当前企业 ID。Knodo 的 JSAPI 免登会读取 URL 中的 corpId 参数并传给钉钉 SDK；后端会按该值匹配组织配置的钉钉企业 ID，并使用对应组织应用凭证。若该值与专属入口对应组织不一致，或平台通用域名下未找到对应组织，系统会拒绝登录，不会回退到其他组织应用。使用平台通用域名配置钉钉工作台入口时，也必须追加 ?corpId=$CORPID$，否则钉钉 SDK 无法获取免登授权码。参数名建议统一使用 corpId；系统也兼容小写 corpid。

钉钉网页应用配置

钉钉安全设置回调域名

开通权限并关联企业

在权限管理中申请免密登录和通讯录同步所需权限：

通讯录个人信息读权限（Contact.User.Read）
邮箱等个人信息读取权限
通讯录部门信息读权限
成员信息读权限
通讯录部门成员读权限
通讯录组织基础信息读权限
获取钉钉开放接口用户访问凭证的基础权限
企业微应用后台免登接口的访问权限

如果还需要发送通知或机器人消息，请增加机器人能力以及“企业内机器人发消息权限”。AppKey 对应的应用未启用机器人时，发送单聊消息会出现 robotCode.notExsit。

钉钉添加机器人能力

回到 组织设置 > 登录与身份 > 企业平台接入 > 钉钉，填写企业 ID、企业名称、AppKey 和 AppSecret，完成企业关联。

Knodo 钉钉 SSO 集成配置

企业微信

配置备案域名和应用主页

企业微信要求应用主页和可信域名与企业备案域名一致。登录企业微信管理后台，进入 应用管理 > 自建应用，配置桌面端和移动端应用主页，例如：

https://knodo.example.com:9000/workspaces

企业微信应用主页配置

在开发者接口中启用 网页授权及 JS-SDK 和 企业微信授权登录，并根据部署情况配置可信域名、回调域名和企业可信 IP。

企业微信开发者接口

企业微信可信域名

企业微信回调域名

企业微信企业可信 IP

企业专属入口必须使用 HTTPS。平台注入的 Cookie 带有 secure: true，使用 HTTP 时浏览器不会写入 Cookie，认证后会再次回到登录页。

Nginx 配置

企业微信必须使用企业自有备案域名，请先完成自有域名解析，再按企业自有域名的 Nginx 配置配置反向代理到 knodo.vip。使用 Knodo 泛域名时无法满足企业微信的应用域名与备案域名一致性要求。

关联企业

回到 组织设置 > 登录与身份 > 企业平台接入 > 企业微信，填写企业 ID、企业名称、AgentId 和 Secret，完成企业关联。

Knodo 企业微信 SSO 集成配置

飞书

配置应用地址

登录飞书开放平台，进入企业自建应用，在 应用能力 > 网页应用 中配置：

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

在 开发配置 > 安全设置 中配置：

重定向 URL：https://acme.knodo.vip/login
OAuth 回调 URL：https://acme.knodo.vip/api/v1/auth/feishu/callback
H5 可信域名：https://acme.knodo.vip

测试、生产或使用非默认端口的地址需要分别配置，协议、域名、端口和路径必须完全一致。

飞书网页应用配置

飞书安全设置

开通权限并关联企业

根据需要开通以下权限：

权限名称	权限标识	用途
获取企业信息	`tenant:tenant:readonly`	关联企业时识别 Tenant Key 和企业名称
获取企业完整域名	`tenant:tenant.domain:read`	字段权限，关联企业时读取企业完整域名
获取用户基本信息	`contact:user.base:readonly`	获取用户姓名和头像
获取用户邮箱	`contact:user.email:readonly`	通过邮箱可靠匹配账号
获取部门列表	`contact:department.base:readonly`	同步部门
获取部门成员列表	`contact:department.member:readonly`	同步成员
获取通讯录基本信息	`contact:contact.base:readonly`	读取授权范围和组织结构
获取用户 userid	`contact:user.employee_id:readonly`	建立组织成员外部身份
获取与发送单聊、群组消息	`im:message`	机器人接收和回复消息
以应用的身份发消息	`im:message:send_as_bot`	主动发送通知和机器人消息

回到 组织设置 > 登录与身份 > 企业平台接入 > 飞书，填写 App ID 和 App Secret，完成企业关联。系统会通过飞书接口识别企业 Tenant Key 和企业名称。

Knodo 飞书 SSO 集成配置

包含新增权限的飞书应用版本必须发布并通过审批后才会生效。如果发送测试消息返回 99991672 Access denied，请检查 im:message:send_as_bot 权限和应用版本状态。

四、同步组织成员和部门

完成钉钉或飞书平台接入后，可以在对应平台页签中配置并执行组织成员同步。同步用于批量建立 Knodo 组织成员与企业通讯录成员之间的组织级身份，后续登录、通知和机器人识别都使用该身份。

同步遵循以下规则：

只根据平台成员 ID、邮箱、手机号等可靠信息自动匹配或创建成员。
姓名等非唯一信息不能用于自动绑定。
已绑定给其他 Knodo 用户的企业身份不会被覆盖，冲突会记录在同步结果中。
外部成员离职或不再属于企业时，按现有成员同步策略停用组织成员及其身份，不删除 Knodo 用户和历史记录。
同步结果会展示新增、通过、禁用、部门变更、身份刷新、冲突和跳过数量，并保留执行历史。

钉钉成员同步

钉钉应用需要具备通讯录部门和成员读取权限。管理员可以选择同步范围、启用自动同步或点击 立即同步，成功匹配或创建的成员会同时建立钉钉组织成员身份。

钉钉组织成员同步

飞书成员同步

飞书同步只读取应用通讯录授权范围内的成员和部门。应用可用范围覆盖需要同步的成员即可，不要求开放给全部员工。同步不会覆盖与用户自行验证身份不一致的记录。

企业微信成员身份

当前版本没有与钉钉、飞书等价的企业微信通讯录同步入口。企业微信成员通过组织 SSO 登录或在个人设置中绑定企业身份后建立组织成员身份；后续增加企业微信通讯录同步时将沿用相同的组织级身份和冲突保护规则。

用户身份匹配

用户通过企业 SSO 登录或执行通讯录同步时，系统按可靠程度匹配已有账号：

平台成员身份匹配。
邮箱匹配。
手机号匹配。
均未匹配时，根据组织策略创建新账号或进入待处理状态。

平台身份或邮箱已经命中时，不会继续用手机号改变账号归属。手机号为空、格式不可用或已被其他用户占用时，也不会抢占或覆盖现有账号。企业身份以“用户 + 组织 + 平台”为作用域，同一用户在不同组织中的身份彼此隔离。

企业身份标识从哪里来？

IM 机器人识别发送人依赖企业平台返回的身份标识，例如钉钉 userId、飞书 user_id/open_id/union_id 或企业微信 userid。机器人配置成功只代表消息可以到达 Knodo，不会自动把每位发送人与 Knodo 用户绑定。

企业身份标识可以通过以下三种方式建立：

专属域名企业 SSO 登录：用户从组织专属地址使用钉钉、飞书或企业微信登录，系统在登录成功后自动记录该用户在当前组织中的企业身份。
个人设置绑定企业身份：用户先从目标组织的专属入口进入 Knodo，再进入 个人设置 > 账号安全 > 企业身份，选择组织和平台完成绑定。这仍然使用组织已配置的企业应用凭证；如果从其他入口访问，产品会提示前往专属入口。
管理员同步组织成员和部门：管理员在 组织设置 > 登录与身份 > 企业平台接入 中完成平台配置后，执行同步，批量建立组织成员的企业身份，适合首次接入或批量初始化成员。

完成任一方式后，企业身份即可用于企业 SSO、组织通知和 IM 机器人发送人识别。具体操作请参阅登录方式和 IM 机器人集成。

常见问题

专属入口没有显示企业登录方式

依次检查：

当前访问地址是否与组织登记的完整 Origin 一致，包括协议和非默认端口。
组织是否已完成对应 IM 平台的企业关联和凭证配置。
是否已开启“自定义登录方式”并将该平台加入已启用列表。
Nginx 是否正确传递 X-Forwarded-Proto 和 X-Forwarded-Host。

组织反查只认完整 Origin，不做裸域名或跨协议回退匹配：协议、主机、端口任一不一致，都会按“当前域名未关联组织”处理。需要更换访问地址时，请同步更新组织登记的专属地址。

在平台默认域名看不到组织自定义登录方式

这是预期行为。组织策略只对组织专属入口生效，平台默认入口始终使用平台统一登录方式。

通过非默认端口访问时无法识别组织

确认组织中登记的是包含端口的完整地址，例如 https://knodo.example.com:9000，并确认 Nginx 使用：

proxy_set_header X-Forwarded-Host $http_host;
proxy_set_header X-Forwarded-Proto $scheme;

如果专属入口前面还有一层 Knodo 入口（例如先跳转到 javis.elevo.vip 再由平台转发），这一层不能再用 $host 覆盖 X-Forwarded-Host，否则同样会丢掉端口。Knodo 内部代理（apps/backend/docker/nginx.conf）会保留外层传入的 Host，含非默认端口。

SSO 登录后没有自动加入组织

检查“允许 SSO 用户自动加入”是否开启。关闭时，新成员需要管理员审批；同时确认平台返回的企业成员身份与当前组织一致。

机器人也一定要通过专属域名识别组织吗？

不一定。机器人的回调地址既可以配置为组织专属域名，也可以配置为 Knodo 平台默认域名，例如：

https://acme.knodo.vip/api/v1/im/webhook/<callbackToken>
https://knodo.vip/api/v1/im/webhook/<callbackToken>

系统通过回调地址中的 callbackToken 找到机器人配置和所属组织，不通过请求域名判断组织。因此，使用平台默认域名不会影响机器人识别组织；成员身份仍通过企业 SSO、个人绑定或通讯录同步建立。

企业登录、身份与 IM 集成

企业登录、身份与 IM 集成

一、配置组织专属入口

两类专属地址

企业自有域名的 Nginx 配置

二、配置专属入口的登录方式

配置的生效范围

三、配置企业 IM 平台

钉钉

配置应用地址

开通权限并关联企业

企业微信

配置备案域名和应用主页

Nginx 配置

关联企业

飞书

配置应用地址

开通权限并关联企业

四、同步组织成员和部门

钉钉成员同步

飞书成员同步

企业微信成员身份

用户身份匹配

企业身份标识从哪里来？

常见问题

专属入口没有显示企业登录方式

在平台默认域名看不到组织自定义登录方式

通过非默认端口访问时无法识别组织

SSO 登录后没有自动加入组织

机器人也一定要通过专属域名识别组织吗？

相关文档