应用安装流程概述

本文介绍第三方应用如何安装到 IM 工作空间，建立应用与工作空间的绑定关系。

安装流程架构

应用安装是将第三方应用接入 IM 系统的核心流程。安装完成后，应用将获得 Bot Token，可以向该工作空间的用户发送消息。

核心概念

概念	说明
工作空间	IM 中的租户单位，一个工作空间对应一个企业/团队
应用安装	将第三方应用绑定到某个工作空间
Bot Token	安装成功后获得的令牌，用于调用 Bot API
签名机制	使用 SHA256 签名验证请求来源

安装流程时序图

建议跳转到第三方应用的后端接口，原因：

1. 后端可以安全地保存签名信息到 Session
2. 后端可以验证签名参数的完整性
3. 后端可以根据业务逻辑决定重定向到哪个前端页面

安装流程步骤

步骤 1：用户发起安装

用户在 IM 客户端中点击"安装应用"按钮，IM 系统会：

1. 获取当前用户 ID（initiator_user_id）
2. 获取当前工作空间信息
3. 生成签名时间戳和签名值
4. 跳转到应用配置的 安装回调地址 installRedirectUri

步骤 2：接收安装回调

IM 跳转到您的后端接口，携带以下参数：

参数	类型	说明
workspace_id	long	IM 工作空间 ID
workspace_name	string	IM 工作空间名称（URL 编码）
app_id	number	应用 ID
initiator_user_id	long	发起安装的 IM 用户 ID
timestamp	long	签名时间戳（秒级）
sign	string	签名值（SHA256）

回调 URL 示例：

https://your-app.com/api/im/install/callback?workspace_id=1001&workspace_name=%E6%B5%8B%E8%AF%95%E5%B7%A5%E4%BD%9C%E7%A9%BA%E9%97%B4&app_id=123&initiator_user_id=456&timestamp=1704528000&sign=a1b2c3d4...

步骤 3：保存签名信息

后端接收到回调后，将签名信息保存到 Session：

@GetMapping("/api/im/install/callback")
public String handleInstallCallback(
    @RequestParam("workspace_id") Long workspaceId,
    @RequestParam("workspace_name") String workspaceName,
    @RequestParam("app_id") Long appId,
    @RequestParam("initiator_user_id") Long initiatorUserId,
    @RequestParam("timestamp") Long timestamp,
    @RequestParam("sign") String sign,
    HttpSession session
) {
    // 保存安装信息到 Session
    session.setAttribute("install_workspace_id", workspaceId);
    session.setAttribute("install_workspace_name", workspaceName);
    session.setAttribute("install_initiator_user_id", initiatorUserId);
    session.setAttribute("install_timestamp", timestamp);
    session.setAttribute("install_sign", sign);
    
    // 重定向到前端安装确认页
    return "redirect:/im/install-confirm";
}

步骤 4：用户登录并选择租户

前端显示安装确认页面，用户需要：

1. 登录第三方应用账号
2. 选择要绑定的租户（如果是多租户应用）
3. 点击"确认安装"

步骤 5：调用确认安装接口

后端调用 IM 的确认安装接口：

接口地址： POST /im-user/api/v1/oauth/install/confirm

请求参数：

{
  "clientId": "550e8400-e29b-41d4-a716-446655440000",
  "workspaceId": 1001,
  "externalTenantId": "1",
  "installerUserId": 456,
  "timestamp": 1704528000,
  "sign": "a1b2c3d4..."
}

步骤 6：获取 Bot Token

IM 验证签名通过后，返回 Bot Token：

{
  "code": 200,
  "data": {
    "botToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "bot",
    "botUserId": 456,
    "botName": "OA办公系统",
    "workspaceId": 1001,
    "workspaceName": "测试工作空间",
    "installationId": 789,
    "expiresIn": 31536000,
    "scope": "bot:message:send,bot:user:read"
  }
}

步骤 7：保存绑定关系

将 Bot Token 和绑定关系保存到数据库，安装完成。

签名验证机制

IM 系统会对确认安装请求进行 3 层验证：

1. 验证 Client ID - 检查 clientId 是否存在
2. 验证时间戳 - 检查 timestamp 是否在有效期内（10分钟，允许1分钟时钟偏差）
3. 验证签名 - 重新计算签名并对比

详细的签名机制请参考 签名机制。

安装者自动绑定

如果提供了 initiatorUserId（发起安装的 IM 用户 ID），系统会自动为安装者创建用户绑定：

• 绑定对象: IM 用户(initiatorUserId) ↔ 第三方应用用户(当前登录用户)
• 绑定标记: binding_method = 'installer_auto'
• 安全保护: 不覆盖已有绑定，避免破坏现有关系
• 容错处理: 自动绑定失败不影响安装流程

下一步

• 签名机制 - 了解签名算法和验证流程
• 回调处理 - 详细的回调处理实现
• 多租户绑定 - 了解工作空间与租户的绑定机制