Nacos 鉴权与权限模型全解析从 RBAC 到 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/nacosNacosAn easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications将认证Authentication与授权Authorization拆分为请求级准入 数据级可见性两层正交模型并以内置 RBAC 为基础、插件 SPI 为扩展点统一覆盖 HTTP API、gRPC API、插件 API 与服务端内部调用。本文以仓库中 鉴权与权限规范 为骨架结合源码与默认配置讲清Secured注解、资源解析、授权流程、权限资源命名与鉴权开关读完即可掌握 Nacos 权限体系的设计脉络与实战配置方法。一、模型总览请求身份到资源动作的授权链Nacos 授权模型可以抽象为一条单向链路请求身份 - 已认证主体 - 角色 - 权限 - 资源/动作内置实现采用 RBAC基于角色的访问控制请求先被解析为已认证主体用户用户被授予角色角色携带对资源 动作的权限最终决定该请求能否访问目标资源。自定义鉴权插件可以接入 LDAP、OIDC 等外部身份系统但无论接入何种身份源都必须通过身份、资源、动作这套语义来评估 Nacos 请求从而保证插件体系与内置模型的行为可互换。该模型的传输细节由 HTTP 鉴权规范 与 gRPC API 规范 定义插件契约由 鉴权插件规范 与 可见性插件规范 定义传输过滤器执行与AuthContext写入则遵循 请求过滤与运行时上下文规范。二、鉴权插件与可见性插件两层正交模型Nacos 将请求级授权与数据级可见性分开处理二者分别由两个 SPI 承担层次主要问题典型 SPI范围鉴权插件该调用方是否可以针对解析出的资源/动作调用这个 APIAuthPluginService请求准入与权限判断可见性插件该调用方是否可以看见或修改这个具体资源或范围查询应该返回哪些资源VisibilityService资源实例可见性与查询计划从源码看AuthPluginService见 AuthPluginService.java定义了identityNames()声明请求需要携带哪些身份信息如 username、password、accessToken、enableAuth(action, type)判断该插件是否为某动作与领域启用鉴权、validateIdentity(identityContext, resource)校验身份合法性、validateAuthority(identityContext, permission)校验对某资源的权限四个核心方法外加isLoginEnabled()、isAdminRequest()等默认能力钩子。而VisibilityService见 VisibilityService.java则聚焦资源粒度resolveDefaultScopeForCreate决定新建资源的默认可见范围、validateVisibility校验单个资源的可见性、adviseQuery为列表/搜索查询给出可见性裁剪建议。两层是正交关系可以独立存在与组合鉴权插件可以在没有可见性插件的情况下存在可见性插件也可以独立存在但每个领域必须定义没有请求身份时的行为可见性插件可以复用鉴权插件产出的身份也可以把显式资源权限检查委托回当前选中的鉴权插件通过Secured鉴权只代表请求级准入通过不代表所有匹配数据行都可见。对于具备可见性语义的资源推荐请求流程为Secured AuthPlugin - VisibilityService - 业务操作错误语义上规范给出了明确约定单资源读在可见性拒绝时返回 not found 以隐藏资源存在性写操作在调用方能定位资源但不能修改时应返回 access denied列表和搜索 API 必须在产生分页数据和总数之前应用可见性避免泄露不可见资源的存在与数量。三、RBAC 模型与核心概念3.1 RBAC 基本元素默认权限模型包含五个概念概念含义用户可以登录或调用 API 的认证主体角色分配给用户的命名权限组权限某个角色对某个 Nacos 资源允许执行的动作资源由命名空间、分组或资源类型、资源名和领域类型共同标识的 Nacos 对象动作操作类型目前为读或写ROLE_ADMIN是全局管理员角色全局管理员会跳过普通资源权限检查。该角色常量在默认鉴权插件中定义为GLOBAL_ADMIN_ROLE ROLE_ADMIN见 AuthConstants.java。3.2ApiTypeAPI 受众与鉴权开关范围ApiType描述 API 的受众决定请求适用的鉴权开关范围。枚举定义见 ApiType.java值含义OPEN_API面向应用或 SDK 的客户端 APIADMIN_API面向维护者、工具和网关的管理 APICONSOLE_APINacos 控制台使用的 APIINNER_API服务端内部 API通常由服务端身份保护3.3SignType资源解析与授权领域SignType标识用于解析和授权资源的领域。源码中以字符串常量定义见 SignType.java值含义CONFIG配置资源NAMING服务发现和注册资源AIMCP、Prompt、Agent、Tool 等 AI 注册中心资源CONSOLE用户、角色、权限等控制台管理资源LOCK锁资源SPECIFIED由受保护端点显式提供的资源字符串3.4ActionTypes读与写动作只有两种存储值为单字符值存储值语义READr查询、列表、详情、订阅、监听或只读查看WRITEw创建、更新、删除、发布、注册、注销或状态变更实现可以存储rw这类组合动作但端点注解必须使用与 API 行为匹配的明确动作避免宽泛授权。枚举定义见 ActionTypes.java。3.5Secured端点级授权声明Secured是端点级声明把 Controller 或请求处理器绑定到鉴权模型。完整定义见 Secured.java字段目的默认值action需要的动作通常为READ或WRITEActionTypes.READresource显式资源名主要用于SPECIFIED或控制台资源空字符串signType用于资源解析和权限判断的领域SignType.NAMINGparser默认解析器不足时使用的自定义资源解析器DefaultResourceParser.classtags复制到Resource.properties的附加元数据空数组apiTypeAPI 受众与鉴权范围ApiType.OPEN_API在实际 Controller 中典型用法形如Secured(action ActionTypes.READ, signType SignType.AI, apiType ApiType.CONSOLE_API)例如 ConsoleAgentController.java 对 Agent 的每个读写端点都声明了SignType.AI与ApiType.CONSOLE_API控制台管理类资源则使用显式resource如Secured(resource .../force-publish, ...)。这套声明让鉴权元数据直接附着在端点定义上可被框架统一扫描执行。资源解析优先级规范明确定义resource非空时直接转换为SPECIFIED资源方法级parser不是默认DefaultResourceParser时由其解析请求并保留注解声明的signType和apiType否则根据signType选择协议对应的类型化 Parser配置、注册发现、AI 等领域各有专属解析器找不到类型化 Parser 时由DefaultResourceParser返回空资源。关键约束显式指定的 Parser 构造或解析失败时不得静默降级为空资源——该失败应作为请求处理错误抛出因为继续使用更宽泛的资源可能削弱鉴权约束。此外每个非公开的 v3 HTTP API 和 gRPC 请求处理器都必须声明预期的鉴权元数据公开端点必须由所属规范明确记录。四、授权流程与内部传输保护4.1 通用鉴权流程一次 Nacos 请求的鉴权按如下步骤执行定位请求的Secured元数据从 header、参数、token、证书或连接器元数据中构造IdentityContext从请求参数或Secured显式资源中解析 NacosResource询问选中的鉴权插件该动作和领域是否启用鉴权对应AuthPluginService.enableAuth校验身份对应AuthPluginService.validateIdentity针对Permission(resource, action)校验权限对应AuthPluginService.validateAuthority。4.2 服务端内部请求与 JRaft服务端内部请求在继续处理前还可能要求配置的服务端身份 key 和 value 校验通过见下文的nacos.core.auth.server.identity.*。JRaft 原生 gRPC 虽然不使用 NacosRequestHandler仍属于服务端内部传输客户端通过 gRPCCallCredentials传输 server identity服务端通过ServerInterceptor校验。集群进入强制状态后关闭公开 Open API 鉴权不得绕过 JRaft server identity——内部传输通道的安全底线不随业务鉴权开关而变化。五、资源权限名通配符与标准形式Nacos 权限基于 资源模型 派生的资源进行评估NamespaceId - Group 或 resourceType - resourceName标准资源形式如下领域权限资源形式配置{namespaceId}:{group}:config/{dataId}注册发现{namespaceId}:{group}:naming/{serviceName}AI{namespaceId}:{group}:ai/{resourceName}并携带 AI 资源元数据控制台console/{managementResource}显式资源Secured(resource ...)提供的字符串默认鉴权实现支持在权限资源中使用*通配符例如*:*:config/*表示全部命名空间下全部配置。命名空间、分组、资源类型和资源名的具体语义以 资源模型规范 为准。六、鉴权开关范围与默认配置鉴权启用状态按 API 受众划分互不影响可在 application.properties 中独立配置配置范围默认值nacos.core.auth.enabled启用 Open API 和通用鉴权系统控制 SDK 与 gRPC 请求认证falsenacos.core.auth.admin.enabled启用 Admin API 鉴权控制/v3/admin/*HTTP 请求truenacos.core.auth.console.enabled启用 Console API 和登录行为鉴权控制/v3/console/*HTTP 请求true选中的鉴权插件由nacos.plugin.auth.type指定默认nacos还支持ldap、oidc及自定义实现nacos.core.auth.system.type继续作为历史启动 alias 保留。配套的关键配置项# 选中的鉴权插件默认 nacos nacos.plugin.auth.typenacos # 服务端身份白名单服务端内部请求互信 nacos.core.auth.server.identity.key nacos.core.auth.server.identity.value # 内置 nacos 插件的鉴权信息缓存开启后更新可能有 15 秒延迟 nacos.plugin.auth.nacos.caching.enabledtrue # Token 解析与校验缓存 nacos.plugin.auth.nacos.token.cache.enablefalse # Token 过期时间秒默认 180005 小时 nacos.plugin.auth.nacos.token.expire.seconds18000 # Token 密钥Base64 字符串生产环境必须设置 nacos.plugin.auth.nacos.token.secret.key # 是否允许匿名读 AI 资源skill、agentspec默认 false #nacos.plugin.auth.nacos.anonymous.ai.enabledtrue同时可通过nacos.security.ignore.urls配置鉴权忽略路径默认包含静态资源、/v1/auth/**、/actuator/**、健康检查等该配置未来将废弃。LDAP 插件配置位于nacos.plugin.auth.ldap.*url、base-dn、user-dn、filter-prefix 等OIDC 插件配置位于nacos.plugin.auth.oidc.*issuer-uri、client-id、roles-claim、admin-role 等旧键nacos.core.auth.plugin.*系列作为 alias 兼容保留新旧键同时配置时新键优先。七、插件 API 与公开端点/v3/auth/*下的鉴权相关 HTTP API 属于插件提供的 API。默认 Nacos 鉴权插件 提供用户、角色、权限和登录端点。这些端点按路径不归属于 Open、Admin 或 Console API但仍必须遵守 Nacos v3 API 的响应、错误和鉴权约定。公开端点是例外而非默认端点只有在所属规范和文档明确说明时才可以被设计为无需鉴权。典型例子包括登录端点认证本身由服务端状态保护的一次性管理员初始化为未认证探测而设计的健康检查或状态端点。当某个端点因兼容性而公开、而非当前设计要求公开时新文档化 API 应作为主 API旧端点只作为兼容面保留。这一约定与 v3 API 表面 的演进思路一致确保权限边界随 API 演进保持清晰。八、实践要点总结先分清楚两层请求能否调用AuthPluginService与能看到哪些数据VisibilityService是两回事Secured通过不代表数据全部可见列表类接口务必在分页与计数前应用可见性裁剪。注解语义要精确Secured的action必须与 API 行为一致能写READ就不要用rw资源解析失败不要依赖静默降级错误应显式抛出。开关按受众独立打开生产环境建议至少开启nacos.core.auth.admin.enabled与nacos.core.auth.console.enablednacos.core.auth.enabled则按是否需要对 SDK/gRPC 客户端做 RBAC 校验决定。内部传输单独加固配置nacos.core.auth.server.identity.key/value保护服务端内部调用JRaft 的 server identity 校验不随 Open API 鉴权开关变化。AI 资源纳入权限模型SignType.AI覆盖 MCP、Prompt、Agent、Tool 等 AI 注册中心资源匿名访问默认关闭需通过nacos.plugin.auth.nacos.anonymous.ai.enabled显式开启。【免费下载链接】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），仅供参考 Nacos 鉴权与权限模型全解析：从 RBAC 到 @Secured 的插件化授权架构
Nacos 鉴权与权限模型全解析从 RBAC 到 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/nacosNacosAn easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications将认证Authentication与授权Authorization拆分为请求级准入 数据级可见性两层正交模型并以内置 RBAC 为基础、插件 SPI 为扩展点统一覆盖 HTTP API、gRPC API、插件 API 与服务端内部调用。本文以仓库中 鉴权与权限规范 为骨架结合源码与默认配置讲清Secured注解、资源解析、授权流程、权限资源命名与鉴权开关读完即可掌握 Nacos 权限体系的设计脉络与实战配置方法。一、模型总览请求身份到资源动作的授权链Nacos 授权模型可以抽象为一条单向链路请求身份 - 已认证主体 - 角色 - 权限 - 资源/动作内置实现采用 RBAC基于角色的访问控制请求先被解析为已认证主体用户用户被授予角色角色携带对资源 动作的权限最终决定该请求能否访问目标资源。自定义鉴权插件可以接入 LDAP、OIDC 等外部身份系统但无论接入何种身份源都必须通过身份、资源、动作这套语义来评估 Nacos 请求从而保证插件体系与内置模型的行为可互换。该模型的传输细节由 HTTP 鉴权规范 与 gRPC API 规范 定义插件契约由 鉴权插件规范 与 可见性插件规范 定义传输过滤器执行与AuthContext写入则遵循 请求过滤与运行时上下文规范。二、鉴权插件与可见性插件两层正交模型Nacos 将请求级授权与数据级可见性分开处理二者分别由两个 SPI 承担层次主要问题典型 SPI范围鉴权插件该调用方是否可以针对解析出的资源/动作调用这个 APIAuthPluginService请求准入与权限判断可见性插件该调用方是否可以看见或修改这个具体资源或范围查询应该返回哪些资源VisibilityService资源实例可见性与查询计划从源码看AuthPluginService见 AuthPluginService.java定义了identityNames()声明请求需要携带哪些身份信息如 username、password、accessToken、enableAuth(action, type)判断该插件是否为某动作与领域启用鉴权、validateIdentity(identityContext, resource)校验身份合法性、validateAuthority(identityContext, permission)校验对某资源的权限四个核心方法外加isLoginEnabled()、isAdminRequest()等默认能力钩子。而VisibilityService见 VisibilityService.java则聚焦资源粒度resolveDefaultScopeForCreate决定新建资源的默认可见范围、validateVisibility校验单个资源的可见性、adviseQuery为列表/搜索查询给出可见性裁剪建议。两层是正交关系可以独立存在与组合鉴权插件可以在没有可见性插件的情况下存在可见性插件也可以独立存在但每个领域必须定义没有请求身份时的行为可见性插件可以复用鉴权插件产出的身份也可以把显式资源权限检查委托回当前选中的鉴权插件通过Secured鉴权只代表请求级准入通过不代表所有匹配数据行都可见。对于具备可见性语义的资源推荐请求流程为Secured AuthPlugin - VisibilityService - 业务操作错误语义上规范给出了明确约定单资源读在可见性拒绝时返回 not found 以隐藏资源存在性写操作在调用方能定位资源但不能修改时应返回 access denied列表和搜索 API 必须在产生分页数据和总数之前应用可见性避免泄露不可见资源的存在与数量。三、RBAC 模型与核心概念3.1 RBAC 基本元素默认权限模型包含五个概念概念含义用户可以登录或调用 API 的认证主体角色分配给用户的命名权限组权限某个角色对某个 Nacos 资源允许执行的动作资源由命名空间、分组或资源类型、资源名和领域类型共同标识的 Nacos 对象动作操作类型目前为读或写ROLE_ADMIN是全局管理员角色全局管理员会跳过普通资源权限检查。该角色常量在默认鉴权插件中定义为GLOBAL_ADMIN_ROLE ROLE_ADMIN见 AuthConstants.java。3.2ApiTypeAPI 受众与鉴权开关范围ApiType描述 API 的受众决定请求适用的鉴权开关范围。枚举定义见 ApiType.java值含义OPEN_API面向应用或 SDK 的客户端 APIADMIN_API面向维护者、工具和网关的管理 APICONSOLE_APINacos 控制台使用的 APIINNER_API服务端内部 API通常由服务端身份保护3.3SignType资源解析与授权领域SignType标识用于解析和授权资源的领域。源码中以字符串常量定义见 SignType.java值含义CONFIG配置资源NAMING服务发现和注册资源AIMCP、Prompt、Agent、Tool 等 AI 注册中心资源CONSOLE用户、角色、权限等控制台管理资源LOCK锁资源SPECIFIED由受保护端点显式提供的资源字符串3.4ActionTypes读与写动作只有两种存储值为单字符值存储值语义READr查询、列表、详情、订阅、监听或只读查看WRITEw创建、更新、删除、发布、注册、注销或状态变更实现可以存储rw这类组合动作但端点注解必须使用与 API 行为匹配的明确动作避免宽泛授权。枚举定义见 ActionTypes.java。3.5Secured端点级授权声明Secured是端点级声明把 Controller 或请求处理器绑定到鉴权模型。完整定义见 Secured.java字段目的默认值action需要的动作通常为READ或WRITEActionTypes.READresource显式资源名主要用于SPECIFIED或控制台资源空字符串signType用于资源解析和权限判断的领域SignType.NAMINGparser默认解析器不足时使用的自定义资源解析器DefaultResourceParser.classtags复制到Resource.properties的附加元数据空数组apiTypeAPI 受众与鉴权范围ApiType.OPEN_API在实际 Controller 中典型用法形如Secured(action ActionTypes.READ, signType SignType.AI, apiType ApiType.CONSOLE_API)例如 ConsoleAgentController.java 对 Agent 的每个读写端点都声明了SignType.AI与ApiType.CONSOLE_API控制台管理类资源则使用显式resource如Secured(resource .../force-publish, ...)。这套声明让鉴权元数据直接附着在端点定义上可被框架统一扫描执行。资源解析优先级规范明确定义resource非空时直接转换为SPECIFIED资源方法级parser不是默认DefaultResourceParser时由其解析请求并保留注解声明的signType和apiType否则根据signType选择协议对应的类型化 Parser配置、注册发现、AI 等领域各有专属解析器找不到类型化 Parser 时由DefaultResourceParser返回空资源。关键约束显式指定的 Parser 构造或解析失败时不得静默降级为空资源——该失败应作为请求处理错误抛出因为继续使用更宽泛的资源可能削弱鉴权约束。此外每个非公开的 v3 HTTP API 和 gRPC 请求处理器都必须声明预期的鉴权元数据公开端点必须由所属规范明确记录。四、授权流程与内部传输保护4.1 通用鉴权流程一次 Nacos 请求的鉴权按如下步骤执行定位请求的Secured元数据从 header、参数、token、证书或连接器元数据中构造IdentityContext从请求参数或Secured显式资源中解析 NacosResource询问选中的鉴权插件该动作和领域是否启用鉴权对应AuthPluginService.enableAuth校验身份对应AuthPluginService.validateIdentity针对Permission(resource, action)校验权限对应AuthPluginService.validateAuthority。4.2 服务端内部请求与 JRaft服务端内部请求在继续处理前还可能要求配置的服务端身份 key 和 value 校验通过见下文的nacos.core.auth.server.identity.*。JRaft 原生 gRPC 虽然不使用 NacosRequestHandler仍属于服务端内部传输客户端通过 gRPCCallCredentials传输 server identity服务端通过ServerInterceptor校验。集群进入强制状态后关闭公开 Open API 鉴权不得绕过 JRaft server identity——内部传输通道的安全底线不随业务鉴权开关而变化。五、资源权限名通配符与标准形式Nacos 权限基于 资源模型 派生的资源进行评估NamespaceId - Group 或 resourceType - resourceName标准资源形式如下领域权限资源形式配置{namespaceId}:{group}:config/{dataId}注册发现{namespaceId}:{group}:naming/{serviceName}AI{namespaceId}:{group}:ai/{resourceName}并携带 AI 资源元数据控制台console/{managementResource}显式资源Secured(resource ...)提供的字符串默认鉴权实现支持在权限资源中使用*通配符例如*:*:config/*表示全部命名空间下全部配置。命名空间、分组、资源类型和资源名的具体语义以 资源模型规范 为准。六、鉴权开关范围与默认配置鉴权启用状态按 API 受众划分互不影响可在 application.properties 中独立配置配置范围默认值nacos.core.auth.enabled启用 Open API 和通用鉴权系统控制 SDK 与 gRPC 请求认证falsenacos.core.auth.admin.enabled启用 Admin API 鉴权控制/v3/admin/*HTTP 请求truenacos.core.auth.console.enabled启用 Console API 和登录行为鉴权控制/v3/console/*HTTP 请求true选中的鉴权插件由nacos.plugin.auth.type指定默认nacos还支持ldap、oidc及自定义实现nacos.core.auth.system.type继续作为历史启动 alias 保留。配套的关键配置项# 选中的鉴权插件默认 nacos nacos.plugin.auth.typenacos # 服务端身份白名单服务端内部请求互信 nacos.core.auth.server.identity.key nacos.core.auth.server.identity.value # 内置 nacos 插件的鉴权信息缓存开启后更新可能有 15 秒延迟 nacos.plugin.auth.nacos.caching.enabledtrue # Token 解析与校验缓存 nacos.plugin.auth.nacos.token.cache.enablefalse # Token 过期时间秒默认 180005 小时 nacos.plugin.auth.nacos.token.expire.seconds18000 # Token 密钥Base64 字符串生产环境必须设置 nacos.plugin.auth.nacos.token.secret.key # 是否允许匿名读 AI 资源skill、agentspec默认 false #nacos.plugin.auth.nacos.anonymous.ai.enabledtrue同时可通过nacos.security.ignore.urls配置鉴权忽略路径默认包含静态资源、/v1/auth/**、/actuator/**、健康检查等该配置未来将废弃。LDAP 插件配置位于nacos.plugin.auth.ldap.*url、base-dn、user-dn、filter-prefix 等OIDC 插件配置位于nacos.plugin.auth.oidc.*issuer-uri、client-id、roles-claim、admin-role 等旧键nacos.core.auth.plugin.*系列作为 alias 兼容保留新旧键同时配置时新键优先。七、插件 API 与公开端点/v3/auth/*下的鉴权相关 HTTP API 属于插件提供的 API。默认 Nacos 鉴权插件 提供用户、角色、权限和登录端点。这些端点按路径不归属于 Open、Admin 或 Console API但仍必须遵守 Nacos v3 API 的响应、错误和鉴权约定。公开端点是例外而非默认端点只有在所属规范和文档明确说明时才可以被设计为无需鉴权。典型例子包括登录端点认证本身由服务端状态保护的一次性管理员初始化为未认证探测而设计的健康检查或状态端点。当某个端点因兼容性而公开、而非当前设计要求公开时新文档化 API 应作为主 API旧端点只作为兼容面保留。这一约定与 v3 API 表面 的演进思路一致确保权限边界随 API 演进保持清晰。八、实践要点总结先分清楚两层请求能否调用AuthPluginService与能看到哪些数据VisibilityService是两回事Secured通过不代表数据全部可见列表类接口务必在分页与计数前应用可见性裁剪。注解语义要精确Secured的action必须与 API 行为一致能写READ就不要用rw资源解析失败不要依赖静默降级错误应显式抛出。开关按受众独立打开生产环境建议至少开启nacos.core.auth.admin.enabled与nacos.core.auth.console.enablednacos.core.auth.enabled则按是否需要对 SDK/gRPC 客户端做 RBAC 校验决定。内部传输单独加固配置nacos.core.auth.server.identity.key/value保护服务端内部调用JRaft 的 server identity 校验不随 Open API 鉴权开关变化。AI 资源纳入权限模型SignType.AI覆盖 MCP、Prompt、Agent、Tool 等 AI 注册中心资源匿名访问默认关闭需通过nacos.plugin.auth.nacos.anonymous.ai.enabled显式开启。【免费下载链接】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），仅供参考