Authorization Plugin

Since version 2.1.0, Nacos support to inject authentication plugins through SPI, and select a plugin implementation in the configuration file application.properties as the actual authentication service. This document will describe how to implement an authentication plugin and how to make it work.

Attention: At present, the authentication plugin is still in the beta stage, and its API and interface definitions maybe modified with version upgrades. Please pay attention to the applicable version of your plugin.

Concepts in Authentication Plugins

Authentication, the common expression is to verify whether who can perform some operation on something. So when Nacos designs the authentication plugin, the authentication information abstracted as three main concepts: identity context, resource and action type.

IdentityContext

IdentityContext is the abstraction of the request originator in the Nacos authentication plugin. Due to different plugin implementations, the identity context may be different, for example, username and password are one type of identity information, and accessToken is another type of identity information. Therefore, the IdentityContext does not limit the specific size and key. The plugin implementation can customize any size and keywords. Nacos will automatically obtain the identity keywords defined by the plugin implementation and their corresponding value from the request and inject them into IdentityContext which will be used in plugins.

IdentityContext must include:

Resource

Resource is the abstraction of the object operated by the request in the Nacos authentication plugin. It is mainly defined by Nacos, which can be a configuration, a service, or a group.

Resource mainly consists of the following:

Action

Action is the abstraction of the request operation in the Nacos authentication plugin, mainly include the read operation R and write operation W. For details, see the ActionTypes enumeration.

Server Plugin

To develop a Nacos server-side authentication plugin, developer first need to depend on the relevant API of the authentication plugin.

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

${project.version} is the version of Nacos for your development plugin.

Then implement interface com.alibaba.nacos.plugin.auth.spi.server.AuthPluginService, and put your implementation into services of SPI.

The methods of interface in following:

Load Server Plugin

After the plugin finished, it needs to be packaged into jar/zip and places in the classpath of the nacos server. If you don’t know how to add plugins into the classpath, please place plugins under ${nacos-server.path}/plugins directly.

After Adding plugins into classpath, also need to modify some configuration in ${nacos-server.path}/conf/application.properties.

### The plugin name nacos using，should be same as the return value of  `com.alibaba.nacos.plugin.auth.spi.server.AuthPluginService#getAuthServiceName`
nacos.core.auth.system.type=${authServiceName}

### open authorization
nacos.core.auth.enabled=true

Restart nacos cluster, and after any request, some logs can be saw in ${nacos-server.path}/logs/core-auth.log:

[AuthPluginManager] Load AuthPluginService(xxxx) AuthServiceName(xxx) successfully.

Use the default Nacos authentication plugin

Nacos provides a simple authentication plugin. It is a weak authentication system to prevent business misuse, not a strong authentication system to prevent malicious attacks. The usage detail see Admin Manual-Authentication.

Client Plugin

The authentication plugin for Nacos Client is to inject authentication-related identity context into the request so that each request can be recognized by the server authentication plugin.

The Java client of Nacos comes with two implementations by default:

• A default implementation using username,password and accessToken;
• An Aliyun implementation using accessKey and secretKey.

Default implementation

When username, password are included in the properties passed into a nacos client instance, the nacos client will use the simple authentication plugin to inject identity context; e.g.:

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

The plugin will login through username and password asynchronously, and obtain the accessToken after the login is successful. Finally, the plugin will inject the accessToken into all requests, which make the server plugins can validate identity and permission according to accessToken.

Aliyun implementation

When accessKey and secretKey are included in the properties, the nacos client will use the aliyun authentication plugin to inject identity context.

e.g.:

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

The plugin will generate signatures by accessKey, secretKey and the request resource, and inject into the request.

The identity context may be different for the different request resource:

Developers can validate authentication and authorization in the server plugin based on the above information.

Custom Plugin

Considering that the developer’s authentication plugin may have custom identity keywords, the Java client of Nacos can also use the SPI to inject the plugin implementation.

To develop a Nacos client authentication plugin, developers first need to depend on the relevant API of the authentication plugin.

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

${project.version} is the version of Nacos for your development plugin.

Then implement interface com.alibaba.nacos.plugin.auth.spi.client.ClientAuthService, and put your implementation into services of SPI.

The methods of interface in following:

Developers can choose to inherit com.alibaba.nacos.plugin.auth.spi.client.AbstractClientAuthService, which implements setServerList and setNacosRestTemplate.

Then package the developed client plugin into jar/zip and put it into the classpath of your application and take effect automatically.

Plugin for other programming language

TODO