diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index d2b45ab9f..74f229538 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -164,10 +164,10 @@ *** xref:manage:cluster-maintenance/partition-recovery.adoc[Forced Partition Recovery] *** xref:manage:cluster-maintenance/nodewise-partition-recovery.adoc[Node-wise Partition Recovery] ** xref:manage:security/index.adoc[Security] -*** xref:manage:security/authentication.adoc[Configure Authentication] -*** xref:manage:security/authorization/index.adoc[Redpanda Authorization Mechanisms] -**** xref:manage:security/authorization/acl.adoc[Access Control Lists] -**** xref:manage:security/authorization/rbac.adoc[Role-Based Access Control] +*** xref:manage:security/authentication.adoc[Authentication] +*** xref:manage:security/authorization/index.adoc[Authorization] +**** xref:manage:security/authorization/rbac.adoc[Role-Based Access Control (RBAC)] +**** xref:manage:security/authorization/acl.adoc[Access Control Lists (ACLs)] *** xref:manage:security/fips-compliance.adoc[FIPS Compliance] *** xref:manage:security/encryption.adoc[] *** xref:manage:security/listener-configuration.adoc[] diff --git a/modules/manage/pages/security/authorization/acl.adoc b/modules/manage/pages/security/authorization/acl.adoc index ff7486696..0c34cc4c8 100644 --- a/modules/manage/pages/security/authorization/acl.adoc +++ b/modules/manage/pages/security/authorization/acl.adoc @@ -1,19 +1,15 @@ -= Access Control Lists += Configure Access Control Lists :page-categories: Management, Security :page-aliases: features:acls.adoc, security:acls.adoc // tag::single-source[] -:description: Learn how to use ACLs to configure fine-grained access to provisioned users. +:description: Learn how to use ACLs to configure fine-grained access to Redpanda resources. -Access control lists (ACLs) provide a way to configure fine-grained access to provisioned users. ACLs work with SASL/SCRAM and with mTLS with principal mapping for authentication. - -== ACLs - -Use access control lists (ACLs) to manage user permissions. ACLs are assigned principals, which then access resources within Redpanda. Redpanda stores ACLs internally, replicated with glossterm:Raft[] to provide the same consensus guarantees as your data. +Access control lists (ACLs) provide a way to configure fine-grained access to Redpanda resources. ACLs are permission rules that determine which actions users or roles can perform on Redpanda resources. Redpanda stores ACLs internally, replicated with glossterm:Raft[] to provide the same consensus guarantees as your data. ifndef::env-cloud[] -After you enable authorization, by default, only superusers have access to the resources. Redpanda recommends creating other users to effectively use Redpanda and then, create ACLs for them. You can manage ACLs with `rpk security acl`. +After you enable authorization, access to Redpanda resources is limited to superusers. To follow <>, create standard users and use ACLs to grant only the permissions they need for specific resources. -For complex organizational hierarchies or large numbers of users, consider using xref:manage:security/authorization/rbac.adoc[role-based access control] for a more flexible and efficient way to manage user permissions. +NOTE: For complex organizational hierarchies or large numbers of users, consider using xref:manage:security/authorization/rbac.adoc[role-based access control] for a more flexible and efficient way to manage user permissions. endif::[] @@ -22,24 +18,80 @@ For complex organizational hierarchies or large numbers of users, consider using endif::[] -=== ACL terminology +== ACLs overview + +ACLs control access by defining: -Entities accessing the *resources* are called *principals*. A User:foo is the principal for user "foo". You can decide whether to allow or deny *permissions* to access to the resources. +* *Who* can access resources (principals - users or roles) +* *What* they can access (clusters, topics, consumer groups, transactional IDs, Schema Registry subjects, and Schema Registry operations) +* *How* they can interact with those resources (operations like read, write, describe) +* *Where* they can connect from (host restrictions) -You can also specify the *hosts* for which they have access. +ACLs work with SASL/SCRAM and mTLS authentication methods to provide comprehensive security. -This access is represented as *operations*, such as `read`, `write`, or `describe`, and the operations can be performed on *resources*, such as a topic. You can filter the resources by name. +== Manage ACLs -ACL commands work on a multiplicative basis. If you set up two principals and two permissions, the result is four ACLs: both permissions for the first principal, as well as both permissions for the second principal. Adding two resources further doubles the ACLs created. +You can create and manage ACLs in the following ways: + +* *{ui}*: Select *Security* from the left navigation menu, select the *ACLs* tab. After the ACL is created, you can add users or roles to it. +* *Command Line*: Use the `rpk` command-line tool for programmatic management. ++ +For example, suppose you want to create a user named `analytics-user` who can read from topics starting with `logs-` and write to a topic called `processed-data`: ++ +[,bash] +---- +# 1. Create the user +rpk security user create analytics-user --password 'secure-password' + +# 2. Grant read access to topics with "logs-" prefix +rpk security acl create --allow-principal analytics-user \ + --operation read,describe --topic 'logs-' \ + --resource-pattern-type prefixed + +# 3. Grant write access to the processed-data topic +rpk security acl create --allow-principal analytics-user \ + --operation write,describe --topic processed-data +---- -TIP: Be as specific as possible when granting ACLs. +== ACL terminology -Granting more ACLs than necessary per principal may inadvertently allow clients to do things they should not, such as deleting topics or joining the wrong consumer group. +Understanding these terms helps you configure least-privilege access. + +[cols="1,2,2"] +|=== +| Term | Definition | Example + +| Principal +| The entity (user or role) requesting access +| `User:analytics-user`, `RedpandaRole:data-engineers` + +| Resource +| The Redpanda component being accessed (cluster, topic, consumer group, transactional ID, Schema Registry glossterm:subject[], and Schema Registry operation) +| Topic: `sensor-data`, Group: `analytics-group`, Cluster: `kafka-cluster` + +| Operation +| The action being performed on the resource +| `READ`, `WRITE`, `CREATE`, `DELETE`, `DESCRIBE` + +| Host +| The IP address or hostname from which access is allowed/denied +| `192.168.1.100`, `*` (any host) + +| Permission +| Whether access is allowed or denied +| `ALLOW`, `DENY` +|=== + +An ACL rule combines these elements to create a permission statement: + +`ALLOW User:analytics-user to READ topic:sensor-data from host:192.168.1.100` + +ACL commands work on a multiplicative basis. If you specify two principals and two permissions, you create four ACLs: both permissions for each principal. [[principals]] === Principals -All ACLs require a principal. A principal is composed of two parts: the type, and the name. Redpanda supports the type "User". When you create user "bar", Redpanda expects you to add ACLs for "User:bar". +All ACLs require a principal. A principal is composed of two parts: the type, and the name. Redpanda supports the types "User" and "RedpandaRole". When you create user "bar", Redpanda expects you to add ACLs for "User:bar". The `--allow-principal` and `--deny-principal` flags add this prefix for you, if necessary. @@ -57,63 +109,126 @@ When specifying hosts, you must pair the `--allow-host` flag with the `--allow-p A resource is what an ACL allows or denies access to. The following resources are available within Redpanda: +- `cluster` - `topics` - `groups` -- `cluster` - `transactionalid` Starting in v25.2, Redpanda also supports the following ACL resources for Schema Registry: -* `registry`: Controls whether or not to grant ACL access to global, or top-level Schema Registry operations. Specify using the flag `registry-global`. -* `subject`: Controls ACL access for specific Schema Registry subjects. Specify using the flag `registry-subject`. +* `subject`: Controls ACL access for specific Schema Registry subjects. Specify using the flag `--registry-subject`. +* `registry`: Controls whether or not to grant ACL access to global, or top-level Schema Registry operations. Specify using the flag `--registry-global`. -Names for each of these resources can be specified with their respective flags. +IMPORTANT: ACLs for Schema Registry must be enabled for each cluster. See xref:manage:schema-reg/schema-reg-authorization.adoc[]. Resources combine with the operation that is allowed or denied on that resource. By default, resources are specified on an exact name match (a "literal" match). +Names for each of these resources can be specified with their respective flags. + Use the `--resource-pattern-type` flag to specify that a resource name is "prefixed", meaning to allow anything with the given prefix. A literal name of "foo" matches only the topic "foo", while the prefixed name of "foo-" matches both "foo-bar" and "foo-jazz". The special wildcard resource name '\*' matches any name of the given resource type (`--topic` '*' matches all topics). === Operations -Paired with resources, operations are the actions that are allowed or denied. -Redpanda supports the following operations: +Operations define what actions are allowed or denied on resources. Here are the available operations with common use cases: |=== -| Operation | Description - -| ALL -| Allows all operations below. +| Operation | Description | Common use case | READ -| Allows reading a given resource. +| Allows reading data from a resource +| Consumers reading from topics, fetching consumer group offsets | WRITE -| Allows writing to a given resource. +| Allows writing data to a resource +| Producers publishing messages to topics | CREATE -| Allows creating a given resource. +| Allows creating new resources +| Auto-creating topics, creating new consumer groups | DELETE -| Allows deleting a given resource. - -| ALTER -| Allows altering non-configurations. +| Allows deleting resources +| Removing topics, deleting consumer groups | DESCRIBE -| Allows querying non-configurations. +| Allows querying resource metadata +| Listing topics, getting topic configurations + +| ALTER +| Allows modifying resource properties +| Changing topic partition counts, updating consumer group settings | DESCRIBE_CONFIGS -| Allows describing configurations. +| Allows viewing resource configurations +| Reading topic settings, broker configurations | ALTER_CONFIGS -| Allows altering configurations. +| Allows modifying resource configurations +| Changing topic retention policies, updating broker settings + +| IDEMPOTENT_WRITE +| Allows idempotent produce semantics initialization +| Required for idempotent producers (InitProducerID) + +| ALL +| Grants all operations above +| Administrative access to resources |=== +Common combinations: + +* Producer: `WRITE` + `DESCRIBE` on topics +* Consumer: `READ` + `DESCRIBE` on topics, `READ` on consumer groups +* Admin: `ALL` on cluster and specific resources + === Producing/Consuming -The following operations are necessary for each individual client request, where *resource* corresponds to the resource flag, and "for xyz" corresponds to the resource names in the request: +For quick reference, here are the ACL requirements for common client scenarios: + +[cols="1,3a"] +|=== +| Client type | Required ACLs + +| Simple producer +| +* `WRITE` + `DESCRIBE` on target topics + +| Simple consumer +| +* `READ` + `DESCRIBE` on target topics +* `READ` on consumer group + +| Transactional producer +| +* `WRITE` + `DESCRIBE` on target topics +* `WRITE` on transactional ID + +| Consumer group admin +| +* `READ` + `DESCRIBE` on target topics +* `READ` + `DESCRIBE` + `DELETE` on consumer groups +|=== + +Command examples: + +[,bash] +---- +# Basic producer access +rpk security acl create --allow-principal producer-user \ + --operation write,describe --topic my-topic + +# Basic consumer access +rpk security acl create --allow-principal consumer-user \ + --operation read,describe --topic my-topic +rpk security acl create --allow-principal consumer-user \ + --operation read --group my-consumer-group +---- + +The following operations are necessary for each individual client request, where *resource* corresponds to the resource flag, and "for xyz" corresponds to the resource names in the request. -[.no-copy] +.Show operations +[%collapsible] +==== ---- PRODUCING/CONSUMING @@ -253,8 +368,9 @@ ADMIN GetSchemaById READ on SUBJECT for subject ---- +==== -To get this information at the CLI, run: +To get this information with `rpk`, run: [,bash] ---- @@ -278,55 +394,98 @@ A client can be allowed access or denied access. By default, all permissions are Commands for managing users and ACLs work on a specific ACL basis, but listing and deleting ACLs works on filters. Filters allow matching many ACLs to be printed, listed, and deleted at the same time. Because this can be risky for deleting, the delete command prompts for confirmation by default. -== rpk for managing users and ACLs +== ACLs best practices + +Follow these recommendations for secure and manageable ACL configurations. + +Security best practices: + +* Principle of least privilege: Grant only the minimum permissions required for each user or role +* Avoid wildcards: Use specific resource names instead of `*` whenever possible +* Separate environments: Use different principals for development, staging, and production +* Regular audits: Periodically review and clean up unused ACLs + +Management best practices: -The `rpk security acl` command manages your ACLs as well as your SASL/SCRAM users. +* Use descriptive names: Choose clear user and topic names that indicate their purpose +* Group related permissions: Create roles for users with similar access patterns +* Document ACL decisions: Keep records of why specific permissions were granted + +Common pitfalls to avoid + +* Over-privileging: Granting `ALL` operations when specific ones would suffice +* Forgetting consumer groups: Not granting necessary group permissions for consumers +* Host restrictions: Accidentally blocking legitimate client connections with overly restrictive host rules +* Pattern confusion: Mixing up literal vs. prefixed resource pattern types +* Test ACLs: Verify permissions work as expected before deploying to production + +== Manage ACLs with rpk + +Use xref:reference:rpk/rpk-acl.adoc[`rpk security acl`] to manage ACLs and SASL/SCRAM users from the command line. ifndef::env-cloud[] -If you're on Kubernetes, you can use `kubectl exec` to run `rpk` commands. +On Kubernetes, you can use `kubectl exec` to run `rpk` commands. endif::[] -[,bash] ----- -rpk security acl [command] [flags] ----- +=== Basic workflow + +Follow this typical workflow when setting up ACLs: -For example, to create a user: +1. *Create a user*: `rpk security user create --password ''` +2. *Create ACLs*: `rpk security acl create --allow-principal --operation --topic ` +3. *Verify access*: `rpk security acl list --allow-principal ` + +Example setup: [,bash] ---- -rpk security user create Jack \ ---password '' \ --X admin.hosts=localhost:9644 +# 1. Create user +rpk security user create data-processor \ + --password 'secure-password' \ + -X admin.hosts=localhost:9644 + +# 2. Grant topic access +rpk security acl create --allow-principal data-processor \ + --operation read,write,describe --topic 'data-*' \ + --resource-pattern-type prefixed + +# 3. Grant consumer group access +rpk security acl create --allow-principal data-processor \ + --operation read,describe --group data-processing-group + +# 4. Verify the setup +rpk security acl list --allow-principal data-processor ---- -`Created user 'Jack'` +=== Command overview -Here are all the available commands and how they interact with Redpanda: +Here's how `rpk` commands interact with Redpanda: |=== -| Command | Protocol | Default Port +| Command | Protocol | Default port | Purpose ifndef::env-cloud[] | user | Admin API | 9644 +| Manage SASL/SCRAM users endif::[] | list | Kafka API | 9092 +| View existing ACLs | create | Kafka API | 9092 +| Create new ACLs | delete | Kafka API | 9092 +| Remove ACLs |=== -For more information, see xref:reference:rpk/rpk-acl.adoc[`rpk security acl`]. - === Global flags Every xref:reference:rpk/rpk-acl.adoc[`rpk security acl`] command can use these flags: @@ -432,6 +591,12 @@ You can use the global flags and some other local flags. Following are the avail | --transactional-id | Transactional IDs to grant ACLs for (repeatable). + +| --registry-subject +| Schema Registry subject to grant ACLs for (repeatable). + +| --registry-global +| Grants ACLs for global Schema Registry operations (no name required). |=== Examples: @@ -527,6 +692,12 @@ You can use the global flags and some other local flags. Following are the avail | --transactional-id | Transactional IDs to list/remove ACLs for. (repeatable) + +| --registry-subject +| Schema Registry subject(s) to list/remove ACLs for. (repeatable) + +| --registry-global +| Match ACLs for global Schema Registry operations. |=== === User @@ -542,11 +713,9 @@ Following are the available global user flags: |=== | Flag | Description | Supported Value -ifndef::env-cloud[] | -X admin.hosts -| The comma-separated list of Admin API addresses (IP:port). You must specify one for each broker. +| The comma-separated list of IP addresses (IP:port). You must specify one for each broker. | strings -endif::[] | -h, --help | -h, --help | Help. diff --git a/modules/manage/pages/security/authorization/index.adoc b/modules/manage/pages/security/authorization/index.adoc index 00150315f..16ff7a1f2 100644 --- a/modules/manage/pages/security/authorization/index.adoc +++ b/modules/manage/pages/security/authorization/index.adoc @@ -1,4 +1,4 @@ -= Redpanda Authorization Mechanisms += Configure Authorization :description: Redpanda provides two mechanisms for controlling user permissions. :page-aliases: security:authorization/index.adoc, manage:security/authorization.adoc :page-categories: Management, Security diff --git a/modules/manage/pages/security/authorization/rbac.adoc b/modules/manage/pages/security/authorization/rbac.adoc index 22c90a628..fc9d98ee3 100644 --- a/modules/manage/pages/security/authorization/rbac.adoc +++ b/modules/manage/pages/security/authorization/rbac.adoc @@ -12,13 +12,4 @@ Role-based access control (RBAC) provides a way to configure permissions for pro endif::[] -include::manage:partial$rbac-dp.adoc[] - -ifndef::env-cloud[] -== Suggested reading - -* xref:reference:rpk/rpk-security/rpk-security.adoc[`rpk security`] -* xref:reference:rpk/rpk-security/rpk-security-acl.adoc[`rpk security acl`] -* xref:reference:rpk/rpk-security/rpk-security-acl-create.adoc[`rpk security acl create`] - -endif::[] \ No newline at end of file +include::manage:partial$rbac-dp.adoc[] \ No newline at end of file diff --git a/modules/manage/partials/rbac-assign-role.adoc b/modules/manage/partials/rbac-assign-role.adoc index 5b927f694..97c415c62 100644 --- a/modules/manage/partials/rbac-assign-role.adoc +++ b/modules/manage/partials/rbac-assign-role.adoc @@ -1,27 +1,21 @@ -There are two ways to add a role to a principal: +To assign a role to a principal, edit the role or edit the user. -Option 1, using the `Edit Role` view: +Option 1: Edit the role -1. Select `Security` from the left navigation menu. +. From *Security* on the left navigation menu, select the *Roles* tab. -2. Select the `Roles` tab. +. Select the role you want to assign to one or more users/principals. -3. Find the role you want to assign to one or more principals and then click on the role name. +. Click *Edit*. -4. Click *Edit*. +. Below the list of permissions, find the Principals section. You can add any number of users/principals to the role. After listing all new users/principals, click *Update*. -5. Below the list of permissions, find the `Principals` section. You can add any number of principals to the role at a time. +Option 2: Edit the user -6. After you have listed all new principals, click *Update*. +. From *Security* on the left navigation menu, select the *Users* tab. -Option 2, using the `Edit User` view: +. Select the user you want to assign one or more roles to. -1. Select `Security` from the left navigation menu. +. In the *Assign roles* input field, select the roles you want to add to this user. -2. Select the `Users` tab. - -3. Find the user you want to assign one or more roles to then click the user's name. - -4. Using the `Assign Roles` input field, list the roles you want to add to this user. - -5. After you have added all roles, click *Update*. \ No newline at end of file +. After adding all roles, click *Update*. \ No newline at end of file diff --git a/modules/manage/partials/rbac-create-role.adoc b/modules/manage/partials/rbac-create-role.adoc index 44e79b6a8..483cd8922 100644 --- a/modules/manage/partials/rbac-create-role.adoc +++ b/modules/manage/partials/rbac-create-role.adoc @@ -1,15 +1,14 @@ To create a new role: -1. Select `Security` from the left navigation menu. +. From *Security* on the left navigation menu, select the *Roles* tab. -2. Select the `Roles` tab. +. Click *Create role*. -3. Click *Create role*. +. Provide a name for the role and an optional origin host for users to connect from. -4. In the `Create role` view, provide a name for the role and an optional origin host for users to connect from. +. Define the permissions (ACLs) for the role. You can create ACLs for clusters, topics, consumer groups, transactional IDs, Schema Registry subjects, and Schema Registry operations. -5. Define the permissions (access control lists, ACLs) for the role. You can create ACLs for topics, consumer groups, and transactional IDs. ++ +TIP: You can assign more than one user/principal to the role when creating it. -6. __(Optional)__ You can assign one or more principals (users) to the role when creating it. - -7. Click *Create*. \ No newline at end of file +. Click *Create*. \ No newline at end of file diff --git a/modules/manage/partials/rbac-delete-role.adoc b/modules/manage/partials/rbac-delete-role.adoc index 54c55ff00..ecb9f8fbf 100644 --- a/modules/manage/partials/rbac-delete-role.adoc +++ b/modules/manage/partials/rbac-delete-role.adoc @@ -1,11 +1,9 @@ To delete an existing role: -1. Select `Security` from the left navigation menu. +. From *Security* on the left navigation menu, select the *Roles* tab. -2. Click the role you want to delete. This shows all currently assigned permissions (ACLs) and principals (users). +. Click the role you want to delete. This shows all currently assigned permissions (ACLs) and principals (users). -3. Click *Delete*. +. Click *Delete*. -4. {ui} displays a prompt asking you to confirm deletion of the role. The prompt differs based on whether there are principals assigned to the role or not. If there are principals assigned to the role, you must type the role name in the input field when prompted before you can continue. - -5. Click *Delete*. \ No newline at end of file +. Click *Delete*. \ No newline at end of file diff --git a/modules/manage/partials/rbac-describe-role.adoc b/modules/manage/partials/rbac-describe-role.adoc index 1d52f2d2e..ba6e1e1a6 100644 --- a/modules/manage/partials/rbac-describe-role.adoc +++ b/modules/manage/partials/rbac-describe-role.adoc @@ -1,9 +1,7 @@ To view details of an existing role: -1. Select `Security` from the left navigation menu. +1. From *Security* on the left navigation menu, select the *Roles* tab. -2. Select the `Roles` tab. - -3. Find the role you want to view and click the role name. +2. Find the role you want to view and click the role name. All roles are listed in a paginated view. You can also filter the view using the input field at the top of the list. \ No newline at end of file diff --git a/modules/manage/partials/rbac-dp.adoc b/modules/manage/partials/rbac-dp.adoc index b25974f0c..fa58b7f35 100644 --- a/modules/manage/partials/rbac-dp.adoc +++ b/modules/manage/partials/rbac-dp.adoc @@ -2,40 +2,152 @@ == RBAC overview -RBAC is designed to address the critical challenge of access management at scale. It alleviates the process of manually maintaining and verifying a set of raw permissions (access control lists, or ACLs) for a user base that could contain thousands of users. RBAC provides a method to onboard new employees easier, audit accesses faster, and adapt more readily to evolutions of usage and compliance needs. +RBAC addresses the challenge of access management at scale. Instead of managing individual ACLs for each user, RBAC groups permissions into roles that you can assign to multiple users. Roles can reflect organizational structure or job duties. This approach decouples users and permissions, allowing a one-to-many mapping that reduces the number of custom ACLs needed. -Using RBAC, you can define roles to reflect organizational structure or job duties. This approach decouples users and permissions through the assignment of roles. RBAC allows a one-to-many mapping of a given role to many users, dramatically reducing the number of custom policies needed for a resource from one per user, to one per group of users. +Benefits of RBAC: -=== RBAC terminology +* Simplified management: Create roles once, assign to many users +* Easier onboarding: New employees inherit permissions by role assignment +* Faster audits: Review permissions by role rather than individual user +* Better compliance: Roles align with organizational structure and job duties +* Reduced errors: Fewer individual ACL assignments mean fewer mistakes -Under the RBAC framework, you create *roles*, grant *permissions* to those roles, and assign the roles to *users*. When you change the permissions for a given role, all users with that role automatically gain the modified permissions. You grant or deny permissions for a role by creating an ACL and specifying the RBAC role as either allowed or denied respectively. +== Manage roles + +ifndef::env-cloud[] +Administrators can create and manage RBAC configurations with `rpk`, the Redpanda Admin API, or {ui}. + +endif::[] + +ifdef::env-cloud[] +Administrators can manage RBAC configurations with `rpk` or {ui}. + +endif::[] + +In {ui}, select *Security* from the left navigation menu, and then select the *Roles* tab. After the role is created, you can add users/principals to it. + +For `rpk`, use xref:reference:rpk/rpk-security/rpk-security.adoc[`rpk security`]. For example, suppose you want to create a `DataAnalysts` role for users who need to read from analytics topics and write to reporting topics: + +[,bash] +---- +# 1. Create the role +rpk security role create DataAnalysts + +# 2. Grant read access to analytics topics +rpk security acl create --operation read,describe \ + --topic 'analytics-*' --resource-pattern-type prefixed \ + --allow-role DataAnalysts + +# 3. Grant write access to reporting topics +rpk security acl create --operation write,describe \ + --topic 'reports-*' --resource-pattern-type prefixed \ + --allow-role DataAnalysts + +# 4. Assign users to the role +rpk security role assign DataAnalysts --principal alice,bob,charlie + +# 5. Verify the setup +rpk security role describe DataAnalysts +---- + +All three users (`alice`, `bob`, `charlie`) now have identical permissions without managing individual ACLs for each user. + + +== RBAC terminology + +Understanding RBAC terminology is essential for effective role management: + +[cols="1,2,2"] +|=== +| Term | Definition | Example + +| Role +| A named collection of ACLs that can be assigned to users +| `DataEngineers`, `ApplicationDevelopers`, `ReadOnlyUsers` + +| Principal +| A user account in the system (same as ACL principals) +| `User:alice`, `User:bob`, `User:analytics-service` + +| Permission +| An ACL rule that allows or denies specific operations +| `ALLOW READ on topic:sensor-data`, `DENY DELETE on cluster` + +| Assignment +| The association between a user and one or more roles +| User `alice` has roles `DataEngineers` and `TopicAdmins` +|=== + +RBAC workflow: + +1. *Create roles*: Define roles that match your organizational needs +2. *Grant permissions*: Create ACLs specifying the role as allowed/denied +3. *Assign users*: Associate users with appropriate roles +4. *Automatic inheritance*: Users gain all permissions from their assigned roles + +Under the RBAC framework, you create *roles*, grant *permissions* to those roles, and assign the roles to *users*. When you change the permissions for a given role, all users with that role automatically gain the modified permissions. You grant or deny permissions for a role by creating an ACL and specifying the RBAC role as either allowed or denied respectively. Redpanda treats all *users* as security principals and defines them with the `Type:Name` syntax (for example, `User:mike`). You can omit the `Type` when defining a principal and Redpanda will assume the `User:` type. All examples here use the full syntax for clarity. ifndef::env-cloud[] -See xref:security/authorization/acl.adoc[access control lists] for more information on defining ACLs and working with principals. +See xref:manage:security/authorization/acl.adoc[access control lists] for more information on defining ACLs and working with principals. +endif::[] +ifdef::env-cloud[] +See xref:security:authorization/rbac/acl.adoc[access control lists] for more information on defining ACLs and working with principals. endif::[] -==== Roles +=== Roles -A role is a named collection of ACLs which may have users (security principals) assigned to it. You can assign any number of roles to a given user. When installing a new Redpanda cluster, no roles are provisioned by default. +You can assign any number of roles to a given user. When installing a new Redpanda cluster, no roles are provisioned by default. ifndef::env-cloud[] -If you want to use RBAC, you must create your first roles using your `superuser` account, which enables you to create additional roles and assign appropriate ACLs as necessary. See xref:security/authentication.adoc#create_superusers[configure authentication] for more information on creating and managing superusers. +To use RBAC, you must create your first roles using your `superuser` account, which enables you to create additional roles and assign appropriate ACLs as necessary. See xref:security/authentication.adoc#create_superusers[configure authentication] for more information on creating and managing superusers. endif::[] -When performing an upgrade from older versions of Redpanda, all existing SASL/SCRAM users are assigned to the placeholder `Users` role to help you more readily migrate away from pure ACLs. As a security measure, this default role has no assigned ACLs. +When performing an upgrade from older versions of Redpanda, all existing SASL/SCRAM users are assigned to the placeholder `User` role to help you more readily migrate away from pure ACLs. As a security measure, this default role has no assigned ACLs. + +=== Policy conflicts + +You can assign a combination of ACLs and roles to any given principal. ACLs allow permissions, deny permissions, or specify a combination of both. As a result, users may at times have role assignments with conflicting policies. + +Permission resolution rules: + +A user is permitted to perform an operation if and only if: + +. No `DENY` permission exists matching the operation +. An `ALLOW` permission exists matching the operation + +Examples: + +[cols="2,2,1,2"] +|=== +| User's direct ACLs | Role-based ACLs | Result | Explanation + +| `ALLOW READ topic:logs` +| Role has `DENY READ topic:logs` +| ❌ denied +| `DENY` always takes precedence -==== Policy conflicts +| `DENY WRITE topic:sensitive` +| Role has `ALLOW WRITE topic:*` +| ❌ denied +| Specific `DENY` blocks wildcard `ALLOW` -You can assign a combination of ACLs and roles to any given principal. ACLs allow permissions, deny permissions, or specify a combination of both. As a result, users may at times have role assignments with conflicting policies. If this situation arises, the user is permitted to perform an operation if and only if: +| No direct ACLs +| Role has `ALLOW READ topic:data` +| ✅ allowed +| Role permission applies -* There does not exist a DENY permission matching the operation. -* There exists an ALLOW permission matching the operation. +| `ALLOW READ topic:public` +| No role ACLs for this topic +| ✅ allowed +| Direct permission applies +|=== ifndef::env-cloud[] + === RBAC example Consider a scenario where your software engineers use a set of private topics to publish application update information to users. All your private topics begin with the prefix `private-`. You might create a new `SoftwareEng` role to represent the software engineers with write access to these private topics. You would then assign the `SoftwareEng` role as the allowed role for a new ACL specifying read and write permissions to `private-*`. Using a wildcard includes all existing private topics and any new ones you might create later. You then assign the new role to John and Jane, your two software engineers who will write messages to this topic. The `rpk` commands to accomplish this are: @@ -60,6 +172,31 @@ rpk security acl create --operation write --topic private-software-versions --al endif::[] +== RBAC best practices + +Follow these recommendations for effective role-based access control: + +Role design + +* Use descriptive names: Choose role names that clearly indicate their purpose (`DataEngineers`, `ReadOnlyAnalysts`) +* Follow job functions: Align roles with actual job responsibilities and organizational structure +* Keep roles focused: Create specific roles rather than overly broad ones (`TopicReaders` vs `SuperUsers`) +* Plan for growth: Design roles that can accommodate new team members and evolving needs + +Permission management + +* Start with minimal permissions: Grant only the access required for the role's function +* Use wildcards carefully: Prefixed patterns like `analytics-*` are useful but review regularly +* Avoid `DENY` rules: Prefer specific `ALLOW` rules over complex `DENY`/`ALLOW` combinations +* Document role purpose: Maintain clear documentation about what each role is intended for + +Operational guidelines + +* Regular reviews: Audit roles and assignments quarterly to ensure they remain appropriate +* Least privilege: Users should have the minimum roles needed for their current responsibilities +* Temporary access: Create time-limited roles for contractors or temporary project access +* Monitor usage: Track which roles and permissions are actively used vs. dormant + == Manage users and roles ifndef::env-cloud[] @@ -68,15 +205,30 @@ Administrators can manage RBAC configurations with `rpk`, the Redpanda Admin API endif::[] ifdef::env-cloud[] -Administrators can manage RBAC configurations with {ui}. +Administrators can manage RBAC configurations with `rpk` or {ui}. endif::[] +Common management tasks: + +* Create roles: Define new roles for organizational functions +* Assign permissions: Add ACLs to roles to define what they can access +* Assign users: Associate users with appropriate roles +* Modify roles: Add or remove permissions from existing roles +* Audit access: Review roles and assignments for compliance + +Typical workflow: + +. Create role +. Add ACL permissions +. Assign users +. Test access +. Monitor and adjust + === Create a role Creating a new role is a two-step process. First you define the role, giving it a unique and descriptive name. Second, you assign one or more ACLs to allow or deny access for the new role. This defines the permissions that are inherited by all users assigned to the role. It is possible to have an empty role with no ACLs assigned. -ifndef::env-cloud[] [tabs] ===== rpk:: @@ -114,13 +266,6 @@ include::manage:partial$rbac-create-role.adoc[] -- ===== -endif::[] - -ifdef::env-cloud[] -include::manage:partial$rbac-create-role.adoc[] - -endif::[] - === Delete a role When a role is deleted, Redpanda carries out the following actions automatically: @@ -130,7 +275,6 @@ When a role is deleted, Redpanda carries out the following actions automatically Redpanda lists all impacted ACLs and role assignments when running this command. You receive a prompt to confirm the deletion action. The delete operation is irreversible. -ifndef::env-cloud[] [tabs] ==== rpk:: @@ -172,18 +316,11 @@ include::manage:partial$rbac-delete-role.adoc[] -- ==== -endif::[] - -ifdef::env-cloud[] -include::manage:partial$rbac-delete-role.adoc[] - -endif::[] === Assign a role You can assign a role to any security principal. Principals are referred to using the format: `Type:Name`. Redpanda currently supports only the `User` type. If you omit the type, Redpanda assumes the `User` type by default. With this command, you can assign the role to multiple principals at the same time by using a comma separator between each principal. -ifndef::env-cloud[] [tabs] ==== rpk:: @@ -217,18 +354,10 @@ include::manage:partial$rbac-assign-role.adoc[] -- ==== -endif::[] - -ifdef::env-cloud[] -include::manage:partial$rbac-assign-role.adoc[] - -endif::[] - === Unassign a role You can remove a role assignment from a security principal without deleting the role. Principals are referred to using the format: `Type:Name`. Redpanda currently supports only the `User` type. If you omit the type, Redpanda assumes the `User` type by default. With this command, you can remove the role from multiple principals at the same time by using a comma separator between each principal. -ifndef::env-cloud[] [tabs] ==== rpk:: @@ -261,18 +390,10 @@ include::manage:partial$rbac-unassign-role.adoc[] -- ==== -endif::[] - -ifdef::env-cloud[] -include::manage:partial$rbac-unassign-role.adoc[] - -endif::[] - === Edit role permissions You can add or remove ACLs from any of the roles you have previously created. -ifndef::env-cloud[] [tabs] ==== rpk:: @@ -309,7 +430,6 @@ rpk security acl list --allow-role --deny-role See also: -* xref:security/authorization/acl.adoc[Access Control Lists] for more information on defining and using ACLs. * xref:reference:rpk/rpk-acl/rpk-acl-create.adoc[] * xref:reference:rpk/rpk-acl/rpk-acl-delete.adoc[] * xref:reference:rpk/rpk-acl/rpk-acl-list.adoc[] @@ -322,18 +442,10 @@ include::manage:partial$rbac-edit-role.adoc[] -- ==== -endif::[] - -ifdef::env-cloud[] -include::manage:partial$rbac-edit-role.adoc[] - -endif::[] - === List all roles Redpanda lets you view a list of all existing roles. -ifndef::env-cloud[] [tabs] ==== rpk:: @@ -365,18 +477,10 @@ include::manage:partial$rbac-list-role.adoc[] -- ==== -endif::[] - -ifdef::env-cloud[] -include::manage:partial$rbac-list-role.adoc[] - -endif::[] - === Describe a role When managing roles, you may need to review the ACLs the role grants or the list of principals assigned to the role. -ifndef::env-cloud[] [tabs] ==== rpk:: @@ -416,11 +520,18 @@ include::manage:partial$rbac-describe-role.adoc[] -- ==== +== Suggested reading + +* xref:reference:rpk/rpk-security/rpk-security.adoc[`rpk security`] - Complete security command reference +* xref:reference:rpk/rpk-security/rpk-security-acl.adoc[`rpk security acl`] - ACL management commands + +ifndef::env-cloud[] +* xref:manage:security/authorization/acl.adoc[Access Control Lists] - Understanding the underlying ACL system +* xref:manage:security/authentication.adoc[Authentication] - Setting up users and authentication methods endif::[] ifdef::env-cloud[] -include::manage:partial$rbac-describe-role.adoc[] - +* xref:security:authorization/rbac/acl.adoc[Access Control Lists] - Understanding the underlying ACL system endif::[] // end::single-source[] \ No newline at end of file diff --git a/modules/manage/partials/rbac-edit-role.adoc b/modules/manage/partials/rbac-edit-role.adoc index b6c6b0713..5102715af 100644 --- a/modules/manage/partials/rbac-edit-role.adoc +++ b/modules/manage/partials/rbac-edit-role.adoc @@ -1,15 +1,11 @@ To edit the ACLs for an existing role: -1. Select `Security` from the left navigation menu. +. From *Security* on the left navigation menu, select the *Roles* tab. -2. Select the `Roles` tab. +. Select the role you want to edit and click *Edit*. -3. Find the role you want to assign to one or more principals and then click on the role name. +. While editing the role, you can update the optional origin host for users to connect from. -4. Click *Edit*. +. You can add or remove ACLs for the role. As when creating a new role, you can create or modify ACLs for topics, consumer groups, transactional IDs, Schema Registry subjects, and Schema Registry operations. -5. In the `Edit Role` view, you can update the optional origin host for users to connect from. - -6. You can add or remove existing (ACLs) for the role. As when creating a new role, you can create or modify ACLs for topics, consumer groups, and transactional IDs. - -7. After making all changes, click *Update*. \ No newline at end of file +. After making all changes, click *Update*. \ No newline at end of file diff --git a/modules/manage/partials/rbac-list-role.adoc b/modules/manage/partials/rbac-list-role.adoc index c4946ac52..7d00a9e27 100644 --- a/modules/manage/partials/rbac-list-role.adoc +++ b/modules/manage/partials/rbac-list-role.adoc @@ -1,7 +1,5 @@ To view all existing roles: -1. Select `Security` from the left navigation menu. - -2. Select the `Roles` tab. - +. From *Security* on the left navigation menu, select the *Roles* tab. ++ All roles are listed in a paginated view. You can also filter the view using the input field at the top of the list. \ No newline at end of file diff --git a/modules/manage/partials/rbac-unassign-role.adoc b/modules/manage/partials/rbac-unassign-role.adoc index 0db2b0228..998408296 100644 --- a/modules/manage/partials/rbac-unassign-role.adoc +++ b/modules/manage/partials/rbac-unassign-role.adoc @@ -1,27 +1,23 @@ There are two ways to remove a role from a principal: -Option 1, using the `Edit Role` view: +Option 1: Edit the role -1. Select `Security` from the left navigation menu. +. From *Security* on the left navigation menu, select the *Roles* tab. -2. Select the `Roles` tab. +. Select the role you want to remove from one or more principals. -3. Find the role you want to remove from one or more principals and then click on the role name. +. Click *Edit*. -4. Click *Edit*. +. Below the list of permissions, find the Principals section. Click *x* beside the name of any principals you want to remove from the role. -5. Below the list of permissions, find the `Principals` section. Click *x* beside the name of any principals you want to remove from the role. +. After you have removed all needed principals, click *Update*. -6. After you have removed all needed principals, click *Update*. +Option 2: Edit the user -Option 2, using the `Edit User` view: +. From *Security* on the left navigation menu, select the *Users* tab. -1. Select `Security` from the left navigation menu. +. Select the user you want to remove from one or more roles. -2. Select the `Users` tab. +. Click *x* beside the name of any roles you want to remove this user from. -3. Find the user you want to remove from one or more roles and then click the user's name. - -4. Click *x* beside the name of any roles you want to remove this user from. - -5. After you have removed the user from all roles, click *Update*. \ No newline at end of file +. After you have removed the user from all roles, click *Update*. \ No newline at end of file