feat(rbac)!: improve validation from source (#1643)

* feat(rbac)!: improve validation from source

BREAKING CHANGE: This will lead to more strict validation on the source of permission policies and roles based on the where the first role is defined.

Improves the validation of the different sources of permission policies and roles. Aims to make policy definition more consistent.

Now checks if a permission policy or role with new member matches the originating role's source and prevents any action if the sources do not match. Exception includes the event of adding
new permission policies to the RBAC Admin role defined by the configuration file. Sources include 'REST, 'CSV', 'Configuration', and 'legacy'.

Before updating, ensure that you have attempted to migrate all permission policies and roles to a single source. This can be done by checking source information through the REST API and
by querying the database. Make updates through one of the available avenues: REST API, CSV file, and the database.

To view the originating source for a particular role, query the role-metadata table or use the GET roles endpoint.

* feat(rbac): remove the ability to add permission policies to configuration role

* feat(rbac): remove no longer needed check for source in EnforcerDelegate

* feat(rbac): update yarn lock

* feat(rbac): address review comments

plugins/rbac-backend/README.md

@@ -178,6 +178,8 @@ permission:
 
 For more information on the available permissions within Showcase and RHDH, refer to the [permissions documentation](./docs/permissions.md).
 
+We also have a fairly strict validation for permission policies and roles based on the originating role's source information, refer to the [api documentation](./docs/apis.md).
+
 ### Configuring Database Storage for policies
 
 The RBAC plugin offers the option to store policies in a database. It supports two database storage options:

plugins/rbac-backend/docs/apis.md

@@ -4,12 +4,22 @@
 
 To access the APIs for the RBAC Backend plugin, a user will need to have admin access. Refer to the [README](../README.md#configure-policy-admins) on how to set up admin access.
 
-Each endpoint also requires an Authorization header with the Bearer token that was generated by Backstage. To access this token, traverse to your deployed instance and inspect the web page. Here are two places and example network calls that will have the Bearer token
+Each endpoint also requires an Authorization header with the Bearer token that was generated by Backstage. If not using the RBAC Frontend plugin, then to access this token, traverse to your deployed instance and inspect the web page. Here are two places and example network calls that will have the Bearer token
 
 - From the Homepage, the network call `query?term=`
 
 - From the Catalog, any network call with `entity-facets`
 
+## Source
+
+Each permission policy and role that is created through the RBAC Backend plugin will have a source associated with it. When adding new permission policies and roles, we evaluate the ability to modify them based on the location of the first role that was defined. This means that permissions policies that are associated with a role that was created in the CSV file will also need to be defined in the CSV file.
+
+This strictness helps to keep the integrity and consistency of the data. A permission policy defined in by the REST API with a role in the CSV file can lead to issues in the event that the role was removed from the CSV file. The permission policy would be hanging without a role and would not show up in the RBAC Frontend.
+
+We have four options for source locations: CSV file, Configuration file, REST API, and legacy. The CSV file and REST API are fairly straightforward and involve modifying the role and permissions policies from that particular source only. Configuration file involves the `role:default/rbac_admin` role where the role can only be modified from the `app-config.yaml`. You are unable to add permission policies to the `role:default/rbac_admin` role. This is because we consider this as a default role for starting out. It is encouraged to either use the `superUsers` configuration feature or to craft your own admin role with the permission policies that are required of your admins.
+
+Finally, the legacy source is a source that may appear if your permission policies and roles were defined prior to RBAC Backend plugin `2.1.3`. It is recommended to update these legacy sourced roles and permission polices to a source of REST API or CSV file. This can be done by redefining these permission policies and roles using one of the available options. Remember that future permission policies and members of the role will be based on the first originating role with the new source. Be sure to add the role first through one of the described methods, then proceed to add additional members and permission policies to the roles.
+
 ## Role
 
 ### GET role
@@ -401,6 +411,42 @@ Returns a status code of 204 upon success.
 
 ---
 
+DELETE </api/permission/policies/:kind/:namespace/:name>
+ex. <http://localhost:7007/api/permission/policies/role/default/test>
+
+Deletes a group of permission policies of a specified entity.
+
+Request Parameters:
+
+| Parameter name | Description             | Type   |
+| -------------- | ----------------------- | ------ |
+| kind           | Kind of the entity      | String |
+| namespace      | Namespace of the entity | String |
+| name           | Username of the entity  | String |
+
+body:
+
+```json
+[
+  {
+    "entityReference": "role:default/test",
+    "permission": "catalog-entity",
+    "policy": "delete",
+    "effect": "allow"
+  },
+  {
+    "entityReference": "role:default/test",
+    "permission": "catalog-entity",
+    "policy": "update",
+    "effect": "allow"
+  }
+]
+```
+
+Returns a status code of 204 upon success.
+
+---
+
 ## Plugin
 
 ### GET plugin permission policies

plugins/rbac-backend/docs/permissions.md

@@ -19,6 +19,52 @@ When defining a permission for the RBAC Backend plugin to consume, follow these
 - If the permission does not have a policy associated with it, use the keyword `use` in its place.
   - Example: `p, role:default/test, kubernetes.proxy, use, allow`
 
+## Resource Type vs Basic Named Permissions
+
+There are two types of permissions within Backstage that can be defined using the RBAC Backend plugin. These are resource permissions and basic named permissions. The difference between the two is whether or not a permission has a resource type. Resource type permissions can be defined either using their associated resource type or their name. Basic named permissions must use their name.
+
+Basic name permissions are simple permissions that handle most use cases for plugins. These permissions on require a name and an attribute during creation. While the name and attribute for the basic named permission are required, the actions under the attributes are optional. These actions are what we consider policies within the RBAC Backend plugin.
+
+- Example of the `catalog.location.read` permission and how it would be defined using the RBAC Backend plugin:
+
+  ```ts
+  export const catalogLocationReadPermission = createPermission({
+    name: 'catalog.location.read',
+    attributes: {
+      action: 'read',
+    },
+  });
+  ```
+
+  ```CSV
+  p, role:default/myrole, catalog.location.read, read, allow
+  g, user:default/myuser, role:default/myrole
+  ```
+
+Resource type permissions on the other hand are basic named permissions with a resource type. These permissions are typically associated with conditional permission rules based on that particular resource type. We can define these permissions using either their name or resource type.
+
+- Example of the `catalog.entity.read` permission and two ways that we can define its permissions using the RBAC Backend plugin:
+
+  ```ts
+  export const RESOURCE_TYPE_CATALOG_ENTITY = 'catalog-entity';
+
+  export const catalogEntityReadPermission = createPermission({
+    name: 'catalog.entity.read',
+    attributes: {
+      action: 'read',
+    },
+    resourceType: RESOURCE_TYPE_CATALOG_ENTITY,
+  });
+  ```
+
+  ```CSV
+  p, role:default/myrole, catalog.entity.read, read, allow
+  g, user:default/myuser, role:default/myrole
+
+  p, role:default/another-role, catalog-entity, read, allow
+  g, user:default/another-user, role:default/another-role
+  ```
+
 ## Catalog
 
 | Name                    | Resource Type  | Policy | Description                                             | Requirements            |

plugins/rbac-backend/src/__fixtures__/data/invalid-csv/error-policy.csv

@@ -2,3 +2,9 @@ g, user:default/, role:default/catalog-deleter
 g, user:default/test, role:default/
 p, role:default/, catalog.entity.create, use, allow
 p, role:default/test, catalog.entity.create, delete, temp
+
+p, role:default/rest, catalog-entity, update, allow
+g, user:default/guest, role:default/rest
+
+p, role:default/config, catalog-entity, update, allow
+g, user:default/guest, role:default/config

plugins/rbac-backend/src/__fixtures__/data/valid-csv/rbac-policy.csv

@@ -1,8 +1,10 @@
 g, user:default/guest, role:default/catalog-writer
+g, user:default/guest, role:default/legacy
 g, user:default/guest, role:default/catalog-reader
 g, user:default/guest, role:default/catalog-deleter
 
 p, role:default/catalog-writer, catalog-entity, update, allow
+p, role:default/legacy, catalog-entity, update, allow
 p, role:default/catalog-writer, catalog-entity, read, allow
 p, role:default/catalog-writer, catalog.entity.create, use, allow
 p, role:default/catalog-deleter, catalog-entity, delete, deny