Merge pull request #1122 from btat/sync-pr898-restricted-admin

Sync latest with changes from PR#989 - 'Updates to the Global roles f…
rancher · Feb 13, 2024 · 74f23ff · 74f23ff
2 parents 3d10005 + b9f1ae8
commit 74f23ff
Show file tree

Hide file tree

Showing 2 changed files with 191 additions and 81 deletions.
diff --git a/...lobal-configuration/manage-role-based-access-control-rbac/global-permissions.md b/...lobal-configuration/manage-role-based-access-control-rbac/global-permissions.md
@@ -12,85 +12,14 @@ Global Permissions define user authorization outside the scope of any particular
 
 - **Administrator:** These users have full control over the entire Rancher system and all clusters within it.
 
-- **Restricted Admin:** These users have full control over downstream clusters, but cannot alter the local Kubernetes cluster.
+- **Restricted Admin (Deprecated) :** These users have full control over downstream clusters, but cannot alter the local Kubernetes cluster.
 
 - **Standard User:** These users can create new clusters and use them. Standard users can also assign other users permissions to their clusters.
 
 - **User-Base:** User-Base users have login-access only.
 
 You cannot update or delete the built-in Global Permissions.
 
-## Restricted Admin
-
-A new `restricted-admin` role was created in Rancher v2.5 in order to prevent privilege escalation from the local Rancher server Kubernetes cluster. This role has full administrator access to all downstream clusters managed by Rancher, but it does not have permission to alter the local Kubernetes cluster.
-
-The `restricted-admin` can create other `restricted-admin` users with an equal level of access.
-
-A new setting was added to Rancher to set the initial bootstrapped administrator to have the `restricted-admin` role. This applies to the first user created when the Rancher server is started for the first time. If the environment variable is set, then no global administrator would be created, and it would be impossible to create the global administrator through Rancher.
-
-To bootstrap Rancher with the `restricted-admin` as the initial user, the Rancher server should be started with the following environment variable:
-
-```
-CATTLE_RESTRICTED_DEFAULT_ADMIN=true
-```
-### List of `restricted-admin` Permissions
-
-The following table lists the permissions and actions that a `restricted-admin` should have in comparison with the `Administrator` and `Standard User` roles:
-
-| Category | Action | Global Admin | Standard User | Restricted Admin | Notes for Restricted Admin role |
-| -------- | ------ | ------------ | ------------- | ---------------- | ------------------------------- |
-| Local Cluster functions | Manage Local Cluster (List, Edit, Import Host) | Yes | No | No | |
-| | Create Projects/namespaces | Yes | No | No | |
-| | Add cluster/project members | Yes | No | No | |
-| | Global DNS | Yes | No | No | |
-| | Access to management cluster for CRDs and CRs | Yes | No | Yes | |
-| | Save as RKE Template | Yes | No | No | |
-| Security | | | | | |
-| Enable auth | Configure Authentication | Yes | No | Yes | |
-| Roles	| Create/Assign GlobalRoles | Yes | No (Can list) | Yes | Auth webhook allows creating globalrole for perms already present |
-| | Create/Assign ClusterRoles | Yes | No (Can list) | Yes | Not in local cluster |
-| | Create/Assign ProjectRoles | Yes | No (Can list) | Yes | Not in local cluster |
-| Users	| Add User/Edit/Delete/Deactivate User | Yes | No | Yes | |
-| Groups | Assign Global role to groups | Yes | No | Yes | As allowed by the webhook |
-| | Refresh Groups | Yes | No | Yes | |
-| PSP's | Manage PSP templates | Yes | No (Can list) | Yes | Same privileges as Global Admin for PSPs |
-| Tools | | | | | |
-| | Manage RKE Templates | Yes | No | Yes | |
-| | Manage Global Catalogs | Yes | No | Yes | Cannot edit/delete built-in system catalog. Can manage Helm library |
-| | Cluster Drivers | Yes | No | Yes | |
-| | Node Drivers | Yes | No | Yes | |
-| | GlobalDNS Providers | Yes | Yes (Self) | Yes | |
-| | GlobalDNS Entries | Yes | Yes (Self) | Yes | |
-| Settings | | | | | |
-| | Manage Settings | Yes | No (Can list) | No (Can list) | |
-| User | | | | | |
-| | Manage API Keys | Yes (Manage all) | Yes (Manage self) | Yes (Manage self) | |
-| | Manage Node Templates | Yes | Yes (Manage self) | Yes (Manage self) | Can only manage their own node templates and not those created by other users |
-| | Manage Cloud Credentials | Yes | Yes (Manage self) | Yes (Manage self) | Can only manage their own cloud credentials and not those created by other users |
-| Downstream Cluster | Create Cluster | Yes | Yes | Yes | |
-| | Edit Cluster | Yes | Yes | Yes | |
-| | Rotate Certificates	| Yes | | Yes | |
-| | Snapshot Now | Yes | | Yes | |
-| | Restore Snapshot | Yes | | Yes | |
-| | Save as RKE Template | Yes | No | Yes | |
-| | Run CIS Scan | Yes | Yes | Yes | |
-| | Add Members	| Yes | Yes | Yes | |
-| | Create Projects | Yes | Yes | Yes | |
-| Feature Charts since v2.5 | | | | | |
-| | Install Fleet | Yes | | Yes | Should not be able to run Fleet in local cluster |
-| | Deploy EKS cluster | Yes | Yes | Yes | |
-| | Deploy GKE cluster | Yes | Yes | Yes | |
-| | Deploy AKS cluster | Yes | Yes | Yes | |
-
-
-### Changing Global Administrators to Restricted Admins
-
-If Rancher already has a global administrator, they should change all global administrators over to the new `restricted-admin` role.
-
-This can be done through **Security > Users** and moving any Administrator role over to Restricted Administrator.
-
-Signed-in users can change themselves over to the `restricted-admin` if they wish, but they should only do that as the last step, otherwise they won't have the permissions to do so.
-
 ## Global Permission Assignment
 
 Global permissions for local users are assigned differently than users who log in to Rancher using external authentication.
@@ -135,13 +64,15 @@ The default roles, Administrator and Standard User, each come with multiple glob
 
 Administrators can enforce custom global permissions in multiple ways:
 
-- [Changing the default permissions for new users](#configuring-default-global-permissions)
-- [Configuring global permissions for individual users](#configuring-global-permissions-for-individual-users)
-- [Configuring global permissions for groups](#configuring-global-permissions-for-groups)
+- [Creating custom global roles](#custom-globalroles).
+- [Changing the default permissions for new users](#configuring-default-global-permissions).
+- [Configuring global permissions for individual users](#configuring-global-permissions-for-individual-users).
+- [Configuring global permissions for groups](#configuring-global-permissions-for-groups).
 
-### Custom Global Permissions Reference
+### Combining Built-in GlobalRoles
 
-The following table lists each custom global permission available and whether it is included in the default global permissions, `Administrator`, `Standard User` and `User-Base`.
+Rancher provides several GlobalRoles which grant granular permissions for certain common use cases.
+The following table lists each built-in global permission and whether it is included in the default global permissions, `Administrator`, `Standard User` and `User-Base`.
 
 | Custom Global Permission           | Administrator | Standard User | User-Base |
 | ---------------------------------- | ------------- | ------------- |-----------|
@@ -171,6 +102,112 @@ For details on which Kubernetes resources correspond to each global permission,
 
 :::
 
+### Custom GlobalRoles
+
+You can create custom GlobalRoles to satisfy use cases not directly addressed by built-in GlobalRoles. 
+
+Create custom GlobalRoles through the UI or through automation (such as the Rancher Kubernetes API). You can specify the same type of rules as the rules for upstream roles and clusterRoles. 
+
+#### Escalate and Bind verbs
+
+When giving permissions on GlobalRoles, keep in mind that Rancher respects the `escalate` and `bind` verbs, in a similar fashion to [Kubernetes](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#restrictions-on-role-creation-or-update).
+
+Both of these verbs, which are given on the GlobalRoles resource, can grant users the permission to bypass Rancher's privilege escalation checks. This potentially allows users to become admins. Since this represents a serious security risk, `bind` and `escalate` should be distributed to users with great caution. 
+
+The `escalate` verb allows users to change a GlobalRole and add any permission, even if the users doesn't have the permissions in the current GlobalRole or the new version of the GlobalRole. 
+
+The `bind` verb allows users to create a GlobalRoleBinding to the specified GlobalRole, even if they do not have the permissions in the GlobalRole. 
+
+:::danger
+
+The wildcard verb `*` also includes the `bind` and `escalate` verbs. This means that giving `*` on GlobalRoles to a user also gives them both `escalate` and `bind`.
+
+:::
+
+##### Custom GlobalRole Examples
+
+To grant permission to escalate only the `test-gr` GlobalRole:
+
+```yaml
+rules:
+- apiGroups:
+  - 'management.cattle.io'
+  resources:
+  - 'globalroles'
+  resourceNames:
+  - 'test-gr'
+  verbs:
+  - 'escalate'
+```
+
+To grant permission to escalate all GlobalRoles:
+
+```yaml
+rules:
+- apiGroups:
+  - 'management.cattle.io'
+  resources:
+  - 'globalroles'
+  verbs:
+  - 'escalate'
+```
+
+To grant permission to create bindings (which bypass escalation checks) to only the `test-gr` GlobalRole:
+
+```yaml
+rules:
+- apiGroups:
+  - 'management.cattle.io'
+  resources:
+  - 'globalroles'
+  resourceNames:
+  - 'test-gr'
+  verbs:
+  - 'bind'
+- apiGroups:
+  - 'management.cattle.io'
+  resources:
+  - 'globalrolebindings'
+  verbs:
+  - 'create'
+```
+
+Granting `*` permissions (which includes both `escalate` and `bind`):
+
+```yaml
+rules:
+- apiGroups:
+  - 'management.cattle.io'
+  resources:
+  - 'globalroles'
+  verbs:
+  - '*'
+```
+
+#### GlobalRole Permissions on Downstream Clusters
+
+GlobalRoles can grant one or more RoleTemplates on every downstream cluster through the `inheritedClusterRoles` field. Values in this field must refer to a RoleTemplate which exists and has a `context` of Cluster.
+
+With this field, users gain the specified permissions on all current or future downstream clusters. For example, consider the following GlobalRole:
+
+```yaml
+apiVersion: management.cattle.io/v3
+kind: GlobalRole
+displayName: All Downstream Owner 
+metadata:
+  name: all-downstream-owner
+inheritedClusterRoles:
+- cluster-owner
+```
+
+Any user with this permission will be a cluster-owner on all downstream clusters. If a new cluster is added, regardless of type, the user will be an owner on that cluster as well.
+
+:::danger
+
+Using this field on [default GlobalRoles](#configuring-default-global-permissions) may result in users gaining excessive permissions.
+
+:::
+
 ### Configuring Default Global Permissions
 
 If you want to restrict the default permissions for new users, you can remove the `user` permission as default role and then assign multiple individual permissions as default instead. Conversely, you can also add administrative permissions on top of a set of other standard permissions.
@@ -249,3 +286,79 @@ To refresh group memberships,
 1. Click **Refresh Group Memberships**.
 
 **Result:** Any changes to the group members' permissions will take effect.
+
+## Restricted Admin
+
+:::warning Deprecated
+
+The Restricted Admin role is deprecated, and will be removed in a future version of Rancher (2.10 or higher). You should make a custom role with the desired permissions instead of relying on this built-in role.
+
+:::
+
+A new `restricted-admin` role was created in Rancher v2.5 in order to prevent privilege escalation on the local Rancher server Kubernetes cluster. This role has full administrator access to all downstream clusters managed by Rancher, but it does not have permission to alter the local Kubernetes cluster.
+
+The `restricted-admin` can create other `restricted-admin` users with an equal level of access.
+
+A new setting was added to Rancher to set the initial bootstrapped administrator to have the `restricted-admin` role. This applies to the first user created when the Rancher server is started for the first time. If the environment variable is set, then no global administrator would be created, and it would be impossible to create the global administrator through Rancher.
+
+To bootstrap Rancher with the `restricted-admin` as the initial user, the Rancher server should be started with the following environment variable:
+
+```
+CATTLE_RESTRICTED_DEFAULT_ADMIN=true
+```
+### List of `restricted-admin` Permissions
+
+The following table lists the permissions and actions that a `restricted-admin` should have in comparison with the `Administrator` and `Standard User` roles:
+
+| Category | Action | Global Admin | Standard User | Restricted Admin | Notes for Restricted Admin role |
+| -------- | ------ | ------------ | ------------- | ---------------- | ------------------------------- |
+| Local Cluster functions | Manage Local Cluster (List, Edit, Import Host) | Yes | No | No | |
+| | Create Projects/namespaces | Yes | No | No | |
+| | Add cluster/project members | Yes | No | No | |
+| | Global DNS | Yes | No | No | |
+| | Access to management cluster for CRDs and CRs | Yes | No | Yes | |
+| | Save as RKE Template | Yes | No | No | |
+| Security | | | | | |
+| Enable auth | Configure Authentication | Yes | No | Yes | |
+| Roles	| Create/Assign GlobalRoles | Yes | No (Can list) | Yes | Auth webhook allows creating globalrole for perms already present |
+| | Create/Assign ClusterRoles | Yes | No (Can list) | Yes | Not in local cluster |
+| | Create/Assign ProjectRoles | Yes | No (Can list) | Yes | Not in local cluster |
+| Users	| Add User/Edit/Delete/Deactivate User | Yes | No | Yes | |
+| Groups | Assign Global role to groups | Yes | No | Yes | As allowed by the webhook |
+| | Refresh Groups | Yes | No | Yes | |
+| PSP's | Manage PSP templates | Yes | No (Can list) | Yes | Same privileges as Global Admin for PSPs |
+| Tools | | | | | |
+| | Manage RKE Templates | Yes | No | Yes | |
+| | Manage Global Catalogs | Yes | No | Yes | Cannot edit/delete built-in system catalog. Can manage Helm library |
+| | Cluster Drivers | Yes | No | Yes | |
+| | Node Drivers | Yes | No | Yes | |
+| | GlobalDNS Providers | Yes | Yes (Self) | Yes | |
+| | GlobalDNS Entries | Yes | Yes (Self) | Yes | |
+| Settings | | | | | |
+| | Manage Settings | Yes | No (Can list) | No (Can list) | |
+| User | | | | | |
+| | Manage API Keys | Yes (Manage all) | Yes (Manage self) | Yes (Manage self) | |
+| | Manage Node Templates | Yes | Yes (Manage self) | Yes (Manage self) | Can only manage their own node templates and not those created by other users |
+| | Manage Cloud Credentials | Yes | Yes (Manage self) | Yes (Manage self) | Can only manage their own cloud credentials and not those created by other users |
+| Downstream Cluster | Create Cluster | Yes | Yes | Yes | |
+| | Edit Cluster | Yes | Yes | Yes | |
+| | Rotate Certificates	| Yes | | Yes | |
+| | Snapshot Now | Yes | | Yes | |
+| | Restore Snapshot | Yes | | Yes | |
+| | Save as RKE Template | Yes | No | Yes | |
+| | Run CIS Scan | Yes | Yes | Yes | |
+| | Add Members	| Yes | Yes | Yes | |
+| | Create Projects | Yes | Yes | Yes | |
+| Feature Charts since v2.5 | | | | | |
+| | Install Fleet | Yes | | Yes | Should not be able to run Fleet in local cluster |
+| | Deploy EKS cluster | Yes | Yes | Yes | |
+| | Deploy GKE cluster | Yes | Yes | Yes | |
+| | Deploy AKS cluster | Yes | Yes | Yes | |
+
+### Changing Global Administrators to Restricted Admins
+
+In previous version, the docs recommended that all users should be changed over to Restricted Admin if the role was in use. Users are now encouraged to use a custom-built role using the cluster permissions feature, and migrate any current restricted admins to use that approach. 
+
+This can be done through **Security > Users** and moving any Administrator role over to Restricted Administrator.
+
+Signed-in users can change themselves over to the `restricted-admin` if they wish, but they should only do that as the last step, otherwise they won't have the permissions to do so.
diff --git a/...lobal-configuration/manage-role-based-access-control-rbac/global-permissions.md b/...lobal-configuration/manage-role-based-access-control-rbac/global-permissions.md
@@ -64,6 +64,7 @@ The default roles, Administrator and Standard User, each come with multiple glob
 
 Administrators can enforce custom global permissions in multiple ways:
 
+- [Creating custom global roles](#custom-globalroles).
 - [Changing the default permissions for new users](#configuring-default-global-permissions).
 - [Configuring global permissions for individual users](#configuring-global-permissions-for-individual-users).
 - [Configuring global permissions for groups](#configuring-global-permissions-for-groups).
@@ -207,7 +208,6 @@ Using this field on [default GlobalRoles](#configuring-default-global-permission
 
 :::
 
-
 ### Configuring Default Global Permissions
 
 If you want to restrict the default permissions for new users, you can remove the `user` permission as default role and then assign multiple individual permissions as default instead. Conversely, you can also add administrative permissions on top of a set of other standard permissions.
@@ -355,13 +355,10 @@ The following table lists the permissions and actions that a `restricted-admin`
 | | Deploy GKE cluster | Yes | Yes | Yes | |
 | | Deploy AKS cluster | Yes | Yes | Yes | |
 
-
 ### Changing Global Administrators to Restricted Admins
 
 In previous version, the docs recommended that all users should be changed over to Restricted Admin if the role was in use. Users are now encouraged to use a custom-built role using the cluster permissions feature, and migrate any current restricted admins to use that approach. 
 
 This can be done through **Security > Users** and moving any Administrator role over to Restricted Administrator.
 
 Signed-in users can change themselves over to the `restricted-admin` if they wish, but they should only do that as the last step, otherwise they won't have the permissions to do so.
-
-