---
title: "Users and permissions"
description: "Create broker users with permissions on Kafka topics or RabbitMQ vhosts, keep their passwords in Secrets, rotate and delete them."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Users and permissions

Every connection to a cluster uses a username and password. EZGH generates each user's password and
keeps it in a [Secret](/secrets) in the cluster's project, ready for your app to read. You manage users
and their permissions through EZGH, not inside the broker, and changes apply without a restart.

A cluster comes with the user `app`, with full access to its topics and groups (Kafka) or its vhosts
(RabbitMQ). Names starting `ezgh_` are reserved.

## Kafka permissions

A Kafka user has a preset:

| Preset | Can |
| --- | --- |
| `admin` | Produce and consume on every topic, use every group, and create, delete and change the settings of topics. |
| `readWrite` | Produce and consume on every topic, use every group, and create topics (which topic auto-creation needs). |
| `readOnly` | Consume every topic and use every group. |
| `custom` | What its entries allow. |

A `custom` user lists topic entries, `{ "topic": "orders", "access": "produceConsume", "create": false }`,
where `topic` is a name or a prefix ending in `*` and `access` is `produce`, `consume` or
`produceConsume`, and group entries, `{ "group": "billing-*" }`.

No user can change ACLs, users or the cluster's own settings.

## RabbitMQ permissions

A RabbitMQ user has permissions per vhost, each with a preset:

| Preset | Configure | Write | Read |
| --- | --- | --- | --- |
| `readWrite` | `.*` | `.*` | `.*` |
| `readOnly` | `^$` | `^$` | `.*` |
| `custom` | Your regex | Your regex | Your regex |

`custom` takes RabbitMQ's own configure, write and read regular expressions. Users have no tags, and
no user can reach a management UI or change users and permissions.

## Create a user

### Console

Open **Hosted Queues**, then the cluster, then its **Users** tab, and choose **Create user**. Enter a
name and its permissions. The user's row links to its Secret.
### CLI

```sh
ezgh hosted-queues users create hqc_4k2m9x0a7qpe sentry --preset readWrite --wait
ezgh hosted-queues users create hqc_4k2m9x0a7qpe worker --vhost /=readWrite --wait
ezgh hosted-queues users get hqc_4k2m9x0a7qpe sentry
```

`--preset` is Kafka's; a RabbitMQ user takes `--vhost <vhost>=<preset>`, repeated, and either takes
custom grants as JSON with `--permissions`. `ezgh hosted-queues users update …` changes the permissions, `rotate-password` writes a new password,
and `delete` deletes the user.

A user exists from the start of its create, `creating`, with its `secret` set.

## Passwords in Secrets

Each user's Secret is named `hostedqueues/<cluster ID>/users/<user>`, with the fields:

| Field | Holds |
| --- | --- |
| `username` | The user's name. |
| `password` | Its password, 32 letters and digits. |
| `engine` | `kafka` or `rabbitmq`. |
| `host` | The cluster's name (on Kafka, its bootstrap name). |
| `port` | The TLS port: 9093 on Kafka, 5671 on RabbitMQ. |
| `plaintextPort` | The [plaintext port](/hosted-queues/connect#the-plaintext-port), or empty while it's off. |
| `bootstrapServers` | Kafka: the bootstrap name and port, for a client's `bootstrap.servers`. |
| `saslMechanism` | Kafka: `SCRAM-SHA-512`. |
| `securityProtocol` | Kafka: `SASL_SSL`. |
| `vhost` | RabbitMQ: the user's first vhost. |
| `uri` | RabbitMQ: an `amqps://` URL with the username, password, name, port and that vhost. |

The console, the CLI and the API never show a password: read it from the Secret.

```sh
ezgh secrets read sec_u1v2w3x4y5z6 --field password --format raw
```

To use it on an instance without handling it yourself, see
[Read a secret on an instance](/secrets/instances).

Creating a user writes its Secret as you, so it also needs `secrets.secrets.create` and
`secrets.versions.create` in the project.

## Rotate a password

```sh
ezgh hosted-queues users rotate-password hqc_4k2m9x0a7qpe sentry --wait
```

The new password is written as a new version of the Secret and works at once; the old one stops
working for new connections. On RabbitMQ, the user's open connections are closed. Rotating needs
`secrets.versions.create`.

## Delete a user

```sh
ezgh hosted-queues users delete hqc_4k2m9x0a7qpe sentry --wait
```

Deleting a user deletes its Secret as you, so it also needs `secrets.secrets.delete`.

## Status

| Status | Means |
| --- | --- |
| `creating` | It's being created. |
| `available` | It can connect. |
| `modifying` | Its permissions are changing. |
| `rotating` | Its password is being rotated. |
| `deleting` | It's being deleted. |
| `failed` | A change failed; `failure` says why. |

Source: https://docs.ezghcloud.com/hosted-queues/users/index.mdx
