Auth Plugin

Since 2.1.0, Nacos can load auth implementations through SPI. The server selects one auth plugin at startup through nacos.plugin.auth.type; nacos.core.auth.system.type is a historical alias.

An auth plugin answers one question: who is calling, and can that caller perform this action on this resource.

IdentityContext + Resource + Action -> allow or reject

If you only need to enable the built-in auth capability, start with Admin Manual - Authorization. If you need enterprise SSO or an external identity provider, see OIDC/OAuth2 Authentication. This page focuses on the plugin model, built-in implementation boundaries, and custom extension.

Unified Management Contract

auth is an EXCLUSIVE, STANDARD type with type-level critical=true. When any auth entry gate is enabled, or an auth type is explicitly configured, the selected provider becomes the active critical implementation. A missing or disabled provider fails startup; Nacos does not fall back to another implementation.

nacos.plugin.auth.type=nacos

Selection is snapshotted at startup and cannot be changed through runtime plugin state. nacos.core.auth.enabled, nacos.core.auth.admin.enabled, and nacos.core.auth.console.enabled are request-entry gates, not auth:nacos definitions.

Concepts

IdentityContext

IdentityContext describes the caller. Different plugins can use different identity material.

Common identity fields include:

A plugin declares the fields it needs through identityNames(). Nacos extracts those fields from the request, puts them into IdentityContext, and passes the context to the selected plugin.

Resource

Resource is the object being accessed. Nacos controllers, protocol filters, and resource parsers create it. Auth plugins should consume this model instead of redefining Nacos resource semantics.

Action

Nacos mainly uses two actions:

Built-In Auth Implementations

Nacos 3.2 provides the following built-in auth implementations. They share the same auth SPI, but their identity source and permission model are different.

Default Nacos Auth Implementation

The default Nacos auth implementation has plugin ID auth:nacos. It provides username/password login, JWT tokens, user management, role management, permission management, and the default AI resource visibility integration.

Typical configuration:

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}

auth:nacos definitions:

All definitions are required=false. When an auth entry needs tokens, token.secret.key must in practice be valid Base64 that decodes to at least 32 bytes. Plugin detail masks it.

The default implementation uses an RBAC model:

ROLE_ADMIN is the global administrator role. Users with this role can access all resources and console management features.

Default permission resources usually use this format:

{namespaceId}:{group}:{signType}/{resourceName}

Examples:

v3 Auth APIs Owned By The Default Implementation

The /v3/auth/* API family is provided by the default Nacos auth plugin. It is not a generic Nacos Core API surface, so it should be documented and used as part of the default auth implementation.

LDAP Auth Plugin

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

LDAP plugin boundaries:

• LDAP authenticates usernames and passwords.
• Nacos still issues login tokens.
• Nacos still uses local roles and permissions for authorization.
• Login still uses /v3/auth/user/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

All auth:ldap definitions are RESTART and required=false:

The historical nacos.core.auth.ldap.userdn template was not consumed by production code and is not a supported alias.

Before enabling LDAP, check that:

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

OIDC/OAuth2 Auth Plugin

The OIDC/OAuth2 plugin ID is auth:oidc. It is designed for enterprise SSO and external identity providers. It supports Keycloak, Okta, Auth0, Microsoft Entra ID, and similar providers through OIDC Discovery.

Differences from the default Nacos auth implementation:

• Authentication is delegated to the external IdP.
• Console login uses compatibility endpoints under /v1/auth/oidc/* for browser redirect and callback.
• The Java SDK can use the OAuth2 Client Credentials flow to obtain bearer tokens.
• Local Nacos user, role, permission, and password management are no longer the identity source of truth.
• /v3/auth/user/login does not apply to plugin type oidc.
• If no external authorization endpoint is configured, the current implementation allows non-admin authorization decisions by default.

Example:

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

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

All auth:oidc fields are RESTART and required=false; historical aliases use nacos.core.auth.plugin.oidc.{itemKey}:

For detailed setup, Keycloak examples, and troubleshooting, see Admin Manual - OIDC/OAuth2 Authentication.

Server Plugin Development

To build a server-side auth plugin, depend on the auth plugin API:

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-auth-plugin</artifactId>
    <version>${project.version}</version>
</dependency>

Then implement com.alibaba.nacos.plugin.auth.spi.server.AuthPluginService and register it with Java SPI.

Package the plugin and place it under ${nacos-server.path}/plugins, then configure:

nacos.plugin.auth.type=${authServiceName}
nacos.core.auth.enabled=true

After restart, check ${nacos-server.path}/logs/nacos.log for plugin loading logs.

AuthPluginService inherits PluginConfigSpec. An old binary implementation with no definitions still loads but appears as configurable=false. A new implementation should declare definitions, implement atomic applyConfig, and return its accepted snapshot. Do not declare module gates, type selection, or enabled as private config.

Client Auth Plugins

Client auth plugins inject identity material into requests. The selected server-side auth plugin still makes the final decision.

The Java client includes these common implementations:

Default Nacos client example:

Properties properties = new Properties();
properties.setProperty(PropertyKeyConst.SERVER_ADDR, "localhost:8848");
properties.setProperty(PropertyKeyConst.USERNAME, "nacos");
properties.setProperty(PropertyKeyConst.PASSWORD, "nacos");
NamingFactory.createNamingService(properties);
ConfigFactory.createConfigService(properties);

OIDC/OAuth2 client example:

Properties properties = new Properties();
properties.setProperty(PropertyKeyConst.SERVER_ADDR, "localhost: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");
NamingFactory.createNamingService(properties);
ConfigFactory.createConfigService(properties);

Custom Java client auth plugins should implement com.alibaba.nacos.plugin.auth.spi.client.ClientAuthService, or extend com.alibaba.nacos.plugin.auth.spi.client.AbstractClientAuthService.

Relationship With Visibility Plugins

Auth and visibility often appear together, but they answer different questions:

• Auth decides whether the current identity can access one target resource.
• Visibility decides whether a resource should appear in detail, list, or search results.

A visibility plugin may delegate explicit permission checks to the selected auth plugin. For example, the default implementation checks resources such as @@visibility/{namespaceId}/{resourceType}/{resourceName} through the current auth plugin. See Visibility Plugin for details.