鉴权方式详解

概述

BPMAX 支持多种鉴权方式,可以满足不同外部系统的鉴权需求。选择合适的鉴权方式是确保接口调用安全的关键。

支持的鉴权方式

鉴权方式说明适用场景
无鉴权不需要任何鉴权信息公开 API、内网 API
API Key使用固定的 API 密钥简单的 API 鉴权
Bearer Token使用 Bearer TokenOAuth 2.0、JWT 等
Basic AuthHTTP 基本认证传统的用户名密码认证
OAuth 2.0OAuth 2.0 协议标准的 OAuth 2.0 认证
自定义鉴权通过插件实现特殊的鉴权需求

无鉴权（None）

适用场景

  • 公开的 API 接口
  • 内网环境下的 API
  • 不需要鉴权的测试接口

配置方法

在接口实例配置中，鉴权方式选择"无鉴权"即可。

{
  "auth": {
    "type": "none"
  }
}

注意事项

  • 确保接口确实不需要鉴权
  • 注意网络安全，避免暴露敏感数据
  • 建议仅在内网环境使用

API Key

适用场景

  • 简单的 API 鉴权
  • 第三方服务提供的 API Key
  • 不需要动态刷新的场景

配置方法

API Key 可以通过两种方式传递：

1. 通过请求头传递

{
  "auth": {
    "type": "api_key",
    "api_key": {
      "in": "header",
      "name": "X-API-Key",
      "value": "your-api-key-here"
    }
  }
}

请求示例：

GET /api/customers HTTP/1.1
Host: api.example.com
X-API-Key: your-api-key-here

2. 通过查询参数传递

{
  "auth": {
    "type": "api_key",
    "api_key": {
      "in": "query",
      "name": "apiKey",
      "value": "your-api-key-here"
    }
  }
}

请求示例：

GET /api/customers?apiKey=your-api-key-here HTTP/1.1
Host: api.example.com

配置项说明

字段说明示例
inAPI Key 的位置header 或 query
nameAPI Key 的参数名X-API-Key、apiKey 等
valueAPI Key 的值your-api-key-here

注意事项

  • API Key 是敏感信息，注意保密
  • 定期更换 API Key
  • 不要在日志中记录 API Key
  • 使用 HTTPS 协议传输

Bearer Token

适用场景

  • OAuth 2.0 认证
  • JWT（JSON Web Token）认证
  • 需要动态 Token 的场景

配置方法

{
  "auth": {
    "type": "bearer",
    "bearer": {
      "token": "your-access-token-here"
    }
  }
}

请求示例：

GET /api/customers HTTP/1.1
Host: api.example.com
Authorization: Bearer your-access-token-here

配置项说明

字段说明示例
tokenBearer Token 的值eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token 刷新

如果 Token 有过期时间，可以使用 OAuth 2.0 方式自动刷新 Token。

注意事项

  • Token 是敏感信息，注意保密
  • 注意 Token 的有效期
  • Token 过期后需要重新获取
  • 使用 HTTPS 协议传输

Basic Auth

适用场景

  • 传统的 HTTP 基本认证
  • 简单的用户名密码认证
  • 内网系统认证

配置方法

{
  "auth": {
    "type": "basic",
    "basic": {
      "username": "your-username",
      "password": "your-password"
    }
  }
}

请求示例：

GET /api/customers HTTP/1.1
Host: api.example.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

注：dXNlcm5hbWU6cGFzc3dvcmQ= 是 username:password 的 Base64 编码。

配置项说明

字段说明示例
username用户名admin
password密码password123

注意事项

  • 用户名和密码是敏感信息，注意保密
  • 必须使用 HTTPS 协议，避免明文传输
  • 定期更换密码
  • 不要在日志中记录密码

OAuth 2.0

适用场景

  • 标准的 OAuth 2.0 认证
  • 需要自动刷新 Token 的场景
  • 第三方平台授权

支持的授权类型

目前支持 Client Credentials 授权类型。

配置方法

{
  "auth": {
    "type": "oauth2",
    "oauth2": {
      "grant_type": "client_credentials",
      "token_url": "https://api.example.com/oauth/token",
      "client_id": "your-client-id",
      "client_secret": "your-client-secret",
      "scope": "read write"
    }
  }
}

配置项说明

字段说明示例
grant_type授权类型client_credentials
token_url获取 Token 的 URLhttps://api.example.com/oauth/token
client_id客户端 IDyour-client-id
client_secret客户端密钥your-client-secret
scope权限范围（可选）read write

工作流程

  1. 系统使用 client_id 和 client_secret 向 token_url 请求 Access Token
  2. 获取到 Access Token 后，缓存起来
  3. 在调用接口时，自动在请求头中添加 Authorization: Bearer {access_token}
  4. Token 过期后，自动重新获取

Token 缓存

  • Token 会自动缓存，避免频繁请求
  • 缓存时间根据 Token 的 expires_in 字段确定
  • Token 过期前会自动刷新

请求示例

获取 Token 请求：

POST /oauth/token HTTP/1.1
Host: api.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret&scope=read+write

获取 Token 响应：

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

调用接口请求：

GET /api/customers HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

注意事项

  • client_id 和 client_secret 是敏感信息，注意保密
  • 确保 token_url 正确
  • 注意 Token 的有效期
  • 使用 HTTPS 协议

自定义鉴权

适用场景

  • 特殊的鉴权需求
  • 复杂的签名算法
  • 需要动态计算鉴权参数

实现方法

通过开发插件实现自定义鉴权逻辑。

1. 创建鉴权插件

// plugins/custom-auth.js
export default {
  name: 'custom-auth',
  type: 'auth',
  
  // 鉴权处理函数
  async handle(config, authConfig) {
    // 获取当前时间戳
    const timestamp = Date.now();
    
    // 生成签名
    const signature = this.generateSignature(config, timestamp, authConfig.secret);
    
    // 添加鉴权参数到请求头
    config.headers['X-Timestamp'] = timestamp;
    config.headers['X-Signature'] = signature;
    
    return config;
  },
  
  // 生成签名
  generateSignature(config, timestamp, secret) {
    const data = `${config.method}${config.url}${timestamp}${secret}`;
    return md5(data);
  }
};

2. 注册插件

在系统中注册自定义鉴权插件。

3. 配置使用

{
  "auth": {
    "type": "custom",
    "custom": {
      "plugin": "custom-auth",
      "config": {
        "secret": "your-secret-key"
      }
    }
  }
}

插件开发指南

详细的插件开发指南请参考 插件开发文档。

鉴权配置示例

示例 1：阿里云 API

{
  "auth": {
    "type": "api_key",
    "api_key": {
      "in": "header",
      "name": "Authorization",
      "value": "APPCODE your-app-code"
    }
  }
}

示例 2：GitHub API

{
  "auth": {
    "type": "bearer",
    "bearer": {
      "token": "ghp_xxxxxxxxxxxxxxxxxxxx"
    }
  }
}

示例 3：企业内部系统

{
  "auth": {
    "type": "basic",
    "basic": {
      "username": "api_user",
      "password": "api_password"
    }
  }
}

示例 4：OAuth 2.0 系统

{
  "auth": {
    "type": "oauth2",
    "oauth2": {
      "grant_type": "client_credentials",
      "token_url": "https://oauth.example.com/token",
      "client_id": "client_12345",
      "client_secret": "secret_abcdef",
      "scope": "api.read api.write"
    }
  }
}

安全建议

1. 保护敏感信息

  • 不要在代码中硬编码密钥
  • 使用环境变量或配置中心存储敏感信息
  • 定期轮换密钥和凭证
  • 不要在日志中记录敏感信息

2. 使用 HTTPS

  • 所有接口调用必须使用 HTTPS 协议
  • 验证 SSL 证书
  • 避免中间人攻击

3. 最小权限原则

  • 只授予必要的权限
  • 使用专门的 API 账号
  • 定期审查权限

4. 监控和告警

  • 监控异常的接口调用
  • 设置告警规则
  • 记录所有鉴权失败的尝试

5. 定期审计

  • 定期检查鉴权配置
  • 审查 API 访问日志
  • 及时发现和处理安全问题

常见问题

Q1: 如何选择合适的鉴权方式？

A: 根据外部系统的要求选择：

  • 如果外部系统提供了 API Key，使用 API Key 方式
  • 如果外部系统支持 OAuth 2.0，优先使用 OAuth 2.0
  • 如果是简单的用户名密码认证，使用 Basic Auth
  • 如果有特殊需求，开发自定义鉴权插件

Q2: Token 过期后如何处理？

A:

  • 使用 OAuth 2.0 方式，系统会自动刷新 Token
  • 使用 Bearer Token 方式，需要手动更新 Token
  • 可以在请求前脚本中实现 Token 刷新逻辑

Q3: 如何保证鉴权信息的安全？

A:

  • 使用 HTTPS 协议
  • 不在日志中记录敏感信息
  • 定期更换密钥
  • 使用环境变量存储敏感配置
  • 限制接口访问权限

Q4: 多个环境如何管理鉴权信息？

A:

  • 为不同环境创建不同的接口实例
  • 每个实例配置对应环境的鉴权信息
  • 在调用时指定使用哪个实例

相关文档