When multiple applications and teams share an ApsaraMQ for RocketMQ instance, unrestricted access to topics and groups creates security risks. User authentication lets you control which clients can connect and what resources they can access. ApsaraMQ for RocketMQ authenticates every client that connects to a broker -- only authenticated clients can send and receive messages.
Authentication methods
ApsaraMQ for RocketMQ provides two authentication methods. Select at least one for each instance.
| Method | Description | Permissions after authentication |
|---|---|---|
| Intelligent authentication (default) | The default authentication method. Authenticates clients based on the instance username and password. | Full access to all topics and groups |
| ACL-based authentication | Provides more fine-grained access control on specific topics or groups on the instance. | Only the resources explicitly granted to the ACL user |
Choose your method
All clients need full access -- Use intelligent authentication. Every client authenticates with the instance username and password and gets access to all topics and groups.
Different clients need different permissions -- Use ACL-based authentication. Create ACL users, grant each user permissions on specific topics or groups, and authenticate clients with ACL user credentials.
Both scenarios apply -- Enable both methods on the same instance. The system selects the method based on the credentials in the client code:
Instance username and password -- uses intelligent authentication.
ACL user username and password -- uses ACL-based authentication.
How intelligent authentication works
When an instance is initialized, the system assigns it a unique username and password. Clients that authenticate with these credentials get full access to all topics and groups on the instance.
VPC connections: If Authentication-free in VPCs is enabled, clients connecting through a VPC endpoint do not need credentials -- the system identifies them by the VPC endpoint. This feature is disabled by default.
Internet connections: Clients connecting over the Internet must always specify the instance username and password.
How ACL-based authentication works
ACL-based authentication grants each ACL user permissions on specific topics or groups. After a client authenticates with an ACL user's credentials, it can access only the resources that the ACL user is authorized to use.
For example, if ACL user user_mq has publish permissions on Topic_A only, a client authenticated as user_mq can publish messages to Topic_A but cannot access any other topic or group.
A newly created ACL user has no permissions. Grant permissions before the user can publish or subscribe to any resource.
When both Allow and Deny rules exist for the same resource, the Deny rule takes precedence.
Select the authentication method
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, select Intelligent Authentication, ACL-based Authentication, or both, then click OK.
Configure intelligent authentication
The intelligent authentication settings appear in the console only after you select Intelligent Authentication as the access control type.
Changing the instance username and password disconnects all clients that use the current credentials. Proceed with caution.
Enable or disable authentication-free in VPCs
In the left-side navigation pane, click Access Control. On the page that appears, click the Intelligent Authentication tab.
Turn Authentication-free in VPCs on or off.
On: Clients connecting through a VPC endpoint do not need credentials. The system identifies the client by the VPC endpoint.
Off (default): All clients must specify the instance username and password, whether they connect over the Internet or through a VPC.
Get the instance credentials
If intelligent authentication is enabled and Authentication-free in VPCs is disabled, specify the instance credentials in your client code.
On the Access Control page, click the Intelligent Authentication tab.
View the instance username in the username list and copy the password.
Configure ACL-based authentication
ACL-based authentication requires two steps: create an ACL user, then grant the user permissions on specific resources. A new ACL user has no permissions by default.
Specify the ACL user's username and password in your client code. After authentication, the client can access only the resources within the ACL user's permission scope.
The ACL user management settings appear in the console only after you select ACL-based Authentication as the access control type.
Disabling or deleting an ACL user disconnects all clients that use that user's credentials. Proceed with caution.
Create an ACL user
In the left-side navigation pane, click Access Control. On the page that appears, click the ACL User tab.
On the ACL User tab, click Create ACL User. In the panel that appears, set the username and password as prompted.
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 following parameters and click OK.
| Parameter | Description | Example |
|---|---|---|
| Username | The ACL user to grant permissions to. Select an existing ACL user from the drop-down list. | user_mq |
| Resource Type | TOPIC: grant permissions on topics. GROUP: grant permissions on groups. | TOPIC |
| Resource Name | The topic or group name. Enter a specific name, an asterisk (*) to match all, or a prefix with an asterisk (such as order_*) to match by pattern. | normal_topic |
| Action | The operations allowed on the resource. If the resource type is GROUP, only Subscribe is available. Publish: publish messages to the specified topics. Subscribe: subscribe to messages from the specified topics or groups. | Publish |
| IP Address Whitelist | IP addresses or CIDR blocks allowed to access the resource, separated by semicolons (;) or commas (,). Leave blank to allow all IP addresses. | 192.168.xx.xx |
| Permission Rule | Allow: permit the specified action. Deny: block the specified action. | Allow |
Example: The settings in the table above mean: a client authenticated as user_mq can connect only from IP address 192.168.xx.xx and can publish messages only to the topic normal_topic.
Get ACL user credentials
Whether the client connects over the Internet or through a VPC, specify the ACL user's username and password in the client code.
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 in the user list and copy the password.
Manage ACL users and permissions in bulk
Use CSV templates to create ACL users and grant permissions in bulk through the import/export feature.
Bulk-create ACL users
On the Access Control page, click the ACL User tab.
Click Export File to download the template, or click Import File to upload a completed template.
To get the template format, create at least one ACL user first, then export.
Before importing, fill in the template with the ACL user information.
During import, choose whether to overwrite existing users. If overwrite is disabled and a user in the template already exists, that record fails to import. If overwrite is enabled, existing user records are updated.
ACL user template parameters
| Parameter | Description | Valid value |
|---|---|---|
| Username | The ACL username. | Starts with a letter. Contains only letters, digits, hyphens (-), and underscores (_). 3 to 64 characters. |
| Password | The ACL user password. | 3 to 64 characters. |
| AccountStatus | The status of the account. | ENABLE (available) or DISABLE (unavailable). |
Example
| Username | Password | AccountStatus |
|---|---|---|
| user1 | xxx | ENABLE |
| user2 | xxx | DISABLE |
| user3 | xxx | ENABLE |
Bulk-grant ACL permissions
On the Access Control page, click the ACL Permissions tab.
Click Export File to download the template, or click Import File to upload a completed template.
To get the template format, create at least one ACL permission first, then export.
Before importing, fill in the template with the permission information.
During import, choose whether to overwrite existing permissions. The system matches existing records by username, resource type, and resource name. If overwrite is disabled and a matching record exists, it fails to import. If overwrite is enabled, the existing record is updated.
ACL permission template parameters
| Parameter | Description |
|---|---|
| Username | The ACL user to grant permissions to. Must be an existing ACL user. |
| ResourceType | The resource type: TOPIC or GROUP. |
| ResourceName | The resource name. |
| Actions | PUB (publish), SUB (subscribe), or PUB|SUB (both). PUB|SUB is valid only when ResourceType is TOPIC. |
| SourceIps | Allowed IP addresses or CIDR blocks. |
| Decision | Allow or Deny. |
Example
| 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 |
Limits
If user authentication is not yet enabled for your instance, submit a ticket to request enablement. The Access Control entry point appears in the console only after the request is approved.