wehub-resource-sync
6.7 KiB
鉴权插件规范
范围
鉴权插件类别允许 Nacos 在不修改 API Controller 或资源解析器的情况下替换认证与授权实现。 通用契约为：
IdentityContext + Resource + Action -> 允许或拒绝
鉴权插件不拥有 Nacos 资源模型。它消费由 Nacos Controller、协议过滤器和资源解析器创建的 资源。共享权限模型由 鉴权与权限规范 定义，通用插件生命周期 规则由 Nacos 插件化规范 定义。
服务端 SPI
服务端鉴权插件实现 AuthPluginService。
| 方法 | 要求 |
|---|---|
getAuthServiceName() |
返回稳定的插件名称，由 nacos.core.auth.system.type 选择。 |
identityNames() |
声明可以从请求中提取的身份字段。 |
enableAuth(action, type) |
判断该动作和 SignType 是否需要鉴权。 |
validateIdentity(identityContext, resource) |
认证调用方，并补充身份元数据。 |
validateAuthority(identityContext, permission) |
校验调用方是否拥有目标资源和动作的权限。 |
isLoginEnabled() |
声明是否暴露插件提供的登录能力。 |
isAdminRequest() |
声明当前请求是否属于管理员初始化流程。 |
当身份或权限被拒绝时，插件必须抛出或返回 Nacos 鉴权异常，使协议层可以映射为标准 API 错误。
客户端 SPI
客户端鉴权插件负责为 Java SDK 请求提供身份材料。客户端插件只能注入所选服务端插件需要的 凭据或 token，不得改变请求载荷的语义。
Java 客户端通过 SPI 加载 AbstractClientAuthService 实现，并通过
ClientAuthPluginManager 和 SecurityProxy 暴露给请求链路。
| 方法 | 要求 |
|---|---|
login(properties) |
从客户端配置或外部身份提供方初始化或刷新身份材料。 |
setServerList(serverList) |
接收当前客户端侧 server list，用于登录或 token 刷新请求。 |
setNacosRestTemplate(template) |
接收插件登录调用使用的 HTTP client。 |
getLoginIdentityContext(resource) |
返回需要附加到该 RequestResource 请求上的 header 或参数。 |
shutdown() |
释放插件自身资源。 |
SecurityProxy 会合并所有已加载客户端鉴权服务返回的 identity context。当 Java 客户端收到
需要重新登录的鉴权失败时，它会标记已加载客户端鉴权服务在下一次 login 时刷新。
Java 客户端必须支持内置用户名/密码和 token 流程。自定义客户端鉴权插件可以提供 AK、 签名、证书或外部 token，但必须与匹配的服务端鉴权插件声明的身份字段保持兼容。
内置 Java 客户端鉴权服务属于客户端扩展。默认用户名/密码 token 服务与 默认 Nacos 鉴权插件集成，RAM 和 OIDC 服务则通过同一个客户端 SPI 提供其他身份材料。这些内置 实现的 Java 客户端细节由 Java SDK 实现规范定义。
客户端鉴权插件必须保持 Nacos 资源语义。插件需要按资源签名时，必须使用传入的
RequestResource 中的 config、naming、AI、lock 或显式资源字段，而不是自行解析传输
payload。
选择与状态
选中的鉴权实现由以下配置指定：
nacos.core.auth.system.type=nacos
鉴权插件同时以 auth 类型注册到核心插件系统。只有被选中且处于启用状态的鉴权插件可以
处理请求。如果插件已加载但被插件状态禁用，则不得参与鉴权判断。
身份上下文
IdentityContext 是与传输协议无关的调用方描述。它可以包含：
- 远端 IP 等内置字段。
Authorization、accessToken、username、password等 header 或参数。- AK、签名、租户声明、外部主体等插件自定义字段。
- 已认证用户名、用户 ID、全局管理员标记等认证结果元数据。
身份字段名属于插件契约的一部分。服务端和客户端插件实现必须对这些名称达成一致。
资源与权限
鉴权插件接收 Nacos Resource 和 Permission 对象。插件可以将这些对象映射到外部权限
系统，但必须保留：
- 命名空间隔离。
- 分组或资源类型语义。
- 资源名语义。
READ和WRITE动作语义。- 通过
SignType.SPECIFIED声明的显式资源。
插件 API
如果鉴权插件暴露 HTTP API，这些 API 必须：
- 使用
/v3/auth/{resource}路径族。 - 使用
Result<T>作为响应封装。 - 使用标准 Nacos 错误码和异常处理。
- 为受保护的管理端点添加
@Secured。 - 记录登录、初始化等有意公开的端点。
默认 Nacos 鉴权插件是当前 /v3/auth/user、
/v3/auth/role 和 /v3/auth/permission API 的参考实现。这些端点的 HTTP 鉴权规则由
HTTP 鉴权规范 定义。
内置鉴权实现
| 实现 | 运行位置 | 规范 |
|---|---|---|
| 默认 Nacos 鉴权 | 服务端插件和 Java 客户端 token 集成。 | 默认鉴权插件实现规范 |
| RAM 兼容鉴权 | Java 客户端鉴权扩展和服务端兼容契约。 | RAM 鉴权插件规范 |
| OIDC 鉴权 | 服务端插件和 Java 客户端 client-credentials 集成。 | OIDC 鉴权插件规范 |
与可见性的关系
鉴权回答调用方是谁，以及调用方是否拥有某个资源/动作的权限。可见性回答单资源操作或范围 查询中哪些资源应对调用方可见。
可见性插件可以将显式权限检查委托回当前选中的鉴权插件。 因此鉴权插件必须让显式资源和领域资源的权限判断都保持稳定。
安全要求
内置 Nacos 鉴权插件面向可信内网环境设计，并不是针对恶意公网环境的完整强鉴权方案。需要 更强认证能力的部署，应提供或选择符合自身安全要求的鉴权插件。