Enable authentication for a Nacos instance to implement access control - Microservices Engine

You can enable the authentication feature for Nacos instances on Microservices Engine (MSE). The authentication feature helps prevent malicious users from obtaining or modifying information about an MSE Nacos instance. This topic describes how to configure access authentication for Nacos instances in the MSE console and how to use the Nacos client to perform authorized access to Nacos instances.

Prerequisites

MSE is activated. If you do not activate MSE, go to the MSE product page to activate it.
An MSE Nacos instance is created. For more information, see Create a Nacos engine.

Access methods

This topic describes how to configure access authentication if you use the direct connection of the engine. After the authorization is successful, you can use the Nacos client to access the MSE Nacos instance as a RAM user or by using a RAM role. The following access methods are supported:

Direct connection of the engine: You can use an SDK or a client to directly access the Nacos engine. This access method is suitable for scenarios in which an application attempts to access the Nacos engine.
Console-based connection of the engine: You can manage, view, and perform O&M on the Nacos engine in the MSE console. This access method is suitable for all users who want to use the Nacos engine. For more information about how to authorize a RAM user to use the MSE console, see Grant permissions on Microservices Registry resources.

Enable authentication

Important

For a newly created Nacos engine, authentication is not enabled by default. In this case, the Nacos engine responds to all requests.
The logon feature of the open source Nacos console is used only to record information about users, and is unable to authenticate or intercept requests. You can enable the authentication feature by following the instructions in this topic. After you enable the authentication feature for a Nacos instance, you cannot access the instance in the open source Nacos console. You must access the instance in the MSE console.

Log on to the MSE console, and select a region in the top navigation bar.
In the left-side navigation pane, choose Microservices Registry > Instances.
On the Instances page, click the name of the instance.
In the left-side navigation pane of the Basic Information page, click Parameter Settings. On the page that appears, click Edit.

Set the ConfigAuthEnabled or NamingAuthEnabled parameter to Yes, and click Save and Restart Instance.

Important

Before you enable the authentication feature for a configuration center or registry, you need to configure access credentials on the client. Otherwise, you cannot obtain configurations or services. For more information about how to configure access credentials, see Configure access credentials on the client in this topic.
The two parameters are independent of each other.

Parameter	Description
ConfigAuthEnabled	Specifies whether to enable the authentication feature for a configuration center. This parameter is supported by MSE Nacos instances in version 1.2.1 or later of the Basic Edition and all versions of the Professional Edition and Developer Edition.
NamingAuthEnabled	Specifies whether to enable the authentication feature for a registry. This parameter is supported by MSE Nacos instances in version 2.0.4 or later of the Professional Edition or Developer Edition.

Configure access credentials on the client

MSE Nacos instances support multiple methods to initialize a credential provider. You can select a method based on the authentication and authorization requirements of your business scenario.

Initialization method	Scenario	AccessKey pair or STS token required	Underlying credential	Credential validity period	Credential rotation or refresh method
Method 1: Use an AccessKey pair	Applications are deployed and run in a secure and stable environment that is not vulnerable to external attacks and need to access cloud services for a long period of time without frequent credential rotations.	Yes	AK	Long-term	Manual rotation
Method 2: Use an AccessKey pair that automatically rotates	Applications are deployed and run in an environment in which the AccessKey pair may be leaked and requires frequent rotation of the access credentials to access cloud services for a long period of time.	No	AccessKey pair	Long-term	Automatic rotation
Method 3: Use an STS token	Applications are deployed and run in an untrusted environment, in which case you want to manage the credential validity period and permissions.	Yes	STS token	Temporary	Manual refresh
Method 4: Use the ARN of a RAM role	Applications need to be authorized to access cloud services. For example, you can use this method to allow cross-account access to cloud services.	Yes	STS token	Temporary	Automatic refresh
Method 5: Use the RAM role of an ECS instance	Applications are deployed and run on Elastic Compute Service (ECS) instances, elastic container instances, and Container Service for Kubernetes (ACK) worker nodes.	No	STS token	Temporary	Automatic refresh
Method 6: Use the RAM role of an OIDC IdP	Untrusted applications are deployed and run on ACK worker nodes.	No	STS token	Temporary	Automatic refresh
Method 7: Use credentials URIs	Applications require access credentials from external systems.	No	STS token	Temporary	Automatic refresh

Method 1: Use an AccessKey pair

(Optional) Step 1: Create a RAM user

Perform this step if you do not have a RAM user or need to create a RAM user. For more information, see Create a RAM user.

Step 2: Grant permissions to the RAM user

Grant permissions to the RAM user that you created in Step 1, and attach one of the following system policies to the RAM user. In this step, a coarse-grained authorization operation is performed to grant the RAM user read permissions and write permissions or read-only permissions on the configurations and services of all MSE Nacos instances. For information about how to perform authorization operations, see Grant permissions to a RAM user.

Policy	Description
AliyunMSEFullAccess	The permissions that are required to manage MSE. You can use a RAM user to which this policy is attached to manage all features the same way you use an Alibaba Cloud account to manage all features.
AliyunMSEReadOnlyAccess	The read-only permissions on the resources of MSE. A RAM user to which this policy is attached can only read all MSE resources of the Alibaba Cloud account.

Note

You can attach a maximum of five policies at a time. If you want to attach more than five policies, repeat the step multiple times.
If you want to grant fine-grained permissions, you need to create a custom policy. For more information, see Fine-grained authentication in registries, Fine-grained authentication in configuration centers, and Examples of common custom policies for Microservices Registry.

Step 3: Configure authentication on the Nacos client (SDK)

An AccessKey pair consists of an AccessKey ID and an AccessKey secret. After you enable the authentication feature for an MSE Nacos instance, you must specify the AccessKey ID and AccessKey secret of a RAM user if you want to access the Nacos instance as the RAM user by using the Nacos client. If you do not specify the AccessKey ID and AccessKey secret of a RAM user for the Nacos client, you cannot access the Nacos instance as the RAM user. For more information about how to obtain an AccessKey pair, see Create an AccessKey pair.

Nacos client (SDK for Java)

If you use the Nacos client (SDK for Java), add the following code for your application.

Note

To use an AccessKey pair for authentication, you need to upgrade the client to the required version. For more information, see Nacos client versions supported for authentication, encryption, and decryption.

properties.put(PropertyKeyConst.SERVER_ADDR, "${Endpoint of the MSE Nacos instance}");
properties.put(PropertyKeyConst.ACCESS_KEY, "${accessKey}");
properties.put(PropertyKeyConst.SECRET_KEY, "${secretKey}");
NamingService naming = NamingFactory.createNamingService(properties);
ConfigService configService = ConfigFactory.createConfigService(properties);

Spring Cloud Alibaba framework

If you use the Spring Cloud Alibaba framework, add the following configuration to the configuration file of your application:

Note

You need to upgrade the Spring Cloud Alibaba framework to 2.2.1.RELEASE or later.

## Registry
spring.cloud.nacos.discovery.accessKey=${accessKey}
spring.cloud.nacos.discovery.secretKey=${secretKey}

## Configuration center
spring.cloud.nacos.config.accessKey=${accessKey}
spring.cloud.nacos.config.secretKey=${secretKey}

Dubbo framework

If you use the Dubbo framework, add the following configuration to the registry URL in the configuration file of your Dubbo application.

dubbo.registry.address=nacos://${Endpoint of the MSE Nacos instance}:8848?accessKey=${accessKey}&secretKey=${secretKey}

Nacos client (SDK for Go)

If you use the Nacos client (SDK for Go), add the following configuration to the code of your application:

Note

cc := constant.ClientConfig{
    AccessKey:   "${accessKey}",
    SecretKey:   "${secretKey}"
}

serverConfigs := []constant.ServerConfig{
    {
        IpAddr:      "${Endpoint of the MSE Nacos instance}",
        Port:        8848
    }
}

namingClient, err := clients.NewNamingClient(
    vo.NacosClientParam{
        ClientConfig:  &clientConfig,
        ServerConfigs: serverConfigs,
    },
)

configClient, err := clients.NewConfigClient(
    vo.NacosClientParam{
        ClientConfig:  &clientConfig,
        ServerConfigs: serverConfigs,
    },
)

Nacos client (SDK for Python)

If you use the Nacos client (SDK for Python), add the following configuration to the code of your application:

Note

client = nacos.NacosClient(${Endpoint of the MSE Nacos instance}, ak=${accessKey}, sk=${secretKey})

Method 2: Use an AccessKey pair that automatically rotates

If your application needs to access your MSE Nacos instance for a long period of time, but the AccessKey pair may be leaked in the runtime environment, you need to manually rotate the AccessKey pair with high frequency. In this case, you can use a client key to initialize the credential provider. The underlying logic of this method is to use an AccessKey pair to access services. After you use a client key, Key Management Service (KMS) regularly rotates the AccessKey pair of a managed RAM user and dynamically changes the static AccessKey pair of a RAM user. This reduces the risk of AccessKey pair leaks. KMS also supports immediate rotation to quickly replace a leaked AccessKey pair. This frees you from manually maintaining an AccessKey pair and reduces security risks and maintenance complexity. For more information about how to obtain a client key, see Create an AAP.

Step 1: Manage RAM users by using RAM secrets in KMS

You must manage RAM users by using RAM secrets in the KMS instance. For more information about how to manage RAM secrets in KMS, see Manage and use RAM secrets.

Step 2: Grant permissions to the RAM user

Policy	Description
AliyunMSEFullAccess	The permissions that are required to manage MSE. You can use a RAM user to which this policy is attached to manage all features the same way you use an Alibaba Cloud account to manage all features.
AliyunMSEReadOnlyAccess	The read-only permissions on the resources of MSE. A RAM user to which this policy is attached can only read all MSE resources of the Alibaba Cloud account.

Note

You can attach a maximum of five policies at a time. If you want to attach more than five policies, repeat the step multiple times.
If you want to grant fine-grained permissions, you need to create a custom policy. For more information, see Fine-grained authentication in registries, Fine-grained authentication in configuration centers, and Examples of common custom policies for Microservices Registry.

Step 3: Create a credential management configuration file

Create a configuration file in the project root directory or classpath. Note that the configuration file name must be secretsmanager.properties. The file contains the following content:

cache_client_dkms_config_info=[{"regionId":"<your dkms region>","endpoint":"<your dkms endpoint>","passwordFromFilePath":"< your password file path >","clientKeyFile":"<your Client Key file path>","ignoreSslCerts":false,"caFilePath":"<your CA certificate file path>"}]

Note

For more information about the configuration items in the configuration file, see Client key.

Step 4: Configure authentication on the Nacos client (SDK)

Nacos Client (SDK for Java)

If you use the Nacos client (SDK for Java), add the required dependency and add the following configuration for your application.

Note

The version of the Nacos client must be 2.1.0 or later. For more information, see Nacos client versions supported for authentication, encryption, and decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- The version must be 1.0.5 or later. -->
    <version>1.0.5</version>
</dependency>

properties.put(PropertyKeyConst.SERVER_ADDR, "${Endpoint of the MSE Nacos instance}");
# You can configure the environment variable ALIBABA_CLOUD_SECRET_NAME instead.
properties.put(ExtensionAuthPropertyKey.SECRET_NAME.getKey(), "${Name of the RAM secret}");
NamingService naming = NamingFactory.createNamingService(properties);
ConfigService configService = ConfigFactory.createConfigService(properties);

Spring Cloud Alibaba framework

If you use the Spring Cloud Alibaba framework, add the required dependency and add the following configuration to the configuration file of your application.

Note

You need to upgrade the Spring Cloud Alibaba framework to 2.2.9.RELEASE or later.
The version of the Nacos client must be 2.1.0 or later. For more information, see Nacos client versions supported for authentication, encryption, and decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- The version must be 1.0.5 or later. -->
    <version>1.0.5</version>
</dependency>

## Registry
# You can configure the environment variable ALIBABA_CLOUD_SECRET_NAME instead.
spring.cloud.nacos.discovery.alibabaCloudSecretName=${Name of the RAM secret}

## Configuration center
# You can configure the environment variable ALIBABA_CLOUD_SECRET_NAME instead.
spring.cloud.nacos.config.alibabaCloudSecretName=${Name of the RAM secret}

Dubbo framework

If you use the Dubbo framework, add the required dependency and add the following configuration to the registry URL in the configuration file of your Dubbo application.

Note

The version of the Nacos client must be 2.1.0 or later. For more information, see Nacos client versions supported for authentication, encryption, and decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- The version must be 1.0.5 or later. -->
    <version>1.0.5</version>
</dependency>

# You can configure the environment variable ALIBABA_CLOUD_SECRET_NAME instead.
dubbo.registry.address=nacos://${Endpoint of the MSE Nacos instance}:8848?alibabaCloudSecretName=${Name of the RAM secret}

Method 3: Use an STS token

If your application needs to temporarily access an MSE Nacos instance, you can use security token service (STS) to obtain temporary access credentials and use the credentials to initialize the credential provider. Temporary access credentials consist of an AccessKey ID, an Access Key secret, and an STS token.

Important

This method requires you to manually maintain an STS token. This poses stability risks and increases maintenance complexity. If you want to access an MSE Nacos instance multiple times, you must manually refresh the STS token.

(Optional) Step 1: Create a RAM user and a RAM role

Perform this step if you do not have a RAM user or need to create a RAM user. For more information, see Create a RAM user.
Perform this step if you do not have a RAM role or need to create a RAM role whose trusted entity is an Alibaba Cloud account. For more information, see Create a RAM role for a trusted Alibaba Cloud account.

Step 2: Grant permissions to the RAM user and RAM role

Grant management permissions on STS to the RAM user in Step 1. For more information, see AssumeRole.
Grant permissions to the RAM role in Step 1, and attach one of the following system policies to the RAM role. In this step, a coarse-grained authorization operation is performed to grant the RAM role read permissions and write permissions or read-only permissions on the configurations and services of all MSE Nacos instances. For information about how to perform authorization operations, see Grant permissions to a RAM role.

Policy	Description
AliyunMSEFullAccess	The permissions that are required to manage MSE. You can use a RAM user to which this policy is attached to manage all features the same way you use an Alibaba Cloud account to manage all features.
AliyunMSEReadOnlyAccess	The read-only permissions on the resources of MSE. A RAM user to which this policy is attached can only read all MSE resources of the Alibaba Cloud account.

Note

You can attach a maximum of five policies at a time. If you want to attach more than five policies, repeat the step multiple times.
If you want to grant fine-grained permissions, you need to create a custom policy. For more information, see Fine-grained authentication in registries, Fine-grained authentication in configuration centers, and Examples of common custom policies for Microservices Registry.

Step 3: Obtain an STS token

You must obtain the STS token of the temporary access credentials of the RAM role in Step 1. For more information about how to obtain an STS token, see AssumeRole.

Step 4: Configure authentication on the Nacos client (SDK)

Temporary access credentials consist of an AccessKey ID, an Access Key secret, and an STS token. You must use them together.

Nacos client (SDK for Java)

If you use the Nacos client (SDK for Java), add the required dependency and add the following configuration for your application.

Note

The version of the Nacos client must be 2.1.0 or later. For more information, see Nacos client versions supported for authentication, encryption, and decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- The version must be 1.0.5 or later. -->
    <version>1.0.5</version>
</dependency>

properties.put(PropertyKeyConst.SERVER_ADDR, "${Endpoint of the MSE Nacos instance}");
# You can configure the environment variable ALIBABA_CLOUD_ACCESS_KEY_ID instead.
properties.put(ExtensionAuthPropertyKey.ACCESS_KEY_ID.getKey(), "${AccessKey ID of the temporary credentials}");
# You can configure the environment variable ALIBABA_CLOUD_ACCESS_KEY_SECRET instead.
properties.put(ExtensionAuthPropertyKey.ACCESS_KEY_SECRET.getKey(), "${AccessKey secret of the temporary credentials}");
# You can configure the environment variable ALIBABA_CLOUD_SECURITY_TOKEN instead.
properties.put(ExtensionAuthPropertyKey.SECURITY_TOKEN_KEY.getKey(), "${Security token of the temporary credentials}");
NamingService naming = NamingFactory.createNamingService(properties);
ConfigService configService = ConfigFactory.createConfigService(properties);

Spring Cloud Alibaba framework

If you use the Spring Cloud Alibaba framework, add the required dependency and add the following configuration to the configuration file of your application.

Note

You need to upgrade the Spring Cloud Alibaba framework to 2.2.9.RELEASE or later.
The version of the Nacos client must be 2.1.0 or later. For more information, see Nacos client versions supported for authentication, encryption, and decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- The version must be 1.0.5 or later. -->
    <version>1.0.5</version>
</dependency>

## Registry
# You can configure the environment variable ALIBABA_CLOUD_ACCESS_KEY_ID instead.
spring.cloud.nacos.discovery.alibabaCloudAccessKeyId=${AccessKey ID of the temporary credentials}
# You can configure the environment variable ALIBABA_CLOUD_ACCESS_KEY_SECRET instead.
spring.cloud.nacos.discovery.alibabaCloudAccessKeySecret=${AccessKey secret of the temporary credentials}
# You can configure the environment variable ALIBABA_CLOUD_SECURITY_TOKEN instead.
spring.cloud.nacos.discovery.alibabaCloudSecurityToken=${Security token of the temporary credentials}

## Configuration center
# You can configure the environment variable ALIBABA_CLOUD_ACCESS_KEY_ID instead.
spring.cloud.nacos.config.alibabaCloudAccessKeyId=${AccessKey ID of the temporary credentials}
# You can configure the environment variable ALIBABA_CLOUD_ACCESS_KEY_SECRET instead.
spring.cloud.nacos.config.alibabaCloudAccessKeySecret=${AccessKey secret of the temporary credentials}
# You can configure the environment variable ALIBABA_CLOUD_SECURITY_TOKEN instead.
spring.cloud.nacos.config.alibabaCloudSecurityToken=${Security token of the temporary credentials}

Dubbo framework

If you use the Dubbo framework, add the required dependency and add the following configuration to the registry URL in the configuration file of your Dubbo application.

Note

The version of the Nacos client must be 2.1.0 or later. For more information, see Nacos client versions supported for authentication, encryption, and decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- The version must be 1.0.5 or later. -->
    <version>1.0.5</version>
</dependency>

# You can configure the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET, and ALIBABA_CLOUD_SECURITY_TOKEN instead.
dubbo.registry.address=nacos://${Endpoint of the MSE Nacos instance}:8848?alibabaCloudAccessKeyId=${AccessKey ID of the temporary credentials}&alibabaCloudAccessKeySecret=${AccessKey secret of the temporary credentials}&alibabaCloudSecurityToken=${Security token of the temporary credentials}

Method 4: Use the ARN of a RAM role

This method is suitable for scenarios in which you need to authorize your application to access an MSE Nacos instance. For example, if you want to access an MSE Nacos instance across Alibaba Cloud accounts, you can use the Alibaba Cloud Resource Name (ARN) of a RAM role to initialize the credential provider. The underlying logic of this method is to use an STS token to access services. With the ARN of a specified RAM role, the Nacos client obtains an STS token from STS and automatically refreshes the STS token before the session expires. You can assign a value to the policy parameter to limit the permissions of the RAM role.

Important

This method requires an AccessKey pair that can be used to assume a role. We recommend that you grant the AccessKey pair the permissions to assume roles and restrict the roles that the AccessKey pair can assume. For more information, see AssumeRole.

(Optional) Step 1: Create a RAM user and a RAM role

Perform this step if you do not have a RAM user or need to create a RAM user. For more information, see Create a RAM user.
Perform this step if you do not have a RAM role or need to create a RAM role whose trusted entity is an Alibaba Cloud account. For more information, see Create a RAM role for a trusted Alibaba Cloud account.

Step 2: Grant permissions to the RAM user and RAM role

Grant management permissions on STS to the RAM user in Step 1. For more information, see AssumeRole.
Grant permissions to the RAM role in Step 1, and attach one of the following system policies to the RAM role. In this step, a coarse-grained authorization operation is performed to grant the RAM role read permissions and write permissions or read-only permissions on the configurations and services of all MSE Nacos instances. For information about how to perform authorization operations, see Grant permissions to a RAM role.

Policy	Description
AliyunMSEFullAccess	The permissions that are required to manage MSE. You can use a RAM user to which this policy is attached to manage all features the same way you use an Alibaba Cloud account to manage all features.
AliyunMSEReadOnlyAccess	The read-only permissions on the resources of MSE. A RAM user to which this policy is attached can only read all MSE resources of the Alibaba Cloud account.

Note

You can attach a maximum of five policies at a time. If you want to attach more than five policies, repeat the step multiple times.
If you want to grant fine-grained permissions, you need to create a custom policy. For more information, see Fine-grained authentication in registries, Fine-grained authentication in configuration centers, and Examples of common custom policies for Microservices Registry.

Step 3: Configure authentication on the Nacos client (SDK)

To use this method, you must configure an AccessKey pair and the ARN of the RAM role as the credentials.

Nacos client (SDK for Java)

If you use the Nacos client (SDK for Java), add the required dependency and add the following configuration for your application.

Note

The version of the Nacos client must be 2.1.0 or later. For more information, see Nacos client versions supported for authentication, encryption, and decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- The version must be 1.0.5 or later. -->
    <version>1.0.5</version>
</dependency>

properties.put(PropertyKeyConst.SERVER_ADDR, "${Endpoint of the MSE Nacos instance}");
# You can configure the environment variable ALIBABA_CLOUD_ACCESS_KEY_ID instead.
properties.put(ExtensionAuthPropertyKey.ACCESS_KEY_ID.getKey(), "${AccessKey ID that can assume a role}");
# You can configure the environment variable ALIBABA_CLOUD_ACCESS_KEY_SECRET instead.
properties.put(ExtensionAuthPropertyKey.ACCESS_KEY_SECRET.getKey(), "${AccessKey secret that can assume a role}");
# You can configure the environment variable ALIBABA_CLOUD_ROLE_ARN instead.
properties.put(ExtensionAuthPropertyKey.ROLE_ARN.getKey(), "${ARN of the assumed role}");
# You can configure the environment variable ALIBABA_CLOUD_ROLE_SESSION_NAME instead.
properties.put(ExtensionAuthPropertyKey.ROLE_SESSION_NAME.getKey(), "${Custom name of the session for role assuming}");
## The following parameters are optional.
# You can configure the environment variable ALIBABA_CLOUD_POLICY instead.
properties.put(ExtensionAuthPropertyKey.POLICY.getKey(), "${Configure a policy with limited permissions}");
# You can configure the environment variable ALIBABA_CLOUD_ROLE_SESSION_EXPIRATION instead.
properties.put(ExtensionAuthPropertyKey.ROLE_SESSION_EXPIRATION.getKey(), "${Validity period of role assuming. Unit: seconds}");
NamingService naming = NamingFactory.createNamingService(properties);
ConfigService configService = ConfigFactory.createConfigService(properties);

Spring Cloud Alibaba framework

If you use the Spring Cloud Alibaba framework, add the required dependency and add the following configuration to the configuration file of your application.

Note

You need to upgrade the Spring Cloud Alibaba framework to 2.2.9.RELEASE or later.
The version of the Nacos client must be 2.1.0 or later. For more information, see Nacos client versions supported for authentication, encryption, and decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- The version must be 1.0.5 or later. -->
    <version>1.0.5</version>
</dependency>

## Registry
# You can configure the environment variable ALIBABA_CLOUD_ACCESS_KEY_ID instead.
spring.cloud.nacos.discovery.alibabaCloudAccessKeyId=${AccessKey ID that can assume a role}
# You can configure the environment variable ALIBABA_CLOUD_ACCESS_KEY_SECRET instead.
spring.cloud.nacos.discovery.alibabaCloudAccessKeySecret=${AccessKey secret that can assume a role}
# You can configure the environment variable ALIBABA_CLOUD_ROLE_ARN instead.
spring.cloud.nacos.discovery.alibabaCloudRoleArn=${ARN of the assumed role}
# You can configure the environment variable ALIBABA_CLOUD_ROLE_SESSION_NAME instead.
spring.cloud.nacos.discovery.alibabaCloudRoleSessionName=${Custom name of the session for role assuming}

## Configuration center
# You can configure the environment variable ALIBABA_CLOUD_ACCESS_KEY_ID instead.
spring.cloud.nacos.config.alibabaCloudAccessKeyId=${AccessKey ID that can assume a role}
# You can configure the environment variable ALIBABA_CLOUD_ACCESS_KEY_SECRET instead.
spring.cloud.nacos.config.alibabaCloudAccessKeySecret=${AccessKey secret that can assume a role}
# You can configure the environment variable ALIBABA_CLOUD_ROLE_ARN instead.
spring.cloud.nacos.config.alibabaCloudRoleArn=${ARN of the assumed role}
# You can configure the environment variable ALIBABA_CLOUD_ROLE_SESSION_NAME instead.
spring.cloud.nacos.config.alibabaCloudRoleSessionName=${Custom name of the session for role assuming}

## The following parameters are optional.
# You can configure the environment variable ALIBABA_CLOUD_POLICY instead.
spring.cloud.nacos.discovery.alibabaCloudPolicy=${Configure a policy with limited permissions}
spring.cloud.nacos.config.alibabaCloudPolicy=${Configure a policy with limited permissions}
# You can configure the environment variable ALIBABA_CLOUD_ROLE_SESSION_EXPIRATION instead.
spring.cloud.nacos.discovery.alibabaCloudRoleSessionExpiration=${Validity period of role assuming. Unit: seconds}
spring.cloud.nacos.config.alibabaCloudRoleSessionExpiration=${Validity period of role assuming. Unit: seconds}

Dubbo framework

If you use the Dubbo framework, add the required dependency and add the following configuration to the registry URL in the configuration file of your Dubbo application.

Note

The version of the Nacos client must be 2.1.0 or later. For more information, see Nacos client versions supported for authentication, encryption, and decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- The version must be 1.0.5 or later. -->
    <version>1.0.5</version>
</dependency>

# You can configure the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET, ALIBABA_CLOUD_ROLE_ARN, and ALIBABA_CLOUD_ROLE_SESSION_NAME instead.
dubbo.registry.address=nacos://${Endpoint of the MSE Nacos instance}:8848?alibabaCloudAccessKeyId=${AccessKey ID that can assume a role}&alibabaCloudAccessKeySecret=${AccessKey secret that can assume a role}&alibabaCloudRoleArn=${ARN of the assumed role}&alibabaCloudRoleSessionName=${Custom name of the session for role assuming}

## The following parameters are optional and are added after the URL. You can configure the environment variables ALIBABA_CLOUD_POLICY and ALIBABA_CLOUD_ROLE_SESSION_EXPIRATION instead.
&alibabaCloudPolicy=${Configure a policy with limited permissions}&alibabaCloudRoleSessionExpiration=${Validity period of role assuming. Unit: seconds}

Method 5: Use the RAM role of an ECS instance

You can associate a RAM role with an ECS instance or ACK cluster and notify the Nacos client of the RAM role name. This way, your application can access the MSE Nacos instance without requiring you to specify the AccessKey pair. You can configure RAM roles and policies for instances to control the granularity or the scope of access permissions of the RAM roles. For more information, see Overview, Use RAM and RBAC to implement access control, and RAM role overview.

Note

To use a RAM role of an ECS instance for access authentication, you must deploy your application on an ECS instance or in an ACK cluster and make sure that the network type of the ECS instance or ACK cluster is virtual private cloud (VPC). For more information, see What is ECS?, What is ACK?, and What is a VPC?

Step 1: Create a RAM role and attach policies to the RAM role

Grant an ECS instance a role that can access an MSE Nacos instance

Optional. Create a RAM role whose trusted entity is an Alibaba Cloud service. For more information, see Create a RAM role for a trusted Alibaba Cloud service.

Grant permissions to an existing RAM role or the RAM role that you created, and attach one of the following system policies to the RAM role. In this step, a coarse-grained authorization operation is performed to grant the RAM role read permissions and write permissions or read-only permissions on the configurations and services of all MSE Nacos instances. For information about how to perform authorization operations, see Grant permissions to a RAM role.

Policy	Description
AliyunMSEFullAccess	The permissions that are required to manage MSE. You can use a RAM user to which this policy is attached to manage all features the same way you use an Alibaba Cloud account to manage all features.
AliyunMSEReadOnlyAccess	The read-only permissions on the resources of MSE. A RAM user to which this policy is attached can only read all MSE resources of the Alibaba Cloud account.

Note

You can attach a maximum of five policies at a time. If you want to attach more than five policies, repeat the step multiple times.
If you want to grant fine-grained permissions, you need to create a custom policy. For more information, see Fine-grained authentication in registries, Fine-grained authentication in configuration centers, and Examples of common custom policies for Microservices Registry.

Log on to the ECS console. In the left-side navigation pane, choose Instances & Images > Instances.
In the top navigation bar, select the resource group and region where the destination resources reside.
Find the desired ECS instance, and choose > Instance Settings > Attach/Detach RAM Role.
In the Attach/Detach RAM Role dialog box, select the instance RAM role that you create from the RAM Role drop-down list, and click Confirm.

Grant permissions to the worker RAM role in the ACK cluster

Note

When you create an ACK cluster, the worker RAM role is automatically created. Therefore, you do not need to create a RAM role again.

Create a custom policy. For more information, see Create custom policies.

Grant the worker RAM role the management permissions on MSE.

{
    "Action": "mse:*",
    "Resource": "*",
    "Effect": "Allow"
},
{
    "Action": "ram:CreateServiceLinkedRole",
    "Resource": "*",
    "Effect": "Allow",
    "Condition": {
        "StringEquals": {
            "ram:ServiceName": "mse.aliyuncs.com"
        }
    }
}

Grant the worker RAM role the read-only permissions on MSE.

{
    "Action": [
        "mse:Query*",
        "mse:List*",
        "mse:Get*"
    ],
    "Resource": "*",
    "Effect": "Allow"
},
{
    "Action": "ram:CreateServiceLinkedRole",
    "Resource": "*",
    "Effect": "Allow",
    "Condition": {
        "StringEquals": {
            "ram:ServiceName": "mse.aliyuncs.com"
        }
    }
}

Note

If you want to grant fine-grained permissions, you need to create a custom policy. For more information, see Fine-grained authentication in registries, Fine-grained authentication in configuration centers, and Examples of common custom policies for Microservices Registry.

Attach the custom policy to the worker RAM role of the cluster. For more information, see Grant permissions to the worker RAM role.

Step 2: Configure authentication on the client (SDK)

Nacos client (SDK for Java)

If you use the Nacos client (SDK for Java), add the following code for your application.

Note

To use a RAM role for authentication, you need to upgrade the client to the required version. For more information, see Nacos client versions supported for authentication, encryption, and decryption.

properties.put(PropertyKeyConst.SERVER_ADDR, "${Endpoint of the MSE Nacos instance}");
properties.put(PropertyKeyConst.RAM_ROLE_NAME, "${roleName}");
// Registry
NamingService naming = NamingFactory.createNamingService(properties);
// Configuration center
ConfigService configService = ConfigFactory.createConfigService(properties);

Spring Cloud Alibaba framework

If you use the Spring Cloud Alibaba framework, add the following configuration to the configuration file of your application:

Note

You need to upgrade the Spring Cloud Alibaba framework to 2.2.9.RELEASE or later.

## Registry
spring.cloud.nacos.discovery.ramRoleName=${roleName}

## Configuration center
spring.cloud.nacos.config.ramRoleName=${roleName}

Dubbo framework

If you use the Dubbo framework, add the following configuration to the registry URL in the configuration file of your Dubbo application.

dubbo.registry.address=nacos://${Endpoint of the MSE Nacos instance}:8848?ramRoleName=${roleName}

Method 6: Use the RAM role of an OIDC IdP

After you attach a RAM role (Method 5) to a worker node in an ACK cluster, applications in the pods on the worker node can use the metadata server to obtain an STS token the same way in which applications on ECS instances do. However, if an untrusted application is deployed on the worker node, such as an application that is submitted by your customer and whose code is unavailable to you, you may not want the application to use the metadata server to obtain an STS token of the RAM role attached to the worker node.

To ensure the security of cloud resources, allow untrusted applications to securely obtain the required security token, and minimize application-level permissions, you can use the RAM Roles for Service Account (RRSA) feature. The underlying logic of this method is to use an STS token to access services. ACK clusters create and mount OpenID Connect (OIDC) token files of accounts for different application pods, and pass relevant configuration information to environment variables. The Nacos client obtains the configuration information of environment variables and calls the AssumeRoleWithOIDC operation of STS to obtain the STS token of attached roles. This method eliminates the risks that may arise when you manually maintain an AccessKey pair or an STS token.

Step 1: Enable the RRSA feature for the ACK cluster

For more information about how to enable the RRSA feature for the ACK cluster, see Use RRSA to authorize different pods to access different cloud services.

Step 2: Grant permissions to the RAM role

Grant the RAM role in Step 1, such as the demo-role-for-rrsa role in Use RRSA to authorize different pods to access different cloud services the permissions to access the MSE Nacos instance, and attach one of the following system policies to the RAM role. In this step, a coarse-grained authorization operation is performed to grant the RAM role read permissions and write permissions or read-only permissions on the configurations and services of all MSE Nacos instances. For information about how to perform authorization operations, see Grant permissions to a RAM role.

Policy	Description
AliyunMSEFullAccess	The permissions that are required to manage MSE. You can use a RAM user to which this policy is attached to manage all features the same way you use an Alibaba Cloud account to manage all features.
AliyunMSEReadOnlyAccess	The read-only permissions on the resources of MSE. A RAM user to which this policy is attached can only read all MSE resources of the Alibaba Cloud account.

Note

You can attach a maximum of five policies at a time. If you want to attach more than five policies, repeat the step multiple times.
If you want to grant fine-grained permissions, you need to create a custom policy. For more information, see Fine-grained authentication in registries, Fine-grained authentication in configuration centers, and Examples of common custom policies for Microservices Registry.

Step 3: Configure authentication on the Nacos client (SDK)

This method requires you to configure only RoleSessionName. Other temporary credentials are provided based on the environment variables passed by the RRSA feature of the ACK cluster.

Nacos client (SDK for Java)

If you use the Nacos client (SDK for Java), add the following code for your application.

Note

The version of the Nacos client must be 2.1.0 or later. For more information, see Nacos client versions supported for authentication, encryption, and decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- The version must be 1.0.5 or later. -->
    <version>1.0.5</version>
</dependency>

properties.put(PropertyKeyConst.SERVER_ADDR, "${Endpoint of the MSE Nacos instance}");
# You can configure the environment variable ALIBABA_CLOUD_ROLE_SESSION_NAME instead.
properties.put(ExtensionAuthPropertyKey.ROLE_SESSION_NAME.getKey(), "${Custom name of the session for role assuming}");
## The following parameters are optional.
# You can configure the environment variable ALIBABA_CLOUD_POLICY instead.
properties.put(ExtensionAuthPropertyKey.POLICY.getKey(), "${Configure a policy with limited permissions}");
# You can configure the environment variable ALIBABA_CLOUD_ROLE_SESSION_EXPIRATION instead.
properties.put(ExtensionAuthPropertyKey.ROLE_SESSION_EXPIRATION.getKey(), "${Validity period of role assuming. Unit: seconds}");
NamingService naming = NamingFactory.createNamingService(properties);
ConfigService configService = ConfigFactory.createConfigService(properties);

Spring Cloud Alibaba framework

If you use the Spring Cloud Alibaba framework, add the required dependency and add the following configuration to the configuration file of your application.

Note

You need to upgrade the Spring Cloud Alibaba framework to 2.2.9.RELEASE or later.
The version of the Nacos client must be 2.1.0 or later. For more information, see Nacos client versions supported for authentication, encryption, and decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- The version must be 1.0.5 or later. -->
    <version>1.0.5</version>
</dependency>

## Registry
# You can configure the environment variable ALIBABA_CLOUD_ROLE_SESSION_NAME instead.
spring.cloud.nacos.discovery.alibabaCloudRoleSessionName=${Custom name of the session for role assuming}

## Configuration center
# You can configure the environment variable ALIBABA_CLOUD_ROLE_SESSION_NAME instead.
spring.cloud.nacos.config.alibabaCloudRoleSessionName=${Custom name of the session for role assuming}

## The following parameters are optional.
# You can configure the environment variable ALIBABA_CLOUD_POLICY instead.
spring.cloud.nacos.discovery.alibabaCloudPolicy=${Configure a policy with limited permissions}
spring.cloud.nacos.config.alibabaCloudPolicy=${Configure a policy with limited permissions}
# You can configure the environment variable ALIBABA_CLOUD_ROLE_SESSION_EXPIRATION instead.
spring.cloud.nacos.discovery.alibabaCloudRoleSessionExpiration=${Validity period of role assuming. Unit: seconds}
spring.cloud.nacos.config.alibabaCloudRoleSessionExpiration=${Validity period of role assuming. Unit: seconds}

Dubbo framework

If you use the Dubbo framework, add the required dependency and add the following configuration to the registry URL in the configuration file of your Dubbo application.

Note

The version of the Nacos client must be 2.1.0 or later. For more information, see Nacos client versions supported for authentication, encryption, and decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- The version must be 1.0.5 or later. -->
    <version>1.0.5</version>
</dependency>

# You can configure the environment variable ALIBABA_CLOUD_ROLE_SESSION_NAME instead.
dubbo.registry.address=nacos://${Endpoint of the MSE Nacos instance}:8848?alibabaCloudRoleSessionName=${Custom name of the session for role assuming}

## The following parameters are optional and are added after the URL. You can configure the environment variables ALIBABA_CLOUD_POLICY and ALIBABA_CLOUD_ROLE_SESSION_EXPIRATION instead.
&alibabaCloudPolicy=${Configure a policy with limited permissions}&alibabaCloudRoleSessionExpiration=${Validity period of role assuming. Unit: seconds}

Method 7: Use credentials URIs

If your application needs to obtain an Alibaba Cloud credential from an external system to implement flexible credential management and keyless access, you can use the credentials URI to initialize a credential provider. The underlying logic of this method is to use an STS token to access services. The Nacos client obtains the STS token by using the URI that you specify and use the token to initialize the credential client. This method eliminates the risks that may arise when you manually maintain an AccessKey pair or an STS token.

Important

The backend service that provides the credentials URI response must automatically refresh the STS token to ensure that your application can always obtain a valid credential.

Step 1: Confirm that the response from the credentials URI service is valid

To allow the Nacos client to correctly parse and use an STS token, the credentials URI must comply with the following response protocol:

Response status code: 200

Response body structure:

{
    "Code": "Success",
    "AccessKeySecret": "AccessKeySecret",
    "AccessKeyId": "AccessKeyId",
    "Expiration": "2021-09-26T03:46:38Z",
    "SecurityToken": "SecurityToken"
}

Step 2: Grant permissions to the RAM role

Grant the RAM role in Step 1 the permissions to access the MSE Nacos instance, and attach one of the following system policies to the RAM role: In this step, a coarse-grained authorization operation is performed to grant the RAM role read permissions and write permissions or read-only permissions on the configurations and services of all MSE Nacos instances. For information about how to perform authorization operations, see Grant permissions to a RAM role.

Policy	Description
AliyunMSEFullAccess	The permissions that are required to manage MSE. You can use a RAM user to which this policy is attached to manage all features the same way you use an Alibaba Cloud account to manage all features.
AliyunMSEReadOnlyAccess	The read-only permissions on the resources of MSE. A RAM user to which this policy is attached can only read all MSE resources of the Alibaba Cloud account.

Note

You can attach a maximum of five policies at a time. If you want to attach more than five policies, repeat the step multiple times.
If you want to grant fine-grained permissions, you need to create a custom policy. For more information, see Fine-grained authentication in registries, Fine-grained authentication in configuration centers, and Examples of common custom policies for Microservices Registry.

Step 3: Configure authentication on the Nacos client (SDK)

Nacos client (SDK for Java)

If you use the Nacos client (SDK for Java), add the required dependency and add the following configuration for your application.

Note

The version of the Nacos client must be 2.1.0 or later. For more information, see Nacos client versions supported for authentication, encryption, and decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- The version must be 1.0.5 or later. -->
    <version>1.0.5</version>
</dependency>

properties.put(PropertyKeyConst.SERVER_ADDR, "${Endpoint of the MSE Nacos instance}");
# You can configure the environment variable ALIBABA_CLOUD_CREDENTIALS_URI instead.
properties.put(ExtensionAuthPropertyKey.CREDENTIALS_URI.getKey(), "${URI of the credentials service, such as https://$host:$port/$path....");
NamingService naming = NamingFactory.createNamingService(properties);
ConfigService configService = ConfigFactory.createConfigService(properties);

Spring Cloud Alibaba framework

If you use the Spring Cloud Alibaba framework, add the required dependency and add the following configuration to the configuration file of your application.

Note

You need to upgrade the Spring Cloud Alibaba framework to 2.2.9.RELEASE or later.
The version of the Nacos client must be 2.1.0 or later. For more information, see Nacos client versions supported for authentication, encryption, and decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- The version must be 1.0.5 or later. -->
    <version>1.0.5</version>
</dependency>

## Registry
# You can configure the environment variable ALIBABA_CLOUD_CREDENTIALS_URI instead.
spring.cloud.nacos.discovery.alibabaCloudCredentialsUri=${URI of the credentials service, such as https://$host:$port/$path....}

## Configuration center
# You can configure the environment variable ALIBABA_CLOUD_CREDENTIALS_URI instead.
spring.cloud.nacos.config.alibabaCloudCredentialsUri=${URI of the credentials service, such as https://$host:$port/$path....}

Dubbo framework

If you use the Dubbo framework, add the required dependency and add the following configuration to the registry URL in the configuration file of your Dubbo application.

Note

The version of the Nacos client must be 2.1.0 or later. For more information, see Nacos client versions supported for authentication, encryption, and decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- The version must be 1.0.5 or later. -->
    <version>1.0.5</version>
</dependency>

# You can configure the environment variable ALIBABA_CLOUD_CREDENTIALS_URI instead.
dubbo.registry.address=nacos://${Endpoint of the MSE Nacos instance}:8848?alibabaCloudCredentialsUri=${Credentials URI, such as https://$host:$port/$path....}

References

If you need to access an MSE Nacos instance over the Internet, make sure that a public IP address whitelist is configured. For more information, see Configure a public IP address whitelist.
For more information about fine-grained authorization, see Fine-grained authentication in registries and Fine-grained authentication in configuration centers.
For more information about how to grant permissions in the MSE console, see Grant permissions on Microservices Registry resources.
For more information about Nacos issues, see Nacos FAQ.