权限校验

注意

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

Nacos 的鉴权能力由鉴权插件提供。Nacos 3.2 内置了默认 Nacos 鉴权、LDAP 鉴权和 OIDC/OAuth2 鉴权。不同插件使用同一套开关，但身份来源和权限模型不同。

选择鉴权模式

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

核心配置

开启默认 Nacos 鉴权

默认 Nacos 鉴权使用本地用户、角色、权限和 token。它提供 /v3/auth/user、/v3/auth/role、/v3/auth/permission 等 v3 Auth API。这些 API 属于默认鉴权插件，不是所有鉴权插件都支持。

nacos.core.auth.system.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.core.auth.plugin.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

初始化管理员密码

自 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.core.auth.system.type=ldap
nacos.core.auth.enabled=true
nacos.core.auth.admin.enabled=true
nacos.core.auth.console.enabled=true

nacos.core.auth.ldap.url=ldap://localhost:389
nacos.core.auth.ldap.basedc=dc=example,dc=org
nacos.core.auth.ldap.userDn=cn=admin,${nacos.core.auth.ldap.basedc}
nacos.core.auth.ldap.password=admin
nacos.core.auth.ldap.userdn=cn={0},dc=example,dc=org
nacos.core.auth.ldap.filter.prefix=uid
nacos.core.auth.ldap.case.sensitive=true
nacos.core.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.core.auth.system.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.core.auth.plugin.nacos.token.secret.key=${custom_base64_token_secret_key}

nacos.core.auth.plugin.oidc.issuer-uri=https://idp.example.com/realms/nacos
nacos.core.auth.plugin.oidc.client-id=nacos-server
nacos.core.auth.plugin.oidc.client-secret=${client_secret}
nacos.core.auth.plugin.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.core.auth.plugin.nacos.token.cache.enable=true

注意事项：

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

关闭控制台鉴权

从 Nacos 3.0 起，控制台访问默认开启鉴权。如果只在本地开发或受控环境中临时关闭，可以设置：

nacos.core.auth.console.enabled=false

升级注意事项

• 从旧版本升级时，如果已经存在管理员用户 nacos，Nacos 不会重新要求初始化管理员密码。
• 如果旧集群仍使用默认或弱密码，升级后请尽快修改。
• 如果从旧 LDAP 配置升级到 3.2，请确认 LDAP 插件 jar 和 spring-ldap-core 依赖都已放入 plugins/。
• 如果切换到 oidc，请同步调整控制台使用习惯：用户、角色、密码和权限通常由外部 IdP 或外部授权服务维护。