访问控制
以接口组为最小单位,一个访问控制策略可以绑定多个接口组,同样,接口组可以被多个访问控制策略绑定(多对多关系) 若同一个接口组被绑定到多个访问策略,则按照认证类型的优先级: 本平台Token > 不鉴权(公开) > IP鉴权 > 平台用户 > API key > JWT 依次验证访问权限,直至拥有访问权限。
- 使用 HTTP Authorization 携带认证凭据
认证类型
1. 不鉴权(公开)
不对访问者进行身份认证(任何人可访问),多用于初期测试或开放类API,请务必注意数据安全。
- HTTP 不需要携带认证凭据
2. API Key
API Key,即 API 密钥。 申请时由 APISQL 下发,API 发起请求时,需要在请求中包含这个 API Key,服务端接收到请求后会检查这个 Key 是否有效。
2.1 请求示例
Authorization 类型(auth-scheme
): Bearer
Authorization: Bearer sk-****
- API 密钥一旦被盗,就可以无限期使用。除非且直到项目所有者撤销 API 密钥,因此请妥善保管
3. IP鉴权
允许某些IP地址访问,可用于有固定IP的用户/应用服务,如公网上部署的应用服务。
- HTTP 不需要携带认证凭据
4. 平台用户
已在平台注册的用户可以通过使用平台账户调用接口,一个用户只能创建一个策略。
调用 API 时,使用平台用户的 用户名
以及 密码
分别作为 Basic 认证的用户名与密码
4.1 请求示例
对于 "Basic" 身份验证,凭据首先将用户名和密码使用一个冒号(username:password)相结合,然后将生成的字符串编码为 base64(dXNlcm5hbWU6cGFzc3dvcmQ=)。
Authorization 类型(auth-scheme
): Basic
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
- Base64 编码很容易被解码,以得到原始的名称和密码,所以 Basic 身份验证是完全不安全的。因此总是推荐使用 HTTPS
5. 本平台Token
用户登录 APISQL 平台后会有一个 Token,项目成员可使用此 Token 作为接口认证凭据
- 需要在 项目设置 中启用
- 一般在开发&调试时使用,启用此设置后,在接口调式时可直接使用
本平台Token
作为认证凭据,不需要再去 访问控制 中设置 接口组 的访问权限 - 仅限于项目成员,便于开发且安全性强
5.1 请求示例
- Authorization 类型(
auth-scheme
):Bearer
- 需要携带固定的标识符
apisqlp
来代表 JWT 的来源,格式apisqlp@JWT
如: JWT为 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....
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 字段,用于指定允许访问的接口组信息
示例:
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 是哪个访问控制策略的
- 在 Payload 中使用
aud
声明访问控制的名称
- 在使用签名时,用前缀携带, 格式
访问控制的名称@JWT
- 在 Payload 中使用
如: 访问控制的名称 为 jwt_A
,JWT为 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....
签发时已声明
aud
信息,HTTPAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
签发时未声明
aud
信息,则使用前缀HTTPAuthorization: Bearer jwt_A@eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
6.4 在项目中配置
在 项目中,点击顶部导航栏的访问控制,在打开的认证页面,单击创建,选择认证方式为 JWT:
- 过期时间: 用标准 JWT 中 预设的 claims
exp
表示, 单位为秒 - Secret:用于校验签名的密钥,与生成签名时使用的密钥相同
- Secret 使用 Base64 编码:在使用 Secret 校验签名时是否需要先对其进行 Base64 解密
- Payload 中指明权限信息的 Claim: 可自定义一个 Claim 来表示 权限信息
- Payload 中指明权限信息的 Claim 不存在时通过认证: Payload 解码后若表示权限的 Claim 未找到,是否通过认证; 默认值: false
- 加密方式: hmac-based ,暂不支持
public-key