Enable Nacos access authentication - Microservices Engine

Enable authentication for Nacos instances in Microservices Engine (MSE) to prevent unauthorized access to or modification of instance data. This topic describes how to enable authentication and configure client credentials.

Prerequisites

Access methods

Authentication uses the direct engine connection method. After authorization, a Nacos client can access the MSE Nacos instance with a RAM user or a RAM role.

Direct engine connection: Access the Nacos engine directly with an SDK or client. This method is for programmatic access.
Console-based engine connection: Manage and monitor the Nacos engine in the MSE console. For details about granting a RAM user access to the MSE console, see registry and configuration center authorization.

Enable authentication

Important

By default, authentication is disabled for new Nacos engines, which means they respond to all requests.
The logon feature of the open source Nacos console only records user information and does not authenticate or intercept requests. After you enable authentication for a Nacos instance, you can no longer access it from the open source Nacos console and must use the MSE console.
For Nacos 2.x and certain later versions where console password modification is not supported: after you enable authentication, you cannot reset or modify the Nacos password through the MSE console. You must use AccessKey (AK) and SecretKey (SK) to configure client authentication. For more information, see Method 6: Use an AccessKey in this topic.

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, click parameter settings. On the parameter settings page, click Edit.

Select the ConfigAuthEnabled or NamingAuthEnabled parameter, click Yes in the Value column for the parameter, and then click Save and Restart Instance.

Important

Before you enable authentication for the configuration center or registry, you must configure access credentials on the client. Otherwise, the client cannot obtain configurations or services. For more information, see Configure access credentials on the client.
These two parameters function independently of each other, and each controls its respective module.

Parameter	Description
ConfigAuthEnabled	Enables authentication for the configuration center. Supported by instances of Basic Edition V1.2.1 and later, and all versions of Professional Edition and Developer Edition.
NamingAuthEnabled	Enables authentication for the registry. Supported by instances of Professional Edition or Developer Edition V2.0.4 and later.

Configure client credentials

MSE Nacos supports several credential initialization methods. Choose the one that best fits your scenario.

Initialization method	Scenario	Prerequisite	Underlying credential	Validity	Rotation and refresh
Method 1: Use an ECS RAM role	Applications deployed on Alibaba Cloud compute resources, such as Elastic Compute Service (ECS) instances, Elastic Container Instance (ECI) instances, or worker nodes in Container Service for Kubernetes (ACK).	No	STS token	Temporary	Automatic refresh
Method 2: Use an OIDC role ARN	Untrusted applications deployed on worker nodes in Container Service for Kubernetes (ACK).	No	STS token	Temporary	Automatic refresh
Method 3: Use an STS token	Applications in untrusted environments that require control over credential validity and access permissions.	Yes	STS token	Temporary	Manual refresh
Method 4: Use a credentials URI	Applications that obtain credentials from an external system.	No	STS token	Temporary	Automatic refresh
Method 5: Use a RAM role ARN	Applications that require delegated access to cloud services, such as for cross-account access.	Yes	STS token	Temporary	Automatic refresh
Method 6: Use an Access Key (AK)	Applications in secure environments requiring long-term access to cloud services without frequent credential rotation.	Yes	Access Key (AK)	Long-term	Manual rotation
Method 7: Use an automatically rotated Access Key	Applications in environments with a risk of Access Key (AK) compromise, requiring frequent credential rotation for long-term cloud service access.	No	Access Key (AK)	Long-term	Automatic rotation

Method 1: Authenticate with a RAM role

Associate a RAM role with an ECS instance or an ACK cluster to grant your application access to MSE. The application authenticates by providing the RAM role name to the Nacos client, eliminating the need for static AccessKey credentials. You can define different roles and policies for granular access control. For more information, see RAM Roles for ECS Instances, Authorization Overview, and RAM Role Overview.

Note

To use a RAM role for authentication, you must deploy your application to an Alibaba Cloud ECS instance or an ACK cluster within a VPC. For more information, see What is ECS?, What is ACK?, and What is VPC?.

Step 1: Create a RAM role and configure policies

Grant an ECS instance access to MSE

(Optional) Create a RAM role that uses an Alibaba Cloud service as the trusted entity. For more information, see Create a RAM role for an Alibaba Cloud service.

Grant permissions to the RAM role by attaching one of the following system policies. These policies provide coarse-grained read/write or read-only access to all Nacos instance configurations and services. For more information, see Grant permissions to a RAM role.

Policy name	Description
AliyunMSEFullAccess	Grants full MSE management permissions. A RAM user with this policy has the same operational permissions as an Alibaba Cloud account.
AliyunMSEReadOnlyAccess	Grants read-only MSE permissions. A RAM user with this policy can view all MSE resources under the Alibaba Cloud account.

Note

You can attach a maximum of five policies at a time. To attach more policies, repeat the operation.
To grant fine-grained permissions to an instance, create a custom policy. For more information, see Fine-grained authentication for registries, Fine-grained authentication for configuration centers, and Examples of common custom policies for registries and configuration centers.

Log on to the ECS console. In the left-side navigation pane, choose Instances & Images > Instance.
In the top-left corner of the page, select the target region and resource group.

For example, select a resource group from the All Resources drop-down list and a region, such as China (Hangzhou), from the region selector.
Find the ECS instance that you want to manage, and choose > Instance Settings > Attach/Detach RAM Role.
In the dialog box, select the instance RAM role that you created and click OK.

Grant permissions to an ACK worker RAM role

Note

When you create an ACK cluster, a worker RAM role is automatically created. You can grant permissions directly to this role without creating a new one.

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

To grant full management permissions for MSE:

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

To grant read-only permissions for 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

To grant fine-grained permissions for a specific MSE instance, create a custom policy. For more information, see Fine-grained authentication for registries, Fine-grained authentication for configuration centers, and Examples of common custom policies for registries and configuration centers.

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

Step 2: Configure client authentication

Nacos client for Java

If you use the Nacos client for Java, configure your application code as follows.

Note

To use a RAM role for authentication, upgrade your client to a supported version. For more information, see Nacos client versions that support authentication and encryption/decryption.

properties.put(PropertyKeyConst.SERVER_ADDR, "${mse-nacos-instance-domain}");
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 your application's configuration file.

Note

Upgrade the Spring Cloud Alibaba framework to version 2.2.9.RELEASE or later.

Upgrade the Nacos client to version 2.2.0 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 parameter to the registry URL in your Dubbo configuration file.

Note

Upgrade the Nacos client to version 2.2.0 or later.

dubbo.registry.address=nacos://${mse-nacos-instance-domain}:8848?ramRoleName=${roleName}

Go SDK

If you use the Nacos client for Go, configure your application code as follows.

Note

Version 2.3.3 or later is recommended.

	// Create ServerConfig
	sc := []constant.ServerConfig{
		*constant.NewServerConfig("${mse-nacos-instance-domain}", 8848, constant.WithContextPath("/nacos")),
	}
	ramConfig := constant.RamConfig{
		RamRoleName: "${roleName}",
	}
	// Create ClientConfig
	cc := *constant.NewClientConfig(
		constant.WithNamespaceId(""),
		constant.WithTimeoutMs(5000),
		constant.WithNotLoadCacheAtStart(true),
		constant.WithLogDir("/tmp/nacos/log"),
		constant.WithCacheDir("/tmp/nacos/cache"),
		constant.WithRamConfig(&ramConfig),
	)
	// Create a config client
	configClient, err := clients.NewConfigClient(
		vo.NacosClientParam{
			ClientConfig:  &cc,
			ServerConfigs: sc,
		},
	)
	// Create a naming client
	serviceClient, err := clients.NewNamingClient(
		vo.NacosClientParam{
			ClientConfig:  &cc,
			ServerConfigs: sc,
		},
	)

Method 2: Use OIDCRoleARN

When a RAM role is configured for a worker node in Container Service for Kubernetes (ACK) (as described in Method 1), pods on that node can obtain an STS token from the metadata server. However, if your cluster hosts untrusted applications, you may not want them to access the metadata server and retrieve the worker node's STS token.

To enforce pod-level, least-privilege permissions, use the RRSA (RAM Roles for Service Account) feature. The ACK cluster mounts a service account OIDC token file for each pod and injects the configuration into environment variables. The Nacos client reads these variables and calls the STS AssumeRoleWithOIDC operation, exchanging the OIDC token for an STS token bound to the specified RAM role. No AccessKey pair or manual STS token management is required.

Step 1: Enable RRSA for the ACK cluster

To enable the RRSA feature for your ACK cluster, see Use RRSA to grant RAM permissions to service accounts for pod-level access control.

Step 2: Grant permissions to the RAM role

Grant the RAM role from Step 1 (for example, demo-role-for-rrsa in Use RRSA to grant RAM permissions to service accounts for pod-level access control) access to MSE Nacos by attaching one of the following system policies. These policies grant the RAM role coarse-grained read/write or read-only permissions on the configurations and services of all Nacos instances. For detailed instructions, see Manage permissions for a RAM role.

Policy name	Description
AliyunMSEFullAccess	Grants full MSE management permissions. A RAM user with this policy has the same permissions as an Alibaba Cloud account to perform all operations.
AliyunMSEReadOnlyAccess	Grants read-only MSE permissions. A RAM user with this policy can view all MSE resources under the Alibaba Cloud account.

Note

You can attach a maximum of five policies at a time. To attach more policies, repeat the operation.
To grant fine-grained MSE access permissions to an instance, create a custom policy. For more information, see Fine-grained authentication for registries, Fine-grained authentication for configuration centers, and Examples of common custom policies for registries and configuration centers.

Step 3: Configure client authentication

With this method, you only need to configure the RoleSessionName. The ACK RRSA feature provides other temporary credentials through injected environment variables.

Nacos client for Java

If you use the Nacos client for Java, configure your application code as follows.

Note

The Nacos client must be version 2.1.0 or later. For more information, see Nacos client versions that support authentication and encryption/decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- Version 1.0.5 or later is required. -->
    <version>1.0.5</version>
</dependency>

properties.put(PropertyKeyConst.SERVER_ADDR, "${mse-nacos-instance-domain}");
# This can be replaced by the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
properties.put(ExtensionAuthPropertyKey.ROLE_SESSION_NAME.getKey(), "${custom-role-session-name}");
## The following parameters are optional.
# This can be replaced by the ALIBABA_CLOUD_POLICY environment variable.
properties.put(ExtensionAuthPropertyKey.POLICY.getKey(), "${policy-with-limited-permissions}");
# This can be replaced by the ALIBABA_CLOUD_ROLE_SESSION_EXPIRATION environment variable.
properties.put(ExtensionAuthPropertyKey.ROLE_SESSION_EXPIRATION.getKey(), "${session-duration-in-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 the following configuration to your application's configuration file.

Note

Upgrade the Spring Cloud Alibaba framework to version 2.2.9.RELEASE or later.
The Nacos client must be version 2.1.0 or later. For more information, see Nacos client versions that support authentication and encryption/decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- Version 1.0.5 or later is required. -->
    <version>1.0.5</version>
</dependency>

## registry
spring.cloud.nacos.discovery.server-addr=${nacos-server-address}
# This can be replaced by the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
spring.cloud.nacos.discovery.alibabaCloudRoleSessionName=${custom-role-session-name}
## configuration center
spring.cloud.nacos.config.server-addr=${nacos-server-address}
# This can be replaced by the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
spring.cloud.nacos.config.alibabaCloudRoleSessionName=${custom-role-session-name}
## The following parameters are optional.
# This can be replaced by the ALIBABA_CLOUD_POLICY environment variable.
spring.cloud.nacos.discovery.alibabaCloudPolicy=${policy-with-limited-permissions}
spring.cloud.nacos.config.alibabaCloudPolicy=${policy-with-limited-permissions}
# This can be replaced by the ALIBABA_CLOUD_ROLE_SESSION_EXPIRATION environment variable.
spring.cloud.nacos.discovery.alibabaCloudRoleSessionExpiration=${session-duration-in-seconds}
spring.cloud.nacos.config.alibabaCloudRoleSessionExpiration=${session-duration-in-seconds}

Dubbo framework

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

Note

The Nacos client must be version 2.1.0 or later. For more information, see Nacos client versions that support authentication and encryption/decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- Version 1.0.5 or later is required. -->
    <version>1.0.5</version>
</dependency>

# This can be replaced by the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
dubbo.registry.address=nacos://${mse-nacos-instance-domain}:8848?alibabaCloudRoleSessionName=${custom-role-session-name}
## The following optional parameters are appended to the URL and can be replaced by the ALIBABA_CLOUD_POLICY and ALIBABA_CLOUD_ROLE_SESSION_EXPIRATION environment variables.
&alibabaCloudPolicy=${policy-with-limited-permissions}&alibabaCloudRoleSessionExpiration=${session-duration-in-seconds}

Go SDK

If you use the Nacos client for Go, configure your application code as follows.

Note

Use version 2.3.3 or later.

	// Create ServerConfig
	sc := []constant.ServerConfig{
		*constant.NewServerConfig("${mse-nacos-instance-domain}", 8848, constant.WithContextPath("/nacos")),
	}
	ramConfig := constant.RamConfig{
		RoleSessionName: "${custom-role-session-name}",
	}
	// The following parameters are optional.
	ramConfig.Policy = "${policy-with-limited-permissions}"
	ramConfig.RoleSessionExpiration = ${session-duration-in-seconds}
	// Create ClientConfig
	cc := *constant.NewClientConfig(
		constant.WithNamespaceId(""),
		constant.WithTimeoutMs(5000),
		constant.WithNotLoadCacheAtStart(true),
		constant.WithLogDir("/tmp/nacos/log"),
		constant.WithCacheDir("/tmp/nacos/cache"),
		constant.WithRamConfig(&ramConfig),
	)
	// Create a config client
	configClient, err := clients.NewConfigClient(
		vo.NacosClientParam{
			ClientConfig:  &cc,
			ServerConfigs: sc,
		},
	)
	// Create a naming client
	serviceClient, err := clients.NewNamingClient(
		vo.NacosClientParam{
			ClientConfig:  &cc,
			ServerConfigs: sc,
		},
	)

Method 3: Use an STS token

If your application requires temporary access to an MSE Nacos instance, use temporary credentials from Security Token Service (STS). These credentials consist of an AccessKey ID, an AccessKey Secret, and a security token.

Important

This method requires you to manually maintain an STS token, which increases maintenance complexity. If your application requires repeated temporary access, you must manually refresh the STS token before it expires.

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

If you need to create a RAM user, see Create a RAM user.
If you need to create a RAM role with an Alibaba Cloud account as the trusted entity, see Create a RAM role for an Alibaba Cloud account.

Step 2: Grant permissions

Grant the RAM user from Step 1 permission to assume roles. For more information, see AssumeRole - Obtain temporary access credentials for a role.
Grant permissions to the RAM role from Step 1 by attaching one of the following system policies. These policies grant the RAM role coarse-grained read/write or read-only access to the configurations and services of all Nacos instances. For more information, see Manage permissions for a RAM role.

Policy name	Description
AliyunMSEFullAccess	Grants full permissions to manage MSE. A RAM user with this policy has the same operational permissions as an Alibaba Cloud account.
AliyunMSEReadOnlyAccess	Grants read-only permissions for MSE. A RAM user with this policy has read-only access to all resources under the Alibaba Cloud account.

Note

You can attach a maximum of five policies at a time. To attach more policies, repeat the operation.
To grant fine-grained permissions to an instance, create a custom policy. For more information, see Fine-grained authentication for registries, Fine-grained authentication for the configuration center, and Examples of common custom policies for registries and configuration centers.

Step 3: Obtain an STS token

Obtain the temporary access credentials (STS token) for the RAM role from Step 1. For more information, see AssumeRole - Obtain temporary access credentials for a role.

Step 4: Configure client authentication

The temporary access credentials include an AccessKey ID, an AccessKey Secret, and a security token, which must be used together.

Nacos client for Java

If you use the Nacos client for Java, add the required dependency and configure your application code as follows.

Note

The Nacos client must be version 2.1.0 or later. For more information, see Nacos client versions that support authentication and encryption/decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- Version 1.0.5 or later is required. -->
    <version>1.0.5</version>
</dependency>

properties.put(PropertyKeyConst.SERVER_ADDR, "YOUR_MSE_NACOS_INSTANCE_DOMAIN");
# You can use the ALIBABA_CLOUD_ACCESS_KEY_ID environment variable instead.
properties.put(ExtensionAuthPropertyKey.ACCESS_KEY_ID.getKey(), "YOUR_TEMP_ACCESSKEY_ID");
# You can use the ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variable instead.
properties.put(ExtensionAuthPropertyKey.ACCESS_KEY_SECRET.getKey(), "YOUR_TEMP_ACCESSKEY_SECRET");
# You can use the ALIBABA_CLOUD_SECURITY_TOKEN environment variable instead.
properties.put(ExtensionAuthPropertyKey.SECURITY_TOKEN_KEY.getKey(), "YOUR_TEMP_SECURITY_TOKEN");
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 your application configuration file.

Note

The Spring Cloud Alibaba framework must be version 2.2.9.RELEASE or later.
The Nacos client must be version 2.1.0 or later. For more information, see Nacos client versions that support authentication and encryption/decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- Version 1.0.5 or later is required. -->
    <version>1.0.5</version>
</dependency>

## Registry
# You can use the ALIBABA_CLOUD_ACCESS_KEY_ID environment variable instead.
spring.cloud.nacos.discovery.alibabaCloudAccessKeyId=YOUR_TEMP_ACCESSKEY_ID
# You can use the ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variable instead.
spring.cloud.nacos.discovery.alibabaCloudAccessKeySecret=YOUR_TEMP_ACCESSKEY_SECRET
# You can use the ALIBABA_CLOUD_SECURITY_TOKEN environment variable instead.
spring.cloud.nacos.discovery.alibabaCloudSecurityToken=YOUR_TEMP_SECURITY_TOKEN
## Configuration center
# You can use the ALIBABA_CLOUD_ACCESS_KEY_ID environment variable instead.
spring.cloud.nacos.config.alibabaCloudAccessKeyId=YOUR_TEMP_ACCESSKEY_ID
# You can use the ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variable instead.
spring.cloud.nacos.config.alibabaCloudAccessKeySecret=YOUR_TEMP_ACCESSKEY_SECRET
# You can use the ALIBABA_CLOUD_SECURITY_TOKEN environment variable instead.
spring.cloud.nacos.config.alibabaCloudSecurityToken=YOUR_TEMP_SECURITY_TOKEN

Dubbo framework

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

Note

The Nacos client must be version 2.1.0 or later. For more information, see Nacos client versions that support authentication and encryption/decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- Version 1.0.5 or later is required. -->
    <version>1.0.5</version>
</dependency>

# You can use the ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET, and ALIBABA_CLOUD_SECURITY_TOKEN environment variables instead.
dubbo.registry.address=nacos://YOUR_MSE_NACOS_INSTANCE_DOMAIN:8848?alibabaCloudAccessKeyId=YOUR_TEMP_ACCESSKEY_ID&alibabaCloudAccessKeySecret=YOUR_TEMP_ACCESSKEY_SECRET&alibabaCloudSecurityToken=YOUR_TEMP_SECURITY_TOKEN

Go SDK

If you use the Nacos client for Go, configure your application code as follows.

Note

Version 2.3.3 or later is recommended.

	//create ServerConfig
	sc := []constant.ServerConfig{
		*constant.NewServerConfig("YOUR_MSE_NACOS_INSTANCE_DOMAIN", 8848, constant.WithContextPath("/nacos")),
	}
	ramConfig := constant.RamConfig{
		SecurityToken: "YOUR_TEMP_SECURITY_TOKEN",
	}
	//create ClientConfig
	cc := *constant.NewClientConfig(
		constant.WithNamespaceId(""),
		constant.WithTimeoutMs(5000),
		constant.WithAccessKey("YOUR_TEMP_ACCESSKEY_ID"),
		constant.WithSecretKey("YOUR_TEMP_ACCESSKEY_SECRET"),
		constant.WithNotLoadCacheAtStart(true),
		constant.WithLogDir("/tmp/nacos/log"),
		constant.WithCacheDir("/tmp/nacos/cache"),
		constant.WithRamConfig(&ramConfig),
	)
	// create config client
	configClient, err := clients.NewConfigClient(
		vo.NacosClientParam{
			ClientConfig:  &cc,
			ServerConfigs: sc,
		},
	)
	//create naming client
	serviceClient, err := clients.NewNamingClient(
		vo.NacosClientParam{
			ClientConfig:  &cc,
			ServerConfigs: sc,
		},
	)

Method 4: Use a credentials URI

To obtain credentials from an external system without managing keys directly, use a credentials URI. The Nacos client retrieves an STS token from the specified URI, eliminating the need to manually maintain an AccessKey or STS token.

Important

The backend service for the credentials URI must automatically refresh the STS token to ensure your application always uses a valid credential.

Step 1: Verify the credentials URI response

The credentials URI must return a response in the following format for the Nacos client to correctly parse and use the STS token:

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 that generates STS tokens access to MSE Nacos by attaching one of the following system policies. These policies grant the RAM role coarse-grained read/write or read-only access to all Nacos instance configurations and services. For detailed instructions, see Manage permissions for a RAM role.

Policy	Description
AliyunMSEFullAccess	Grants full MSE management permissions. A RAM user with this policy has the same operational permissions as an Alibaba Cloud account.
AliyunMSEReadOnlyAccess	Grants read-only MSE permissions. A RAM user with this policy can view all MSE resources under the Alibaba Cloud account.

Note

You can attach a maximum of five policies at a time. To attach more policies, repeat the operation.
To grant fine-grained permissions to an instance, create a custom policy. For more information, see Fine-grained authentication for registries, Fine-grained authentication for the configuration center, and Common custom authorization examples for registries and configuration centers.

Step 3: Configure client authentication

Nacos client for Java

If you use the Nacos client for Java, add the required dependency and configure your application as follows.

Note

The Nacos client must be version 2.1.0 or later. For more information, see Nacos client versions that support 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>
    <!-- Version 1.0.5 or later is required. -->
    <version>1.0.5</version>
</dependency>

properties.put(PropertyKeyConst.SERVER_ADDR, "${mse-nacos-instance-domain}");
# Alternatively, set the ALIBABA_CLOUD_CREDENTIALS_URI environment variable.
properties.put(ExtensionAuthPropertyKey.CREDENTIALS_URI.getKey(), "${credentials-service-uri}");
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 properties to your application's configuration file.

Note

The Spring Cloud Alibaba framework must be version 2.2.9.RELEASE or later.
The Nacos client must be version 2.1.0 or later. For more information, see Nacos client versions that support 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>
    <!-- Version 1.0.5 or later is required. -->
    <version>1.0.5</version>
</dependency>

## Registry
# Alternatively, set the ALIBABA_CLOUD_CREDENTIALS_URI environment variable.
spring.cloud.nacos.discovery.alibabaCloudCredentialsUri=${credentials-service-uri}
## Configuration center
# Alternatively, set the ALIBABA_CLOUD_CREDENTIALS_URI environment variable.
spring.cloud.nacos.config.alibabaCloudCredentialsUri=${credentials-service-uri}

Dubbo framework

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

Note

The Nacos client must be version 2.1.0 or later. For more information, see Nacos client versions that support 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>
    <!-- Version 1.0.5 or later is required. -->
    <version>1.0.5</version>
</dependency>

# Alternatively, set the ALIBABA_CLOUD_CREDENTIALS_URI environment variable.
dubbo.registry.address=nacos://${mse-nacos-instance-domain}:8848?alibabaCloudCredentialsUri=${credentials-service-uri}

Go SDK

If you use the Nacos client for Go, configure your application as follows.

Note

Version 2.3.3 or later is recommended.

	//create ServerConfig
	sc := []constant.ServerConfig{
		*constant.NewServerConfig("${mse-nacos-instance-domain}", 8848, constant.WithContextPath("/nacos")),
	}
	ramConfig := constant.RamConfig{
		CredentialsURI: "${credentials-service-uri}",
	}
	//create ClientConfig
	cc := *constant.NewClientConfig(
		constant.WithNamespaceId(""),
		constant.WithTimeoutMs(5000),
		constant.WithNotLoadCacheAtStart(true),
		constant.WithLogDir("/tmp/nacos/log"),
		constant.WithCacheDir("/tmp/nacos/cache"),
		constant.WithRamConfig(&ramConfig),
	)
	// create config client
	configClient, err := clients.NewConfigClient(
		vo.NacosClientParam{
			ClientConfig:  &cc,
			ServerConfigs: sc,
		},
	)
	//create naming client
	serviceClient, err := clients.NewNamingClient(
		vo.NacosClientParam{
			ClientConfig:  &cc,
			ServerConfigs: sc,
		},
	)

Method 5: Use RAMRoleARN

If your application requires delegated access to MSE Nacos, such as for cross-account access, use a RAMRoleARN. The Nacos client fetches an STS token from STS and automatically refreshes it before expiration. You can also use the policy parameter to further restrict the RAM role's permissions.

Important

This method requires an AccessKey with permission to assume roles. As a best practice, grant this AccessKey only the AssumeRole permission and restrict which roles it can assume. For more information, see AssumeRole - Obtain temporary security credentials for a role.

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

If you do not have a RAM user or need to create one, see Create a RAM user.
If you do not have a RAM role or need to create one that trusts an Alibaba Cloud account, see Create a RAM role for an Alibaba Cloud account.

Step 2: Grant RAM permissions

Grant the RAM user from Step 1 permission to assume roles. For more information, see AssumeRole - Obtain temporary security credentials for a role.
Grant permissions to the RAM role from Step 1 by attaching one of the following system policies. These policies grant the RAM role coarse-grained read/write or read-only access to the configurations and services of all Nacos instances. For more information, see Manage permissions for a RAM role.

Policy name	Description
AliyunMSEFullAccess	Grants full MSE management permissions, equivalent to the permissions of an Alibaba Cloud account.
AliyunMSEReadOnlyAccess	Grants read-only permissions for all MSE resources under the Alibaba Cloud account.

Note

You can attach up to five policies at a time. To attach more, repeat the operation.
To grant fine-grained permissions to an instance, create a custom policy. For more information, see Fine-grained authentication for registries, Fine-grained authentication for the configuration center, and Examples of common custom authorization policies for registries and configuration centers.

Step 3: Configure client authentication

To use this method, configure the client with the required AccessKey and the target role's RAMRoleARN.

Nacos client for Java

If you use the Nacos client for Java, add the required dependency and configure your application code as follows.

Note

The Nacos client must be version 2.1.0 or later. For more information, see Nacos client versions that support authentication and encryption/decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- Version 1.0.5 or later is required. -->
    <version>1.0.5</version>
</dependency>

properties.put(PropertyKeyConst.SERVER_ADDR, "${mse-nacos-instance-domain-name}");
# You can configure the ALIBABA_CLOUD_ACCESS_KEY_ID environment variable instead.
properties.put(ExtensionAuthPropertyKey.ACCESS_KEY_ID.getKey(), "${access-key-id-with-assume-role-permission}");
# You can configure the ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variable instead.
properties.put(ExtensionAuthPropertyKey.ACCESS_KEY_SECRET.getKey(), "${access-key-secret-with-assume-role-permission}");
# You can configure the ALIBABA_CLOUD_ROLE_ARN environment variable instead.
properties.put(ExtensionAuthPropertyKey.ROLE_ARN.getKey(), "${role-arn-to-assume}");
# You can configure the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable instead.
properties.put(ExtensionAuthPropertyKey.ROLE_SESSION_NAME.getKey(), "${custom-role-session-name}");
## The following parameters are optional.
# You can configure the ALIBABA_CLOUD_POLICY environment variable instead.
properties.put(ExtensionAuthPropertyKey.POLICY.getKey(), "${scoped-down-policy}");
# You can configure the ALIBABA_CLOUD_ROLE_SESSION_EXPIRATION environment variable instead.
properties.put(ExtensionAuthPropertyKey.ROLE_SESSION_EXPIRATION.getKey(), "${session-duration-in-seconds}");
NamingService naming = NamingFactory.createNamingService(properties);
ConfigService configService = ConfigFactory.createConfigService(properties);

Spring Cloud Alibaba

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

Note

The Spring Cloud Alibaba framework must be version 2.2.9.RELEASE or later.
The Nacos client must be version 2.1.0 or later. For more information, see Nacos client versions that support authentication and encryption/decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- Version 1.0.5 or later is required. -->
    <version>1.0.5</version>
</dependency>

## Registry
# You can configure the ALIBABA_CLOUD_ACCESS_KEY_ID environment variable instead.
spring.cloud.nacos.discovery.alibabaCloudAccessKeyId=${access-key-id-with-assume-role-permission}
# You can configure the ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variable instead.
spring.cloud.nacos.discovery.alibabaCloudAccessKeySecret=${access-key-secret-with-assume-role-permission}
# You can configure the ALIBABA_CLOUD_ROLE_ARN environment variable instead.
spring.cloud.nacos.discovery.alibabaCloudRoleArn=${role-arn-to-assume}
# You can configure the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable instead.
spring.cloud.nacos.discovery.alibabaCloudRoleSessionName=${custom-role-session-name}
## Configuration center
# You can configure the ALIBABA_CLOUD_ACCESS_KEY_ID environment variable instead.
spring.cloud.nacos.config.alibabaCloudAccessKeyId=${access-key-id-with-assume-role-permission}
# You can configure the ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variable instead.
spring.cloud.nacos.config.alibabaCloudAccessKeySecret=${access-key-secret-with-assume-role-permission}
# You can configure the ALIBABA_CLOUD_ROLE_ARN environment variable instead.
spring.cloud.nacos.config.alibabaCloudRoleArn=${role-arn-to-assume}
# You can configure the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable instead.
spring.cloud.nacos.config.alibabaCloudRoleSessionName=${custom-role-session-name}
## The following parameters are optional.
# You can configure the ALIBABA_CLOUD_POLICY environment variable instead.
spring.cloud.nacos.discovery.alibabaCloudPolicy=${scoped-down-policy}
spring.cloud.nacos.config.alibabaCloudPolicy=${scoped-down-policy}
# You can configure the ALIBABA_CLOUD_ROLE_SESSION_EXPIRATION environment variable instead.
spring.cloud.nacos.discovery.alibabaCloudRoleSessionExpiration=${session-duration-in-seconds}
spring.cloud.nacos.config.alibabaCloudRoleSessionExpiration=${session-duration-in-seconds}

Dubbo

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

Note

The Nacos client must be version 2.1.0 or later. For more information, see Nacos client versions that support authentication and encryption/decryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- Version 1.0.5 or later is required. -->
    <version>1.0.5</version>
</dependency>

# You can configure the ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET, ALIBABA_CLOUD_ROLE_ARN, and ALIBABA_CLOUD_ROLE_SESSION_NAME environment variables instead.
dubbo.registry.address=nacos://${mse-nacos-instance-domain-name}:8848?alibabaCloudAccessKeyId=${access-key-id-with-assume-role-permission}&alibabaCloudAccessKeySecret=${access-key-secret-with-assume-role-permission}&alibabaCloudRoleArn=${role-arn-to-assume}&alibabaCloudRoleSessionName=${custom-role-session-name}
## The following parameters are optional and are appended to the URL. You can configure the ALIBABA_CLOUD_POLICY and ALIBABA_CLOUD_ROLE_SESSION_EXPIRATION environment variables instead.
&alibabaCloudPolicy=${scoped-down-policy}&alibabaCloudRoleSessionExpiration=${session-duration-in-seconds}

Go SDK

If you use the Nacos client for Go, configure your application code as follows.

Note

Version 2.3.3 or later is recommended.

	//create ServerConfig
	sc := []constant.ServerConfig{
		*constant.NewServerConfig("${mse-nacos-instance-domain-name}", 8848, constant.WithContextPath("/nacos")),
	}
	ramConfig := constant.RamConfig{
		RoleArn:         "${role-arn-to-assume}",
		RoleSessionName: "${custom-role-session-name}",
	}
	// The following parameters are optional.
	ramConfig.Policy = "${scoped-down-policy}"
	ramConfig.RoleSessionExpiration = "${session-duration-in-seconds}"
	//create ClientConfig
	cc := *constant.NewClientConfig(
		constant.WithNamespaceId(""),
		constant.WithTimeoutMs(5000),
		constant.WithAccessKey("${access-key-id-with-assume-role-permission}"),
		constant.WithSecretKey("${access-key-secret-with-assume-role-permission}"),
		constant.WithNotLoadCacheAtStart(true),
		constant.WithLogDir("/tmp/nacos/log"),
		constant.WithCacheDir("/tmp/nacos/cache"),
		constant.WithRamConfig(&ramConfig),
	)
	// create config client
	configClient, err := clients.NewConfigClient(
		vo.NacosClientParam{
			ClientConfig:  &cc,
			ServerConfigs: sc,
		},
	)
	//create naming client
	serviceClient, err := clients.NewNamingClient(
		vo.NacosClientParam{
			ClientConfig:  &cc,
			ServerConfigs: sc,
		},
	)

Method 6: Use an AccessKey

Step 1 (Optional): Create a RAM user

If you need to create a RAM user, see Create a RAM user.

Step 2: Grant permissions to the RAM user

Grant permissions to the RAM user from Step 1 by attaching one of the following system policies. These policies grant the RAM user coarse-grained read/write or read-only permissions on the configurations and services of all Nacos instances. For detailed instructions, see Manage RAM user permissions.

Policy	Description
AliyunMSEFullAccess	Grants full permissions to manage MSE. A RAM user with this policy has the same operational permissions as an Alibaba Cloud account.
AliyunMSEReadOnlyAccess	Grants read-only permissions for MSE. A RAM user with this policy has read-only access to all MSE resources under the Alibaba Cloud account.

Note

You can attach a maximum of five policies at a time. To attach more policies, repeat the operation.
To grant fine-grained access to an MSE instance, create a custom policy. For more information, see Fine-grained authentication for registries, Fine-grained authentication for the configuration center, and Examples of common custom authorization policies for Microservices Registry and Configuration Center.

Step 3: Configure client authentication

An AccessKey pair consists of an AccessKey ID and an AccessKey Secret, which must be used together. After you enable authentication for a Nacos instance, you must provide the RAM user's AccessKey pair in the Nacos client. Otherwise, the client cannot access the instance. To obtain an AccessKey pair, see Create an AccessKey.

Nacos client for Java

If you use the Nacos client for Java, configure your application code as follows.

Note

To use an AccessKey for authentication, you must upgrade your client to a supported version. For more information, see Nacos client versions that support authentication and encryption.

properties.put(PropertyKeyConst.SERVER_ADDR, "${mse-nacos-endpoint}");
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 your application configuration file.

Note

The Spring Cloud Alibaba framework must be version 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 parameters to the registry URL in your Dubbo configuration file.

dubbo.registry.address=nacos://${mse-nacos-endpoint}:8848?accessKey=${accessKey}&secretKey=${secretKey}

Nacos client for Go

If you use the Nacos client for Go, configure your application code as follows.

Note

To use an AccessKey for authentication, you must upgrade your client to a supported version. Use version 2.3.3 or later. For more information, see Nacos client versions that support authentication and encryption.

cc := constant.ClientConfig{
    AccessKey:   "${accessKey}",
    SecretKey:   "${secretKey}"
}
serverConfigs := []constant.ServerConfig{
    {
        IpAddr:      "${mse-nacos-endpoint}",
        Port:        8848
    }
}
namingClient, err := clients.NewNamingClient(
    vo.NacosClientParam{
        ClientConfig:  &clientConfig,
        ServerConfigs: serverConfigs,
    },
)
configClient, err := clients.NewConfigClient(
    vo.NacosClientParam{
        ClientConfig:  &clientConfig,
        ServerConfigs: serverConfigs,
    },
)

Nacos client for Python

If you use the Nacos client for Python, configure your application code as follows.

Note

To use an AccessKey for authentication, you must upgrade your client to a supported version. For more information, see Nacos client versions that support authentication and encryption.

client = nacos.NacosClient("${mse-nacos-endpoint}", ak=${accessKey}, sk=${secretKey})

Method 7: Use an automatically rotating AccessKey

If your application needs long-term access but the AccessKey pair is at risk of compromise, use a ClientKey with Key Management Service (KMS). KMS automatically rotates the AccessKey pair of the managed RAM user at regular intervals, turning a static credential into a dynamic one. KMS also supports on-demand rotation to quickly replace a compromised AccessKey pair. This eliminates manual maintenance, reducing security risks and operational overhead. To obtain a ClientKey, see Create an application access point.

Step 1: Store RAM credentials in KMS

Store the credentials of an existing RAM user as a RAM secret in a KMS instance. For more information about enabling and using RAM secrets in KMS, see Manage and use RAM secrets.

Step 2: Grant permissions to the RAM user

Policy	Description
AliyunMSEFullAccess	Grants full permissions to manage MSE. A RAM user with this policy has the same operational permissions as an Alibaba Cloud account.
AliyunMSEReadOnlyAccess	Grants read-only permissions for MSE. A RAM user with this policy has read-only access to all MSE resources under the Alibaba Cloud account.

Note

You can attach a maximum of five policies at a time. To attach more policies, repeat the operation.
To grant fine-grained access to an MSE instance, create a custom policy. For more information, see Fine-grained authentication for registries, Fine-grained authentication for the configuration center, and Examples of common custom authorization policies for Microservices Registry and Configuration Center.

Step 3: Create a Secrets Manager configuration file

Create a configuration file named secretsmanager.properties in your project's root directory or classpath. The file must contain the following content:

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

Note

For a description of the parameters in the configuration file, see Secrets Manager Client.

Step 4: Configure client authentication

Nacos Client for Java

If you use the Nacos Client for Java, add the required dependency and configure your application code as follows.

Note

The Nacos Client version must be 2.1.0 or later. For more information, see Nacos Client versions that support authentication and data encryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- Version 1.0.5 or later is required. -->
    <version>1.0.5</version>
</dependency>

properties.put(PropertyKeyConst.SERVER_ADDR, "${mse-nacos-instance-domain}");
# This can be replaced by the ALIBABA_CLOUD_SECRET_NAME environment variable.
properties.put(ExtensionAuthPropertyKey.SECRET_NAME.getKey(), "${name-of-the-ram-secret}");
NamingService naming = NamingFactory.createNamingService(properties);
ConfigService configService = ConfigFactory.createConfigService(properties);

Spring Cloud Alibaba

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

Note

The Spring Cloud Alibaba version must be 2.2.9.RELEASE or later.
The Nacos Client version must be 2.1.0 or later. For more information, see Nacos Client versions that support authentication and data encryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- Version 1.0.5 or later is required. -->
    <version>1.0.5</version>
</dependency>

## Registry
# This can be replaced by the ALIBABA_CLOUD_SECRET_NAME environment variable.
spring.cloud.nacos.discovery.alibabaCloudSecretName=${name-of-the-ram-secret}
## Configuration center
# This can be replaced by the ALIBABA_CLOUD_SECRET_NAME environment variable.
spring.cloud.nacos.config.alibabaCloudSecretName=${name-of-the-ram-secret}

Dubbo

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

Note

The Nacos Client version must be 2.1.0 or later. For more information, see Nacos Client versions that support authentication and data encryption.

<!-- https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client-mse-extension -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <!-- Version 1.0.5 or later is required. -->
    <version>1.0.5</version>
</dependency>

# This can be replaced by the ALIBABA_CLOUD_SECRET_NAME environment variable.
dubbo.registry.address=nacos://${mse-nacos-instance-domain}:8848?alibabaCloudSecretName=${name-of-the-ram-secret}

Go SDK

If you use the Nacos Client for Go, configure your application code as follows.

Note

Version 2.3.3 or later is recommended.

	//create ServerConfig
	sc := []constant.ServerConfig{
		*constant.NewServerConfig("${mse-nacos-instance-domain}", 8848, constant.WithContextPath("/nacos")),
	}
	ramConfig := constant.RamConfig{
		SecretName: "${name-of-the-ram-secret}",
	}
	//create ClientConfig
	cc := *constant.NewClientConfig(
		constant.WithNamespaceId(""),
		constant.WithTimeoutMs(5000),
		constant.WithNotLoadCacheAtStart(true),
		constant.WithLogDir("/tmp/nacos/log"),
		constant.WithCacheDir("/tmp/nacos/cache"),
		constant.WithRamConfig(&ramConfig),
	)
	// create config client
	configClient, err := clients.NewConfigClient(
		vo.NacosClientParam{
			ClientConfig:  &cc,
			ServerConfigs: sc,
		},
	)
	//create naming client
	serviceClient, err := clients.NewNamingClient(
		vo.NacosClientParam{
			ClientConfig:  &cc,
			ServerConfigs: sc,
		},
	)

FAQ

Q: Does MSE Nacos support client authentication with username and password (for example, nacos/nacos)?

No. After you enable RAM authentication for MSE Nacos, the built-in username/password authentication is no longer supported. The two authentication mechanisms are mutually exclusive.

If your client application has spring.cloud.nacos.username and spring.cloud.nacos.password configured, the Nacos server discards these requests, causing Read timed out errors or connection failures even when the network is normal.

Correct approach: Remove or leave the username and password fields empty in your client configuration, and switch to one of the supported RAM credential methods, such as AccessKey/SecretKey or ECS RAM Role. For more information about how to configure credentials, see Configure client credentials.

Note

Related search terms: set application connection password, reset Nacos password to original nacos, KMS causing connection issues.

Q: My Nacos client reports NacosException: Forbidden/no right or accessKeyId can't be null. How do I troubleshoot this?

Troubleshoot based on the specific error:

Scenario 1: Forbidden/no right error

Cause: The client authentication configuration does not meet the requirements. This error appears if the SDK version or authentication parameters are incorrect, even when the network connection is normal.

Resolution:

Verify that you have upgraded the Nacos Client SDK to a compatible version. For the required client version, see the version requirements in the respective credential configuration method in this topic.
Confirm that you have correctly configured all required authentication parameters (for example, AccessKey ID, AccessKey secret, or RAM role name) according to the instructions in this topic.

Scenario 2: accessKeyId can't be null error in ACK clusters using ECS RAM Role

This error indicates that the ECS RAM Role credentials cannot be retrieved. Troubleshoot in the following order:

Check VPC network connectivity: Verify that the Pod can reach the MSE instance on port 8848. Run the following command from inside the Pod:
```
telnet <MSE Nacos instance domain> 8848
```
Verify RAM role binding: Run the following command inside the Pod to confirm that the metadata service returns the role name (not a 404 error):
```
curl http://100.100.100.200/latest/meta-data/ram/security-credentials/
```
If the command returns a 404 error or an empty response, the RAM role is not correctly bound to the ECS instance or the ACK cluster worker node.
Check RAM role permissions: Confirm that the RAM role has been granted the required MSE access permissions, such as AliyunMSEFullAccess or AliyunMSEReadOnlyAccess. For information about how to grant permissions, see the authorization steps in Method 1: Authenticate with a RAM role in this topic.

Note

Temporary verification: If the ECS RAM Role method continues to report errors after you complete the steps above, temporarily switch to the AccessKey/SecretKey method to verify the connection. If the AK/SK method succeeds, the issue is specific to the RAM Role configuration (for example, role binding or metadata service accessibility).

Prerequisites

Access methods

Enable authentication

Configure client credentials

Method 1: Authenticate with a RAM role

Step 1: Create a RAM role and configure policies

Grant an ECS instance access to MSE

Grant permissions to an ACK worker RAM role

Step 2: Configure client authentication

Nacos client for Java

Spring Cloud Alibaba framework

Dubbo framework

Go SDK

Method 2: Use OIDCRoleARN

Step 1: Enable RRSA for the ACK cluster

Step 2: Grant permissions to the RAM role

Step 3: Configure client authentication

Nacos client for Java

Spring Cloud Alibaba framework

Dubbo framework

Go SDK

Method 3: Use an STS token

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

Step 2: Grant permissions

Step 3: Obtain an STS token

Step 4: Configure client authentication

Nacos client for Java

Spring Cloud Alibaba framework

Dubbo framework

Go SDK

Method 4: Use a credentials URI

Step 1: Verify the credentials URI response

Step 2: Grant permissions to the RAM role

Step 3: Configure client authentication

Nacos client for Java

Spring Cloud Alibaba framework

Dubbo framework

Go SDK

Method 5: Use RAMRoleARN

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

Step 2: Grant RAM permissions

Step 3: Configure client authentication

Nacos client for Java

Spring Cloud Alibaba

Dubbo

Go SDK

Method 6: Use an AccessKey

Step 1 (Optional): Create a RAM user

Step 2: Grant permissions to the RAM user

Step 3: Configure client authentication

Nacos client for Java

Spring Cloud Alibaba framework

Dubbo framework

Nacos client for Go

Nacos client for Python

Method 7: Use an automatically rotating AccessKey

Step 1: Store RAM credentials in KMS

Step 2: Grant permissions to the RAM user

Step 3: Create a Secrets Manager configuration file

Step 4: Configure client authentication

Nacos Client for Java

Spring Cloud Alibaba

Dubbo

Go SDK

Related documents

FAQ