Iam Third Party Integration

Skill: 第三方应用接入 IAM（iam-boot-mini）

用途

指导如何将第三方系统接入 iam-boot-mini 项目，复用其登录/注册、身份验证、组织管理和权限管理能力。

USE FOR: 第三方系统接入 IAM、统一身份认证、OAuth2 对接、开放平台 API 调用、组织权限同步。

适用场景

• 第三方后端服务需要调用 IAM 的用户/部门/角色/权限管理接口。
• 第三方 Web/移动应用希望跳转 IAM 登录页完成统一认证（类 SSO）。
• 内部新模块需要复用 IAM 的用户与权限数据。
• 为外部合作伙伴开放受控的 API 访问。

前置条件

• IAM 项目已启动，数据库已初始化（sql/mysql/iam.sql 或 ruoyi-vue-pro.sql）。
• 网络可达 IAM 服务，默认端口 48080。
• 第三方系统已确定接入形态（后端服务 / 前端应用 / 内部模块）。

接入方案速查

方案 A：OAuth2 Client Credentials（后端服务调用）

步骤

1. 在 IAM 后台创建第三方应用

   • 接口：POST /admin-api/system/app/create
   • 系统自动生成对应的 OAuth2 Client（client_id / client_secret）。

2. 第三方服务获取 Access Token

   POST /admin-api/system/oauth2/token
   Authorization: Basic {base64(clientId:clientSecret)}
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=client_credentials&scope=user.read
   

3. 调用 IAM 管理接口

   GET /admin-api/system/user/page
   Authorization: Bearer {accessToken}
   tenant-id: {tenantId}
   

4. Token 刷新

   • client_credentials 模式通常不返回 refresh_token。
   • Token 过期后重新用 Basic Auth 获取。

权限说明

• 服务账号本身没有权限，需要给该账号关联一个 IAM 用户/角色，或赋予 super_admin。
• 用于管理接口时，建议创建一个专门的服务账号并赋予最小权限。

方案 B：OAuth2 Authorization Code（前端应用单点登录）

步骤

1. 创建 OAuth2 Client，授权类型包含 authorization_code、refresh_token。

2. 第三方前端引导用户到 IAM 登录页。

3. 登录后调用授权接口获取 code：

   POST /admin-api/system/oauth2/authorize
   Authorization: Bearer {loginAccessToken}
   Content-Type: application/x-www-form-urlencoded
   
   response_type=code&client_id={clientId}&redirect_uri={redirectUri}&scope=user.read
   

4. 第三方后端用 code 换 token：

   POST /admin-api/system/oauth2/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code&code={code}&redirect_uri={redirectUri}&client_id={clientId}&client_secret={clientSecret}
   

5. 后续携带 Authorization: Bearer {accessToken} 访问 IAM 接口。

注意事项

• redirect_uri 必须与创建 Client 时配置的一致。
• 简化模式（implicit）也在 /authorize 接口支持，但不推荐用于生产。

方案 C：OAuth2 Password（受信任内部应用）

步骤

POST /admin-api/system/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username={username}&password={password}&client_id={clientId}&client_secret={clientSecret}&scope=user.read

注意事项

• 仅用于完全受控的内部系统。
• 若账号开启 MFA，会返回 mfaRequired=true，需额外处理 MFA 流程。
• 泄露风险高，不建议对外使用。

方案 D：App Key + API 签名

前提

当前签名框架已实现与 system_app 表打通：

• 请求头携带 X-App-Key。
• 服务端从 system_app.app_secret 读取密钥。
• 支持 IP 白名单/黑名单和 API 权限拦截。

签名规则

请求头：

appId: {appKey}
timestamp: {毫秒时间戳}
nonce: {10位以上随机数}
sign: {sha256签名}

签名字符串：

请求参数 + 请求体 + appId={appId}&timestamp={timestamp}&nonce={nonce} + appSecret

示例 Java 客户端签名：

public static String sign(String appId, String appSecret, Map<String, String> params, String body) {
    SortedMap<String, String> sortedParams = new TreeMap<>(params);
    String paramStr = MapUtil.join(sortedParams, "&", "=");
    String headerStr = "appId=" + appId + "&timestamp=" + System.currentTimeMillis()
                     + "&nonce=" + RandomUtil.randomNumbers(16);
    String signStr = paramStr + body + headerStr + appSecret;
    return SecureUtil.sha256(signStr);
}

安全增强

• 在 IAM 后台为应用配置 ipWhitelist / ipBlacklist。
• 在 system_app_api_permission 中配置该应用可调用的 API。
• 请求会自动经过 AppIpInterceptor 和 AppApiPermissionInterceptor 校验。

方案 E：同 JVM 内部模块复用

步骤

1. 在第三方模块的 pom.xml 中引入：

   <dependency>
       <groupId>cn.iocoder.boot</groupId>
       <artifactId>iam-module-system</artifactId>
   </dependency>
   

2. 注入 AdminUserApi、DeptApi、PermissionApi 等接口：

   @Resource
   private AdminUserApi adminUserApi;
   @Resource
   private PermissionApi permissionApi;
   
   AdminUserRespDTO user = adminUserApi.getUser(userId);
   boolean hasPermission = permissionApi.hasAnyPermissions(userId, "system:user:create");
   

限制

仅适用于与 IAM 同属一个 Spring Boot 聚合应用的内部模块。

常用管理接口速查

用户管理

部门（组织）管理

角色/权限管理

OAuth2 接口

独立开放 API 入口 /open-api

用途

将面向第三方的接口与 /admin-api 管理后台接口隔离，避免安全策略混用。

使用方式

在任意模块创建 controller.open 包下的 Controller：

package cn.iocoder.yudao.module.system.controller.open.user;

@RestController
@RequestMapping("/user")
public class OpenUserController {

    @GetMapping("/get")
    public CommonResult<UserRespVO> getUser(@RequestParam Long id) {
        // ...
    }
}

访问路径：/open-api/user/get

自动生效的安全拦截

对 /open-api/** 和 /admin-api/** 自动生效：

1. AppIpInterceptor：IP 黑白名单
2. AppApiPermissionInterceptor：API 权限校验
3. AppQuotaInterceptor：调用配额
4. AppAuditLogInterceptor：审计日志

配置属性

Web API 前缀

yudao:
  web:
    admin-api:
      prefix: /admin-api
      controller: "**.controller.admin.**"
    app-api:
      prefix: /app-api
      controller: "**.controller.app.**"
    open-api:
      prefix: /open-api
      controller: "**.controller.open.**"

安全相关

yudao:
  security:
    permit-all_urls:
      - /admin-api/system/auth/**
      - /open-api/system/auth/**

最佳实践

1. 优先使用 client_credentials：纯后端调用首选，避免传递用户密码。
2. 每个第三方系统一个 OAuth2 Client：便于隔离权限、监控调用、独立吊销。
3. 使用 /open-api 暴露第三方接口：不要直接让外部调用 /admin-api。
4. 启用 IP 白名单：生产环境为每个应用配置允许的 IP 或网段。
5. 配置 API 权限清单：在 system_app_api_permission 中精确控制每个应用可调用的接口。
6. 关闭 Mock 登录：生产环境必须设置 yudao.security.mock-enable=false。
7. 限制 CORS：生产环境不要配置 * 来源，按具体域名配置。

故障排查

相关文件

• iam-module-system/.../controller/admin/oauth2/OAuth2OpenController.java
• iam-module-system/.../service/oauth2/OAuth2TokenServiceImpl.java
• iam-module-system/.../api/interceptor/AppIpInterceptor.java
• iam-module-system/.../api/interceptor/AppApiPermissionInterceptor.java
• iam-module-system/.../config/AppOpenApiSecurityConfiguration.java
• iam-framework/iam-spring-boot-starter-web/.../web/config/WebProperties.java

版本说明

• 适用于 iam-boot-mini Spring Boot 3.x 分支。
• 自研 OAuth2 实现，非 Spring Authorization Server，不支持标准 OIDC/SAML（如需标准协议需二次开发）。