.. _rbac-overview: Authorization using Role-Based Access Control ============================================= Role-based access control (RBAC) is a method for controlling system access based on roles assigned to users within an organization. |rbac| is defined around :ref:`predefined roles ` and the privileges associated with those roles (also known as *role bindings*). Roles are a collection of permissions that you can bind to a resource; this binding allows the privileges associated with that role to be performed on that resource. You must grant the role to a principal at the time you bind a resource to the role. Using |rbac|, you can manage who has access to specific |cp| resources, and the actions a user can perform within that resource. |rbac| leverages the |cp| :ref:`Metadata Service ` to configure and manage your |rbac| implementation from a centralized configuration context, thereby simplifying access management across |cp| resources. Before implementing |rbac| you should evaluate the security needs of the users in your organization and, based on the resources they require to perform their duties, group users into roles that satisfy those requirements. See :ref:`RBAC Role Use Cases ` for an example of this planning task. It is a best practice to limit users to the minimum required role necessary for them to complete their assigned tasks. Like ACLs, |rbac| uses principals, so you can associate whatever principal a client is using with an |rbac| role, which is authorized by the |csa| to communicate with both |rbac| and ACLs. For details about the |csa|, see :ref:`confluent_server_authorizer`. |rbac| roles do not support DENY rules, and there is no difference in the way you create and use :ref:`legacy ZooKeeper-based ACLs ` while also using RBAC. However, if you intend to continue using ACLs, we recommend that you migrate to :ref:`centralized ACLs `, which store ACL information in MDS, just like role bindings. Legacy |zk|-based ACLs will continue to work in the meantime. For details about enabling and configuring |rbac|, see :ref:`mds-configuration-options` and :ref:`rbac-mds-config`. |rbac| benefits --------------- |rbac| helps you: * Manage security access across the |cp| (|ak|, |ksqldb|, |kconnect|, |sr|, |c3|) using granular permissions to control user and group access. For example, with |rbac| you can specify permissions for each connector in a cluster, making it easier and quicker to get multiple connectors up and running. * Manage authorization at scale. Administrators can centrally manage the assignment of predefined roles, and also delegate the responsibility of managing access and permissions to the different departments or business units who are the true owners and most familiar with those resources. * Centrally manage authentication and authorization for multiple clusters, which includes: the MDS, a |ak| cluster, |kconnect|, |ksqldb|, |sr| clusters, and a single instance of |c3|. .. _how-rbac-works: How |rbac| works ---------------- Predefined role assignments determine who can access specific |cp| resources, and what actions an individual user can perform within that resource. An administrator assigns predefined roles to users and groups on various resources; each user can be assigned multiple roles on each resource. Certain privileged users (such as the ``UserAdmin`` or ``SystemAdmin``) assign roles to users and groups, and then map specific resources to those user roles. For example, a ``ResourceOwner`` in the finance department can grant department members access to all topics that use the prefix ``finance_``, which makes it easier for them to manage the resources with which they are most familiar. User administrators can add LDAP users and groups, making it quicker and easier to centrally configure authentication and authorization for the various |cp| resources used in an organization. .. figure:: /images/rbac-overview.png :align: center |rbac| Overview With |rbac|, the user administrator can map roles to LDAP users and groups that are scoped to specific resources (role binding). After a role binding is set using the |confluent-cli| :confluent-cli:`confluent iam rbac role-binding create|command-reference/iam/rbac/role-binding/confluent_iam_rbac_role-binding_create.html` command, users can't go to an API or |c3| to bypass and get access to resources. Binding roles to groups enables client administrators to avoid having to grant explicit access to each user across every component. For details about viewing role bindings, refer to |confluent-cli| :confluent-cli:`confluent iam rbac role-binding list|command-reference/iam/rbac/role-binding/confluent_iam_rbac_role-binding_list.html` command. Note that role binding does not support wildcard matching in principal names. For details, refer to :ref:`acl-wildcard-principals`. .. note:: When setting up role bindings (``confluent iam rbac role-binding create``), if you need to troubleshoot, it may be helpful to view audit logs on the fly to identify authorization events for specific principals, resources, or operations. For details, refer to :ref:`view-audit-logs-on-the-fly`. |cp| |cr| provides a way for cluster administrators to centrally register |ak| clusters in the metadata service (MDS) to enable a more user-friendly RBAC role binding experience. For details, refer to :ref:`cluster-registry`. .. _metadata-service: |cp| Metadata Service --------------------- MDS is the primary mechanism by which |rbac| is implemented, and offers a single, centralized configuration context that once set up for a cluster, saves administrators from the complex and time-consuming task of defining and assigning roles for each resource on an individual basis. The |cp| MDS binds and enforces a |ak| cluster configuration across different resources (such as topics, connectors, and schemas). The |mds-long| acts as the central authority for all authorization and authentication data. You must configure each Kafka broker in the MDS cluster with MDS. MDS provides ease of use and convenience in the implementation of |rbac-long|; it can also scale so that you can use this same non-binding permissions model to offer other types of security. Running on a |ak| broker, MDS is also integrated with LDAP to provide authentication and refreshable bearer tokens for impersonation. The MDS is also the master of record for role binding. For details about configuring LDAP integration with |rbac|, see :ref:`kafka_ldap_config` and :ref:`ldap-auth-mds`. For details about configuring MDS, see :ref:`rbac-mds-config`. .. _rbac-and-acls: RBAC and ACLs ------------- RBAC serves as an additional authorization enforcement layer on top of :ref:`ACLs `, and does not change the way ACLs are created or managed. When considering whether to use RBAC or ACLs for access control, it is suggested you use RBAC as the default because of its ease of use and manageability at scale, but for edge cases where you need to have more granular access control, or wish to explicitly deny access, ACLs may make more sense. For example, you could use RBAC to allow access for a group of users, but an ACL to deny access for a particular member of that group. RBAC adds an additional authorization mechanism that addresses the following authorization challenges when using ACLs: * Without RBAC, you cannot use ACLs to grant access to connectors. With RBAC, each connector has its own principal that identifies access to resources. Users have access only to connectors on which they have explicitly been granted permission. If you require connector access control, RBAC is essential. * RBAC provides the ability to offer |c3| users granular access to resources; prior to RBAC, any user with access to |c3| had full or read-only access to topics and resources. If granular access control in |c3| is a requirement, RBAC is recommended. * RBAC provides a consistent authentication and authorization mechanism for users access across the entire |cp|, which is not possible if solely using ACLs. * Prior to RBAC, the creation and management of ACLs could be difficult to manage and maintain, and in organizations with thousands of resources and users, ACL setup could take a long time. With RBAC, the delegation of responsibility to various resources is managed using the ``ResourceOwner`` role. For example, say you are responsible for managing user access to 1000 topics. Using RBAC, you could grant ``ResourceOwner`` to other users to manage the topics owned by specific business units, and in turn, those users could manage access for others within their own teams. Using ACLs in this scenario, you would need to centrally manage access to all the topics, which would be a time and resource-intensive task. .. _rbac-authentication-options: RBAC Authentication Options --------------------------- The authentication options in use prior to implementing RBAC may require additional configuration, or you may need to use a different authentication method altogether. .. important:: |cp| components that have a REST endpoint (such as |sr| and |c3|), don't support using a principal derived from mTLS authentication when using RBAC. So if you relied on TLS/SSL certificate authentication across |cp| before configuring RBAC, when using RBAC you must also provide HTTP Basic Auth credentials (such as LDAP user) to authenticate against other components or REST API endpoints. HTTP Basic Auth presents login credentials to other |cp| components and the component uses those credentials to get an OAuth token for the user with MDS (which validates the credentials against LDAP) and then the component uses the OAuth token to make authorization requests to the MDS. You must specify the bearer token for :ref:`http-basic-auth` and more specifically, must specify ``basic.auth.user.info`` and ``basic.auth.credentials.source``. When configuring |cp| components (for example, |c3|, |ksqldb|, and |crest|) for RBAC, use OAuth for authentication with MDS and |ak| clusters. For authentication with other |cp| components, use :ref:`http-basic-auth`. For |cp| components with REST endpoints (such as |sr| and |c3|), you must use HTTP Basic Authentication to authenticate with MDS. For details, refer to :ref:`rbac-config-using-rest-api`. You cannot use :ref:`principal propagation ` with |cp| components (for example, REST Proxy) that have a REST endpoint that requires RBAC. When using RBAC with |sr| and |kconnect| you can use any of the :ref:`authentication methods ` supported by |cp| to communicate with |ak| clusters and MDS. For authentication with other |cp| components, use :ref:`http-basic-auth`. When using RBAC with |ak| clients, you can use any of the :ref:`authentication methods ` supported by |cp| *except OAUTHBEARER*. For details, refer to :ref:`security_sasl_rbac_oauthbearer_clientconfig`. .. figure:: ../../images/rbac-authentication-overview.png :scale: 100% :alt: Diagram that shows authentication methods available when using RBAC *RBAC Authentication Options* .. _rbac-roles-terminology: Terminology ----------- The following terms are used in |rbac|: Access control Access is the ability of an individual user or application to perform a specific task, such as view, create or modify a resource (e.g. topics). Access control enables secure access to |cp| services and resources. Principal The identity of a user or software requesting permission to perform a specific action on a specific resource. Principals can be authenticated or non-authenticated (ANONYMOUS). User principal A single identity tied to a specific user or piece of software. Group principal A shared identity that groups together a list of user principals and/or other group principals. Role A Confluent-defined job function that is assigned a set of permissions required to perform specific actions or operations on Confluent resources. Each role is bound to a principal and Confluent resources. .. _rbac-resource: Resource A resource can be an |ak-tm| topic, consumer group, transactionalID, cluster, |sr|, |ksqldb|, and any other |cp| component. Role binding A principal-role-resource combination that allows a principal to perform operations on a resource or set of resources as defined by the role. Role-based access control (RBAC) With |rbac|, permissions are associated with roles, and users or groups are assigned to appropriate roles. Roles are defined according to job competency, authority, and responsibility within the enterprise. Users and groups are easily reassigned from one role to another. Permissions assigned to roles tend to change relatively slowly compared with changes in user membership of roles. .. _rbac-limitations: RBAC limitations ---------------- For optimal performance of your RBAC configuration, we recommend that you adhere to these limits. +-----------------------------------------------------------+---------------------------+ | Resource | Limit | +===========================================================+===========================+ | Role bindings | 1000 | +-----------------------------------------------------------+---------------------------+ | Requests per second (RPS) API calls to add, | 15 | | remove, or look up role bindings | | +-----------------------------------------------------------+---------------------------+ | :ref:`Centralized ACLs ` | Up to 1000 per cluster | +-----------------------------------------------------------+---------------------------+ .. include:: ../../kafka/includes/rbac-case-sensitivity.rst RBAC error codes ---------------- The following user access HTTP error codes are in use for RBAC: .. note:: In some cases when a user's credentials are correct, but the user does not have the correct permissions, you would expect a 404 error when querying a nonexistent resource. In such cases, error code 403 is returned to avoid exposing details about specific resources. 401 User login failed due to missing or insufficient credentials (user lacks sufficient permissions). 403 User credentials may be correct, but login failed because user does not have required permissions for a specific resource (such as |sr| or |kconnect|). 404 Not Found: user has correct credentials and access to a resource (for example, the user has the ``ResourceOwner`` role), but the resource (such as |kconnect|) doesn't exist. 502 MDS is unreachable. Contact your security administrator. |sr| has many granular error codes that extend beyond the context of RBAC. See :ref:`schemaregistry_api` for descriptions of |sr| HTTP errors (for example, 40401) not covered here. .. _rbac-planning-checklist: |rbac| implementation checklist ------------------------------- This section provides a checklist to help you plan your |rbac| implementation. .. note:: Ansible offers a simpler way to configure and deploy |RBAC| and MDS. Refer to `Ansible RBAC settings `__ for details. To set up |rbac|: ☐ :ref:`Install Confluent Platform `, including the ``confluent-server`` commercial component. For more information, see :ref:`migrate-confluent-server`. ☐ Work with your security team to evaluate the needs of the users in your organization and and, based on the resources they require to perform their duties, identify which roles should be assigned to users and groups. For a description of some typical use cases and required roles for each, refer to :ref:`rbac-roles-use-cases`. To bootstrap RBAC, you must identify an ACL-level ``super.user`` in the |ak| broker's ``server.properties`` file on the cluster that hosts MDS. This ``super.user`` can then assign the SystemAdmin role to another user who can create the required clusters and scope the required role bindings for users and groups. Be sure to identify which user will serve as a bootstrap ``super.user``. For details, refer to :ref:`rbac-predefined-roles`. ☐ :ref:`Configure the Metadata Service (MDS) `. The MDS implements the core RBAC functionality and :ref:`communicates with LDAP ` to get user and group information and authenticate users. After configuring MDS, you can proceed with role bindings and configuration of other |cp| components. Refer to :ref:`mds-id-provider-settings` to view an LDAP configuration for MDS. ☐ After you have determined which roles must be assigned to users and groups, create the appropriate :ref:`role bindings ` for users to access the resources (for example, |sr|, |ksqldb|, |kconnect|, and |c3|) they require to perform their duties. ☐ Confirm the user and group roles you defined using the :confluent-cli:`confluent iam rbac role-binding list|command-reference/iam/rbac/role-binding/confluent_iam_rbac_role-binding_list.html` command. ☐ Configure |cp| components to communicate with MDS for authentication and authorization. For details, see: * :ref:`controlcenter_security_rbac` * :ref:`connect-rbac-index` * :ref:`ksql-rbac` * :ref:`schemaregistry_rbac` * :ref:`Configure RBAC for REST Proxy ` * :ref:`rbac-config-using-rest-api` .. _cp-rbac-demo: Demo ---- To see a working example of |rbac-long|, check out :ref:`Confluent Platform demo `. This demo and accompanying tutorial show users how to deploy an |ak-tm| event streaming application. All the components in the demo have security enabled end-to-end, including |rbac|.