<a id="usm-rbac"></a>

# Role-Based Access Control for Unified Stream Manager

Unified Stream Manager (USM) uses [role-based access control (RBAC)](../security/access-control/rbac/overview.md#cloud-rbac)
to control access to registered Confluent Platform clusters. You can grant roles at
the following scopes:

- **Individual registered cluster**: The UsmClusterAdmin, UsmOperator, and
  MetricsViewer roles can each bind to a single registered Confluent Platform Kafka
  cluster or Confluent Platform Connect cluster to limit access to that specific
  cluster.
- **Environment**: The UsmAgent role binds at the environment level and
  applies to every registered cluster in that environment. The
  UsmOperator and MetricsViewer roles can also bind at the environment
  level to grant visibility into every registered cluster in that
  environment instead of one.
- **Organization**: The MetricsViewer role can bind at the organization
  level for metrics-only visibility across every registered cluster in
  the organization.

Broader Confluent Cloud roles, such as OrganizationAdmin, EnvironmentAdmin,
Operator, DataSteward, and DataDiscovery, also grant access to registered
USM clusters at their respective scopes.

<a id="usm-rbac-roles-at-a-glance"></a>

## USM RBAC roles at a glance

| Role                                                                                             | Scope                                                | Description                                                                                                           |
|--------------------------------------------------------------------------------------------------|------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| [UsmClusterAdmin](../security/access-control/rbac/predefined-rbac-roles.md#usmclusteradmin-role) | Kafka or Connect cluster                             | Full administrative access to a single registered cluster.                                                            |
| [UsmOperator](../security/access-control/rbac/predefined-rbac-roles.md#usmoperator-role)         | Environment, Kafka, or Connect cluster               | Read-only visibility into a single registered cluster or every<br/>registered cluster in an environment.              |
| [MetricsViewer](../security/access-control/rbac/predefined-rbac-roles.md#metricsviewer-role)     | Organization, Environment, Kafka, or Connect cluster | Metrics-only access to a single registered cluster or every<br/>registered cluster in an organization or environment. |
| [UsmAgent](../security/access-control/rbac/predefined-rbac-roles.md#usmagent-role)               | Environment                                          | Required by the service account that the USM Agent uses to<br/>authenticate with Confluent Cloud.                     |

Other Confluent Cloud roles, such as OrganizationAdmin and DataSteward,
also grant access to registered USM clusters. For the full list
and exact permissions, see [Broader roles](#usm-rbac-broader-roles).

<a id="usm-rbac-cluster-scoping"></a>

## How cluster-level scoping works

A registered Confluent Platform Kafka cluster and a registered Confluent Platform Connect cluster
function as independent resources in USM, even when they are
associated with each other. Granting a role, such as UsmClusterAdmin or
UsmOperator, on a registered Kafka cluster does not extend access to the
associated Connect cluster, and vice versa.

To grant a principal such as a user or service account access to both a
registered Kafka cluster and the associated Connect cluster, create
separate role bindings. Scope one to the Kafka cluster and one to the
Connect cluster. For details, see [Manage RBAC role bindings](../security/access-control/rbac/manage-role-bindings.md#manage-rbac-role-bindings).

#### NOTE
In the Confluent Cloud Console, connectors on a registered Connect cluster
appear nested under the associated Kafka cluster for navigation. This UI
grouping does not affect RBAC scoping. A role binding on the Kafka
cluster still does not grant access to the Connect cluster or the
connectors on that cluster. However, to view connectors in the
Confluent Cloud Console, a principal with a role binding on the Connect
cluster also needs at least the UsmOperator role on the associated Kafka
cluster.

<a id="usm-rbac-role-permissions"></a>

## Role permissions reference

The following tables show the specific actions each role permits. The
permissions shown are the same whether you bind a role to a Kafka cluster
or a Connect cluster.

Each column in these tables represents one of the following actions:

- **Describe**: Viewing basic information about the cluster.
- **Manage cluster**: Deleting and altering the cluster.
- **Manage access**: Granting and revoking role bindings on the cluster.
  This includes two operations: altering access covers granting and revoking,
  and describing access covers viewing existing bindings. A role with
  only describe access displays as “View only” in the tables.
- **Catalog metadata**: Viewing and managing Stream Catalog tags and
  business metadata for the cluster’s resources. This includes two
  operations: read catalog and write catalog. A role with only read
  access displays as “Read only” in the tables. For details, see
  [Stream Catalog](../stream-governance/stream-catalog.md#stream-catalog-rbac).
- **Metrics**: Accessing operational metrics for the cluster through the
  [Confluent Cloud Metrics](../monitoring/metrics-api.md#metrics-api).

<a id="usm-rbac-cluster-scoped-roles"></a>

### Cluster-scoped roles

UsmClusterAdmin, UsmOperator, and MetricsViewer grant these permissions
when bound to a single registered cluster. UsmOperator and MetricsViewer
grant the same permissions when bound at the environment level, and
MetricsViewer also grants them when bound at the organization level.

| Role                                                                                             | Describe   | Manage cluster   | Manage access   | Catalog metadata   | Metrics   |
|--------------------------------------------------------------------------------------------------|------------|------------------|-----------------|--------------------|-----------|
| [UsmClusterAdmin](../security/access-control/rbac/predefined-rbac-roles.md#usmclusteradmin-role) | Yes        | Yes              | Yes             | Read, write        | Yes       |
| [UsmOperator](../security/access-control/rbac/predefined-rbac-roles.md#usmoperator-role)         | Yes        | No               | No              | No                 | Yes       |
| [MetricsViewer](../security/access-control/rbac/predefined-rbac-roles.md#metricsviewer-role)     | No         | No               | No              | No                 | Yes       |

<a id="usm-rbac-environment-scoped-roles"></a>

### Environment-scoped roles

UsmAgent is the only role that binds only at the environment
level. It grants the permissions that the USM Agent requires to report
data for every registered cluster in that environment. UsmOperator and
MetricsViewer can also bind at the environment level, but their
permissions match the [Cluster-scoped roles](#usm-rbac-cluster-scoped-roles) table.

| Role                                                                               | Describe   | Write metadata   | Write telemetry   |
|------------------------------------------------------------------------------------|------------|------------------|-------------------|
| [UsmAgent](../security/access-control/rbac/predefined-rbac-roles.md#usmagent-role) | Yes        | Yes              | Yes               |

The UsmAgent permissions include two extra actions:

- **Write metadata**: Reporting cluster and connector metadata to
  Confluent Cloud on behalf of the registered cluster.
- **Write telemetry**: Reporting operational metrics and telemetry data
  to Confluent Cloud for the registered cluster.

<a id="usm-rbac-broader-roles"></a>

### Broader roles

Other Confluent Cloud roles also grant access to registered Confluent Platform Kafka and
Connect cluster resources at their respective scopes. For complete role
definitions, see [Predefined RBAC Roles](../security/access-control/rbac/predefined-rbac-roles.md#cloud-rbac-roles).

| Role                                                                                                 | Scope                       | Describe   | Manage cluster   | Manage access   | Catalog metadata   | Metrics   |
|------------------------------------------------------------------------------------------------------|-----------------------------|------------|------------------|-----------------|--------------------|-----------|
| [OrganizationAdmin](../security/access-control/rbac/predefined-rbac-roles.md#organizationadmin-role) | Organization                | Yes        | Yes              | Yes             | Read, write        | Yes       |
| [EnvironmentAdmin](../security/access-control/rbac/predefined-rbac-roles.md#environmentadmin-role)   | Environment                 | Yes        | Yes              | Yes             | Read, write        | Yes       |
| [Operator](../security/access-control/rbac/predefined-rbac-roles.md#operator-role)                   | Organization or environment | Yes        | No               | View only       | Read only          | Yes       |
| [DataSteward](../security/access-control/rbac/predefined-rbac-roles.md#datasteward-role)             | Environment                 | Yes        | No               | No              | Read, write        | Yes       |
| [DataDiscovery](../security/access-control/rbac/predefined-rbac-roles.md#datadiscovery-role)         | Environment                 | Yes        | No               | No              | Read only          | Yes       |
| [DataDiscovery](../security/access-control/rbac/predefined-rbac-roles.md#datadiscovery-role)         | Organization                | Yes        | No               | No              | Read only          | No        |

When bound at the environment level, the DataDiscovery role can access
metrics. When bound at the organization level, it cannot access metrics.

## Manage cluster-scoped role bindings

You can create, list, and delete role bindings for the UsmClusterAdmin,
UsmOperator, and MetricsViewer roles. Use the `--usm-kafka-cluster` or
`--usm-connect-cluster` flag to scope the role binding to a specific
registered Kafka or Connect cluster.

Because these roles are not bound to a resource within the cluster, do not use
the `--resource` flag. The MetricsViewer role uses the same flags and
pattern shown in the following examples.

### Create a role binding

### Confluent Cloud Console

To create a role binding in Confluent Cloud Console, use either the resource
or principal view in **Accounts & access**:

- **Access** tab: Grant roles on a specific registered cluster to
  any principal.
- **Accounts** tab: Grant roles to a specific principal across
  registered clusters.

**From the resource**

1. In the Confluent Cloud Console, go to **Administration** > **Accounts & access**
   and click the **Access** tab.
2. In the resource tree, select the environment, and then select the
   registered Confluent Platform Kafka or Connect cluster.
3. Click **Grant access**.
4. Select the account type and account for the principal.
5. In **Roles**, select UsmClusterAdmin, UsmOperator, or
   MetricsViewer, and click **Grant access**.

   #### NOTE
   If you select a Connect cluster, an additional access
   required notice might appear, indicating that the
   principal also needs the UsmOperator role on the associated
   Kafka cluster to view connectors. Click **Assign permissions**
   to grant that role on the associated cluster.

**From the principal**

1. In the Confluent Cloud Console, go to **Administration** > **Accounts & access**.
   The **Accounts** tab is displayed by default.
2. Select the user or service account, and then click **Granted
   permissions**.
3. Click **Grant access**.
4. In the resource tree, select the registered Confluent Platform Kafka or Connect
   cluster.
5. In **Roles**, select UsmClusterAdmin, UsmOperator, or
   MetricsViewer, and click **Save**.

### Confluent CLI

To grant the UsmClusterAdmin role on a registered Kafka cluster, use
the `--usm-kafka-cluster` flag with the `confluent iam rbac role-binding create` command:

```bash
confluent iam rbac role-binding create \
  --principal User:sa-a03bcd \
  --role UsmClusterAdmin \
  --environment env-a12b34 \
  --usm-kafka-cluster usmkc-123
```

Output:

```text
+-----------+-----------------+
| ID        | rb-abc123       |
| Principal | User:sa-a03bcd  |
| Role      | UsmClusterAdmin |
+-----------+-----------------+
```

To grant the UsmOperator role on a registered Connect cluster, use
the `--usm-connect-cluster` flag:

```bash
confluent iam rbac role-binding create \
  --principal User:sa-a03bcd \
  --role UsmOperator \
  --environment env-a12b34 \
  --usm-connect-cluster usmcc-123
```

Output:

```text
+-----------+----------------+
| ID        | rb-def456      |
| Principal | User:sa-a03bcd |
| Role      | UsmOperator    |
+-----------+----------------+
```

For details, see [confluent iam rbac role-binding create](https://docs.confluent.io/confluent-cli/current/command-reference/iam/rbac/role-binding/confluent_iam_rbac_role-binding_create.html).

### List role bindings

### Confluent Cloud Console

To list role bindings in Confluent Cloud Console, use either the resource or
principal view in **Accounts & access**:

- **Access** tab: Displays role bindings for any principal on a specific
  registered cluster.
- **Accounts** tab: Displays role bindings for a specific principal.

**From the resource**

In the Confluent Cloud Console, go to **Administration** > **Accounts & access**,
click the **Access** tab, and then select the registered Confluent Platform Kafka or
Connect cluster in the resource tree. The table lists existing role
bindings for the cluster.

**From the principal**

In the Confluent Cloud Console, go to **Administration** > **Accounts & access**.
The **Accounts** tab is displayed by default. Select the user or
service account, and then click **Granted permissions** to view its
role bindings for that account.

### Confluent CLI

To list a principal’s role bindings on a registered cluster, use the
`--usm-kafka-cluster` or `--usm-connect-cluster` flag with the
`confluent iam rbac role-binding list` command:

```bash
confluent iam rbac role-binding list \
  --principal User:sa-a03bcd \
  --environment env-a12b34 \
  --usm-kafka-cluster usmkc-123
```

The following example lists the UsmOperator role bindings for a
specific principal on a registered Connect cluster:

```bash
confluent iam rbac role-binding list \
  --principal User:sa-a03bcd \
  --role UsmOperator \
  --environment env-a12b34 \
  --usm-connect-cluster usmcc-123
```

For details, see [confluent iam rbac role-binding list](https://docs.confluent.io/confluent-cli/current/command-reference/iam/rbac/role-binding/confluent_iam_rbac_role-binding_list.html).

### Delete a role binding

### Confluent Cloud Console

To delete a role binding in Confluent Cloud Console, use either the resource
or principal view in **Accounts & access**:

- **Access** tab: Delete role bindings on a specific registered
  cluster for any principal.
- **Accounts** tab: Delete role bindings for a specific principal
  across registered clusters.

**From the resource**

1. In the Confluent Cloud Console, go to **Administration** > **Accounts & access**
   and click the **Access** tab.
2. Select the registered Confluent Platform Kafka or Connect cluster in the resource
   tree.
3. Click the row menu for the role binding, and click **Remove
   access**.
4. Confirm the removal.

**From the principal**

1. In the Confluent Cloud Console, go to **Administration** > **Accounts & access**.
   The **Accounts** tab is displayed by default.
2. Select the user or service account with the role binding to remove, and
   then click **Granted permissions**.
3. Click the row menu for the role binding, and then click **Remove
   role assignment**.
4. Confirm the removal.

### Confluent CLI

To delete a role binding, use the same cluster flag with the
`confluent iam rbac role-binding delete` command:

```bash
confluent iam rbac role-binding delete \
  --principal User:sa-a03bcd \
  --role UsmClusterAdmin \
  --environment env-a12b34 \
  --usm-kafka-cluster usmkc-123
```

The following example removes the UsmOperator role binding on a
registered Connect cluster:

```bash
confluent iam rbac role-binding delete \
  --principal User:sa-a03bcd \
  --role UsmOperator \
  --environment env-a12b34 \
  --usm-connect-cluster usmcc-123
```

For details, see [confluent iam rbac role-binding delete](https://docs.confluent.io/confluent-cli/current/command-reference/iam/rbac/role-binding/confluent_iam_rbac_role-binding_delete.html).

## Related content

- [Configure a Service Account for the USM Agent](register/usm-service-account.md#usm-sa)
- [Predefined RBAC Roles](../security/access-control/rbac/predefined-rbac-roles.md#cloud-rbac-roles)
- [Manage RBAC role bindings](../security/access-control/rbac/manage-role-bindings.md#manage-rbac-role-bindings)
- [Unified Stream Manager in Confluent Cloud](overview.md#cloud-usm-overview)
- [Register Your Confluent Platform Cluster](register/overview.md#cloud-usm-register)