RHID-3976 Managing authorization by importing external files (#704)

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

@@ -38,17 +38,10 @@ include::assembly-managing-authorizations-by-using-the-rhdh-web-ui.adoc[leveloff
 include::assembly-managing-authorizations-by-using-the-rest-api.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]
@@ -57,9 +50,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]
+

modules/authorization/proc-defining-authorizations-in-external-files-by-using-helm.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.refresh`, 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 map 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 `rbac-policies` config map:
+
+.. 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 `rbac-policies.csv` and `rbac-conditional-policies.yaml` external files:
++
+.`app-config.yml` fragment
+[source,yaml]
+----
+permission:
+  enabled: true
+  rbac:
+    conditionalPoliciesFile: /opt/app-root/src/rbac-conditional-policies.yaml
+    policies-csv-file: /opt/app-root/src/rbac-policies.csv
+    policyFileReload: true
+----

modules/authorization/proc-defining-authorizations-in-external-files-by-using-the-operator.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.refresh`, 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 map 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 `rbac-policies` config map:
++
+.`Backstage` Custom resource fragment
+[source,yaml]
+----
+apiVersion: rhdh.redhat.com/v1alpha1
+kind: Backstage
+spec:
+  application:
+    extraFiles:
+      mountPath: /opt/app-root/src
+      configMaps:
+        - name: rbac-policies
+----
+
+. Update your {product-short} `app-config.yaml` configuration file to use the `rbac-policies.csv` and `rbac-conditional-policies.yaml` external files:
++
+.`app-config.yml` fragment
+[source,yaml]
+----
+permission:
+  enabled: true
+  rbac:
+    conditionalPoliciesFile: /opt/app-root/src/rbac-conditional-policies.yaml
+    policies-csv-file: /opt/app-root/src/rbac-policies.csv
+    policyFileReload: true
+----