Role-Based Access Control for Unified Stream Manager

Unified Stream Manager (USM) uses role-based access control (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.

USM RBAC roles at a glance

Role	Scope	Description
UsmClusterAdmin	Kafka or Connect cluster	Full administrative access to a single registered cluster.
UsmOperator	Environment, Kafka, or Connect cluster	Read-only visibility into a single registered cluster or every registered cluster in an environment.
MetricsViewer	Organization, Environment, Kafka, or Connect cluster	Metrics-only access to a single registered cluster or every registered cluster in an organization or environment.
UsmAgent	Environment	Required by the service account that the USM Agent uses to 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.

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.

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.

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.

• Metrics: Accessing operational metrics for the cluster through the Confluent Cloud Metrics.

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	Yes	Yes	Yes	Read, write	Yes
UsmOperator	Yes	No	No	No	Yes
MetricsViewer	No	No	No	No	Yes

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 table.

Role	Describe	Write metadata	Write telemetry
UsmAgent	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.

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.

Role	Scope	Describe	Manage cluster	Manage access	Catalog metadata	Metrics
OrganizationAdmin	Organization	Yes	Yes	Yes	Read, write	Yes
EnvironmentAdmin	Environment	Yes	Yes	Yes	Read, write	Yes
Operator	Organization or environment	Yes	No	View only	Read only	Yes
DataSteward	Environment	Yes	No	No	Read, write	Yes
DataDiscovery	Environment	Yes	No	No	Read only	Yes
DataDiscovery	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:

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

Output:

+-----------+-----------------+
| 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:

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

Output:

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

For details, see confluent iam rbac role-binding create.

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:

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:

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.

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:

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:

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.

Related content

• Configure a Service Account for the USM Agent

• Predefined RBAC Roles

• Manage RBAC role bindings

• Unified Stream Manager in Confluent Cloud

• Register Your Confluent Platform Cluster