.. _controlcenter_security_rbac: ############################################## Role-based access control (RBAC) in |c3| ############################################## |c3-short| supports :ref:`rbac-overview` (|rbac|). As of |cp| version 5.3 and later, |rbac-long| provides a fine-grained security model across the platform in a development environment. Prior versions of |c3-short| only provided coarse-grained access control of read-only or full access. .. include:: ../../includes/rbac-preview.rst If |rbac| is not enabled, or |c3-short| is running against |cp| versions prior to 5.3 and later, |c3-short| functions as it has before without restricted access (unless access control feature flags have been turned off in the ``control-center-properties`` files). When |rbac| is not enabled, Access Control settings (referred to as feature flags) in |c3-short| configuration options can remove access for the features that have those flags; such as KSQL, License Manager, |sr|, topic inspections, broker configurations, and more. See :ref:`Access control settings ` for more information on those available settings. If |rbac| is enabled, :ref:`controlcenter_access_control_settings` are superseded by |rbac| role permissions. |rbac| works in conjunction with :ref:`ACLs ` and :ref:`LDAP ` security. In general, |rbac| in |c3-short| enforces access for only a few resources for which it manages; typically those resources for which it keeps internal state (license management, broker metrics, and alerts). See :ref:`c3_feature_access_by_role` for more details. The remainder of |rbac|-enforced operations on resources managed by |c3-short| are delegated downstream to |ak-tm|, |sr|, |kconnect|, and KSQL. .. include:: ../../includes/rbac-demo.rst .. _c3_rbac_prereqs: Prerequisites ############# - The :ref:`Metadata Service ` must be configured. Generate the public key and obtain the MDS URLs that are required for :ref:`configuring ` |c3-short| for |rbac|. - Configure |rbac| for every component |c3-short| must interact with in your environment, which can include: - |sr|. See :ref:`schemaregistry_rbac`. - |kconnect-long| and any connectors. See :ref:`connect-rbac-connect-cluster` and :ref:`connect-rbac-connectors`. - KSQL clusters. See :ref:`ksql-rbac`. .. _c3_rbac_limitations: Limitations ########### When |rbac| is enabled, |c3-short| cannot be used in conjunction with Kerberos because |c3-short| cannot support any SASL mechanism other than ``OAUTHBEARER``. Browsers rely on authenticating using token-based impersonation. .. _c3_rbac_reading: Recommended |cp| |rbac| reading ------------------------------- Review the following documentation to gain a thorough understanding of the |rbac| feature in |cp|: - :ref:`rbac-overview`. - :ref:`rbac-mds-config`. - :ref:`rbac-predefined-roles` and :ref:`rbac-roles-use-cases`. - :ref:`rbac-cli-quickstart`. - :ref:`schemaregistry_rbac`. - :ref:`ksql-rbac`. - :ref:`connect-rbac-connect-cluster`. .. _c3_feature_access_by_role: |c3-short| resource access by role ################################## All of the other components besides |c3-short| (|ak|, |sr|, |kconnect|, KSQL) are being enforced with |rbac| by those components themselves. The only resources that |c3-short| directly enforces with |rbac| are: - :ref:`License management ` (global operation on |cp|). - :ref:`Broker metrics ` (system health per cluster). - :ref:`Alerts ` (global view for all clusters in a |c3-short| instance). =============== ================== ============== ====== Role Scope License management Broker metrics Alerts =============== ================== ============== ====== SystemAdmin Yes [1]_ Yes Yes ClusterAdmin No Yes Yes Operator No Yes Yes =============== ================== ============== ====== .. [1] To access license management, the ``SystemAdmin`` role must be granted on the |ak| cluster running MDS. .. _c3_rbac_alerts_access: About alerts access ------------------- The :ref:`Alerts ` page is a global view of triggers, actions, and alert history for all clusters. Unlike other features in |c3-short| that are scoped to a single cluster, the Alerts feature encompasses all clusters being managed by a |c3-short| instance. |c3-short| alerts consist of three entities: a trigger, an action, and an alert. .. figure:: ../images/c3-alert-entities.png :width: 600px :alt: Control Center alert entities and relationships These entities have the following relationships: - A trigger can have multiple clusters associated with it (1:m). - An action can have multiple triggers associated with it (1:m). - An alert has one trigger associated with it (1:1). These relationships affect how filtering access is performed. Access to each entity when |rbac| is enabled is determined as follows: - :ref:`Trigger ` - Some defined condition on a cluster or set of clusters. Only accessible (read, write, create, delete, and so forth) if a user has Alerts access to all clusters associated with that trigger. The trigger is the base entity for |rbac| enforcement of alerts. - :ref:`Action ` - What to do when a trigger condition is met: Send an :ref:`email`; or notification to :ref:`Slack ` or :ref:`PagerDuty `. Only accessible if a user has access to all triggers and their corresponding clusters because triggers can be associated with different clusters. Otherwise, the action cannot even be viewed. - :ref:`Alert ` - The result of an action performed after a trigger fires. The alert must be a type that populates alert history. Only accessible if a user has access to the trigger (and all its associated clusters) that fired. .. _c3_config_rbac: Configure |rbac| for |c3-short| ############################### Configuring |rbac| in |c3-short| entails following these steps: #. Set the relevant |rbac| :ref:`configuration options ` in the |c3-short| properties file. #. Add any additional clusters for |c3-short| to manage (optional). See lines 18 and 19 in the :ref:`configuration example `. #. Add a role binding for the |c3-short| user to the |c3-short| cluster and any other clusters managed by the |c3-short| instance. See :ref:`c3_config_rbac_user_role_bindings`. #. Configure user privileges for the remaining services (Schema Registry topic management, Connect, KSQL). Refer to the :ref:`privileges by role tables `, and to the respective documentation for each service. .. important:: There are additional configurations required for metrics reporters and interceptors when |rbac| is enabled. For more information, see :ref:`Configure RBAC for the Confluent Metrics Reporter ` and :ref:`interceptor_rbac`. Also review the :ref:`known issue `. .. _c3_config_rbac_props: Set |rbac| configuration options in the |c3-short| properties file ################################################################## The following example shows the settings required for configuring |rbac| in |c3-short|. See the :ref:`c3_RBAC_settings` and other security categories in the :ref:`controlcenter_configuration` for descriptions of each option. Prerequisites: Obtain the path to the public key, the MDS URLs, and your username and password for MDS from your administrator. Determine the cluster IDs for any auxiliary clusters you need |c3-short| to connect to for a multi-cluster environment. See :ref:`rbac-get-cluster-ids`. #. Add the following lines to the appropriate |c3-short| properties file for your environment (``/etc/confluent-control-center/control-center.properties``). Replace the placeholder values shown in with your actual values. .. code-block:: RST :linenos: :emphasize-lines: 2, 5, 8, 11, 12, 15, 18, 19 #REST authentication method (must be BEARER for RBAC) confluent.controlcenter.rest.authentication.method=BEARER #Must be the same public key that MDS uses REQUIRED confluent.controlcenter.auth.bearer.public.key.path= #Set security protocol; you can use other SASL mechanisms too confluent.controlcenter.streams.security.protocol=SASL_PLAINTEXT #MDS username/password for the Confluent Control Center (C3) service principal confluent.controlcenter.metadata.username= confluent.controlcenter.metadata.password= #MDS URLs confluent.controlcenter.metadata.urls= #Must configure these settings for each external cluster confluent.controlcenter.kafka..bootstrap.servers:9092 confluent.controlcenter.kafka..security.protocol=SASL_PLAINTEXT **Line descriptions (single cluster environment):** - **Line 2:** The authentication method required to talk to the |c3-short| backend through the REST layer. The OAuth-style ``BEARER`` method is required. The |c3-short| frontend acquires an access token on your behalf and keeps it refreshed. Basic auth headers are not accepted; you cannot cURL to the |c3-short| backend because that requires a token and that access is handled for you by the frontend bearer token. - **Line 5:** The public key required for REST authentication. Must be the same public key that resides on MDS. The public key checks the token and makes sure that the user requesting access is a valid user in the system. - **Line 8:** The ``confluent.controlcenter.streams`` prefix represents the |ak| streams application and all configurations you need to add for setting up a |ak| cluster. This example uses the ``SASL_PLAINTEXT`` security protocol for connections from |c3-short| to the underlying |ak| cluster instance. Other SASL mechanisms such as ``SASL_SSL`` are also supported. - **Lines 11 and 12:** Username and password for MDS as a |c3-short| |rbac-sa|. - **Line 15:** MDS URL for authorizing resources. In a multiple MDS environment, separate the URLs with a comma. The presence of the MDS URL is what indicates to |c3-short| that |rbac| is enabled. **Line descriptions (additional settings for multi-cluster environment):** - **Line 18:** The name and port of the bootstrap servers for an additional |ak| cluster being monitored by |c3-short|. These settings use the ``confluent.controlcenter.kafka`` prefix. Replace ``name`` with the name of the cluster. That name appears in the cluster navigation bar. For more details, see :ref:`bootstrap servers `. - **Line 19:** Specify the security protocol for each additional cluster. A SASL protocol must be used for lines 8 and 19. .. note:: Additional clusters require connections to |ak| with |rbac| enabled due to a :ref:`known issue `. You can no longer send only metrics to |c3-short| in an |rbac|-enabled environment; you must fully enable management. See :ref:`metrics_reporter`. #. Restart |cp| for the properties file configuration to take effect. If you are using a |cp| development environment with a :ref:`cli`, stop and start as follows: .. sourcecode:: bash confluent local stop confluent local start The ``control-center-dev.properties`` file is passed in automatically. .. _c3_config_rbac_user_role_bindings: Add a role binding for the |c3-short| user ########################################## Add a role binding to bind a role to the |c3-short| user. |rbac| in |c3-short| requires a user to persist |c3-short| state onto a |ak| cluster, referred to as the |c3-short| cluster. Add the role binding for each |ak| cluster in your environment. Prerequisite: Determine the |ak| cluster ID for |c3-short| and all other |ak| clusters managed by |c3-short|. See :ref:`rbac-get-cluster-ids`. .. note:: Replace with cluster ID for |c3-short| in the following example. Remove the backslashes from a copied and pasted command to avoid syntax errors. .. code:: bash confluent iam rolebinding create \ --principal User: \ --role SystemAdmin \ --kafka-cluster-id .. important:: Due to a :ref:`known issue `, the role must be ``SystemAdmin``. .. _c3_role_privs_by_service: Role privileges ############### Use the role privileges tables below as a guideline for the permissions you need to grant to users. .. _c3_rbac_topic_mgmnt: Topic management privileges by role in |c3-short| ------------------------------------------------- The :ref:`Topics ` management area in |c3-short| contains multiple features: - :ref:`Overview `: Access to :ref:`Production ` and :ref:`Consumption ` metrics for a topic. Users can view metrics if they have access to a topic and the appropriate role for broker metrics. See :ref:`c3_feature_access_by_role`. - :ref:`Message browser `: Users can browse messages if they have read access on a topic. - :ref:`Schema `: Access is based on the privileges to read, write, and describe a subject. - :ref:`Configuration `: The ``Describe configs`` privilege allows access to the Configuration page. Topics, schema subjects, and consumer groups are filtered in |c3-short| based on the principal's access. |sr| provides a ``/permissions`` API endpoint that describes subject operations that a user has; such as Read, Write, Delete, and so forth. .. note:: The ability to add a topic is enforced by the topic name. Topic creation is gated at form submission. This means that users can click the Add topic button but will not know their privilege ahead of time because the button is visible at all times due to the topic name restriction. Topic inspect (also referred to as the message browser) WebSocket connections are proxied. .. csv-table:: Topic management (cluster scope) :align: left :header: "Roles", "Create", "Delete", "Read", "Write", "Describe", "Describe configs", "Alter", "Alter configs", "Describe access", "Alter access" :widths: 20, 20, 20, 20, 20, 20, 20, 20, 20, 20, 20 "super.user", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes" "SystemAdmin", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes" "UserAdmin", "No", "No", "No", "No", "No", "No", "No", "No", "No", "No" "ClusterAdmin", "Yes", "Yes", "No", "No", "Yes", "Yes", "Yes", "Yes", "No", "No" "Operator", "No", "No", "No", "No", "No", "No", "No", "No", "No", "No" "SecurityAdmin", "No", "No", "No", "No", "No", "No", "No", "No", "Yes", "No" .. csv-table:: Topic management (resource scope) :align: left :header: "Roles", "Create", "Delete", "Read", "Write", "Describe", "Describe configs", "Alter", "Alter configs", "Describe access", "Alter access" :widths: 20, 20, 20, 20, 20, 20, 20, 20, 20, 20, 20 "ResourceOwner", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes" "DeveloperRead", "No", "No", "Yes", "No", "Yes", "No", "No", "No", "No", "No" "DeveloperWrite", "No", "No", "No", "Yes", "Yes", "No", "No", "No", "No", "No" "DeveloperManage", "Yes", "Yes", "No", "No", "Yes", "Yes", "No", "No", "No", "No" .. note:: |rbac| security roles are additive in nature. Any user assigned multiple roles has a union of the privileges associated with all of their assigned roles. .. _c3_topic_rolebinding_ex: Topic role binding examples --------------------------- **Add read access to a topic for a user:** .. code:: bash confluent iam rolebinding create \ --principal User: \ --role DeveloperRead \ --resource Topic: \ --kafka-cluster-id The user can view the topic in the :ref:`All topics ` page. **Delete read access to a topic for a user:** .. code:: bash confluent iam rolebinding delete \ --principal User: \ --role DeveloperRead \ --resource Topic: \ --kafka-cluster-id The user can no longer view the topic in the All topics page. .. _c3_rbac_connect: Connector privileges by role in |c3-short| ------------------------------------------ Connectors are filtered in |c3-short| based on the principal's access. As of |cp| version 5.3 and later, |kconnect-long| requests are now proxied by |c3-short|. |kconnect| provides a ``/permissions`` API endpoint that informs |c3-short| of everything a user can perform based on their token scope. That permissions endpoint determines the ability to :ref:`add `, :ref:`pause and resume `, and :ref:`delete a connector ` in the |c3-short| web interface. The ability to add a connector is enforced by the connector name. Scaling a connector is accomplished by editing a connector configuration, which is controlled by the ability to describe or alter a connector configuration. |c3-short| does not check the ability to scale until the configuration changes are submitted (that is, launched). .. note:: There is not currently a read-only view of connector configurations in |c3-short| when |rbac| is enabled. .. csv-table:: Connector privileges by role (cluster scope) :header: "Roles", "Create", "Read config", "Read status", "Pause", "Resume", "Scale", "Delete", "Configure", "Describe access", "Alter access" :widths: 20, 20, 20, 20, 20, 20, 20, 20, 20, 20, 20 "super.user", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes" "SystemAdmin", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes" "UserAdmin", "No", "No", "No", "No", "No", "No", "No", "No", "No", "No" "ClusterAdmin", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "No", "No", "No" "Operator", "No", "No", "Yes", "Yes", "Yes", "Yes", "No", "No", "No", "No" "SecurityAdmin", "No", "No", "No", "No", "No", "No", "No", "No", "Yes", "No" .. csv-table:: Connector privileges by role (resource scope) :header: "Roles", "Create", "Read config", "Read status", "Pause", "Resume", "Scale", "Delete", "Configure", "Describe access", "Alter access" :widths: 20, 20, 20, 20, 20, 20, 20, 20, 20, 20, 20 "ResourceOwner", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes", "Yes" "DeveloperRead", "No", "Yes", "Yes", "No", "No", "No", "No", "No", "No", "No" "DeveloperWrite", "No", "No", "Yes", "No", "No", "No", "No", "Yes", "No", "No" "DeveloperManage", "Yes", "No", "Yes", "Yes", "Yes", "Yes", "No", "No", "No", "No" For more information about |rbac| in |kconnect|, see :ref:`connect-rbac-connect-cluster` and :ref:`connect-rbac-connectors`. .. _c3_connector_rolebinding_ex: Connector role binding examples ------------------------------- **Add read access to a connector for a user:** .. code:: bash confluent iam rolebinding create \ --principal User: \ --role DeveloperRead \ --resource Connector: \ --kafka-cluster-id \ --connect-cluster-id The user can view the connector in the :ref:`Connectors ` page. **Delete read access to a connector for a user:** .. code:: bash confluent iam rolebinding delete \ --principal User: \ --role DeveloperRead \ --resource Connector: \ --kafka-cluster-id \ --connect-cluster-id The user can no longer view the connector in the Connectors page. **Grant access to the connect-statuses internal topic** .. important:: If users don't have permission on the |ak| cluster but they'd like to use |kconnect| in |c3-short|, granting the ``DeveloperRead`` role on the internal ``connect-statuses`` topic is recommended. Review the :ref:`known issue ` for details. .. code:: bash confluent iam rolebinding create \ --principal User: \ --role DeveloperRead \ --resource Topic:connect-statuses \ --kafka-cluster-id .. _c3_add_connector_rbac: Add a connector in |c3-short| fields considerations --------------------------------------------------- When |rbac| is enabled in |c3-short|, there are additional fields (such as JAAS configurations) required to configure connectors that are not currently available as default fields. The **Additional Properties** pane allows adding any needed properties when :ref:`adding a connector `. .. note:: The **topics** field (in the **Which topics do you want to get data from?** pane) allows typing a topic name that a user does not have permissions to so as to at least allow the user to configure a connector. .. these UX issues above are slated for UX improvements .. _c3_rbac_ksql: KSQL privileges by role in |c3-short| ------------------------------------- Access to the :ref:`KSQL GUI ` in |c3-short| is determined by the ``CONTRIBUTE`` operation on a KSQL cluster. ``CONTRIBUTE`` grants the ability to connect to a KSQL cluster. HTTP requests in |c3-short| are proxied down to the KSQL server. The subsequent WebSocket connection is directly to KSQL. **KSQL contribute privileges by role (cluster scope)** .. csv-table:: :header: "Roles", "Contribute" :widths: 20, 20 "super.user", "Yes" "SystemAdmin", "Yes" "UserAdmin", "No" "ClusterAdmin", "Yes" "Operator", "No" "SecurityAdmin", "No" **KSQL contribute privileges by role (resource scope)** .. csv-table:: :header: "Roles", "Contribute" :widths: 20, 20 "ResourceOwner", "Yes" "DeveloperRead", "No" "DeveloperWrite", "Yes" "DeveloperManage", "No" For information about KSQL |rbac|, see :ref:`ksql-rbac`. .. _c3_ksql_rolebinding_ex: KSQL role binding example ------------------------- **Add DeveloperWrite access to a KSQL cluster for a user:** .. code:: bash confluent iam rolebinding create \ --principal User: \ --role DeveloperWrite \ --kafka-cluster-id \ --ksql-cluster-id \ --resource KsqlCluster:ksql-cluster For more role binding examples for KSQL, see :ref:`ksql-rbac-assign-startup-roles` and :ref:`ksql-rbac-assign-roles-to-contribute`. .. important:: Grant users access to the topics they want to query. Review the :ref:`known issue ` for details. .. _c3_rbac_known_issues: Known issues with |rbac| in |c3-short| ###################################### .. _c3_KI_cluster connections: |c3-short| connections to external clusters ------------------------------------------- **Direct access to each external cluster is required. (SEC-239, MMA-4394).** When |rbac| is enabled, |c3-short| requires management to be enabled on each cluster. This means that metrics reporters and interceptors that are configured must have a direct connection for |c3-short| to operate properly in an |rbac| environment at this time. This limitation requires setting ``confluent.controlcenter.kafka..bootstrap.servers`` and ``confluent.controlcenter.kafka..security.protocol`` for each external cluster as shown in the :ref:`configuration example `. .. important:: There are additional configurations required for metrics reporters and interceptors when |rbac| is enabled. For more information, see :ref:`Configure RBAC for the Confluent Metrics Reporter ` and :ref:`interceptor_rbac`. .. _c3_KI_service_account: |c3-short| |rbac-sa| role ------------------------- **The service principal for Control Center requires SystemAdmin access (MMA-4634, MMA-4650).** The |c3-short| user must be set up as a privileged user ``SystemAdmin`` on each cluster. Due to the underlying architecture for consumer lag, elevated privileges are required to guarantee users access to all consumer groups and continued support for :ref:`consumer group alerts for consumer lag `. The consumer lag offsets are currently not obtained from metrics reporters. .. _c3_KI_deprecated_views: |c3-short| deprecated views --------------------------- **Deprecated views for System Health and Data Streams cannot be accessed with RBAC enabled.** When |rbac| is enabled, the deprecated views for :ref:`System Health ` and :ref:`Data Streams ` cannot be accessed. RBAC must be disabled to view them. The deprecated views can be re-enabled by setting ``confluent.controlcenter.deprecated.views.enable`` to ``true`` in the appropriate |c3-short| properties file. Deprecated features will eventually be removed from the software. .. _c3_KI_ksql_connect: |kconnect| and KSQL clusters user access ---------------------------------------- **Connect and KSQL require at least minimal user access to the underlying Kafka clusters (MMA-4756).** When |rbac| is enabled, to see :ref:`Connect ` or :ref:`KSQL ` in |c3-short|, a user requires access to the backing |ak| clusters: - If users don't have permission on the |ak| cluster and they'd like to use |kconnect| in |c3-short|, granting the ``DeveloperRead`` role on the internal ``connect-statuses`` topic is recommended. - To run a KSQL query, users require some level of access to the |ak| cluster. To be able to view KSQL in the |c3-short| web interface, grant users access to the topics they need to query. In both these cases, granting users access to the backing |ak| clusters allows them to access the |kconnect| and KSQL pages in |c3-short|. .. _c3_trouble_rbac: Troubleshoot |rbac| in |c3-short| ################################# **Issue:** Get an access message when trying to view streams monitoring data in the **Topics** -> :ref:`Consumption panel `. This applies to the % message consumed chart and the end-to-end latency chart. .. figure:: ../images/c3-rbac-cg-chart-perms.png :scale: 50 :alt: RBAC RBAC message need access to a topic and all its consumer groups to view a chart **Background:** A user attempts to view stream monitoring data on a topic. The user has access to the topic, but does not have full access to all consumer groups reading from a topic. **Remedy:** Grant the user access to all consumer groups reading from a topic if the user should have said access. .. _c3_disable_rbac: Disable |rbac| ############## All components interacting with |c3-short| in your environment must disable |rbac|. To disable |rbac| in |c3-short|, comment out the ``confluent.controlcenter.metadata.urls`` setting and restart |c3-short|.