User authentication - ApsaraMQ for RocketMQ

To improve data security, ApsaraMQ for RocketMQ brokers authenticate identities when clients connect to the brokers. You can use the clients to send and receive messages only after the clients pass the authentication. ApsaraMQ for RocketMQ supports access control list (ACL)-based authentication. You can use this method to grant a specific ACL user the permissions to publish messages to or subscribe to messages from specific topics or groups. This helps implement fine-grained permission control on clients.

Limits

If the user authentication feature is not enabled for an ApsaraMQ for RocketMQ instance, submit a ticket to apply to enable the feature. The entry point to access control is displayed only after your application is approved.

Working mechanism

ApsaraMQ for RocketMQ allows you to use intelligent authentication or ACL-based authentication for access control. You must specify one of the methods as the access control method for an ApsaraMQ for RocketMQ instance to authenticate clients. For more information, see Configure access control.

Intelligent authentication: the default authentication method. When a client accesses an ApsaraMQ for RocketMQ instance, the instance authenticates the client based on the username and password. You can use the client to send and receive messages only after the client passes the authentication.
ACL-based authentication: a method that provides more fine-grained access control. You can use this method to authenticate client identities and implement permission control on specific topics or groups on the instance.
Combined authentication: If you select intelligent authentication and ACL-based authentication at the same time, the system automatically matches the authentication method based on the username and password specified in the client code. If the default username and password of the instance are specified in the client code, the intelligent authentication method is used. If the custom username and password of an ACL user are specified in the client code, the ACL-based authentication method is used.

Process for Intelligent authentication (default configuration)

If the intelligent authentication method is used, you do not need to specify the username or password in the client code when you connect a client to an ApsaraMQ for RocketMQ instance in a virtual private cloud (VPC). The system automatically identifies the client based on the VPC endpoint that the client uses.
If you connect a client to an ApsaraMQ for RocketMQ instance over the Internet or disable the authentication-free in VPCs feature for the instance, you must specify the username and password in the client code.
When an ApsaraMQ for RocketMQ instance is initialized, the system assigns a unique pair of username and password for the instance. If you use intelligent authentication to authenticate the identity of a client, you must specify the username and password assigned to the instance in the client code. For information about how to obtain the username and password assigned to an ApsaraMQ for RocketMQ instance, see Obtain the username and password of an instance.
If you use the username and password assigned to an ApsaraMQ for RocketMQ instance for authentication, you have the permissions to publish messages to and subscribe to messages from all topics and groups on the instance after the client passes the authentication.

Process for ACL-based authentication

ACL-based authentication is performed based on ACL users. If you use this method to authenticate the identity of a client, you must create an ACL user before you grant permissions on specific resources. For more information, see Create an ACL user and Grant permissions to an ACL user.
If you use ACL-based authentication to authenticate the identity of a client, you must specify the username and password of the ACL user in the client code. After the client passes the authentication, you can use the client to perform operations only on the resources on which specific permissions are granted.
For example, User 1 is granted the permissions to publish messages to Topic A. If you use the username and password of User 1 to authenticate the identity of a client, you can use the client to publish messages only to Topic A after the client passes the authentication.
If you do not grant permissions to an ACL user after you create the user, the user does not have the permissions to publish or subscribe to messages.

Configure access control

Log on to the ApsaraMQ for RocketMQ console. In the left-side navigation pane, click Instances.
In the top navigation bar, select a region, such as China (Hangzhou). On the Instances page, click the name of the instance that you want to manage.
In the left-side navigation pane, click Access Control. On the page that appears, click Edit next to Access Control Type.
In the dialog box that appears, select at least one of the Intelligent Authentication and ACL-based Authentication values and click OK.

Intelligent authentication

Important

The entry point for configuring intelligent authentication is displayed in the ApsaraMQ for RocketMQ console only after you select Intelligent Authentication.
If you change the username and password assigned to an ApsaraMQ for RocketMQ instance, clients that use the instance username and password cannot connect to the instance. Exercise caution when you perform the operation.

Configure authentication-free in VPCs

In the left-side navigation pane, click Access Control. On the page that appears, click the Intelligent Authentication tab.
Turn on or off Authentication-free in VPCs.
- If authentication-free in VPCs is enabled, you do not need to specify the username or password in the client code when you connect a client to an ApsaraMQ for RocketMQ instance in a VPC. The system automatically identifies the client based on the VPC endpoint used by the client. By default, authentication-free in VPCs is enabled.
- If authentication-free in VPCs is disabled, you must specify the username and password in the client code, regardless of whether the client connects to the instance over the Internet or in a VPC.

Obtain the username and password of an instance

If you specify intelligent authentication as the access control method and disable authentication-free in VPCs for an ApsaraMQ for RocketMQ instance, you must specify the instance username and password in the client code when you connect a client to the instance over the Internet or in a VPC.

On the Access Control page, click the Intelligent Authentication tab.
View the instance username in the username list and copy the instance password.

ACL-based authentication

If you specify ACL-based authentication as the access control method, you must create an ACL user and grant the user permissions on specific resources. By default, a new ACL user does not have any permissions.

When you connect a client to an ApsaraMQ for RocketMQ instance for messaging, you must specify the username and password of the ACL user that you created and authorized in the client code. After the client passes the authentication, you can use the client to publish messages to or subscribe to messages from the specified resources within the ACL permission scope.

Important

The entry point for creating an ACL user and granting ACL permissions is displayed in the ApsaraMQ for RocketMQ console only after you select ACL-based Authentication.
If you disable or delete an ACL user, clients that use the ACL username and password cannot connect to the ApsaraMQ for RocketMQ instance. Exercise caution when you perform this operation.

Manage an ACL user

Create an ACL user
1. In the left-side navigation pane, click Access Control. On the page that appears, click the ACL User tab.
2. On the ACL User tab, click Create ACL User. In the panel that appears, follow the on-screen instructions to configure the parameters.

Grant permissions to an ACL user

On the Access Control page, click the ACL Permissions tab and then click Add Permissions.
In the Add Permissions panel, configure the parameters and click OK. The following table describes the parameters.

Parameters for granting permissions to an ACL user

Parameter	Description	Example
Username	The ACL user to which you want to grant permissions. Select a created ACL user from the drop-down list.	user_mq
Resource Type	TOPIC: grants permissions on topics to the ACL user. GROUP: grants permissions on groups to the ACL user.	TOPIC
Resource Name	The name of the topic or group on which you want to grant the ACL user permissions. You can use one of the following methods to configure this parameter: Enter the name of a specific topic or group. In this case, the ACL user is granted permissions on the specified topic or group. Enter an asterisk () wildcard character to match all topics or groups. In this case, the ACL user is granted permissions on all topics or groups on the instance. Enter characters and an asterisk () wild character to match specific topics or groups. In this case, the ACL user is granted permission on the specified topics or groups.	normal_topic
Action	The operations that can be performed on the resources. If you set the Resource Type parameter to GROUP, you can set this parameter only to Subscribe. Publish: grants the ACL user the permissions to publish messages to the specified topics. Subscribe: grants the ACL user the permissions to subscribe to messages from the specified topics or groups.	Publish
IP Address Whitelist	The IP addresses or CIDR blocks that can access the resources. Separate multiple IP addresses or CIDR blocks with semicolons (;) or commas (,). If you leave this parameter empty, all IP addresses or CIDR blocks can access the resources.	192.168.xx.xx
Permission Rule	Allow: allows the operations that you specified for the Action parameter. Deny: denies the operations that you specified for the Action parameter. Note If rules that allow and deny access to specific resources exist at the same time, the rule that denies access is preferentially used.	Allow

The sample configurations in the preceding table indicate that you can use the username and password of the ACL user named user_mq for authentication when you connect a client to the ApsaraMQ for RocketMQ instance. The client can connect to the instance for messaging only if the IP address of the client is 192.168.xx.xx.

After the client passes the authentication, the client can publish messages only to the topic named normal_topic.

Manage ACL users in a batch

You can export a template and then import the template to create ACL users in a batch.

On the Access Control page, click the ACL User tab.

On the ACL User tab, click Export File or Import File.

If no ACL user is created, you must create an ACL user and then export the template.
Before you import the template to create ACL users in a batch, specify the information about other ACL users in the template.
When you import a template, you can select whether to overwrite existing users.
- If the existing user overwriting feature is disabled and specific ACL users in the template that you want to import already exist, the information about the ACL users fails to be imported.
- If the existing user overwriting feature is enabled and specific ACL users in the template that you want to import already exist, the system updates the information about the ACL users based on the template.

The following table describes the parameters in an ACL user template.

Parameter	Description	Valid value
Username	The username of the ACL user that you want to create.	The username must start with a letter. The username can contain only letters, digits, hyphens (-), and underscores (_). The username must be 3 to 64 characters in length.
Password	The password of the ACL user that you want to create.	The password must be 3 to 64 characters in length.
AccountStatus	The status of the username and password.	ENABLE: available DISABLE: unavailable

The following table provides an example of ACL user templates.

Username	Password	AccountStatus
user1	xxx	ENABLE
user2	xxx	DISABLE
user3	xxx	ENABLE

You can export a template and then import the template to grant permissions to ACL users in a batch.

On the Access Control page, click the ACL Permissions tab.

On the ACL Permissions tab, click Export File or Import File.

If no permissions are granted to an ACL user, you must create an ACL permission and then export the template.
Before you import the template to grant permissions to ACL users in a batch, specify the information about other ACL permissions in the template.
When you import a template, you can select whether to overwrite existing permissions. The system determines whether a permission record exists based on the username, resource type, and resource name.
- If the existing permission overwriting feature is disabled and specific permission records already exist, the permission records fail to be imported and the system does not change the existing permission records.
- If the existing permission overwriting feature is enabled and specific permission records already exist, the system updates the permission records based on the template.

The following table describes the parameters in an ACL permission template. For more information, see Parameters for granting permissions to an ACL user.

Parameter	Description
Username	The username of the ACL user to which you want to grant permissions. The username that you enter must be the name of an existing ACL user.
ResourceType	The type of the resource on which you want to grant permissions.
ResourceName	The name of the resource on which you want to grant permissions.
Actions	The operations that can be performed on the resources. PUB: grants the ACL user the permissions to publish messages. SUB: grants the ACL user permissions to subscribe to messages. PUB\|SUB: grants the ACL user the permissions to publish and subscribe to messages. This value takes effect only when you set ResourceType to Topic.
SourceIps	The IP addresses or CIDR blocks that can access the resource.
Decision	Specifies whether to allow the ACL user to perform operations on the resources. Allow: allows the ACL user to perform operations on the resources. Deny: does not allow the ACL user to perform operations on the resources.

The following table provides an example of ACL permission templates.

Username	ResourceType	ResourceName	Actions	SourceIps	Decision
user1	TOPIC	topic_normal	PUB	0.0.0.0/0	Allow
user2	TOPIC	*	PUB\|SUB	0.0.0.0/0	Allow
user3	GROUP	Group_a	SUB	192.168.xx.xx	Deny

Obtain the username and password of an ACL user

If you use ACL-based authentication to authenticate the identity of a client, you must specify the username and password of the ACL user in the client code, regardless of whether you connect the client to the broker over the Internet or in a VPC.

In the left-side navigation pane, click Access Control. On the page that appears, click the ACL User tab.
On the ACL User tab, view the username of the ACL user in the user list and copy the password of the ACL user.