Configure Access Credentials

Attention

• Nacos is an internal microservice component and must run in a trusted internal network. Do not expose it to the public Internet, or it may bring security risks.
• Nacos provides a simple auth implementation to prevent business misuse. It is a weak auth system, not a strong auth system designed to resist malicious attacks.
• If Nacos runs in an untrusted network or you require strong auth, use the official simple implementation as a reference to develop a custom auth plugin.

When server-side auth is enabled, SDKs, OpenAPI callers, and console requests must provide identity material. The required material depends on the selected auth plugin.

SDK Configuration

Properties properties = new Properties();
properties.setProperty(PropertyKeyConst.SERVER_ADDR, "127.0.0.1:8848");
properties.setProperty(PropertyKeyConst.USERNAME, "${username}");
properties.setProperty(PropertyKeyConst.PASSWORD, "${password}");

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

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);

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

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 Credentials

Default Nacos Auth And LDAP Auth

Log in with username and password first:

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

Example response:

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

Then attach the token to OpenAPI calls. Prefer the Authorization header:

curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/config?dataId=example.properties&group=DEFAULT_GROUP' \
  -H 'Authorization: Bearer ${accessToken}'

For legacy compatibility, accessToken can also be passed as a request parameter:

curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/config?accessToken=${accessToken}&dataId=example.properties&group=DEFAULT_GROUP'

OIDC/OAuth2 Auth

When the server uses nacos.core.auth.system.type=oidc, do not use /v3/auth/user/login to obtain a token. Obtain an OAuth2/OIDC token from the enterprise IdP, then call Nacos with it:

curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/config?dataId=example.properties&group=DEFAULT_GROUP' \
  -H 'Authorization: Bearer ${idp_access_token}'

For server-side OIDC/OAuth2 setup, see Admin Manual - OIDC/OAuth2 Authentication.

Troubleshooting

The default login API says the current auth type is unsupported

/v3/auth/user/login applies only to nacos and ldap. If the server uses oidc, obtain a token from the external IdP.

A token suddenly becomes invalid

Common causes:

• The token expired.
• nacos.core.auth.plugin.nacos.token.secret.key is inconsistent across cluster nodes.
• The server switched to another auth plugin type.
• Permissions changed while the client still uses an old token.

A valid token still has no permission

Successful authentication only means the server recognizes the caller. Whether the caller can read or write a resource also depends on roles, permissions, and resource visibility.