Skip to content

访问控制

以接口组为最小单位,一个访问控制策略可以绑定多个接口组,同样,接口组可以被多个访问控制策略绑定(多对多关系) 若同一个接口组被绑定到多个访问策略,则按照认证类型的优先级: 本平台Token > 不鉴权(公开) > IP鉴权 > 平台用户 > API key > JWT 依次验证访问权限,直至拥有访问权限。

认证类型

1. 不鉴权(公开)

不对访问者进行身份认证(任何人可访问),多用于初期测试或开放类API,请务必注意数据安全。

  • HTTP 不需要携带认证凭据

2. API Key

API Key,即 API 密钥。 申请时由 APISQL 下发,API 发起请求时,需要在请求中包含这个 API Key,服务端接收到请求后会检查这个 Key 是否有效。

2.1 请求示例

Authorization 类型(auth-scheme): Bearer

HTTP
Authorization: Bearer sk-****
    • API 密钥一旦被盗,就可以无限期使用。除非且直到项目所有者撤销 API 密钥,因此请妥善保管

3. IP鉴权

允许某些IP地址访问,可用于有固定IP的用户/应用服务,如公网上部署的应用服务。

  • HTTP 不需要携带认证凭据

4. 平台用户

已在平台注册的用户可以通过使用平台账户调用接口,一个用户只能创建一个策略。

调用 API 时,使用平台用户的 用户名 以及 密码 分别作为 Basic 认证的用户名与密码

4.1 请求示例

对于 "Basic" 身份验证,凭据首先将用户名和密码使用一个冒号(username:password)相结合,然后将生成的字符串编码为 base64(dXNlcm5hbWU6cGFzc3dvcmQ=)。

Authorization 类型(auth-scheme): Basic

HTTP
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
    • Base64 编码很容易被解码,以得到原始的名称和密码,所以 Basic 身份验证是完全不安全的。因此总是推荐使用 HTTPS

5. 本平台Token

用户登录 APISQL 平台后会有一个 Token,项目成员可使用此 Token 作为接口认证凭据

  • 需要在 项目设置 中启用
  • 一般在开发&调试时使用,启用此设置后,在接口调式时可直接使用 本平台Token 作为认证凭据,不需要再去 访问控制 中设置 接口组 的访问权限
  • 仅限于项目成员,便于开发且安全性强

5.1 请求示例

  • Authorization 类型(auth-scheme): Bearer
  • 需要携带固定的标识符 apisqlp 来代表 JWT 的来源,格式 apisqlp@JWT

如: JWT为 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....

HTTP
Authorization: Bearer apisqlp@eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

6. JWT

JSON Web Token (JWT) 是一种基于 Token 的认证机制。它不需要服务器来保留客户端的认证信息或会话信息。APISQL 支持基于 JWT 进行用户认证,满足用户个性化安全设置的需求。

6.1 认证原理

调用 API 时携带 JWT,服务端将使用预先配置的密钥对 JWT 签名进行验证

如果签名验证成功,会继续检查 Claims。如果存在 iat、nbf 或 exp 等 Claims,APISQL 会主动根据这些 Claims 检查 JWT 的合法性。之外,APISQL 也支持用户自定义的 Claims 检查。签名验证和 Claims 检查均通过后,APISQL 才会接受客户端的连接请求。

加密方式为 hmac-based,即 JWT 使用对称密钥生成签名和校验签名(支持 HS256、HS384 和 HS512 算法)

6.2 权限信息

JWT 权限列表定义了 api_groups 字段,用于指定允许访问的接口组信息

示例:

js
const JWT_Claims={
    // 如果存在 iat、nbf 或 exp 等 Claims,APISQL 会主动根据这些 Claims 检查 JWT 的合法性。
    "exp": 1706844358,
    // 允许指定接口组(区分大小写),`REST`&`SUDB` 模块 也是一个特殊的接口组
    // 支持数据 或 字符串 'all' :允许所有,包含 'REST','SUDB'
    //      'all' :允许所有,包含 'REST','SUDB'    
    //      [] :允许的接口组名称,或接口组ID(若使用ID,则ID是 number 类型)    
    "api_groups":"all" ,
}

// 允许指定接口组(使用接口组名称)
const JWT_Claims={
    "exp": 1706844358
    "api_groups": ["接口组1""接口组2"] 
}

// 允许指定接口组(使用接口组ID, ID 为 number 类型)
const JWT_Claims={
    "exp": 1706844358,
    "api_groups": [1001,1002] 
}

// 允许 SUDB ,`REST` 模块
const JWT_Claims={
    "exp": 1706844358,
    "api_groups": ["SUDB","REST"] 
}

6.3 请求示例

  • 先使用密钥生成签名
  • Authorization 类型(auth-scheme): Bearer
  • 由于JWT 可以有多个,因此需要明确指出 JWT 是哪个访问控制策略的
    1. 在 Payload 中使用aud 声明 访问控制的名称
    2. 在使用签名时,用前缀携带, 格式 访问控制的名称@JWT

如: 访问控制的名称 为 jwt_A,JWT为 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....

  1. 签发时已声明 aud 信息,

    HTTP
    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  2. 签发时未声明aud 信息,则使用前缀

    HTTP
    Authorization: Bearer jwt_A@eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

6.4 在项目中配置

在 项目中,点击顶部导航栏的访问控制,在打开的认证页面,单击创建,选择认证方式为 JWT: alt text

  • 过期时间: 用标准 JWT 中 预设的 claims exp 表示, 单位为秒
  • Secret:用于校验签名的密钥,与生成签名时使用的密钥相同
  • Secret 使用 Base64 编码:在使用 Secret 校验签名时是否需要先对其进行 Base64 解密
  • Payload 中指明权限信息的 Claim: 可自定义一个 Claim 来表示 权限信息
  • Payload 中指明权限信息的 Claim 不存在时通过认证: Payload 解码后若表示权限的 Claim 未找到,是否通过认证; 默认值: false
  • 加密方式: hmac-based ,暂不支持 public-key