配置访问凭据

注意

Nacos是一个内部微服务组件，需要在可信的内部网络中运行，不可暴露在公网环境，防止带来安全风险。

Nacos提供简单的鉴权实现，为防止业务错用的弱鉴权体系，不是防止恶意攻击的强鉴权体系。

如果运行在不可信的网络环境或者有强鉴权诉求，请参考官方简单实现做进行自定义插件开发。

Nacos 3.3 默认开启 Client 鉴权，SDK 和受保护的 Client HTTP API 请求需要携带身份信息；Admin API 和 Console API 也默认开启鉴权。不同鉴权插件使用的身份材料不同。

使用默认鉴权前，先由管理员完成服务端鉴权配置和管理员初始化，再创建业务账号并授予所需资源权限。控制台登录成功不会自动给另一个应用或终端配置身份。服务端 token 签名密钥、节点间身份与应用的用户名、密码、accessToken 用途不同，不要混用。

服务端鉴权类型	客户端常用身份材料	说明
`nacos`	`username`、`password`、`accessToken`	默认 Nacos 鉴权。SDK 会用用户名密码登录并自动携带 token。
`ldap`	`username`、`password`、`accessToken`	LDAP 校验用户名密码，Nacos 签发 token。
`oidc`	`Authorization: Bearer ...`、`accessToken`	使用外部 IdP 签发的 OAuth2/OIDC token。

SDK 配置

以下 Java 默认鉴权示例显式读取 NACOS_USERNAME 和 NACOS_PASSWORD 环境变量；运行前设置为已创建账号的实际值，SDK 会自动登录并刷新 token。

Java SDK 在传入 username 和 password 后，会使用默认登录接口获取 accessToken，并把 token 注入后续请求。

Properties properties = new Properties();
properties.setProperty(PropertyKeyConst.SERVER_ADDR, "127.0.0.1:8848");
properties.setProperty(PropertyKeyConst.USERNAME, System.getenv("NACOS_USERNAME"));
properties.setProperty(PropertyKeyConst.PASSWORD, System.getenv("NACOS_PASSWORD"));

ConfigService configService = NacosFactory.createConfigService(properties);
NamingService namingService = NacosFactory.createNamingService(properties);

Java SDK 可以使用 OAuth2 Client Credentials flow 获取 bearer token。该方式适合服务到服务调用。

Properties properties = new Properties();
properties.setProperty(PropertyKeyConst.SERVER_ADDR, "127.0.0.1:8848");
properties.setProperty("nacos.client.auth.oidc.issuer-uri", "https://idp.example.com/realms/nacos");
properties.setProperty("nacos.client.auth.oidc.client-id", "nacos-client");
properties.setProperty("nacos.client.auth.oidc.client-secret", "${client_secret}");
properties.setProperty("nacos.client.auth.oidc.scope", "openid");

ConfigService configService = NacosFactory.createConfigService(properties);
NamingService namingService = NacosFactory.createNamingService(properties);

如果不希望通过 Discovery 获取 token endpoint，可以直接配置：

properties.setProperty("nacos.client.auth.oidc.token-endpoint",
    "https://idp.example.com/realms/nacos/protocol/openid-connect/token");

Go SDK 使用用户名和密码访问默认 Nacos 鉴权或 LDAP 鉴权：

sc := []constant.ServerConfig{
    *constant.NewServerConfig("${serverAddr}", 8848, constant.WithContextPath("/nacos")),
}

cc := *constant.NewClientConfig(
    constant.WithUsername("${username}"),
    constant.WithPassword("${password}"),
)

namingClient, err := clients.NewNamingClient(vo.NacosClientParam{
    ClientConfig:  &cc,
    ServerConfigs: sc,
})

configClient, err := clients.NewConfigClient(vo.NacosClientParam{
    ClientConfig:  &cc,
    ServerConfigs: sc,
})

OpenAPI 配置

以下命令使用 Bash，Windows 可使用 Git Bash 或 WSL。

默认 Nacos 鉴权和 LDAP 鉴权

先使用用户名和密码登录：

export NACOS_USERNAME='<your-username>'
export NACOS_PASSWORD='<your-password>'
curl -sS -X POST 'http://127.0.0.1:8848/nacos/v3/auth/user/login' \
  --data-urlencode "username=${NACOS_USERNAME}" \
  --data-urlencode "password=${NACOS_PASSWORD}"

返回示例：

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

将响应中的 accessToken 保存为环境变量；后续示例在同一个终端执行。token 过期后重新登录并更新此变量。tokenTtl 表示有效期秒数。

export NACOS_ACCESS_TOKEN='<accessToken-from-login-response>'

请求 OpenAPI 时，通过 Nacos 的 accessToken 请求头携带 token：

curl -X GET 'http://127.0.0.1:8848/nacos/v3/client/cs/config?dataId=example.properties&groupName=DEFAULT_GROUP' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}"

默认鉴权插件也兼容 Authorization: Bearer <token>，本手册的默认 Nacos 鉴权示例统一使用 accessToken 请求头。

也可以通过 accessToken 参数传递，但不要把带 token 的 URL 写入访问日志或分享给他人：

curl -G 'http://127.0.0.1:8848/nacos/v3/client/cs/config' \
  --data-urlencode "accessToken=${NACOS_ACCESS_TOKEN}" \
  --data-urlencode 'dataId=example.properties' \
  --data-urlencode 'groupName=DEFAULT_GROUP'

OIDC/OAuth2 鉴权

当服务端使用 nacos.plugin.auth.type=oidc 时，不使用 /v3/auth/user/login 获取 token。请从企业 IdP 获取 OAuth2/OIDC token，然后请求 Nacos 时携带：

curl -X GET 'http://127.0.0.1:8848/nacos/v3/client/cs/config?dataId=example.properties&groupName=DEFAULT_GROUP' \
  -H "Authorization: Bearer ${IDP_ACCESS_TOKEN}"

OIDC/OAuth2 的服务端配置请参考运维手册 - OIDC/OAuth2 认证。

AI 资源的匿名读取

默认鉴权插件的匿名 AI 访问默认关闭。只有管理员显式启用 nacos.plugin.auth.nacos.anonymous.ai.enabled=true、端点允许匿名且资源权限与可见性允许时，才可以不带凭据读取。资源为 PUBLIC 不等于无需鉴权。已显式提供但为空或错误的凭据会导致认证失败，不会自动退回匿名访问。

常见问题

默认登录接口返回当前鉴权类型不支持

/v3/auth/user/login 只适用于 nacos 和 ldap。如果服务端使用 oidc，请从外部 IdP 获取 token。

token 突然失效

常见原因包括：

token 已过期。
集群节点之间 nacos.plugin.auth.nacos.token.secret.key 不一致。
服务端切换了鉴权插件类型。
权限被修改，但客户端仍在使用旧 token。

有 token 但仍然无权限

认证成功只表示服务端识别了调用者。是否能读取或写入目标资源，还取决于该身份的角色、权限以及资源可见性。