鉴权认证

一、方案结论

OpenAPI 调用统一采用“接口密钥 + 请求签名 + 权限校验”的鉴权方案。

调用方先在管理端生成接口密钥，拿到访问凭证后按接口规则生成签名。平台收到请求后依次校验密钥状态、签名有效性、时间戳有效期和接口权限。全部通过后才执行业务接口。

生成密钥 -> 分配权限 -> 调用方签名 -> 平台验签 -> 权限校验 -> 返回接口结果

二、适用范围

本文用于 OpenAPI 接口调用鉴权，不用于管理端登录、座席登录、菜单权限或座席上线认证。

适用对象：

• 外部业务系统调用呼叫中心 OpenAPI。
• 实施或管理员为外部系统开通接口调用权限。
• 技术对接方配置 OpenAPI 请求凭证和签名参数。

三、凭证方案

3.1 接口密钥管理

管理端通过“接口密钥”页面维护 OpenAPI 调用凭证。

3.2 统一鉴权方式

OpenAPI 对外按 region 区分接入区域。不同 region 可以对应不同网关或后端集群，但对接方不需要感知平台差异，只需要使用正确的 region id、企业或部门身份参数、时间戳和签名。

统一规则：

• region：标识接入区域，不同区域使用不同 region id。
• validateType=1：使用部门编号鉴权，sign=MD5(departmentId + timestamp + 部门token)。
• validateType=2：使用呼叫中心编号鉴权，sign=MD5(enterpriseId + timestamp + 部门token)。
• timestamp：秒级 Unix 时间戳，有效期 30 分钟。
• sign：32 位小写 MD5。

四、配置步骤

4.1 新建密钥

1. 管理员进入“接口密钥”页面。
2. 查看密钥对占用情况，确认未超过上限。
3. 点击“生成密钥对”。
4. 记录访问密钥 ID，并通过安全方式交付 Secret / Token。
5. 填写备注，标明系统、项目和负责人。

4.2 分配权限

1. 在密钥列表找到对应访问密钥 ID。
2. 点击“分配权限”。
3. 只勾选本次对接需要的接口权限。
4. 保存后由对接方发起接口请求验证。

权限分配原则：

• 查询类系统只分配查询接口。
• 录音、话单、外呼任务等敏感能力单独确认权限。
• 不建议多个系统共用同一密钥。
• 项目结束或系统下线后及时禁用或回收密钥。

4.3 禁用与回收

密钥疑似泄露、系统下线、归属不清或临时停止访问时，先执行“禁用”。确认不再使用后，再移入回收站。

禁用后，该密钥不应再通过 OpenAPI 鉴权。

五、请求方案

5.1 OpenAPI 请求参数

OpenAPI 请求中必须带上 region 和鉴权参数。

示例：

region=1
validateType=1
departmentId=BM0000001
timestamp=1491371625
sign=MD5(BM0000001 + 1491371625 + 部门token)

5.2 region 处理

region 只用于选择接入区域，不改变鉴权主体和签名规则。

对接方需要确认：

• 当前企业或部门应使用哪个 region id。
• 请求地址中的 region 与实际企业归属区域一致。
• 测试环境、生产环境不要混用 region。
• 更换 region 后重新发起联调验收。

同一个鉴权方案在不同 region 下保持一致；差异只体现在 region id、请求地址和后端接入区域。

六、平台校验逻辑

平台收到 OpenAPI 请求后按以下顺序处理：

识别调用方身份
  ↓
检查密钥是否存在且启用
  ↓
校验 timestamp 是否在有效期内
  ↓
按平台规则重新计算签名
  ↓
比较请求签名与服务端签名
  ↓
检查该密钥是否具备接口权限
  ↓
执行业务接口并返回结果

任一环节失败，都应返回鉴权失败或无权限结果，不继续执行业务逻辑。

七、联调验收

上线前至少完成以下验证：

• 使用正确密钥调用一个已授权接口，预期成功。
• 使用错误 Secret / Token 调用，预期鉴权失败。
• 使用过期 timestamp 调用，预期鉴权失败。
• 使用未分配权限的接口调用，预期无权限。
• 禁用密钥后再次调用，预期鉴权失败。
• 更换新密钥后，旧密钥不可用，新密钥可用。

八、常见失败处理

九、安全要求

• Secret / Token 只允许通过安全渠道交付。
• 不在截图、日志、工单、公开文档中明文展示密钥。
• 每个系统使用独立密钥，便于权限收敛和风险切断。
• 定期检查长期未使用、备注为空、归属不清的密钥。
• 发现泄露风险时，先禁用旧密钥，再生成新密钥替换。