Document the RBAC management UI for Calico Enterprise

Add "Manage roles in the web console" under Operations > Calico Enterprise
Manager UI, covering what the feature needs to be usable: turning it on,
creating and scoping a role, granting it to a subject, binding it to an
identity provider group, reviewing who holds what, and exporting roles to
another cluster.

Scoped to Calico Enterprise 3.24 (next) only, plus its sidebar entry and a
cross-link from "Configure user roles and permissions".

Behaviour the page is deliberate about, since each is easy to get wrong:

- Role names take any non-empty string up to 253 characters, matching
  ValidateIdentity. Spaces, '@' and non-ASCII are all valid and necessary, since
  the name has to equal the group claim the IdP sends.
- Turning the feature off uses get | jq | kubectl replace, because
  tigera-network-admin holds get and update on rbac-ui-config, not patch.
- Subjects added by hand go on the ClusterRoleBindings. Those are what
  FindExistingMemberSubjects reads back, so a subject added only to a namespaced
  RoleBinding is dropped the next time the role is edited in the console.
- IdP group binding is LDAP-only and single-homed on the management cluster:
  the manager's egress opens 389/636 only when Authentication.spec.ldap is set
  and scopes the destination to spec.ldap.host, and the /team/idp-groups routes
  always target the management cluster. The directory-sync secret is a second
  secret, distinct from tigera-ldap-credentials.
- Export carries bindings, not the ClusterRoles they reference, so the target
  cluster needs role management on and the same tiers and namespaces.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: dimitri-nicolo

calico-enterprise/operations/cnx/manage-roles.mdx

@@ -0,0 +1,142 @@
+---
+description: Create, scope, and export Calico Enterprise roles from the web console instead of writing Kubernetes RBAC manifests by hand.
+---
+
+import IconUser from '/img/icons/user-icon.svg';
+
+# Manage roles in the web console
+
+## Big picture
+
+Create and scope $[prodname] roles from the **Manage Team** page in the web console, instead of writing Kubernetes RBAC manifests by hand.
+
+## Value
+
+Giving a team access to one tier, one namespace, or one web console feature normally means hand-writing `ClusterRole` and `ClusterRoleBinding` manifests, and knowing which $[prodname] API resources each feature reads. **Manage Team** turns that into a list of named permissions: you pick what a role can view or modify and where it applies, and $[prodname] writes and reconciles the underlying Kubernetes RBAC for you.
+
+## Concepts
+
+### A role is a Kubernetes group
+
+A role you create in the console is a Kubernetes **group name**. $[prodname] binds the permissions you select to that group using `ClusterRoleBindings`, or `RoleBindings` for permissions you scope to a namespace. Everything it writes is labeled `app.kubernetes.io/managed-by=calico-ui-rbac`.
+
+A user gets a role when their authenticated identity carries that group. The console does not create or invite users: the **Users** tab is read-only, and lists the subjects it finds on the roles' bindings and in any bound identity provider groups, with the roles in effect for each.
+
+### Role management is per cluster
+
+Role management is off by default and is turned on one cluster at a time, including each managed cluster in a multi-cluster deployment. Roles are local to the cluster they were created on and are not synchronized; use **Export YAML** to copy them to another cluster.
+
+## Before you begin
+
+**Required**
+
+- A cluster running $[prodname] 3.24.0-3.0 or later
+- [Access to the web console](access-the-manager.mdx) as a user bound to `tigera-network-admin`
+
+**Limitations**
+
+- Roles do not synchronize between clusters. Exported roles are a copy, not a link.
+
+## How to
+
+- [Turn on role management](#turn-on-role-management)
+- [Create a role](#create-a-role)
+- [Give a user a role](#give-a-user-a-role)
+- [Bind roles to identity provider groups](#bind-roles-to-identity-provider-groups)
+- [See who has access](#see-who-has-access)
+- [Copy roles to another cluster](#copy-roles-to-another-cluster)
+
+### Turn on role management
+
+1. In the web console, select the cluster you want to manage roles on.
+1. Click the user icon <IconUser width="20"/> > **Manage Team**.
+1. Click **Enable RBAC management**.
+
+$[prodname] sets `rbac-ui-enabled` to `true` in the `rbac-ui-config` ConfigMap in the `calico-system` namespace, then builds the catalogue of permissions. This takes a few seconds, after which the **Roles** and **Users** tabs appear.
+
+To turn role management off again, set the flag back to `false`; the console has no control for this. Roles you already created keep working, but are no longer manageable from the console.
+
+```bash
+kubectl get configmap rbac-ui-config -n calico-system -o json \
+  | jq '.data["rbac-ui-enabled"] = "false"' \
+  | kubectl replace -f -
+```
+
+`kubectl patch` fails here: `tigera-network-admin` holds `get` and `update` on this ConfigMap, not `patch`.
+
+### Create a role
+
+1. Click the user icon <IconUser width="20"/> > **Manage Team** > **Roles** > **Create Role**.
+1. If an LDAP directory is connected, **Create Role** opens on a choice between **Bind an IdP group** and **Manual group binding**. Select **Manual group binding** and click **Next** — to bind a directory group instead, see [Bind roles to identity provider groups](#bind-roles-to-identity-provider-groups). With no directory connected, the role form opens straight away.
+1. Enter a **Role Name** and **Description**. The name is the Kubernetes group this role binds to; any non-empty value up to 253 characters is accepted, spaces and `@` included. You attach users and service accounts to it afterwards — see [Give a user a role](#give-a-user-a-role).
+1. Click **Add Permission** and choose one. Permissions are per feature area — policies, network sets, dashboards, service graph, packet captures, egress gateways and so on — each offered as **View** or **Modify**. The picker lists what is available on the cluster. Note that **Alerts and Security Events Settings** covers alert configuration, not the events themselves.
+1. Scope the permission, where it supports it:
+   - **Tier** — for policy permissions. Leave it as **all tiers** to apply the permission to every tier.
+   - **Namespace** — for namespaced permissions. Leave it as **any namespace** to apply the permission cluster-wide.
+1. Add any further permissions, then click **Save**. A role must carry at least one permission.
+
+To change a role later, select **Actions** > **Edit Permissions**. **Delete Role** removes the role and its bindings from this cluster; subjects bound to it lose the access it granted.
+
+### Give a user a role
+
+Because a role is a group, membership is what grants it. Create the role with [Bind an IdP group](#bind-roles-to-identity-provider-groups) and everyone in that group picks it up at their next sign-in, with nothing to do outside the console. Membership stays managed in your identity provider — see [Configure an external identity provider](configure-identity-provider.mdx).
+
+To audit which group each role binds, list the bindings the console manages. Use the **Users** tab to see who currently holds them.
+
+```bash
+kubectl get clusterrolebinding -l app.kubernetes.io/managed-by=calico-ui-rbac \
+  -o custom-columns='NAME:.metadata.name,ROLE:.roleRef.name,GROUP:.subjects[0].name'
+```
+
+### Bind roles to identity provider groups
+
+A role can be bound to a group that already exists in your directory, so membership stays managed in your identity provider. Users in that group get the role the next time they sign in.
+
+This requires the cluster to authenticate users with [LDAP](configure-identity-provider.mdx): $[prodname] permits directory-sync traffic only to the host named in `Authentication.spec.ldap.host`, and only on ports 389 and 636.
+
+The directory is read on the management cluster only, so create the secret there and turn role management on there too — even when the role applies to a managed cluster. It is a second secret, separate from the `tigera-ldap-credentials` secret that authentication uses: different namespace, different field names, so copy the values across rather than the keys.
+
+1. Create the directory-sync secret, using the same LDAP host as your `Authentication` resource — as a full URL here, where `Authentication.spec.ldap.host` takes `host:port`. $[prodname] walks the directory with these credentials and offers the groups it finds when you create a role.
+
+   ```bash
+   kubectl create secret generic tigera-idp-ldap-config -n calico-system \
+     --from-literal=url=ldaps://ad.example.com:636 \
+     --from-literal=bindDN='cn=admin,dc=example,dc=com' \
+     --from-literal=bindPassword='<password>' \
+     --from-literal=baseDN='ou=groups,dc=example,dc=com'
+   ```
+
+   Optionally add `groupFilter` (default `(objectClass=groupOfNames)`), `nameAttribute` (default `cn`; Active Directory typically uses `sAMAccountName`), `caBundle` for a private certificate authority, and `refreshIntervalSeconds` (default 300, clamped to 60–86400).
+
+1. Click the user icon <IconUser width="20"/> > **Manage Team** > **Roles** > **Create Role**.
+1. Leave **Bind an IdP group** selected, choose a group from the list, and click **Next**. Groups that already back a role are shown as unavailable.
+1. Add permissions as you would for any role, then click **Save**. The form shows the bound group as a read-only **IdP Group**, alongside a **Role Display Name** you can edit. The display name is a label only, so nothing here has to match your directory.
+
+The role appears in the list with type **Custom - IdP**. Membership is owned by your identity provider, so the role's subjects cannot be edited from the console. A group can back only one role; groups that already have one are marked in the picker.
+
+### See who has access
+
+Click the user icon <IconUser width="20"/> > **Manage Team** > **Users** to review which subjects hold which roles, and when each last signed in. Select a subject to see the permissions its roles carry.
+
+The tab is read-only, and lists the subjects on the roles' bindings plus the members of any bound identity provider groups; **Last signed in** fills in once a subject authenticates. Effective permissions are the union of these roles and anything bound to the subject outside the console, which this view does not show.
+
+### Copy roles to another cluster
+
+Roles apply only to the cluster they were created on. To reuse them elsewhere, export them and apply them to a cluster that also has role management turned on. The export carries each role's bindings, not the permissions they point at, and those exist only where the console has built its catalogue.
+
+1. Select the source cluster, then click the user icon <IconUser width="20"/> > **Manage Team** > **Roles** > **Export YAML**.
+1. Apply the file to each target cluster.
+
+   ```bash
+   kubectl apply -f <exported-file>.yaml
+   ```
+
+Check first that the target cluster has the tiers and namespaces the roles were scoped to. A binding naming a tier that is missing there applies without error but grants nothing, and a binding into a namespace that does not exist is rejected.
+
+The roles are independent copies: later changes on the source cluster are not propagated.
+
+## Additional resources
+
+- [Configure user roles and permissions](roles-and-permissions.mdx)
+- [Configure an external identity provider](configure-identity-provider.mdx)
+- [Configure RBAC for tiered policies](../../network-policy/policy-tiers/rbac-tiered-policies.mdx)

calico-enterprise/operations/cnx/roles-and-permissions.mdx

@@ -40,6 +40,8 @@ $[prodname] provides the following predefined roles and permissions:
 
 ## Additional resources
 
+- [Manage roles in the web console](manage-roles.mdx) — create and scope roles without writing RBAC manifests.
+
 For RBAC details on any given feature, see the feature. For example:
 
 - [Tiered policy RBAC](../../network-policy/policy-tiers/rbac-tiered-policies.mdx)

sidebars-calico-enterprise.js

@@ -549,6 +549,7 @@ module.exports = {
             'operations/cnx/authentication-quickstart',
             'operations/cnx/configure-identity-provider',
             'operations/cnx/roles-and-permissions',
+            'operations/cnx/manage-roles',
           ],
         },
         'operations/comms/index',