Administering RabbitMQ Users and Permissions: A Command-Line Guide

Managing users and defining access rights is a fundamental aspect of securing any message broker infrastructure. RabbitMQ, a powerful message broker, provides robust mechanisms for user authentication and authorization, primarily managed through the rabbitmqctl command-line utility. This guide focuses exclusively on using rabbitmqctl to master user administration, covering everything from creation and role assignment to detailed permission setting across virtual hosts.

Properly configured permissions ensure that applications and administrators interact with the broker only where necessary, minimizing security risks and operational confusion. By leveraging these command-line tools, you can script and automate complex security setups efficiently.

Prerequisites

Before proceeding, ensure you have the following:

RabbitMQ Server Installed: The broker must be running.
rabbitmqctl Access: You must have the necessary permissions (usually administrator privileges) to execute commands against the running RabbitMQ instance. Commands are typically executed from the machine hosting the RabbitMQ server.

Managing Users with `rabbitmqctl`

The rabbitmqctl tool uses the user_* family of commands for all user-related operations. It is crucial to understand that RabbitMQ users are distinct from operating system users.

1. Listing Existing Users

To see who currently has access to the broker, use the list_users command:

rabbitmqctl list_users

Example Output:

Listing users ...
user: guest   tags: [administrator]
user: app_prod tags: [policymaker]

2. Creating a New User

When setting up a new service account or administrator, you must create the user and assign an initial password.

To create a user named api_user with the password securepass:

rabbitmqctl add_user api_user securepass

3. Modifying User Tags (Roles)

User tags define predefined roles which grant specific administrative capabilities. The most common tags are administrator, policymaker, and management.

administrator: Can modify users, permissions, vhosts, and set cluster parameters.
policymaker: Can set policies (e.g., for high availability or message TTL).
management: Can use the Management Plugin interface (if installed).

Viewing Current Tags

Use list_user_tags to see current roles:

rabbitmqctl list_user_tags api_user

Setting or Overwriting Tags

To assign the management tag to api_user:

rabbitmqctl set_user_tags api_user management

To add the policymaker tag in addition to existing tags, use the add_tag command:

rabbitmqctl set_user_tags api_user administrator policymaker

Removing Tags

To remove a specific tag:

rabbitmqctl clear_user_tags api_user policymaker

4. Changing a User's Password

If credentials need rotation, use the change_password command:

rabbitmqctl change_password api_user newsecurepass123

5. Deleting a User

To completely remove a user and revoke all associated access:

rabbitmqctl delete_user api_user

Warning: Deleting the guest user is generally recommended in production environments for security reasons, though it requires creating a new administrative user first.

Managing Virtual Host Permissions

Permissions in RabbitMQ are defined on a per-Virtual Host (vhost) basis. A vhost acts as a namespace for queues, exchanges, and bindings. By default, RabbitMQ has a root vhost named /.

1. Listing Vhosts

First, identify the vhosts available:

rabbitmqctl list_vhosts

2. Setting Permissions for a User on a VHost

The set_permissions command is the most critical for application security. It grants a user rights to configure, read, or write resources within a specific vhost.

Syntax: set_permissions <vhost> <user> <conf> <read> <write>

Permissions values are regular expressions (.* means all resources).

Example: Granting Full Access to a Specific VHost

If we want app_prod to have full CRUD (Configure, Read, Write) access only to the /prod_vhost:

rabbitmqctl set_permissions -p /prod_vhost app_prod "^.*" "^.*" "^.*"

Permission	Meaning (Regex)	Description
Configure (`conf`)	`.*`	Can create/delete exchanges, queues, bindings, and set vhost parameters.
Read (`read`)	`.*`	Can consume messages and get queue/exchange status.
Write (`write`)	`.*`	Can publish messages and create bindings.

Example: Restricting a User to Publishing Only

A common pattern for firehose producers is restricting them to writing only:

# User 'publisher' can write but cannot configure or read messages in /analytics_vhost
rabbitmqctl set_permissions -p /analytics_vhost publisher "^$" "^$" "^.*$"

3. Clearing Permissions

To completely remove all permissions a user has on a specific vhost, use clear_permissions:

rabbitmqctl clear_permissions -p /prod_vhost app_prod

4. Listing User Permissions

To verify the permissions granted to a specific user on a vhost:

rabbitmqctl list_permissions -p /prod_vhost app_prod

Best Practices for User Administration

Principle of Least Privilege (PoLP): Always grant the minimum permissions necessary for the application or user to function. Avoid using the administrator tag unless absolutely required.
Dedicated Vhosts: Use different virtual hosts for different environments (e.g., dev, staging, prod) and control access strictly between them.
Avoid Guest User: For security, the default guest user should be disabled or restricted (it defaults to having access only to localhost).
Scripting: Since all these commands are idempotent and command-line based, script user setup and teardown routines for consistent deployment.

By mastering these rabbitmqctl commands, you gain granular, scriptable control over who can access your message broker resources, leading to a more secure and manageable RabbitMQ deployment.