Authorization

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.

Nacos auth is provided by auth plugins. Nacos 3.2 includes the default Nacos auth plugin, LDAP auth plugin, and OIDC/OAuth2 auth plugin. They share the same auth switches, but use different identity sources and permission models. Starting with Nacos 3.3, Client API authentication is also enabled by default; the Client, Admin, and Console API scopes still have independent switches.

Choose An Auth Mode

For plugin boundaries and development details, see Auth Plugin.

Core Configuration

The Client, Admin, and Console API switches do not change one another. /v3/auth/* consists of plugin-provided APIs and must not be assigned to a scope from the URL alone: login is intentionally public; initial administrator bootstrap is available only while no global administrator exists; and user, role, and permission management endpoints are protected by their Console-scoped auth resources. Endpoints explicitly designated as public, bootstrap-only, or health checks also remain identity-free despite the default change.

In the official Docker image, leaving NACOS_AUTH_ENABLE unset adds no JVM override, so the image’s built-in value applies. Nacos 3.3 and later images enable Client API auth by default. An explicit true or false always overrides that default. Environment-variable mappings may differ between image versions, so check the target image documentation during an upgrade.

Credential Prerequisites For Default Nacos Auth

• nacos.plugin.auth.nacos.token.secret.key must be valid Base64 whose decoded value is at least 32 bytes. Generate a strong, deployment-specific value for production.
• When Client API auth is enabled, nacos.core.auth.server.identity.key and nacos.core.auth.server.identity.value must be non-empty. Use the same values on every member of one cluster, and do not reuse them across clusters.
• The standard distribution startup script migrates a valid legacy token secret and interactively requests missing required values. Automated deployments should write these values before first startup instead of depending on interactive input.
• The official Docker startup script requires non-empty NACOS_AUTH_TOKEN, NACOS_AUTH_IDENTITY_KEY, and NACOS_AUTH_IDENTITY_VALUE. Keep these credentials configured even while Client API auth is temporarily disabled so it can be re-enabled safely.

Configure Default Nacos Auth

Default Nacos auth uses local users, roles, permissions, and tokens. It provides the /v3/auth/user, /v3/auth/role, and /v3/auth/permission APIs. These APIs belong to the default auth plugin. Other auth plugins do not necessarily support them. All three API scopes default to enabled in Nacos 3.3; the examples still set each switch explicitly so the complete deployment configuration is easy to audit.

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:${nacos_3_3_version}

Initialize The Administrator Password

Since 2.4.0, Nacos no longer ships a default password for the administrator user nacos. After enabling default Nacos auth for the first time, initialize the administrator password.

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

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

Enable LDAP Auth

The LDAP plugin type is ldap. Since Nacos 3.2, LDAP is separated from the default auth implementation and provided as a standalone optional plugin.

LDAP boundaries:

• LDAP validates usernames and passwords.
• Nacos issues access tokens.
• Local Nacos roles and permissions still authorize requests.
• /v3/auth/user/login is still used for login.

Example:

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

Before enabling LDAP, check that:

• nacos-ldap-auth-plugin-<version>.jar is available in plugins/ or the server classpath.
• org.springframework.ldap:spring-ldap-core related jars are available in plugins/.

If spring-ldap-core is missing, the LDAP plugin cannot work fully. Add the dependency and restart Nacos.

Enable OIDC/OAuth2 Auth

The OIDC/OAuth2 plugin type is oidc. It delegates authentication to an external IdP and is suitable for enterprise SSO, MFA, and centralized account governance.

Basic example:

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

In OIDC/OAuth2 mode, console login uses compatibility endpoints under /v1/auth/oidc/*. The Java SDK can use the OAuth2 Client Credentials flow to obtain bearer tokens.

For detailed configuration, Keycloak examples, external authorization, and troubleshooting, see OIDC/OAuth2 Authentication.

Configure Resource Visibility

The visibility plugin controls whether a resource should appear in detail, list, or search results. It is related to auth, but has a different responsibility:

• Auth decides whether an identity has read or write permission on a target resource.
• Visibility decides whether the target resource should be visible to the current identity.

Default settings:

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

The default nacos visibility implementation reuses user information from the default auth context and currently serves AI Registry resources. For details, see Visibility Plugin.

Client And OpenAPI Credentials

Default Nacos auth and LDAP auth can log in with username and password. Use the returned accessToken for OpenAPI calls.

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"
}

For SDK configuration, see User Manual - Authorization.

Enable Token Cache

The default Nacos auth plugin supports token caching. When enabled, the server caches token parsing and validation results to reduce JWT parsing overhead.

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

Notes:

• Permission updates may take a short time to take effect because of cache delay.
• When a cached token is close to expiration, the login API issues a new token.
• Check your current image version for Docker environment variable support.

Enable Or Temporarily Disable An Auth Scope

The three scope switches are independent. Omitting a switch in Nacos 3.3 enables that scope; you may also set true explicitly. If client credential rollout is incomplete before an upgrade, use an explicit Client-scope opt-out only as a time-bounded compatibility measure:

nacos.core.auth.enabled=false

For Docker deployments, use:

NACOS_AUTH_ENABLE=false

nacos.core.auth.enabled is runtime-refreshable, but a configuration-file refresh applies only to the current node. Apply and verify the same effective value on every cluster member. Changing an environment variable normally requires a rolling container replacement. After client credentials and permissions have been verified, change the value to true, or remove the explicit false from a Nacos 3.3 deployment to restore the enabled default.

To disable Admin API or Console API auth temporarily in local development or a controlled environment, set the corresponding independent switch:

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

Upgrade Notes

• When upgrading from 3.0.x–3.2.x to 3.3.x, an absent nacos.core.auth.enabled changes from “Client API auth disabled” to “enabled.” Older clients and direct OpenAPI calls without a username, password, or token will be rejected. Prepare users, roles, permissions, and client credentials before upgrading; see the Upgrade Manual.
• If an administrator user nacos already exists before upgrade, Nacos does not ask for administrator initialization again.
• If the old cluster still uses a default or weak password, change it after upgrade.
• When upgrading old LDAP deployments to 3.2, make sure the LDAP plugin jar and spring-ldap-core dependency are both available in plugins/.
• When switching to oidc, adjust console operations accordingly. Users, roles, passwords, and permissions are usually maintained by the external IdP or an external authorization service.