Nacos 默认鉴权插件实现规范深度解析nacos 与 ldap 双插件的配置、身份、RBAC 与 AI 可见性实战【免费下载链接】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 的默认鉴权实现包plugin-default-impl内置nacos与ldap两个鉴权插件为配置中心、注册中心以及 AI 资源Skill、AgentSpec、MCP Server 等提供用户名/密码登录、token 认证、RBAC 权限管理和可见性控制。本文以 specs/zh-cn/auth/default-auth-plugin-spec.md 为骨架结合仓库内的真实配置文件、服务端插件实现与 Java 客户端源码完整讲解默认鉴权框架的配置方式、插件化配置模型、身份识别规则、RBAC 存储模型、v3 鉴权 API、登录响应兼容性以及 AI 资源可见性集成的底层原理帮助你在一套可信内网部署中正确启用并加固 Nacos 鉴权。适用前提与边界默认实现定位为降低可信内网环境中的误用风险并非面向恶意公网环境的完整强鉴权方案。如需暴露公网应使用外部安全边界或选择更强的鉴权插件如 OIDC。范围默认鉴权实现包提供了什么默认鉴权实现包当前提供nacos和ldap两个鉴权插件nacos插件提供用户名/密码登录、token 认证、RBAC 权限管理以及 AI 资源使用的默认可见性集成。它实现了三个规范鉴权插件规范共享的鉴权与权限规范可见性插件规范ldap插件通过 LDAP 目录改变身份认证方式token 签名与有效期、Nacos 用户与角色存储及授权仍使用auth:nacos配置的基础设施。Java 客户端为默认插件暴露的用户名/密码和 token 流程提供NacosClientAuthServiceImpl实现在 client-basic/src/main/java/com/alibaba/nacos/client/auth/impl/NacosClientAuthServiceImpl.java。RAM、OIDC 等其他内置客户端鉴权服务属于 Java Client SDK 鉴权扩展由 Java SDK 实现规范 和鉴权插件规范 定义不属于本文描述的服务端默认插件实现。鉴权框架配置开关、作用域与插件选择以下配置负责鉴权模块的开关、API 作用域、启动期插件选择和服务端身份它们不属于auth:nacos插件自身的配置项配置目的nacos.core.auth.enabled启用通用鉴权系统和 Open API 鉴权控制 SDK 与 gRPC 请求认证。nacos.core.auth.admin.enabled启用 Admin API/v3/admin/*鉴权。nacos.core.auth.console.enabled启用 Console API/v3/console/*鉴权和默认登录行为。nacos.plugin.auth.type启动时选择鉴权插件默认nacosnacos.core.auth.system.type是历史 alias。nacos.core.auth.server.identity.key服务端之间调用的身份 key。nacos.core.auth.server.identity.value服务端之间调用的身份 value。在 distribution/conf/application.properties 中可以看到这些配置的真实模板### The auth plugin selected at startup. Legacy nacos.core.auth.system.type remains supported. ### Default nacos; ldap, oidc, and custom implementations are supported. nacos.plugin.auth.typenacos #nacos.core.auth.system.typenacos ### Whether open nacos server API auth system. It controls SDK and gRPC request authentication. nacos.core.auth.enabledfalse # Whether open nacos admin API auth system. It controls /v3/admin/* HTTP request authentication only. nacos.core.auth.admin.enabledtrue # Whether open nacos console API auth system. It controls /v3/console/* HTTP request authentication only. nacos.core.auth.console.enabledtrue ### The two properties is the white list for auth and used by identity the request from other server. nacos.core.auth.server.identity.key nacos.core.auth.server.identity.value需要注意两个要点插件选择需要重启生效因为nacos.plugin.auth.type在启动期决定加载哪个鉴权插件服务端身份值必须由部署环境独立配置不能使用默认值或共享值否则其他节点可伪造服务端之间的调用身份。统一管理的插件配置PluginConfigSpec 与配置快照nacos实现直接实现PluginConfigSpec并以可配置插件auth:nacos注册canonical 配置前缀为nacos.plugin.auth.nacos.。下表完整列出其配置项item keycanonical 静态 key历史静态 alias类型生效模式默认值敏感token.secret.keynacos.plugin.auth.nacos.token.secret.keynacos.core.auth.plugin.nacos.token.secret.keyStringRESTART空是token.expire.secondsnacos.plugin.auth.nacos.token.expire.secondsnacos.core.auth.plugin.nacos.token.expire.secondsNumberRUNTIME18000否token.cache.enablenacos.plugin.auth.nacos.token.cache.enablenacos.core.auth.plugin.nacos.token.cache.enableBooleanRUNTIMEfalse否caching.enablednacos.plugin.auth.nacos.caching.enablednacos.core.auth.caching.enabledBooleanRUNTIMEtrue否anonymous.ai.enablednacos.plugin.auth.nacos.anonymous.ai.enablednacos.core.auth.nacos.anonymous.ai.enabledBooleanRUNTIMEfalse否配置约束与行为要点token.expire.seconds必须大于零当任一 Nacos API 鉴权范围需要 token 能力时token.secret.key必须是有效的 Base64 内容且解码后不少于 32 字节。token 密钥必须由部署环境独立设置使用默认值或共享值不安全插件管理 API 必须返回脱敏后的密钥并禁止通过运行时更新修改该字段canonical key 与历史 alias 同时存在时canonical key 优先。历史 alias 为兼容已有部署继续可读并在使用时输出不包含配置值的迁移提示运行时和 localOnly 更新使用表中的 item key并遵循 Nacos 插件化规范 定义的 source 完整 Map 语义。配置模板中对应的真实写法distribution/conf/application.properties### Preferred keys for the built-in auth:nacos plugin are under nacos.plugin.auth.nacos. ### Legacy nacos.core.auth.plugin.nacos.*, nacos.core.auth.caching.enabled, and ### nacos.core.auth.nacos.anonymous.ai.enabled keys remain supported as aliases. nacos.plugin.auth.nacos.caching.enabledtrue nacos.plugin.auth.nacos.token.cache.enablefalse nacos.plugin.auth.nacos.token.expire.seconds18000 #nacos.plugin.auth.nacos.token.secret.keyVGhpc0lzTXlDdXN0b21TZWNyZXRLZXkwMTIzNDU2Nzg nacos.plugin.auth.nacos.token.secret.key ### Allow anonymous read access, default false, current only ai(skill, agentspec) supported. #nacos.plugin.auth.nacos.anonymous.ai.enabledtrue不可变 effective 配置快照与 token 生命周期插件持有不可变的 effective 配置快照对应源码 NacosAuthPluginConfig.java 中的NacosAuthPluginConfig类。应用新快照时更新 token 过期时间、token 缓存选择、鉴权信息缓存和匿名访问消费者不再直接读取 Spring 环境。其行为细节JWT parser 由已接受的 restart-only 密钥构建开启 token 缓存时在同一个基础 manager 外选择缓存包装关闭时切回基础 manager并清空 token 缓存token 过期时间变化时也会清空包装缓存使下一次取 token 使用新的运行时有效期已经返回给客户端的 token 仍按签名中的原过期时间有效。源码中的默认值与校验逻辑印证了规范描述NacosAuthPluginConfig.javapublic static final String TOKEN_SECRET_KEY token.secret.key; public static final String TOKEN_EXPIRE_SECONDS token.expire.seconds; public static final String TOKEN_CACHE_ENABLE token.cache.enable; public static final String CACHING_ENABLED caching.enabled; public static final String ANONYMOUS_AI_ENABLED anonymous.ai.enabled; private static final boolean DEFAULT_TOKEN_CACHE_ENABLE false; private static final boolean DEFAULT_CACHING_ENABLED true; private static final boolean DEFAULT_ANONYMOUS_AI_ENABLED false;其中from(MapString, String config, boolean tokenSecretRequired)会在 token 能力被要求时强制校验密钥非空并对密钥做 Base64/32 字节校验过期时间解析为parsePositiveLong即必须大于零。独立部署 Console 时的初始化顺序独立部署 Console 时Console 本地 auth initializer 会在开始接收请求前从STATIC DEFAULT对内置auth:nacos应用配置使稳定的TokenManagerDelegate完成具体 token manager 初始化。LDAP 等身份提供方仍消费auth:nacos持有的 token 和授权基础设施因此所有可配置鉴权实现都要执行 apply只有当前选中实现接收可选的启动生命周期回调。LDAP 插件配置auth:ldapldap实现同样实现PluginConfigSpec并以可配置插件auth:ldap注册canonical 配置前缀为nacos.plugin.auth.ldap.item keycanonical 静态 key历史静态 alias类型生效模式默认值敏感urlnacos.plugin.auth.ldap.urlnacos.core.auth.ldap.urlStringRESTARTldap://localhost:389否base-dnnacos.plugin.auth.ldap.base-dnnacos.core.auth.ldap.basedcStringRESTARTdcexample,dcorg否timeoutnacos.plugin.auth.ldap.timeoutnacos.core.auth.ldap.timeoutNumberRESTART3000否user-dnnacos.plugin.auth.ldap.user-dnnacos.core.auth.ldap.userDnStringRESTARTcnadmin,dcexample,dcorg否passwordnacos.plugin.auth.ldap.passwordnacos.core.auth.ldap.passwordStringRESTARTpassword是filter-prefixnacos.plugin.auth.ldap.filter-prefixnacos.core.auth.ldap.filter.prefixStringRESTARTuid否case-sensitivenacos.plugin.auth.ldap.case-sensitivenacos.core.auth.ldap.case.sensitiveBooleanRESTARTtrue否ignore-partial-result-exceptionnacos.plugin.auth.ldap.ignore-partial-result-exceptionnacos.core.auth.ldap.ignore.partial.result.exceptionBooleanRESTARTfalse否约束与细节timeout单位为毫秒且必须大于零插件管理 API 必须对绑定密码脱敏第一阶段 LDAP 自有字段全部为RESTART因此运行时或 local-only 更新只要新增、修改或移除这些字段都必须拒绝canonical key 与历史 alias 同时存在时 canonical key 优先历史模板中的nacos.core.auth.ldap.userdn没有生产读取点且原本想表达的 user DN pattern 语义不明确因此不作为兼容 alias。配置模板distribution/conf/application.properties### worked when nacos.plugin.auth.typeldap #nacos.plugin.auth.ldap.urlldap://localhost:389 #nacos.plugin.auth.ldap.base-dndcexample,dcorg #nacos.plugin.auth.ldap.timeout3000 #nacos.plugin.auth.ldap.user-dncnadmin,${nacos.plugin.auth.ldap.base-dn} #nacos.plugin.auth.ldap.passwordadmin #nacos.plugin.auth.ldap.filter-prefixuid #nacos.plugin.auth.ldap.case-sensitivetrue #nacos.plugin.auth.ldap.ignore-partial-result-exceptionfalseLDAP 插件同样持有不可变的 effective 配置快照Spring LDAP context 和 template 从已接受快照延迟构建LDAP 消费者不再通过第二套Value属性读取配置。LDAP 只改变身份认证方式token 签名和有效期、Nacos 用户与角色存储及授权仍使用auth:nacos配置的基础设施相关共享字段不复制到auth:ldapdefinitions。身份插件接受哪些输入如何降级为匿名插件接受以下身份输入输入用途Authorization: Bearer ...token 认证。accessToken通过请求参数或 header 进行 token 认证。username和password登录或直接用户名/密码认证。服务端身份 key/value服务端之间调用的身份。认证成功后插件会向IdentityContext补充已认证的 Nacos 用户和用户 ID。全局管理员状态由用户角色模型推导。匿名 AI 访问的三重条件与降级规则匿名 AI 访问只有在以下条件同时满足时才允许端点标记该请求允许匿名访问auth:nacos的anonymous.ai.enabled已启用默认插件将请求接受为内置匿名身份。关键降级规则容易踩坑只有当请求没有显式提供任何默认鉴权凭据 key时才允许降级为匿名身份提供Authorization、accessToken、username或password都视为显式凭据存在即使对应值为空白也一样如果这些凭据为空白或无效插件必须返回认证失败而不能降级为匿名身份在 HTTP 过滤器层身份或权限校验失败会被转换为 HTTP 403 的ACCESS_DENIED响应插件级失败码和消息可以保留在响应详情中。匿名用户的协调任务与权限保留开启匿名访问后只会立即开启匿名身份接受。后台协调任务随后保证保留的匿名用户和角色存在首次初始化时增加public:*:ai/*读权限并最后写入匿名角色绑定将该绑定作为持久化完成标记。多节点并发创建发生冲突时只有重新读取到预期持久化状态才视为成功。如果匿名角色绑定已经存在则视为已经初始化协调任务不会重新补回宽泛的默认权限从而保留管理员自定义的匿名权限范围关闭匿名访问只会停止匿名身份接受不删除保留的用户、角色或权限协调任务的本地状态只用于减少数据库操作不参与鉴权判断当找不到匹配的角色或权限时普通 RBAC 权限校验仍然必须拒绝匿名身份。默认 Java 客户端鉴权集成默认插件对应的 Java 客户端侧集成为NacosClientAuthServiceImpl。它通过客户端鉴权 SPI 加载注册文件位于 client-basic/src/main/resources/META-INF/services/com.alibaba.nacos.plugin.auth.spi.client.AbstractClientAuthService并在配置了username和password时调用默认/v3/auth/user/loginAPI。客户端实现身份材料契约NacosClientAuthServiceImplusername、password和accessToken。通过默认鉴权 API 登录附加返回的accessToken并在 token 过期前刷新。该集成不得修改请求 payload只提供当前服务端鉴权插件消费的身份材料。RAM、OIDC 等其他客户端鉴权实现作为 Java Client SDK 扩展在 Java SDK 实现规范 中描述。从源码可以印证 token 刷新机制NacosClientAuthServiceImpl.java客户端保存tokenTtl服务器签发的 token 有效期与tokenRefreshWindow随机刷新窗口刷新窗口通过generateTokenRefreshWindow(tokenTtl)随机生成数值范围为[tokenTtl/15, tokenTtl/10]随机化的目的是避免大量客户端同时重新登录给 Nacos 服务端造成压力在tokenTtl - tokenRefreshWindow时间窗内直接复用已持有的 token超过窗口且已配置username时才发起重新登录登录成功后将服务器返回的accessToken放入LoginIdentityContext随请求携带。对应的测试用例见 client-basic/src/test/java/com/alibaba/nacos/client/auth/impl/NacosClientAuthServiceImplTest.java。登录响应兼容性/v3/auth/user/login和遗留 v1 登录路由的默认鉴权登录成功响应保持为平铺 token 对象包含accessToken、tokenTtl、globalAdmin和username。该响应不使用ResultT包装因为已发布的 Java 客户端会直接解析这一平铺结构——修改包装形态会破坏现有客户端兼容性。登录失败的防枚举设计用户名不存在、密码错误或凭据为空时必须返回相同的 HTTP 403 状态和相同的通用响应体User not found! Please check user exist or password is right!HTTP 状态和响应体不得泄露用户名是否存在。两个安全细节未知用户认证不执行密码哈希比对避免攻击者使用任意用户名迫使服务端执行高 CPU 开销的密码编码操作防止资源耗尽型攻击用户存储或 token 签发的非预期故障属于运行异常不得转换为凭据错误避免掩盖真实故障、也避免向调用方暴露内部错误细节。RBAC 存储模型默认插件存储三类对象对象含义User用户名和密码身份。RoleInfo分配给用户名的角色。PermissionInfo分配给角色的资源和动作。ROLE_ADMIN是全局管理员角色。拥有该角色的用户可以访问所有资源和控制台管理操作。模糊搜索的_通配符转义规则用户、角色和权限的模糊搜索会用反斜杠转义_通配符使其按字面量匹配。反斜杠只在部分数据库上是 LIKE 的默认转义字符因此嵌入式存储显式声明ESCAPE \。两个必须遵守的细节该子句只作用于紧邻其前的那一个LIKE谓词所以组合多个模糊过滤条件的查询必须在每个谓词之后都重复声明该子句该规则适用于同一资源的所有模糊查询入口而不仅是分页搜索。控制台名称联想所依赖的名称搜索findRoleNames、findUserNames必须与分页搜索采用相同的转义方式使同一个关键字在两者中选出相同的记录。权限资源格式默认资源权限使用如下格式{namespaceId}:{group}:{signType}/{resourceName}示例资源示例配置数据public:DEFAULT_GROUP:config/example.properties注册发现服务public:DEFAULT_GROUP:naming/com.example.Service控制台用户console/users控制台角色console/roles控制台权限console/permissions可见性权限visibility/public/mcp/example-mcp规则权限资源中可以使用*作为通配符group 为空时权限检查会在 group 段使用*resource name 为空时资源名段会变成*存储资源以:开头时会补充默认命名空间publicSPECIFIED资源直接使用显式资源字符串存储动作可以是r、w或rw。非管理员角色不得管理控制台用户、角色或权限。默认鉴权 API 族v3默认插件拥有以下 v3 API 族路径目的/v3/auth/user用户管理和密码更新。/v3/auth/user/login登录和 token 签发。/v3/auth/user/admin当不存在全局管理员时进行管理员初始化。/v3/auth/role角色管理。/v3/auth/permission权限管理。/v3/auth/visibility显式资源可见性授权管理。安全约束管理端点必须使用控制台域的Secured资源保护例如console/users、console/roles、console/permissions和console/user/password登录端点是有意公开的管理员初始化端点只在无管理员初始化状态下有意暴露一旦全局管理员已经存在必须拒绝该端点这些 API 属于 V3 API 范围并必须遵守 HTTP 鉴权规范。可见性授权 API/v3/auth/visibility属于插件自有接口不是任何领域 controller 家族的一部分。它使用ApiType.ADMIN_API与 identity-only 请求鉴权并在授权服务层执行资源管理权限判断。启用鉴权时只有资源 owner 或全局管理员可以对该资源执行 grant 或 revoke 显式可见性授权。默认可见性实现AI 资源的访问控制默认可见性实现名称同样为nacos当前用于 AI 资源。其默认行为除非领域提供其他 scope新资源默认PRIVATE全局管理员可以读写所有具备可见性语义的资源资源 owner 可以读写该资源PUBLIC资源可以被非 owner 读取显式可见性权限可以通过鉴权插件授予访问匿名 AI 读访问只能通过匿名 AI 显式选择路径开启读拒绝可以返回 not found以隐藏资源存在性写拒绝返回 access denied。显式可见性权限资源使用如下格式visibility/{namespaceId}/{resourceType}/{resourceName}permissions.resource 列的扩容与数据库迁移默认 RBACpermissions.resource列必须保存完整、精确的 canonical 资源字符串且至少需要支持 512 个字符以避免命名空间资源持久化时被截断。资源匹配语义是精确且大小写敏感的因此默认 MySQL schema 对该列使用utf8mb4_bin并为permissions表使用ROW_FORMATDYNAMIC以保证现有(role, resource, action)索引在utf8mb4下可用。已有 MySQL 部署在应用升级 SQL 前应检查 MySQL 版本、InnoDB page size、row format 以及当前permissions表结构。运维人员必须先配置兼容的 InnoDB 存储模式再执行 MySQL 迁移以确保现有UNIQUE(role, resource, action)索引能够接受扩展后的utf8mb4resource 列。本次变更的升级脚本通过distribution/conf交付数据库升级脚本精确 schema 变更MySQLmysql-upgrade-visibility-permission-resource.sqlALTER TABLE permissions ROW_FORMATDYNAMIC, MODIFY COLUMN resource VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL;Derbyderby-upgrade-visibility-permission-resource.sqlALTER TABLE permissions ALTER COLUMN resource SET DATA TYPE VARCHAR(512);PostgreSQLpg-upgrade-visibility-permission-resource.sqlALTER TABLE permissions ALTER COLUMN resource TYPE VARCHAR(512);Oracleoracle-upgrade-visibility-permission-resource.sqlALTER TABLE permissions MODIFY (resource VARCHAR2(512 CHAR) NOT NULL);MySQL 脚本包含以下预检查先执行确认存储环境兼容SELECT VERSION(); SHOW VARIABLES LIKE innodb_page_size; SHOW VARIABLES LIKE innodb_default_row_format; SHOW CREATE TABLE permissions;这些脚本只扩展原始 canonical resource 列不得添加仅服务于授权列表反查的permissions(resource, action, role)或roles(role, username)索引。面向运维人员的完整升级说明见 doc/visibility-permission-resource-upgrade.md。显式可见性授权的存储与推导当前支持资源的显式可见性授权通过以下接口管理POST /v3/auth/visibility DELETE /v3/auth/visibility两个端点均使用ApiType.ADMIN_API保护。授权行为只读授权存储为动作r写或读写授权请求统一存储为rw并且rw在列表/搜索查询建议中隐式包含读权限授权数据复用默认 RBAC 持久化在鉴权后端以插件自有的内部角色和权限形式存储默认实现最多为每个被授权用户创建一个保留的内部可见性角色。角色名必须确定性生成、对被授权用户唯一并受限于现有角色名列长度。资源和动作信息只能存储在绑定到该角色的权限行中不得编码进角色名列表/搜索鉴权必须从调用方保留可见性角色绑定的实际权限行推导显式可见资源。只有角色绑定、但没有匹配权限行时不得授予可见性资源存在性和 owner 元数据通过领域提供的可见性资源定位桥接解析而不是让鉴权插件直接编译依赖领域持久化类型。范围查询必须组合基础可见性谓词和显式授权资源。当前默认实现已经暴露显式授权资源结构默认可见性实现会从授权服务填充显式授权资源使列表/搜索路径能够返回授权给当前调用方的私有资源。对于 AI 列表和搜索路径可见性必须在count 和分页查询前转换为仓储层查询条件。这可以让totalCount与可见资源集合保持一致并避免全量加载后在内存中过滤。兼容性与迁移策略旧端点或兼容端点可以为已有客户端保留但新的文档和新的开发应以 v3 鉴权 API 以及本文档定义的插件契约为准。配置兼容层面统一管理表中的历史静态 alias 继续兼容新的发行版模板使用 canonical key并在注释中标明历史 key如 distribution/conf/application.properties 中的注释所示canonical token 密钥缺失或为空时启动脚本会把合法的历史密钥迁移到 canonical key二者同时存在时 canonical 值优先迁移过程不得输出密钥内容。待处理问题LDAP 与默认插件的基础设施耦合规范明确列出一个已知演进方向ldap插件已经通过PluginConfigSpec接管 LDAP 连接和查找配置但仍消费由auth:nacos配置的 token、用户、角色和授权基础设施。后续应把这些共享能力迁移到显式的 auth 模块服务使身份提供方插件不再依赖默认插件的配置所有权。这也是理解为什么所有可配置鉴权实现都要执行 apply即使是 LDAP 部署也要初始化auth:nacos的关键原因。快速上手一份最小可行的鉴权启用清单综合以上内容在可信内网环境启用默认nacos插件的推荐步骤生成独立 token 密钥生成一段 Base64 编码且解码后不少于 32 字节的随机串写入nacos.plugin.auth.nacos.token.secret.key切勿使用模板示例值按需打开鉴权开关在 distribution/conf/application.properties 中设置nacos.core.auth.enabledtrue控制 SDK/gRPC、nacos.core.auth.admin.enabledtrue控制/v3/admin/*、nacos.core.auth.console.enabledtrue控制/v3/console/*配置服务端身份为所有节点设置相同的nacos.core.auth.server.identity.key与nacos.core.auth.server.identity.value保证服务端之间调用可通过白名单校验可选调整 token 生命周期按业务需要设置nacos.plugin.auth.nacos.token.expire.seconds默认 18000 秒如需降低验证开销可开启token.cache.enable可选启用匿名 AI 读访问仅在需要 Skill/AgentSpec 等 AI 资源匿名可读时设置nacos.plugin.auth.nacos.anonymous.ai.enabledtrue并注意协调任务会写入public:*:ai/*默认读权限之后可自行收窄匿名权限范围重启服务使插件选择与 RESTART 类配置生效若使用 MySQL 且需要保存显式可见性授权先按 doc/visibility-permission-resource-upgrade.md 执行升级 SQL 预检查与迁移。如需改用 LDAP 身份认证将nacos.plugin.auth.typeldap并配置 auth:ldap 配置段token 与 RBAC 基础设施仍由auth:nacos提供因此nacos.plugin.auth.nacos.token.secret.key等共享配置仍需设置。【免费下载链接】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 默认鉴权插件实现规范深度解析：nacos 与 ldap 双插件的配置、身份、RBAC 与 AI 可见性实战
Nacos 默认鉴权插件实现规范深度解析nacos 与 ldap 双插件的配置、身份、RBAC 与 AI 可见性实战【免费下载链接】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 的默认鉴权实现包plugin-default-impl内置nacos与ldap两个鉴权插件为配置中心、注册中心以及 AI 资源Skill、AgentSpec、MCP Server 等提供用户名/密码登录、token 认证、RBAC 权限管理和可见性控制。本文以 specs/zh-cn/auth/default-auth-plugin-spec.md 为骨架结合仓库内的真实配置文件、服务端插件实现与 Java 客户端源码完整讲解默认鉴权框架的配置方式、插件化配置模型、身份识别规则、RBAC 存储模型、v3 鉴权 API、登录响应兼容性以及 AI 资源可见性集成的底层原理帮助你在一套可信内网部署中正确启用并加固 Nacos 鉴权。适用前提与边界默认实现定位为降低可信内网环境中的误用风险并非面向恶意公网环境的完整强鉴权方案。如需暴露公网应使用外部安全边界或选择更强的鉴权插件如 OIDC。范围默认鉴权实现包提供了什么默认鉴权实现包当前提供nacos和ldap两个鉴权插件nacos插件提供用户名/密码登录、token 认证、RBAC 权限管理以及 AI 资源使用的默认可见性集成。它实现了三个规范鉴权插件规范共享的鉴权与权限规范可见性插件规范ldap插件通过 LDAP 目录改变身份认证方式token 签名与有效期、Nacos 用户与角色存储及授权仍使用auth:nacos配置的基础设施。Java 客户端为默认插件暴露的用户名/密码和 token 流程提供NacosClientAuthServiceImpl实现在 client-basic/src/main/java/com/alibaba/nacos/client/auth/impl/NacosClientAuthServiceImpl.java。RAM、OIDC 等其他内置客户端鉴权服务属于 Java Client SDK 鉴权扩展由 Java SDK 实现规范 和鉴权插件规范 定义不属于本文描述的服务端默认插件实现。鉴权框架配置开关、作用域与插件选择以下配置负责鉴权模块的开关、API 作用域、启动期插件选择和服务端身份它们不属于auth:nacos插件自身的配置项配置目的nacos.core.auth.enabled启用通用鉴权系统和 Open API 鉴权控制 SDK 与 gRPC 请求认证。nacos.core.auth.admin.enabled启用 Admin API/v3/admin/*鉴权。nacos.core.auth.console.enabled启用 Console API/v3/console/*鉴权和默认登录行为。nacos.plugin.auth.type启动时选择鉴权插件默认nacosnacos.core.auth.system.type是历史 alias。nacos.core.auth.server.identity.key服务端之间调用的身份 key。nacos.core.auth.server.identity.value服务端之间调用的身份 value。在 distribution/conf/application.properties 中可以看到这些配置的真实模板### The auth plugin selected at startup. Legacy nacos.core.auth.system.type remains supported. ### Default nacos; ldap, oidc, and custom implementations are supported. nacos.plugin.auth.typenacos #nacos.core.auth.system.typenacos ### Whether open nacos server API auth system. It controls SDK and gRPC request authentication. nacos.core.auth.enabledfalse # Whether open nacos admin API auth system. It controls /v3/admin/* HTTP request authentication only. nacos.core.auth.admin.enabledtrue # Whether open nacos console API auth system. It controls /v3/console/* HTTP request authentication only. nacos.core.auth.console.enabledtrue ### The two properties is the white list for auth and used by identity the request from other server. nacos.core.auth.server.identity.key nacos.core.auth.server.identity.value需要注意两个要点插件选择需要重启生效因为nacos.plugin.auth.type在启动期决定加载哪个鉴权插件服务端身份值必须由部署环境独立配置不能使用默认值或共享值否则其他节点可伪造服务端之间的调用身份。统一管理的插件配置PluginConfigSpec 与配置快照nacos实现直接实现PluginConfigSpec并以可配置插件auth:nacos注册canonical 配置前缀为nacos.plugin.auth.nacos.。下表完整列出其配置项item keycanonical 静态 key历史静态 alias类型生效模式默认值敏感token.secret.keynacos.plugin.auth.nacos.token.secret.keynacos.core.auth.plugin.nacos.token.secret.keyStringRESTART空是token.expire.secondsnacos.plugin.auth.nacos.token.expire.secondsnacos.core.auth.plugin.nacos.token.expire.secondsNumberRUNTIME18000否token.cache.enablenacos.plugin.auth.nacos.token.cache.enablenacos.core.auth.plugin.nacos.token.cache.enableBooleanRUNTIMEfalse否caching.enablednacos.plugin.auth.nacos.caching.enablednacos.core.auth.caching.enabledBooleanRUNTIMEtrue否anonymous.ai.enablednacos.plugin.auth.nacos.anonymous.ai.enablednacos.core.auth.nacos.anonymous.ai.enabledBooleanRUNTIMEfalse否配置约束与行为要点token.expire.seconds必须大于零当任一 Nacos API 鉴权范围需要 token 能力时token.secret.key必须是有效的 Base64 内容且解码后不少于 32 字节。token 密钥必须由部署环境独立设置使用默认值或共享值不安全插件管理 API 必须返回脱敏后的密钥并禁止通过运行时更新修改该字段canonical key 与历史 alias 同时存在时canonical key 优先。历史 alias 为兼容已有部署继续可读并在使用时输出不包含配置值的迁移提示运行时和 localOnly 更新使用表中的 item key并遵循 Nacos 插件化规范 定义的 source 完整 Map 语义。配置模板中对应的真实写法distribution/conf/application.properties### Preferred keys for the built-in auth:nacos plugin are under nacos.plugin.auth.nacos. ### Legacy nacos.core.auth.plugin.nacos.*, nacos.core.auth.caching.enabled, and ### nacos.core.auth.nacos.anonymous.ai.enabled keys remain supported as aliases. nacos.plugin.auth.nacos.caching.enabledtrue nacos.plugin.auth.nacos.token.cache.enablefalse nacos.plugin.auth.nacos.token.expire.seconds18000 #nacos.plugin.auth.nacos.token.secret.keyVGhpc0lzTXlDdXN0b21TZWNyZXRLZXkwMTIzNDU2Nzg nacos.plugin.auth.nacos.token.secret.key ### Allow anonymous read access, default false, current only ai(skill, agentspec) supported. #nacos.plugin.auth.nacos.anonymous.ai.enabledtrue不可变 effective 配置快照与 token 生命周期插件持有不可变的 effective 配置快照对应源码 NacosAuthPluginConfig.java 中的NacosAuthPluginConfig类。应用新快照时更新 token 过期时间、token 缓存选择、鉴权信息缓存和匿名访问消费者不再直接读取 Spring 环境。其行为细节JWT parser 由已接受的 restart-only 密钥构建开启 token 缓存时在同一个基础 manager 外选择缓存包装关闭时切回基础 manager并清空 token 缓存token 过期时间变化时也会清空包装缓存使下一次取 token 使用新的运行时有效期已经返回给客户端的 token 仍按签名中的原过期时间有效。源码中的默认值与校验逻辑印证了规范描述NacosAuthPluginConfig.javapublic static final String TOKEN_SECRET_KEY token.secret.key; public static final String TOKEN_EXPIRE_SECONDS token.expire.seconds; public static final String TOKEN_CACHE_ENABLE token.cache.enable; public static final String CACHING_ENABLED caching.enabled; public static final String ANONYMOUS_AI_ENABLED anonymous.ai.enabled; private static final boolean DEFAULT_TOKEN_CACHE_ENABLE false; private static final boolean DEFAULT_CACHING_ENABLED true; private static final boolean DEFAULT_ANONYMOUS_AI_ENABLED false;其中from(MapString, String config, boolean tokenSecretRequired)会在 token 能力被要求时强制校验密钥非空并对密钥做 Base64/32 字节校验过期时间解析为parsePositiveLong即必须大于零。独立部署 Console 时的初始化顺序独立部署 Console 时Console 本地 auth initializer 会在开始接收请求前从STATIC DEFAULT对内置auth:nacos应用配置使稳定的TokenManagerDelegate完成具体 token manager 初始化。LDAP 等身份提供方仍消费auth:nacos持有的 token 和授权基础设施因此所有可配置鉴权实现都要执行 apply只有当前选中实现接收可选的启动生命周期回调。LDAP 插件配置auth:ldapldap实现同样实现PluginConfigSpec并以可配置插件auth:ldap注册canonical 配置前缀为nacos.plugin.auth.ldap.item keycanonical 静态 key历史静态 alias类型生效模式默认值敏感urlnacos.plugin.auth.ldap.urlnacos.core.auth.ldap.urlStringRESTARTldap://localhost:389否base-dnnacos.plugin.auth.ldap.base-dnnacos.core.auth.ldap.basedcStringRESTARTdcexample,dcorg否timeoutnacos.plugin.auth.ldap.timeoutnacos.core.auth.ldap.timeoutNumberRESTART3000否user-dnnacos.plugin.auth.ldap.user-dnnacos.core.auth.ldap.userDnStringRESTARTcnadmin,dcexample,dcorg否passwordnacos.plugin.auth.ldap.passwordnacos.core.auth.ldap.passwordStringRESTARTpassword是filter-prefixnacos.plugin.auth.ldap.filter-prefixnacos.core.auth.ldap.filter.prefixStringRESTARTuid否case-sensitivenacos.plugin.auth.ldap.case-sensitivenacos.core.auth.ldap.case.sensitiveBooleanRESTARTtrue否ignore-partial-result-exceptionnacos.plugin.auth.ldap.ignore-partial-result-exceptionnacos.core.auth.ldap.ignore.partial.result.exceptionBooleanRESTARTfalse否约束与细节timeout单位为毫秒且必须大于零插件管理 API 必须对绑定密码脱敏第一阶段 LDAP 自有字段全部为RESTART因此运行时或 local-only 更新只要新增、修改或移除这些字段都必须拒绝canonical key 与历史 alias 同时存在时 canonical key 优先历史模板中的nacos.core.auth.ldap.userdn没有生产读取点且原本想表达的 user DN pattern 语义不明确因此不作为兼容 alias。配置模板distribution/conf/application.properties### worked when nacos.plugin.auth.typeldap #nacos.plugin.auth.ldap.urlldap://localhost:389 #nacos.plugin.auth.ldap.base-dndcexample,dcorg #nacos.plugin.auth.ldap.timeout3000 #nacos.plugin.auth.ldap.user-dncnadmin,${nacos.plugin.auth.ldap.base-dn} #nacos.plugin.auth.ldap.passwordadmin #nacos.plugin.auth.ldap.filter-prefixuid #nacos.plugin.auth.ldap.case-sensitivetrue #nacos.plugin.auth.ldap.ignore-partial-result-exceptionfalseLDAP 插件同样持有不可变的 effective 配置快照Spring LDAP context 和 template 从已接受快照延迟构建LDAP 消费者不再通过第二套Value属性读取配置。LDAP 只改变身份认证方式token 签名和有效期、Nacos 用户与角色存储及授权仍使用auth:nacos配置的基础设施相关共享字段不复制到auth:ldapdefinitions。身份插件接受哪些输入如何降级为匿名插件接受以下身份输入输入用途Authorization: Bearer ...token 认证。accessToken通过请求参数或 header 进行 token 认证。username和password登录或直接用户名/密码认证。服务端身份 key/value服务端之间调用的身份。认证成功后插件会向IdentityContext补充已认证的 Nacos 用户和用户 ID。全局管理员状态由用户角色模型推导。匿名 AI 访问的三重条件与降级规则匿名 AI 访问只有在以下条件同时满足时才允许端点标记该请求允许匿名访问auth:nacos的anonymous.ai.enabled已启用默认插件将请求接受为内置匿名身份。关键降级规则容易踩坑只有当请求没有显式提供任何默认鉴权凭据 key时才允许降级为匿名身份提供Authorization、accessToken、username或password都视为显式凭据存在即使对应值为空白也一样如果这些凭据为空白或无效插件必须返回认证失败而不能降级为匿名身份在 HTTP 过滤器层身份或权限校验失败会被转换为 HTTP 403 的ACCESS_DENIED响应插件级失败码和消息可以保留在响应详情中。匿名用户的协调任务与权限保留开启匿名访问后只会立即开启匿名身份接受。后台协调任务随后保证保留的匿名用户和角色存在首次初始化时增加public:*:ai/*读权限并最后写入匿名角色绑定将该绑定作为持久化完成标记。多节点并发创建发生冲突时只有重新读取到预期持久化状态才视为成功。如果匿名角色绑定已经存在则视为已经初始化协调任务不会重新补回宽泛的默认权限从而保留管理员自定义的匿名权限范围关闭匿名访问只会停止匿名身份接受不删除保留的用户、角色或权限协调任务的本地状态只用于减少数据库操作不参与鉴权判断当找不到匹配的角色或权限时普通 RBAC 权限校验仍然必须拒绝匿名身份。默认 Java 客户端鉴权集成默认插件对应的 Java 客户端侧集成为NacosClientAuthServiceImpl。它通过客户端鉴权 SPI 加载注册文件位于 client-basic/src/main/resources/META-INF/services/com.alibaba.nacos.plugin.auth.spi.client.AbstractClientAuthService并在配置了username和password时调用默认/v3/auth/user/loginAPI。客户端实现身份材料契约NacosClientAuthServiceImplusername、password和accessToken。通过默认鉴权 API 登录附加返回的accessToken并在 token 过期前刷新。该集成不得修改请求 payload只提供当前服务端鉴权插件消费的身份材料。RAM、OIDC 等其他客户端鉴权实现作为 Java Client SDK 扩展在 Java SDK 实现规范 中描述。从源码可以印证 token 刷新机制NacosClientAuthServiceImpl.java客户端保存tokenTtl服务器签发的 token 有效期与tokenRefreshWindow随机刷新窗口刷新窗口通过generateTokenRefreshWindow(tokenTtl)随机生成数值范围为[tokenTtl/15, tokenTtl/10]随机化的目的是避免大量客户端同时重新登录给 Nacos 服务端造成压力在tokenTtl - tokenRefreshWindow时间窗内直接复用已持有的 token超过窗口且已配置username时才发起重新登录登录成功后将服务器返回的accessToken放入LoginIdentityContext随请求携带。对应的测试用例见 client-basic/src/test/java/com/alibaba/nacos/client/auth/impl/NacosClientAuthServiceImplTest.java。登录响应兼容性/v3/auth/user/login和遗留 v1 登录路由的默认鉴权登录成功响应保持为平铺 token 对象包含accessToken、tokenTtl、globalAdmin和username。该响应不使用ResultT包装因为已发布的 Java 客户端会直接解析这一平铺结构——修改包装形态会破坏现有客户端兼容性。登录失败的防枚举设计用户名不存在、密码错误或凭据为空时必须返回相同的 HTTP 403 状态和相同的通用响应体User not found! Please check user exist or password is right!HTTP 状态和响应体不得泄露用户名是否存在。两个安全细节未知用户认证不执行密码哈希比对避免攻击者使用任意用户名迫使服务端执行高 CPU 开销的密码编码操作防止资源耗尽型攻击用户存储或 token 签发的非预期故障属于运行异常不得转换为凭据错误避免掩盖真实故障、也避免向调用方暴露内部错误细节。RBAC 存储模型默认插件存储三类对象对象含义User用户名和密码身份。RoleInfo分配给用户名的角色。PermissionInfo分配给角色的资源和动作。ROLE_ADMIN是全局管理员角色。拥有该角色的用户可以访问所有资源和控制台管理操作。模糊搜索的_通配符转义规则用户、角色和权限的模糊搜索会用反斜杠转义_通配符使其按字面量匹配。反斜杠只在部分数据库上是 LIKE 的默认转义字符因此嵌入式存储显式声明ESCAPE \。两个必须遵守的细节该子句只作用于紧邻其前的那一个LIKE谓词所以组合多个模糊过滤条件的查询必须在每个谓词之后都重复声明该子句该规则适用于同一资源的所有模糊查询入口而不仅是分页搜索。控制台名称联想所依赖的名称搜索findRoleNames、findUserNames必须与分页搜索采用相同的转义方式使同一个关键字在两者中选出相同的记录。权限资源格式默认资源权限使用如下格式{namespaceId}:{group}:{signType}/{resourceName}示例资源示例配置数据public:DEFAULT_GROUP:config/example.properties注册发现服务public:DEFAULT_GROUP:naming/com.example.Service控制台用户console/users控制台角色console/roles控制台权限console/permissions可见性权限visibility/public/mcp/example-mcp规则权限资源中可以使用*作为通配符group 为空时权限检查会在 group 段使用*resource name 为空时资源名段会变成*存储资源以:开头时会补充默认命名空间publicSPECIFIED资源直接使用显式资源字符串存储动作可以是r、w或rw。非管理员角色不得管理控制台用户、角色或权限。默认鉴权 API 族v3默认插件拥有以下 v3 API 族路径目的/v3/auth/user用户管理和密码更新。/v3/auth/user/login登录和 token 签发。/v3/auth/user/admin当不存在全局管理员时进行管理员初始化。/v3/auth/role角色管理。/v3/auth/permission权限管理。/v3/auth/visibility显式资源可见性授权管理。安全约束管理端点必须使用控制台域的Secured资源保护例如console/users、console/roles、console/permissions和console/user/password登录端点是有意公开的管理员初始化端点只在无管理员初始化状态下有意暴露一旦全局管理员已经存在必须拒绝该端点这些 API 属于 V3 API 范围并必须遵守 HTTP 鉴权规范。可见性授权 API/v3/auth/visibility属于插件自有接口不是任何领域 controller 家族的一部分。它使用ApiType.ADMIN_API与 identity-only 请求鉴权并在授权服务层执行资源管理权限判断。启用鉴权时只有资源 owner 或全局管理员可以对该资源执行 grant 或 revoke 显式可见性授权。默认可见性实现AI 资源的访问控制默认可见性实现名称同样为nacos当前用于 AI 资源。其默认行为除非领域提供其他 scope新资源默认PRIVATE全局管理员可以读写所有具备可见性语义的资源资源 owner 可以读写该资源PUBLIC资源可以被非 owner 读取显式可见性权限可以通过鉴权插件授予访问匿名 AI 读访问只能通过匿名 AI 显式选择路径开启读拒绝可以返回 not found以隐藏资源存在性写拒绝返回 access denied。显式可见性权限资源使用如下格式visibility/{namespaceId}/{resourceType}/{resourceName}permissions.resource 列的扩容与数据库迁移默认 RBACpermissions.resource列必须保存完整、精确的 canonical 资源字符串且至少需要支持 512 个字符以避免命名空间资源持久化时被截断。资源匹配语义是精确且大小写敏感的因此默认 MySQL schema 对该列使用utf8mb4_bin并为permissions表使用ROW_FORMATDYNAMIC以保证现有(role, resource, action)索引在utf8mb4下可用。已有 MySQL 部署在应用升级 SQL 前应检查 MySQL 版本、InnoDB page size、row format 以及当前permissions表结构。运维人员必须先配置兼容的 InnoDB 存储模式再执行 MySQL 迁移以确保现有UNIQUE(role, resource, action)索引能够接受扩展后的utf8mb4resource 列。本次变更的升级脚本通过distribution/conf交付数据库升级脚本精确 schema 变更MySQLmysql-upgrade-visibility-permission-resource.sqlALTER TABLE permissions ROW_FORMATDYNAMIC, MODIFY COLUMN resource VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL;Derbyderby-upgrade-visibility-permission-resource.sqlALTER TABLE permissions ALTER COLUMN resource SET DATA TYPE VARCHAR(512);PostgreSQLpg-upgrade-visibility-permission-resource.sqlALTER TABLE permissions ALTER COLUMN resource TYPE VARCHAR(512);Oracleoracle-upgrade-visibility-permission-resource.sqlALTER TABLE permissions MODIFY (resource VARCHAR2(512 CHAR) NOT NULL);MySQL 脚本包含以下预检查先执行确认存储环境兼容SELECT VERSION(); SHOW VARIABLES LIKE innodb_page_size; SHOW VARIABLES LIKE innodb_default_row_format; SHOW CREATE TABLE permissions;这些脚本只扩展原始 canonical resource 列不得添加仅服务于授权列表反查的permissions(resource, action, role)或roles(role, username)索引。面向运维人员的完整升级说明见 doc/visibility-permission-resource-upgrade.md。显式可见性授权的存储与推导当前支持资源的显式可见性授权通过以下接口管理POST /v3/auth/visibility DELETE /v3/auth/visibility两个端点均使用ApiType.ADMIN_API保护。授权行为只读授权存储为动作r写或读写授权请求统一存储为rw并且rw在列表/搜索查询建议中隐式包含读权限授权数据复用默认 RBAC 持久化在鉴权后端以插件自有的内部角色和权限形式存储默认实现最多为每个被授权用户创建一个保留的内部可见性角色。角色名必须确定性生成、对被授权用户唯一并受限于现有角色名列长度。资源和动作信息只能存储在绑定到该角色的权限行中不得编码进角色名列表/搜索鉴权必须从调用方保留可见性角色绑定的实际权限行推导显式可见资源。只有角色绑定、但没有匹配权限行时不得授予可见性资源存在性和 owner 元数据通过领域提供的可见性资源定位桥接解析而不是让鉴权插件直接编译依赖领域持久化类型。范围查询必须组合基础可见性谓词和显式授权资源。当前默认实现已经暴露显式授权资源结构默认可见性实现会从授权服务填充显式授权资源使列表/搜索路径能够返回授权给当前调用方的私有资源。对于 AI 列表和搜索路径可见性必须在count 和分页查询前转换为仓储层查询条件。这可以让totalCount与可见资源集合保持一致并避免全量加载后在内存中过滤。兼容性与迁移策略旧端点或兼容端点可以为已有客户端保留但新的文档和新的开发应以 v3 鉴权 API 以及本文档定义的插件契约为准。配置兼容层面统一管理表中的历史静态 alias 继续兼容新的发行版模板使用 canonical key并在注释中标明历史 key如 distribution/conf/application.properties 中的注释所示canonical token 密钥缺失或为空时启动脚本会把合法的历史密钥迁移到 canonical key二者同时存在时 canonical 值优先迁移过程不得输出密钥内容。待处理问题LDAP 与默认插件的基础设施耦合规范明确列出一个已知演进方向ldap插件已经通过PluginConfigSpec接管 LDAP 连接和查找配置但仍消费由auth:nacos配置的 token、用户、角色和授权基础设施。后续应把这些共享能力迁移到显式的 auth 模块服务使身份提供方插件不再依赖默认插件的配置所有权。这也是理解为什么所有可配置鉴权实现都要执行 apply即使是 LDAP 部署也要初始化auth:nacos的关键原因。快速上手一份最小可行的鉴权启用清单综合以上内容在可信内网环境启用默认nacos插件的推荐步骤生成独立 token 密钥生成一段 Base64 编码且解码后不少于 32 字节的随机串写入nacos.plugin.auth.nacos.token.secret.key切勿使用模板示例值按需打开鉴权开关在 distribution/conf/application.properties 中设置nacos.core.auth.enabledtrue控制 SDK/gRPC、nacos.core.auth.admin.enabledtrue控制/v3/admin/*、nacos.core.auth.console.enabledtrue控制/v3/console/*配置服务端身份为所有节点设置相同的nacos.core.auth.server.identity.key与nacos.core.auth.server.identity.value保证服务端之间调用可通过白名单校验可选调整 token 生命周期按业务需要设置nacos.plugin.auth.nacos.token.expire.seconds默认 18000 秒如需降低验证开销可开启token.cache.enable可选启用匿名 AI 读访问仅在需要 Skill/AgentSpec 等 AI 资源匿名可读时设置nacos.plugin.auth.nacos.anonymous.ai.enabledtrue并注意协调任务会写入public:*:ai/*默认读权限之后可自行收窄匿名权限范围重启服务使插件选择与 RESTART 类配置生效若使用 MySQL 且需要保存显式可见性授权先按 doc/visibility-permission-resource-upgrade.md 执行升级 SQL 预检查与迁移。如需改用 LDAP 身份认证将nacos.plugin.auth.typeldap并配置 auth:ldap 配置段token 与 RBAC 基础设施仍由auth:nacos提供因此nacos.plugin.auth.nacos.token.secret.key等共享配置仍需设置。【免费下载链接】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），仅供参考
