Administering RabbitMQ Users and Permissions: A Command-Line Guide

RabbitMQ permissions are easy to get almost right. A user can exist and still be unable to publish. A user can have the management tag and still have no access to the application vhost. A broad regex can accidentally let a service create queues it should only consume from. Most permission problems come from mixing up three separate ideas: users, tags, and vhost permissions.

This guide uses rabbitmqctl for the common user administration workflow: create users, assign tags, set vhost permissions, verify access, rotate passwords, and remove access cleanly.

Prerequisites

Before proceeding, ensure you have the following:

1. RabbitMQ Server Installed: The broker must be running.
2. rabbitmqctl Access: You need administrative access to the node or cluster. Commands are commonly run on a RabbitMQ node, though remote CLI use is possible when the environment is configured for it.
3. The Correct Vhost Name: Permissions are scoped per virtual host. /, /prod, and prod are not interchangeable.

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 an initial password:

rabbitmqctl add_user api_user 'replace-with-a-long-random-password'

Avoid putting real production passwords in shell history. In automated systems, prefer your secret manager and the provisioning mechanism your platform already uses.

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 manage users, permissions, vhosts, policies, and cluster-wide settings.
• policymaker: can manage policies and parameters for vhosts where the user has access.
• management: can log in to the management UI/API, but vhost permissions still control what resources the user can use.
• monitoring: can view management information, useful for observability accounts.

Viewing Current Tags

Use list_user_tags to see current roles:

rabbitmqctl list_user_tags api_user

Setting Tags

To assign the management tag to api_user:

rabbitmqctl set_user_tags api_user management

set_user_tags replaces the user's tag list with exactly the tags you provide. To give both administrator and policymaker tags, include both in the same command:

rabbitmqctl set_user_tags api_user administrator policymaker

Removing Tags

To remove all tags from a user:

rabbitmqctl set_user_tags api_user

Some RabbitMQ versions also provide clear_user_tags. Check rabbitmqctl help clear_user_tags on your installed version before scripting it.

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: rabbitmqctl set_permissions -p <vhost> <user> <configure> <write> <read>

Permission values are regular expressions. .* means all resource names. ^$ means no resource names.

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	Typical Use
Configure	Create, delete, or modify queues, exchanges, and bindings that match the regex.	Deployers or apps that declare their own topology.
Write	Publish to matching exchanges.	Producers.
Read	Consume from matching queues.	Consumers.

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 "^$" "^events\\." "^$"

That example allows publishing to exchanges whose names begin with events.. It does not allow the user to configure topology or consume messages.

Example: Restricting a Consumer

# Can read from queues beginning with worker. but cannot publish or configure
rabbitmqctl set_permissions -p /jobs worker_consumer "^$" "^$" "^worker\\."

Regex permissions are powerful, but they are also easy to over-broaden. If your queues are named prod.orders.created and staging.orders.created in the same vhost, a regex like .*orders.* may cover more than intended. Separate vhosts are usually cleaner than complicated regex boundaries.

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 permissions granted on a vhost:

rabbitmqctl list_permissions -p /prod_vhost

To see all permissions assigned to one user across vhosts:

rabbitmqctl list_user_permissions app_prod

Best Practices for User Administration

• Use least privilege: producers usually need write permission, consumers usually need read permission, and only topology owners need configure permission.
• Use dedicated vhosts: separate environments and tenants with vhosts instead of trying to solve everything with regexes.
• Handle guest deliberately: the default guest user is limited to localhost by default. Many production teams delete it after creating a real administrator account.
• Script the desired state: keep user, vhost, and permission setup in deployment automation so a rebuilt broker does not depend on memory.
• Verify after changes: run list_users, list_permissions, and list_user_permissions after each change in production.

A practical application setup often looks like this:

rabbitmqctl add_vhost /orders
rabbitmqctl add_user orders_publisher 'replace-with-secret'
rabbitmqctl add_user orders_worker 'replace-with-secret'

rabbitmqctl set_permissions -p /orders orders_publisher "^$" "^orders\\." "^$"
rabbitmqctl set_permissions -p /orders orders_worker "^$" "^$" "^orders\\."

rabbitmqctl list_user_permissions orders_publisher
rabbitmqctl list_user_permissions orders_worker

That keeps publishing and consuming credentials separate. If a worker password leaks, it cannot publish new messages. If a publisher password leaks, it cannot drain queues. That separation is simple, but it is one of the most useful RabbitMQ security habits.