帮你快速理解、总结文档立即下载
文档中心>iOA 零信任安全管理系统

企业微信自定义审批配置指南

最近更新时间：2026-10-28 17:53:30
本文档已由 AI 辅助审校
我的收藏

本页目录：

1. 适用范围

本文面向 iOA 管理员、企业微信管理员及网络管理员，用于配置以下能力：
iOA 通过企业自建应用调用企业微信 OA 审批接口。
使用企业微信审批系统应用中已经存在的审批模板和审批流程。
企业微信将审批同意或驳回结果回调给 iOA。
本方案不使用自建应用 > 审批接口中的审批流程引擎模板，iOA 使用的是企业微信 OA 接口：
/cgi-bin/oa/gettemplatedetail
/cgi-bin/oa/applyevent
对应的回调事件为：
sys_approval_change

2. 配置前准备

准备以下信息和资源：
类别
准备项
账号
企业微信管理员账号。
企业标识
企业微信企业 ID（CorpId）。
应用凭据
企业自建应用的 AgentId 和 Secret。
主机
一台具有固定公网出口和公网 HTTPS 入口的 Nginx 主机。
证书
与回调域名或公网 IP 匹配的、受公共 CA 信任的 TLS 证书。
网络信息
iOA 网关域名及 iOA 访问 Nginx 的来源 IP 网段。
iOA 服务域名：
scs.gateway.tencent.com

3. 网络链路

Nginx 同时承担企业微信 API 出站桥接和审批结果入站回调：
发起审批：
 iOA
  -> https://<TrustedIp>/qyapi/cgi-bin/...
  -> 用户 Nginx
  -> https://qyapi.weixin.qq.com/cgi-bin/...

审批回调：
企业微信
  -> https://<TrustedIp>/thirdparty-provider/open/approval/wecom/v1/data
  -> 用户 Nginx
  ->  iOA 网关
需要放通：
链路
放通规则
入站
iOA 到 Nginx TCP 443。
出站
Nginx 到 qyapi.weixin.qq.com TCP 443。
入站
企业微信到 Nginx TCP 443。
出站
Nginx 到 iOA 网关 TCP 443。
域名解析
Nginx 所在主机能够解析企业微信和 iOA 网关域名。

4. 可信 IP 说明

配置中有两个容易混淆的地址：

4.1 企业可信 IP

填写 Nginx 访问 qyapi.weixin.qq.com 时使用的固定公网出口 IP。
该 IP 地址用于企业微信对自建应用 API 调用来源进行校验，请勿填写以下内容：
禁止项
不得填写的内容
内网地址
Nginx 内网 IP。
端口
Nginx 监听端口。
回调地址
回调 URL。
服务地址
iOA 服务 IP。
如果企业微信响应包含：
from ip: <Nginx公网出口IP>
则企业可信 IP 应填写该响应中的 Nginx 公网出口 IP。

4.2 iOA 应用配置中的 TrustedIp

TrustedIp 是 iOA 访问用户 Nginx 并生成企业微信回调 URL 时使用的公网入口，填写格式为：
approval.example.com
或：
<Nginx公网入口IP>
非标准 HTTPS 端口可以填写：
approval.example.com:8443
不要携带 https://、路径或查询参数。
推荐使用域名和公共 CA 证书。直接使用公网 IP 时，TLS 证书必须包含该 IP 的 SAN。自签名证书即使能完成部分人工测试，也可能导致企业微信真实事件回调失败。

5. 部署 Nginx

以下配置在同一 443 端口提供 /qyapi/ 出站桥接和审批回调入站反向代理。
upstream ioa_gateway {
    server scs.gateway.tencent.com:443;
    keepalive 32;
}

# 不记录查询参数，避免 access_token 出现在访问日志中。
log_format wecom_safe '$remote_addr - $remote_user [$time_local] '
                      '"$request_method $uri $server_protocol" $status $body_bytes_sent '
                      '"$http_referer" "$http_user_agent"';

server {
    # 仅在该主机的 443 为本服务专用时使用 default_server。
    listen 443 ssl default_server;
    listen [::]:443 ssl default_server;
    server_name approval.example.com;

    ssl_certificate     /etc/nginx/certs/dlp-approval.fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/dlp-approval.key;
    ssl_protocols       TLSv1.2 TLSv1.3;

    access_log /var/log/nginx/dlp_wecom_bridge_access.log wecom_safe;
    error_log  /var/log/nginx/dlp_wecom_bridge_error.log warn;
    client_max_body_size 4m;

    # iOA 经租户 Nginx 调用企业微信 API。
    location ^~ /qyapi/ {
        # 强烈建议限制为 iOA 出口网段，防止成为公共企业微信 API 代理。
        # allow <iOA 出口IP或网段>;
        # deny all;

        proxy_http_version 1.1;
        proxy_set_header Host qyapi.weixin.qq.com;
        proxy_set_header Connection "";

        proxy_ssl_server_name on;
        proxy_ssl_name qyapi.weixin.qq.com;
        proxy_ssl_verify on;
        proxy_ssl_trusted_certificate /etc/pki/tls/certs/ca-bundle.crt;

        proxy_connect_timeout 5s;
        proxy_send_timeout 30s;
        proxy_read_timeout 30s;
        proxy_buffering off;

        # /qyapi/cgi-bin/... 转换为 /cgi-bin/...
        proxy_pass https://qyapi.weixin.qq.com/;
    }

    # 企业微信审批结果回调。
    location ^~ /thirdparty-provider/open/approval/wecom/v1/data {
        proxy_http_version 1.1;
        proxy_set_header Host scs.gateway.tencent.com;
        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 https;
        proxy_set_header Connection "";

        proxy_ssl_server_name on;
        proxy_ssl_name scs.gateway.tencent.com;
        proxy_ssl_verify on;
        proxy_ssl_trusted_certificate /etc/pki/tls/certs/ca-bundle.crt;

        proxy_connect_timeout 5s;
        proxy_send_timeout 15s;
        proxy_read_timeout 15s;
        proxy_request_buffering on;
        proxy_buffering off;

        # 不添加 URI、不 rewrite，保留原始路径和查询参数。
        proxy_pass https://ioa_gateway;
    }
}
场景
说明
CA 文件（CentOS/RHEL）
CentOS/RHEL 系统 CA 文件通常为 /etc/pki/tls/certs/ca-bundle.crt。
CA 文件（Debian/Ubuntu）
Debian/Ubuntu 通常为 /etc/ssl/certs/ca-certificates.crt。
公网 IP 场景
使用公网 IP 时，可以将 server_name 改为 _。
多虚拟主机
主机存在其他 443 server 时，应检查默认虚拟主机，避免请求进入其他配置。
请求方法
必须允许回调路径的 GET 和 POST。
请求体与参数
不得改写加密请求体及 msg_signature、timestamp、nonce、echostr、tenant_id、callback_id。
加载配置：
nginx -t
systemctl reload nginx
检查最终生效配置：
nginx -T 2>&1 | grep -nE 'listen 443|server_name|qyapi|thirdparty-provider|access_log'

6. 配置企业微信自建应用

6.1 创建应用

1. 进入 企业微信管理后台，在左侧导览中，单击应用管理 > 应用。
2. 在应用页面，选择自建，单击创建应用。
3. 创建应用时，需要：
记录：
AgentId。
Secret。
应用可见范围至少应包含：
DLP 审批发起人。
审批模板中的审批人。
用于执行审批测试的账号。

6.2 设置企业可信 IP

在自建应用详情中找到企业可信 IP，填写第4.1 节确认的 Nginx 固定公网出口 IP。
若 API 返回"不在可信 IP"或响应中出现其他 from ip，应以企业微信实际识别的 from ip 为准，检查 NAT 和出口路由。

6.3 授权调用审批接口

1. 进入 企业微信管理后台，在左侧导览中，单击应用管理 > 应用。
2. 在应用页面，选择基础，单击审批 > API。
3. 单击可调用接口的应用右侧的设置，将当前自建应用加入列表。

说明：
未加入时，gettemplatedetail 或 applyevent 可能返回 301025。

7. 配置企业微信审批模板

7.1 创建模板

1. 进入 企业微信管理后台，在左侧导览中，单击应用管理 > 应用。
2. 在应用页面，单击审批。

3. 在模板管理中，单击添加模板，在模板设置页面配置如下参数：
配置项
配置说明
模板名称
模板名称。
模板可见范围
模板可见范围。
表单控件
表单控件。
审批节点
审批人、抄送人和多级审批节点。
说明：
iOA 不创建或更新现有模板，审批节点和表单内容均以企业微信后台配置为准。

7.2 表单字段建议

iOA 支持企业微信 Text 和 Textarea 控件，建议采用以下两种方式之一。
方式一：每个字段一个控件，控件标题使用以下标准名称：
文件名称
命中敏感数据规则
命中敏感关键词
最高敏感数据级别
发送通道
拦截策略
外发理由
下载链接(24小时内有效)
方式二：配置一个 Textarea 多行文本控件。当模板标题未匹配任何标准字段时，iOA 会将审批信息合并为：
文件名称：Xxx
命中敏感数据规则：xxxx
最高敏感数据级别：S4
发送通道：QQ
注意：
限制类型
注意事项
文本格式
Text 是单行文本，不支持换行；多个字段只能用中文分号合并。
非必填控件
不支持的非必填控件会被跳过。
必填控件
不支持的必填控件会导致发起失败。
必填文本控件
模板中的必填文本控件必须能够获得对应值。

7.3 获取模板 ID

打开模板编辑页，从浏览器 URL 的 template_id 参数或页面复制功能获取模板 ID，填写到 iOA 的 FlowId。
正确的 OA 模板 ID 示例：
3WNhj3eT6qqtyymzLDzPRhyBYdTBpHUkGE2XYszp
请勿使用：
自建应用 → 审批接口
注意：
审批流程引擎模板 ID。两类模板不能混用。

7.4 开启当前模板的状态回调

1. 进入 企业微信管理后台，在左侧导览中，单击应用管理 > 应用。
2. 在应用页面，选择基础，单击审批 > API。
3. 在接收事件服务器配置中，单击开启回调通知的模板右侧的设置。

4. 勾选当前 DLP 审批模板，单击保存。
注意：
自建应用回调 URL 验证成功，仅能证明网络连通和验签正常；模板未在此处启用时，真实审批的提交、同意和驳回事件不会发送到 Nginx。

8. 创建 iOA 应用配置

1. 登录 iOA 零信任管理平台控制台，在左侧导航栏，选择敏感数据保护 > 管控策略 > 审批流配置。
2. 在审批流配置页面，单击添加审批流。
3. 在添加审批流页面，选择企业微信，审批模板选择为自定义，单击安装配置的新建配置。

4. 在新建安装配置页面，配置相关参数：
参数名称
说明
企业 ID
企业微信我的企业 → 企业信息 → 企业 ID。
应用 AgentId
自建应用 AgentId。
审批流程 ID
应用 Secret
该自建应用的 Secret。
Token
用于企业微信回调验签的 Token。
EncodingAESKey
企业微信 EncodingAESKey。
可信 IP
5. 单击确定，iOA 生成回调 URL：
https://<TrustedIp>/thirdparty-provider/open/approval/wecom/v1/data
  ?tenant_id=<租户ID>
  &callback_id=<回调ID>
注意：
必须原样复制，不能删除或修改查询参数。

9. 配置自建应用 API 接收消息

1. 进入 企业微信管理后台，在左侧导览中，单击应用管理 > 应用。
2. 在应用页面，单击当前自建应用，选择功能 > 接收消息 > 设置 API 接收。

3. 在 API 接收消息页面，配置相关参数，单击保存。
配置项
说明
URL
iOA 生成的完整回调 URL。
Token
必须与 iOA VerifyToken 完全一致。
EncodingAESKey
必须与 iOA AesKey 完全一致。
消息事件类型
选择需要接收的消息事件类型，开启审批状态通知事件。
4. 单击保存时，企业微信会发起 GET 验证。保存成功表示：
企业微信能够访问 Nginx。
Nginx 能够转发到 iOA。
Token 和 EncodingAESKey 匹配。
注意：
保存成功不等于真实审批事件已经订阅成功，还必须完成第 7.4 节的模板勾选。

10. 测试 iOA 审批流

1. 在 iOA 创建 DLP 审批流：
配置项
配置说明
审批应用
审批应用选择企业微信。
应用配置
模板开关
开启自定义模板。
测试发起人
测试发起人必须存在于企业微信，并位于自建应用及审批模板可见范围内。
2. 执行审批测试，依次验证：
2.1 gettemplatedetail 返回成功。
2.2 applyevent 返回成功并生成审批单号 SpNo。
2.3 企业微信中出现审批单，字段和审批节点正确。
2.4 审批人执行同意或驳回。
2.5 Nginx 收到企业微信 POST。
2.6 iOA 审批记录和终端状态完成更新。

11. 验证命令

11.1 验证 Nginx 出站桥接

使用无效测试参数，避免在命令历史中泄露真实 Secret：
curl -sS \\
  'https://approval.example.com/qyapi/cgi-bin/gettoken?corpid=invalid&corpsecret=invalid'
若收到企业微信 JSON 响应，即表示 /qyapi/ 转发链路可达。

11.2 验证 TLS 证书

curl -v 'https://approval.example.com/'
不能依赖 curl -k 验收。标准校验必须无证书过期、名称不匹配或自签名错误。

11.3 观察真实回调

tail -f /var/log/nginx/dlp_wecom_bridge_access.log
正确订阅后，审批提交及状态变化均可能产生回调。回调事件名称为：
sys_approval_change
审批通过状态为 SpStatus=2，驳回状态为 SpStatus=3。

12. 常见问题

gettemplatedetail 返回 301025

问题现象：调用 gettemplatedetail 接口时返回错误码 301025。
排查与处理：请依次确认以下各项。
1. FlowId 是否来自审批系统应用的模板编辑页。
2. 当前自建应用是否已加入审批 → API → 可调用接口的应用。
3. CorpId、AgentId、Secret、模板是否属于同一个企业。
4. Nginx /qyapi/ 是否正确移除了路径前缀。

applyevent 返回 301025

问题现象：调用 applyevent 接口时返回错误码 301025。
排查与处理：请依次确认以下各项。
1. 模板控件 ID 和类型是否来自当前模板。
2. 必填控件是否都有值。
3. 模板是否含 iOA 不支持的必填控件。
4. 发起人是否位于应用和模板可见范围内。
5. 审批节点是否完整且可用。

回调 URL 保存成功，但同意后 Nginx 没有请求

问题现象：企业微信回调 URL 保存成功，但审批同意后 Nginx 未收到请求。
排查与处理：请依次确认以下各项。
1. 审批 → API → 开启回调通知的模板是否勾选当前模板。
2. 当前自建应用是否在可调用接口的应用中。
3. 自建应用是否开启审批状态通知事件。
4. 实际审批单是否由当前 FlowId 和当前自建应用发起。
5. TLS 证书是否受公共 CA 信任并匹配 URL 主机名。
6. nginx -T 中是否有其他 443 虚拟主机抢占请求。
若 Nginx 完全未收到请求，问题通常源于企业微信事件订阅、模板范围、证书或公网入口，而非 iOA 回调解析逻辑。

Nginx 收到请求但 iOA 状态未更新

问题现象：Nginx 已收到企业微信回调请求，但 iOA 中审批状态未更新。
排查与处理：请依次确认以下各项。
1. Nginx 返回状态码及错误日志。
2. proxy_set_header Host 和 proxy_ssl_name 是否为正确的 iOA 网关域名。
3. 查询参数 tenant_id、callback_id 是否完整。
4. Token、EncodingAESKey、CorpId 是否与 iOA 配置一致。
5. iOA 发起审批时是否成功保存当前 SpNo 的回调上下文。

13. 最终检查清单

检查维度
检查项
公网与入口
Nginx 有固定公网出口和公网 HTTPS 入口。
证书
TLS 证书受公共 CA 信任且匹配回调地址。
API 转发
/qyapi/ 能转发到 qyapi.weixin.qq.com。
回调转发
回调路径能转发到正确的 iOA 网关。
企业微信可信 IP
企业微信可信 IP 是 Nginx 的公网出口 IP。
iOA 可信 IP
iOA TrustedIp 是 Nginx 的公网入口。
应用可见范围
自建应用可见范围包含发起人和测试人员。
接口权限
自建应用已加入审批可调用接口的应用。
FlowId 来源
FlowId 来自审批系统应用的 OA 模板。
回调模板
当前模板已加入开启回调通知的模板。
通知事件
自建应用已开启审批状态通知事件。
端到端验证
回调 URL、Token、EncodingAESKey 与 iOA 完全一致。
发起、同意和驳回均完成端到端验证。

14. 安全要求

要求类型
安全要求
凭据保密
Secret、access_token、Token 和 EncodingAESKey 不得写入文档、工单或聊天记录。
日志脱敏
Nginx 日志不得记录查询参数中的 access_token。
访问控制
/qyapi/ 应通过 allow/deny、防火墙或上游安全设备限制为 iOA 来源。
暴露面收敛
不得将 iOA 内部接口暴露到公网。
凭据轮换
定期轮换已泄露的凭据，并检查证书有效期。
中国站