Nacos v3 HTTP API 授权机制权威指南Authorization Tuple、AuthFilter 分发与 Secured 注解实战【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacosNacos 在 v3 HTTP API 中引入了一套统一的授权模型通过apiType signType resource action tags五元组刻画每一次请求的鉴权语义并以AuthAdminFilter/AuthFilter双过滤器按 API 类型进行分发。本文以 authorization-spec.md 为骨架结合仓库源码与测试用例完整讲解 v3 HTTP API 的授权声明、公开端点边界、插件化认证 API 与匿名例外帮助你为 Nacos 二次开发、自研认证插件或审计鉴权行为时建立精确的决策依据。1. 授权元组Authorization Tuplev3 HTTP API 鉴权的核心抽象v3 HTTP API 的最终生效授权元组由五个要素构成apiType signType resource action tags各要素的含义如下要素作用说明apiType区分 API 受众将请求划分为OPEN_API、ADMIN_API、CONSOLE_API与内部 APIsignType标识资源域如CONFIG、NAMING、AI、CONSOLE决定资源如何解析与授权resource受保护资源路径或逻辑资源名例如配置的{namespaceId}:{group}:config/{dataId}action操作类型通常为READ或WRITEtags附加行为标记如ONLY_IDENTITY仅校验身份不校验权限、ALLOW_ANONYMOUS允许匿名访问这五元组的语义在 auth-permission-spec.md 中定义得更为完整共享认证领域模型将授权建模为request identity - authenticated subject - roles - permissions - resource/action而ApiType、SignType、ActionTypes是这一模型在 HTTP 传输层的具体落地。其中ActionTypes的存储值为rREAD与wWRITE实现允许存储rw合并动作但端点注解必须使用与 API 行为精确匹配的显式动作。从源码结构看ApiType枚举定义在 ApiType.java包含四个值ADMIN_APINacos 维护者或管理员使用的管理 APICONSOLE_APINacos Web 控制台使用的 APIOPEN_API客户端或基础数据操作使用的开放 APIINNER_APINacos 服务器之间使用的内部 API。2. 过滤器分发Filter Split按 apiType 分流鉴权当前代码按apiType将鉴权责任分派给两个过滤器二者都继承自统一的AbstractWebAuthFilterAuthAdminFilter处理Secured.apiType()为ApiType.ADMIN_API的方法AuthFilter处理apiType()不是ADMIN_API的受保护 API包括OPEN_API、CONSOLE_API以及内部 API。这一分派逻辑在源码中有直接体现。AuthAdminFilter的isMatchFilter判断ApiType.ADMIN_API.equals(secured.apiType())见 AuthAdminFilter.java而AuthFilter则取反判断!ApiType.ADMIN_API.equals(secured.apiType())见 AuthFilter.java注释明确说明 ADMIN API use AuthAdminFilter to handle。AuthFilter还有一个特殊的内部 API 处理逻辑当请求是INNER_API且InnerApiAuthEnabled未启用时旧版本升级场景checkServerIdentity直接返回成功以兼容旧版 Nacos 服务器不带 server identity 的情况见 AuthFilter.java。两个过滤器的公共执行骨架在 AbstractWebAuthFilter.java 中流程为通过ControllerMethodsCache定位请求对应的 Controller 方法若方法不存在或未标注Secured直接放行将secured.apiType()写入RequestContext的AuthContext调用isMatchFilter(secured)判断本过滤器是否接管该请求parseIdentity解析IdentityContext若全局鉴权未启用isAuthEnabled()为 false放行校验 server identity若FAIL直接返回拒绝响应若MATCHED则标记SERVER_IDENTITY并放行判断该 action/domain 是否启用鉴权enableAuth未启用则放行解析Resource执行validateIdentity与validateAuthority(new Permission(resource, action))任一校验失败抛出AccessException最终统一映射为 403/ACCESS_DENIED响应。值得注意的细节是isIdentityOnlyApi当Secured携带ONLY_IDENTITY标签时只校验身份、跳过权限校验见 AbstractWebAuthFilter.java这与授权元组中tags的ONLY_IDENTITY语义完全对应。3. 必需注解v3 HTTP API 默认声明 Securedv3 HTTP API 默认应声明Secured除非端点明确属于以下四类public刻意公开bootstrap-only仅引导阶段health-oriented面向健康检查兼容路径由文档化兼容机制处理。同时注解的apiType选择遵循约定Admin API 使用ApiType.ADMIN_APIConsole API 使用ApiType.CONSOLE_APIOpen API 使用ApiType.OPEN_API。每个非公开的 v3 HTTP API 与 gRPC 请求处理器都必须声明预期的认证元数据。Secured注解定义在 Secured.java字段如下字段默认值用途actionActionTypes.READ必需动作通常为 READ 或 WRITEresource空字符串显式资源名主要用于SPECIFIED或 console 资源signTypeSignType.NAMING资源解析与权限评估使用的域parserDefaultResourceParser.class默认解析器不足时的自定义资源解析器tags{}附加元数据注入Resource.propertiesapiTypeApiType.OPEN_APIAPI 受众与鉴权作用域资源解析遵循固定的优先级顺序定义于 auth-permission-spec.md非空的resource直接转换为SPECIFIED资源非默认的方法级parser解析请求同时保留声明的signType与apiType否则协议按signType选择类型化解析器若无类型化解析器DefaultResourceParser返回空资源。关键约束显式选择的解析器在构造或解析失败时不得静默回退到空资源因为回退到更宽泛的资源会削弱授权强度此类失败应视为请求处理错误。4. 公开端点与 Bootstrap 端点无 Secured 的合法边界端点只有符合刻意公开、仅引导、面向健康、仅兼容四类条件时才可省略Secured。公开端点必须在所属 spec 中明确标记为 public并且不得暴露敏感运维细节。当前已实现的公开端点清单GET /v3/admin/core/stateGET /v3/admin/core/state/livenessGET /v3/admin/core/state/readinessGET /v3/console/server/stateGET /v3/console/server/announcementGET /v3/console/server/guideGET /v3/console/health/livenessGET /v3/console/health/readiness对应的 Admin API 与 Console API 文档将这些端点标记为 public、无需身份信息。仓库中亦有佐证客户端在启动探测时会调用/v3/admin/core/state/liveness见 NamingHttpClientProxy.java集成测试用例CoreStateAdminApiOpenApiITCase对/nacos/v3/admin/core/state进行了验证见 CoreStateAdminApiOpenApiITCase.javaConsole 侧测试则覆盖了/v3/console/health/liveness与/v3/console/server/state见 ConsoleHealthControllerTest.java 与 ConsoleServerStateControllerTest.java。Bootstrap 行为特例POST /v3/auth/user/admin当全局管理员不存在且认证系统为NACOS时允许创建第一个管理员用户。这属于由服务端状态守卫的一次性初始化与 auth-permission-spec.md 中由服务器端状态守卫的一次性管理员初始化的公开端点定义一致。5. 插件提供的认证 API/v3/auth/* 归属插件/v3/auth/*的 API 面属于认证插件。随 Nacos 一起发布的默认 Nacos 认证插件见 default-auth-plugin-spec.md提供用户、角色、权限与登录端点且必须遵循 api-spec.md 中关于路径形态、响应形态、校验与错误行为的 Nacos HTTP API 规则。第三方认证插件若通过 Nacos 暴露 HTTP API也应遵循同样的规则。这些端点虽然从路径上不属于 Open、Admin 或 Console API但仍必须符合 Nacos v3 API 的响应、错误与授权约定。这一设计将认证能力完全插件化选择何种认证插件由nacos.plugin.auth.type指定nacos.core.auth.system.type仅作为遗留的启动别名。认证插件与可见性插件的职责边界来自 auth-permission-spec.md层核心问题典型 SPI作用域认证插件调用者能否为解析出的 resource/action 调用该 APIAuthPluginService请求准入与权限决策可见性插件调用者能否查看或修改该具体资源范围查询应返回哪些资源VisibilityService资源实例可见性与查询规划两层正交通过Secured认证不代表每条匹配的数据行都可见。对于可见性感知的资源推荐流程为Secured AuthPlugin - VisibilityService - 业务操作列表与搜索 API 必须在分页与总数统计之前应用可见性过滤。6. 已实现的例外ALLOW_ANONYMOUS 匿名访问需要端点级文档化的已实现行为包括部分 AI 客户端端点通过ALLOW_ANONYMOUS允许匿名访问。仓库中实际落地了该标签。在 AgentSpecClientController.java 与 SkillClientController.java 上Secured使用parser AgentSpecNameHttpResourceParser.class, tags {ALLOW_ANONYMOUS}声明在 AgentSpecAdminController.java 与 SkillAdminController.java 上同样出现了tags {ALLOW_ANONYMOUS}。这表明 AI 资源域MCP、prompt、agent、skill 等在 v3 路由中确实存在刻意放开匿名访问的端点属于授权元组中tags维度在真实控制器上的直接体现。tags会被注入到Resource.properties因此无论是ONLY_IDENTITY还是ALLOW_ANONYMOUS都可以作为授权插件的决策输入而AbstractWebAuthFilter已内置了对ONLY_IDENTITY的快捷处理。7. 授权作用域开关三个配置项决定鉴权是否生效v3 HTTP API 的鉴权启用按 API 受众分域控制配置项如下来自 auth-permission-spec.md配置项作用域nacos.core.auth.enabled启用 Open API 与通用认证系统的鉴权nacos.core.auth.admin.enabled启用 Admin API 的鉴权nacos.core.auth.console.enabled启用 Console API 的鉴权与登录行为这些开关最终汇聚到NacosAuthConfig.isAuthEnabled()由两个过滤器在doFilter流程中读取见 AbstractWebAuthFilter.java。若全局开关关闭携带Secured的请求也会直接放行——因此生产环境务必在完成认证插件配置后开启对应作用域的开关。另外注意一个安全边界即便公开的 Open API 鉴权被关闭集群进入强制模式后JRaft 原生 gRPC 的服务器身份校验也不得被绕过详见 auth-permission-spec.md。8. 实战建议为 v3 端点正确声明鉴权元数据综合规范与源码为新的 v3 HTTP API 端点添加授权时的决策路径可归纳为先问是否需要保护健康探测、一次性管理员引导、刻意公开的状态端点可省略Secured但必须在文档中明确标记 public其余端点一律声明Secured。再选apiType按受众选择ADMIN_API/CONSOLE_API/OPEN_API/INNER_API过滤器会自动按此分流。再定signType与resource优先复用CONFIG、NAMING、AI、CONSOLE等既有域的解析器资源形态遵循{namespaceId}:{group}:config/{dataId}等标准形式参见 auth-permission-spec.md 的资源权限命名表。选择action查询/列表/详情/订阅用READ创建/更新/删除/发布/注册用WRITE必须与 API 行为精确一致。必要时补充tags仅校验身份用ONLY_IDENTITY刻意允许匿名用ALLOW_ANONYMOUS自定义标签会进入Resource.properties供插件消费。注意解析失败语义自定义parser失败不得静默回退到空资源应作为请求错误处理。在此基础上建议对照 api-spec.md响应与错误行为、auth-plugin-spec.md插件契约与 visibility-plugin-spec.md数据级可见性进一步核对端点行为确保授权声明与数据可见性两层都能覆盖到位。【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考