权限校验

注意

• Nacos是一个内部微服务组件，需要在可信的内部网络中运行，不可暴露在公网环境，防止带来安全风险。
• Nacos提供简单的鉴权实现，为防止业务错用的弱鉴权体系，不是防止恶意攻击的强鉴权体系。
• 如果运行在不可信的网络环境或者有强鉴权诉求，请参考官方简单实现做进行自定义插件开发。

Nacos 的鉴权能力由鉴权插件提供。Nacos 3.2 内置了默认 Nacos 鉴权、LDAP 鉴权和 OIDC/OAuth2 鉴权。不同插件使用同一套开关，但身份来源和权限模型不同。Nacos 3.3 起，Client API 鉴权也默认开启；Client API、Admin API 和 Console API 三个范围仍由独立开关控制。

选择鉴权模式

更多插件边界和开发方式请参考鉴权插件。

核心配置

Client API、Admin API 和 Console API 的开关互不联动。/v3/auth/* 是鉴权插件提供的 API，不应仅根据 URL 将它归入某个范围：登录接口有意保持公开；首次管理员初始化只在尚无全局管理员时开放；用户、角色和权限管理接口受各自的 Console 鉴权资源保护。明确标记为公开、首次初始化或健康检查的端点也不因默认值变化而改为需要身份。

官方 Docker 镜像中，NACOS_AUTH_ENABLE 未设置时不会添加 JVM 覆盖值，因此使用镜像内的默认值；Nacos 3.3 及以上镜像会启用 Client API 鉴权。显式 true 或 false 始终覆盖默认值。不同镜像版本的环境变量映射可能不同，升级时应以目标镜像说明为准。

默认 Nacos 鉴权的凭据前置条件

• nacos.plugin.auth.nacos.token.secret.key 必须是有效 Base64，解码后不少于 32 字节。每个生产部署应使用独立的强随机值。
• 开启 Client API 鉴权时，nacos.core.auth.server.identity.key 和 nacos.core.auth.server.identity.value 必须非空；同一集群各节点使用相同值，不同集群不要复用。
• 标准发行包的启动脚本会迁移有效的历史 token secret，并在必填值为空时交互提示输入。自动化部署应在首次启动前显式写入这些值，避免依赖交互输入。
• 官方 Docker 启动脚本要求 NACOS_AUTH_TOKEN、NACOS_AUTH_IDENTITY_KEY 和 NACOS_AUTH_IDENTITY_VALUE 非空，即使临时显式关闭 Client API 鉴权也应保留这些凭据，以便后续安全地重新开启。

配置默认 Nacos 鉴权

默认 Nacos 鉴权使用本地用户、角色、权限和 token。它提供 /v3/auth/user、/v3/auth/role、/v3/auth/permission 等 v3 Auth API。这些 API 属于默认鉴权插件，不是所有鉴权插件都支持。Nacos 3.3 中三个 API 范围均默认开启，下面仍显式列出开关，便于核对完整部署配置。

nacos.plugin.auth.type=nacos
nacos.core.auth.enabled=true
nacos.core.auth.admin.enabled=true
nacos.core.auth.console.enabled=true

nacos.core.auth.server.identity.key=${custom_server_identity_key}
nacos.core.auth.server.identity.value=${custom_server_identity_value}
nacos.plugin.auth.nacos.token.secret.key=${custom_base64_token_secret_key}

NACOS_AUTH_ENABLE=true
NACOS_AUTH_ADMIN_ENABLE=true
NACOS_AUTH_CONSOLE_ENABLE=true
NACOS_AUTH_SYSTEM_TYPE=nacos
NACOS_AUTH_TOKEN=${custom_base64_token_secret_key}
NACOS_AUTH_IDENTITY_KEY=${custom_server_identity_key}
NACOS_AUTH_IDENTITY_VALUE=${custom_server_identity_value}

docker run --env PREFER_HOST_MODE=hostname \
  --env MODE=standalone \
  --env NACOS_AUTH_ENABLE=true \
  --env NACOS_AUTH_SYSTEM_TYPE=nacos \
  --env NACOS_AUTH_TOKEN=${custom_base64_token_secret_key} \
  --env NACOS_AUTH_IDENTITY_KEY=${custom_server_identity_key} \
  --env NACOS_AUTH_IDENTITY_VALUE=${custom_server_identity_value} \
  -p 8848:8848 -p 9848:9848 nacos/nacos-server:v3.3.0

初始化管理员密码

自 2.4.0 起，Nacos 不再内置管理员用户 nacos 的默认密码。首次开启默认 Nacos 鉴权后，需要初始化管理员密码。

curl -X POST 'http://$nacos_server_host:$nacos_server_port/nacos/v3/auth/user/admin' \
  -d 'password=$your_password'

{"username":"nacos","password":"$your_password"}

启用 LDAP 鉴权

LDAP 插件类型是 ldap。Nacos 3.2 起，LDAP 插件从默认鉴权实现中分离为独立可选插件。

LDAP 的工作边界是：

• LDAP 校验用户名和密码。
• Nacos 签发访问 token。
• Nacos 本地角色和权限仍负责授权。
• /v3/auth/user/login 仍可用于登录。

配置示例：

nacos.plugin.auth.type=ldap
nacos.core.auth.enabled=true
nacos.core.auth.admin.enabled=true
nacos.core.auth.console.enabled=true

nacos.plugin.auth.ldap.url=ldap://localhost:389
nacos.plugin.auth.ldap.base-dn=dc=example,dc=org
nacos.plugin.auth.ldap.user-dn=cn=admin,dc=example,dc=org
nacos.plugin.auth.ldap.password=${ldap_bind_password}
nacos.plugin.auth.ldap.filter-prefix=uid
nacos.plugin.auth.ldap.case-sensitive=true
nacos.plugin.auth.ldap.ignore-partial-result-exception=false

启用前请确认：

• nacos-ldap-auth-plugin-<version>.jar 已在 plugins/ 目录或服务端 classpath 中。
• org.springframework.ldap:spring-ldap-core 相关 jar 已放入 plugins/ 目录。

如果缺少 spring-ldap-core，LDAP 插件无法完整工作。补齐依赖后重启 Nacos。

启用 OIDC/OAuth2 鉴权

OIDC/OAuth2 插件类型是 oidc。它通过外部 IdP 完成身份认证，适合企业 SSO、MFA 和集中账号治理。

基础配置示例：

nacos.plugin.auth.type=oidc
nacos.core.auth.enabled=true
nacos.core.auth.admin.enabled=true
nacos.core.auth.console.enabled=true

nacos.core.auth.server.identity.key=${custom_server_identity_key}
nacos.core.auth.server.identity.value=${custom_server_identity_value}
nacos.plugin.auth.nacos.token.secret.key=${custom_base64_token_secret_key}

nacos.plugin.auth.oidc.issuer-uri=https://idp.example.com/realms/nacos
nacos.plugin.auth.oidc.client-id=nacos-server
nacos.plugin.auth.oidc.client-secret=${client_secret}
nacos.plugin.auth.oidc.scope=openid profile email

OIDC/OAuth2 模式下，控制台登录走 /v1/auth/oidc/* 兼容接口。Java SDK 可通过 OAuth2 Client Credentials flow 获取 bearer token。

详细配置、Keycloak 示例、外部授权接口和排查方式请参考 OIDC/OAuth2 认证。

配置资源可见性

可见性插件控制资源是否应出现在详情、列表和搜索结果中。它和鉴权相关，但职责不同：

• 鉴权判断身份是否拥有目标资源的读写权限。
• 可见性判断资源是否应该被当前身份看到。

默认配置：

nacos.plugin.visibility.enabled=true
nacos.plugin.visibility.type=nacos

默认 nacos 可见性实现复用默认鉴权中的用户信息，当前主要服务于 AI 管理中心资源。更多说明请参考可见性插件。

客户端和 OpenAPI 如何携带身份

默认 Nacos 鉴权和 LDAP 鉴权可以通过用户名、密码登录，获取 accessToken 后访问 OpenAPI。

curl -X POST 'http://127.0.0.1:8848/nacos/v3/auth/user/login' \
  -d 'username=nacos&password=${password}'

返回示例：

{
  "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
  "tokenTtl": 18000,
  "globalAdmin": true,
  "username": "nacos"
}

客户端 SDK 配置方式请参考用户手册 - 配置鉴权。

开启 token 缓存

默认 Nacos 鉴权支持 token 缓存。开启后，服务端会缓存 token 解析和校验结果，减少频繁解析 JWT 的开销。

nacos.plugin.auth.nacos.token.cache.enable=true

注意事项：

• 权限更新后，缓存可能带来短时间延迟。
• 当缓存中的 token 接近过期时，登录接口会重新签发 token。
• Docker 镜像是否暴露对应环境变量，请以当前镜像版本说明为准。

开启或临时关闭鉴权范围

三个范围的开关相互独立。Nacos 3.3 中省略开关等同于启用；也可以显式设置 true。如果升级前尚未完成 Client 凭据改造，只能把显式关闭作为有明确期限的兼容措施：

nacos.core.auth.enabled=false

Docker 部署使用：

NACOS_AUTH_ENABLE=false

nacos.core.auth.enabled 支持运行时刷新，但配置文件刷新只作用于当前节点。集群必须在每个节点应用并核对相同的有效值。环境变量变更通常需要滚动重建容器。客户端凭据和权限验证完成后，将该值改为 true，或在 3.3 部署中删除显式 false 以恢复默认开启状态。

如需在本地开发或受控环境临时关闭 Admin API 或 Console API 鉴权，分别设置：

nacos.core.auth.admin.enabled=false
nacos.core.auth.console.enabled=false

升级注意事项

• 从 3.0.x～3.2.x 升级到 3.3.x 时，缺少 nacos.core.auth.enabled 的配置会从“Client API 鉴权关闭”变为“开启”。未携带用户名、密码或 token 的旧客户端和直接 OpenAPI 调用将被拒绝。升级前应完成用户、角色、权限和客户端凭据准备，详见升级手册。
• 从旧版本升级时，如果已经存在管理员用户 nacos，Nacos 不会重新要求初始化管理员密码。
• 如果旧集群仍使用默认或弱密码，升级后请尽快修改。
• 如果从旧 LDAP 配置升级到 3.2，请确认 LDAP 插件 jar 和 spring-ldap-core 依赖都已放入 plugins/。
• 如果切换到 oidc，请同步调整控制台使用习惯：用户、角色、密码和权限通常由外部 IdP 或外部授权服务维护。