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:
Field Name | Description |
---|---|
remote_ip | source ip of request |
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:
Field Name | Description |
---|---|
namespaceId | Namespace ID of the requested resource, some interfaces may not have this value |
group | The group name of the requested resource, some interfaces may not have this value |
name | The resource name of the requested resource, such as the service name or the configuration dataId, some interfaces may be defined special values, such as nacos/admin |
type | The type of the requested resource, which may be an enumeration value in SignType , which mainly represents the module related to the resource |
properties | The extended configuration of the requested resource, which does not belong to the above-mentioned resource-related information, will be placed in properties, such as the Request name of the Grpc request or the tags on the @Secured annotation, etc. |
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:
method name | parameters | returns | description |
---|---|---|---|
getAuthServiceName | void | String | The name of the plugin. When the name is the same, the plugin loaded later will overwrite the plugin loaded first. |
identityNames | void | Collection<String> | The identity context keywords of the plugin. Nacos will obtain the parameters with these keywords as the key from the request and inject them into the IdentityContext. |
enableAuth | ActionTypes,SignType | boolean | Called before validateIdentity and validateAuthority , the plugin can decide whether to authenticate this type of operation or this type of module. |
validateIdentity | IdentityContext, Resource | boolean | Validate identity, called before validateAuthority |
validateAuthority | IdentityContext, Permission | boolean | Validate permissions, called when validateIdentity returns true |
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 User Guide-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
andaccessToken
; - An Aliyun implementation using
accessKey
andsecretKey
.
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:
Type | Identity keys | description |
---|---|---|
NamingService | ak | accessKey |
NamingService | signature | naming signature |
NamingService | data | signature datum, include timestamp |
ConfigService | Spas-AccessKey | accessKey |
ConfigService | Spas-Signature | config signature |
ConfigService | Timestamp | request timestamp |
ConfigService | Spas-SecurityToken | Temporary token (used when Alibaba Cloud STS function is enabled) |
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:
method name | parameters | returns | description |
---|---|---|---|
setServerList | List<String>,Nacos server address list | void | Called during initialization, to inject the Nacos service list, which is convenient for plugins to access the nacos server, such as calling the login interface, etc. |
setNacosRestTemplate | NacosRestTemplate,http client for Nacos | void | Called during initialization, to inject Nacos' http client, which is convenient for plugins to access the nacos server, such as calling the login interface, etc. |
login | Properties,properties of initialization | boolean | mainly performs the conversion of identity context, such as username , password is converted to accessToken |
getLoginIdentityContext | Resource | IdentityContext | Get the identity context converted by the login interface, and the client will inject all the content of the returned object into the request |
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