RHID-3976 Managing authorization by importing external files

Signed-off-by: Fabrice Flore-Thébault <[email protected]>

Author: themr0c

assemblies/assembly-configuring-authorization-in-rhdh.adoc

@@ -11,16 +11,17 @@ Role-Based Access Control (RBAC) is a security concept that controls access to r
 You define roles with specific permissions, and then assign the roles to users and groups.
 
 RBAC on {product-short} is built on top of the Permissions framework, which defines RBAC policies in code.
-Rather than defining policies in code,
-the {product-short} RBAC feature allows you
-to define policies in a declarative fashion using a simple CSV based format.
-You can define the policies by using {product-short} web interface or REST API, rather than editing the CSV directly.
+Rather than defining policies in code, the {product-short} RBAC feature allows you to define policies in a declarative fashion using a simple CSV based format.
+
+You can define the roles and policies:
+
+* By using {product-short} web interface or REST API
+* By editing the policy CSV file.
+* By editing the `app-config.yaml` configuration file.
 
 To apply RBAC in {product-short}:
 
-. The {product-short} administrator sets up the RBAC feature:
-.. Enable the RBAC feature
-.. Configure Policy Administrators
+. The {product-short} administrator enables and gives access to the RBAC feature.
 
 . The {product-short} policy administrator configures your RBAC policies:
 .. Define roles with specific permissions
@@ -33,17 +34,10 @@ include::modules/authorization/proc-enabling-the-rbac-plugin.adoc[leveloffset=+1
 include::assembly-managing-authorizations-by-using-the-rhdh-web-ui.adoc[leveloffset=+1]
 
 
-include::modules/authorization/ref-rbac-permission-policies.adoc[leveloffset=+1]
-
-
-include::modules/authorization/con-rbac-config-permission-policies.adoc[leveloffset=+2]
-
+include::assembly-managing-authorizations-by-using-external-files.adoc[leveloffset=+1]
 
-include::modules/authorization/con-rbac-config-permission-policies-external-file.adoc[leveloffset=+3]
 
-include::modules/authorization/proc-mounting-the-policy-csv-file-using-the-operator.adoc[leveloffset=+4]
-
-include::modules/authorization/proc-mounting-the-policy-csv-file-using-helm.adoc[leveloffset=+4]
+include::modules/authorization/ref-rbac-permission-policies.adoc[leveloffset=+1]
 
 
 include::modules/authorization/con-rbac-conditional-policies-rhdh.adoc[leveloffset=+1]
@@ -52,10 +46,6 @@ include::modules/authorization/con-rbac-conditional-policies-rhdh.adoc[leveloffs
 include::modules/authorization/ref-rbac-conditional-policy-definition.adoc[leveloffset=+2]
 
 
-include::modules/authorization/proc-rbac-config-conditional-policy-file.adoc[leveloffset=+2]
-
-
-
 include::modules/authorization/con-user-stats-rhdh.adoc[leveloffset=+1]
 
 

assemblies/assembly-managing-authorizations-by-using-external-files.adoc

@@ -0,0 +1,10 @@
+[id='managing-authorizations-by-using-external-files']
+= Managing authorizations by using external files
+
+To automate {product} maintenance, you can configure permissions and roles in external files, before starting {product-short}.
+
+
+include::modules/authorization/proc-defining-authorizations-in-external-files-by-using-the-operator.adoc[leveloffset=+1]
+
+include::modules/authorization/proc-defining-authorizations-in-external-files-by-using-helm.adoc[leveloffset=+1]
+

assemblies/assembly-managing-authorizations-by-using-the-rhdh-web-ui.adoc

@@ -1,4 +1,4 @@
-[id='proc-rbac-ui-manage-roles_{context}']
+[id='managing-authorizations-by-using-the-web-ui']
 = Managing role-based access controls (RBAC) using the {product} Web UI
 
 Policy administrators can use the {product-short} web interface (Web UI) to allocate specific roles and permissions to individual users or groups. Allocating roles ensures that access to resources and functionalities is regulated across the {product-short}.

modules/authorization/con-permission-policy-and-role-source.adoc

@@ -0,0 +1,36 @@
+[id='con-permission-policy-and-role-source']
+= Understanding permission policy and role configuration source
+
+You can configure {product} policy and roles by using different sources.
+To maintain data consistency, {product-short} associates each permission policy and role with one unique source.
+You can only use this source to change the resource.
+
+You can manipulate permission policies and roles based on their source:
+
+Configuration file::
+Configure roles and policies in the `app-config.yaml` configuration file, for instance to xref:enabling-and-giving-access-to-rbac[declare your policy administrators].
+
+REST API::
+Configure roles and policies xref:managing-authorizations-by-using-the-seb-ui[by using the {product-short} Web UI] or xref:managing-authorizations-by-using-the-rest-api[by using the REST API].
+
+CSV file::
+Configure roles and policies by using CSV files.
+
+
+Legacy::
+The legacy source applies to policies and roles defined before RBAC backend plugin version `2.1.3`, and is the least restrictive among the source location options.
++
+IMPORTANT: Update the permissions and roles in legacy source to use either REST API or the CSV file sources.
+
+Managing roles and permission policies originating from CSV files and REST API involves straightforward modification based on their initial source information.
+
+The Configuration file pertains to the default `role:default/rbac_admin` role provided by the RBAC plugin.
+The default role has limited permissions to create, read, update, and delete permission policies or roles, and to read catalog entities.
+
+[NOTE]
+====
+In case the default permissions are insufficient for your administrative requirements, you can create a custom admin role with required permission policies.
+====
+
+You can use the `GET` requests to query roles and policies and determine the source information, if required.
+

modules/authorization/con-rbac-config-permission-policies-external-file.adoc

@@ -0,0 +1,105 @@
+[id='defining-authorizations-in-external-files-by-using-helm']
+= Defining authorizations in external files by using Helm
+
+To automate {product} maintenance, you can define permissions and roles in external files, before starting {product-short}.
+You need to prepare your files, upload them to your {ocp-short} project,
+and configure {product-short} to use the external files.
+
+.Prerequisites
+* xref:enabling-and-giving-access-to-rbac[You enabled the RBAC feature].
+
+.Procedure
+. Define your policies in a `rbac-policies.csv` CSV file by using the following format:
+
+.. Define role permissions:
++
+[source,csv,subs="+quotes"]
+----
+p, _<role_entity_reference>_, _<permission>_, _<action>_, _<allow_or_deny>_
+----
+
+_<role_entity_reference>_::
+Role entity reference, such as: `role:default/guest`.
+
+_<permission>_::
+Permission, such as: `bulk.import`, `catalog.entity.read`, or `catalog.entity.refresg`, or permission resource type, such as: `bulk-import` or `catalog-entity`.
++
+See: xref:ref-rbac-permission-policies_{context}[Permission policies reference].
+_<action>_::
+Action type, such as: `use`, `read`, `create`, `update`, `delete`.
+
+_<allow_or_deny>_::
+Access granted: `allow` or `deny`.
+
+.. Assign the role to a group or a user:
++
+[source,csv,subs="+quotes"]
+----
+g, _<group_or_user>_, _<role_entity_reference>_
+----
+
+_<group_or_user>_::
+Group, such as: `user:default/mygroup`, or user, such as: `user:default/myuser`.
++
+.Sample `rbac-policies.csv`
+[source,csv,subs="+quotes"]
+----
+p, role:default/guests, catalog-entity, read, allow
+p, role:default/guests, catalog.entity.create, create, allow
+g, user:default/my-user, role:default/guests
+g, group:default/my-group, role:default/guests
+----
+
+. Define your conditional policies in a `rbac-conditional-policies.yaml` YAML file by using the following format:
++
+[source,yaml,subs="+quotes"]
+----
+result: CONDITIONAL
+roleEntityRef: _<role_entity_reference>_
+pluginId: _<plugin_id>_
+permissionMapping:
+  - read
+  - update
+  - delete
+conditions: _<conditions>_
+----
++
+See: xref:ref-rbac-conditional-policy-definition_{context}[Conditional policies reference].
+
+. Upload your `rbac-policies.csv` and `rbac-conditional-policies.yaml` files to a `rbac-policies` config maps in your {ocp-short} project containing {product-short}.
++
+[source,terminal]
+----
+$ oc create configmap rbac-policies \
+     --from-file=rbac-policies.csv \
+     --from-file=rbac-conditional-policies.yaml
+----
+
+. Update your {product-short} `Backstage` Helm chart to mount in the {product-short} filesystem your files from the config maps:
+
+.. In the {product-short} Helm Chart, go to *Root Schema -> Backstage chart schema -> Backstage parameters -> Backstage container additional volume mounts*.
+
+.. Select *Add Backstage container additional volume mounts* and add the following values:
+
+mountPath:: `opt/app-root/src`
+Name:: `rbac-policies`
+
+.. Add the RBAC policy to the *Backstage container additional volumes* in the {product-short} Helm Chart:
+
+name:: `rbac-policies`
+configMap::
+defaultMode::: `420`
+name::: `rbac-policies`
+
+. Update your {product-short} `app-config.yaml` configuration file to use the external files in {product-short}:
++
+.`app-config.yml` fragment
+[source,yaml]
+----
+permission:
+  enabled: true
+  rbac:
+    conditionalPoliciesFile: ./rbac-conditional-policies.yaml
+    policies-csv-file: ./rbac-policies.csv
+    policyFileReload: true
+----

modules/authorization/con-rbac-config-permission-policies.adoc

@@ -0,0 +1,104 @@
+[id='defining-authorizations-in-external-files-by-using-the-operator']
+= Defining authorizations in external files by using the operator
+
+To automate {product} maintenance, you can define permissions and roles in external files, before starting {product-short}.
+You need to prepare your files, upload them to your {ocp-short} project,
+and configure {product-short} to use the external files.
+
+.Prerequisites
+* xref:enabling-and-giving-access-to-rbac[You enabled the RBAC feature].
+
+.Procedure
+. Define your policies in a `rbac-policies.csv` CSV file by using the following format:
+
+.. Define role permissions:
++
+[source,csv,subs="+quotes"]
+----
+p, _<role_entity_reference>_, _<permission>_, _<action>_, _<allow_or_deny>_
+----
+
+_<role_entity_reference>_::
+Role entity reference, such as: `role:default/guest`.
+
+_<permission>_::
+Permission, such as: `bulk.import`, `catalog.entity.read`, or `catalog.entity.refresg`, or permission resource type, such as: `bulk-import` or `catalog-entity`.
++
+See: xref:ref-rbac-permission-policies_{context}[Permission policies reference].
+_<action>_::
+Action type, such as: `use`, `read`, `create`, `update`, `delete`.
+
+_<allow_or_deny>_::
+Access granted: `allow` or `deny`.
+
+.. Assign the role to a group or a user:
++
+[source,csv,subs="+quotes"]
+----
+g, _<group_or_user>_, _<role_entity_reference>_
+----
+
+_<group_or_user>_::
+Group, such as: `user:default/mygroup`, or user, such as: `user:default/myuser`.
++
+.Sample `rbac-policies.csv`
+[source,csv,subs="+quotes"]
+----
+p, role:default/guests, catalog-entity, read, allow
+p, role:default/guests, catalog.entity.create, create, allow
+g, user:default/my-user, role:default/guests
+g, group:default/my-group, role:default/guests
+----
+
+. Define your conditional policies in a `rbac-conditional-policies.yaml` YAML file by using the following format:
++
+[source,yaml,subs="+quotes"]
+----
+result: CONDITIONAL
+roleEntityRef: _<role_entity_reference>_
+pluginId: _<plugin_id>_
+permissionMapping:
+  - read
+  - update
+  - delete
+conditions: _<conditions>_
+----
++
+See: xref:ref-rbac-conditional-policy-definition_{context}[Conditional policies reference].
+
+. Upload your `rbac-policies.csv` and `rbac-conditional-policies.yaml` files to a `rbac-policies` config maps in your {ocp-short} project containing {product-short}.
++
+[source,terminal]
+----
+$ oc create configmap rbac-policies \
+     --from-file=rbac-policies.csv \
+     --from-file=rbac-conditional-policies.yaml
+----
+
+. Update your {product-short} `Backstage` custom resource to mount in the {product-short} filesystem your files from the config maps:
++
+.`Backstage` Custom resource fragment
+[source,yaml]
+----
+apiVersion: rhdh.redhat.com/v1alpha1
+kind: Backstage
+spec:
+  application:
+    extraFiles:
+      configMaps:
+        - name: rbac-policies
+        - name: rbac-conditional-policies
+----
+
+. Update your {product-short} `app-config.yaml` configuration file to use the external files in {product-short}:
++
+.`app-config.yml` fragment
+[source,yaml]
+----
+permission:
+  enabled: true
+  rbac:
+    conditionalPoliciesFile: ./rbac-conditional-policies.yaml
+    policies-csv-file: ./rbac-policies.csv
+    policyFileReload: true
+----