apiSQL

Appearance

访问控制 ​

以接口组为最小单位，一个访问控制策略可以绑定多个接口组，同样，接口组可以被多个访问控制策略绑定(多对多关系) 若同一个接口组被绑定到多个访问策略，则按照认证类型的优先级: 本平台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

Copyright © 2022 - present apisql (V:1.0.16-B250527)