Update Orchestrator plugin permissions

Author: GitHub Actions

modules/orchestrator/proc-managing-orchestrator-plugin-permissions-using-rbac-policies.adoc

@@ -3,48 +3,52 @@
 [id="proc-managing-orchestrator-plugin-permissions-using-rbac-policies_{context}"]
 = Managing Orchestrator plugin permissions using RBAC policies
 
-You can configure Role-Based Access Control (RBAC) policies so that users can view workflow details without the permission to run those workflows. This configuration limits user interaction to explicitly authorized workflows.
+You can configure Role-Based Access Control (RBAC) policies so that users can view workflow details without the permission to run those workflows. This configuration restricts user interaction to authorized workflows.
 
 .Prerequisites
-•  You have identified the specific [`workflowId`] for each workflow you want to restrict.
-•  You have enabled the RBAC plugin and configured the `policies-csv-file` path in your `{my-app-config-file}`.
+. You have identified the [`workflowId`] for each workflow you want to restrict.
+. You have enabled the RBAC plugin.
+. You have configured the `policies-csv-file` path in your `{my-app-config-file}`.
 
 .Procedure
-. Identify the `workflowId` from your workflow definition file as shown in the following example:
+. Identify the `workflowId` from your workflow definition file:
 +
 [source,yaml]
 ----
 id: greeting
 version: '1.0'
 ----
-. Create or update your RBAC policy CSV file to define permissions. Use the format `p, role, permission, action, allow`.
+. In your RBAC policy CSV file, define the permissions using the `p, role, permission, action, allow` format.
 +
 [NOTE]
 ====
-You can grant access using generic permissions, (for example, `orchestrator.workflow`) or specific permissions targeting a `workflowId`, (for example, `orchestrator.workflow.greeting`). Generic permissions take precedence; you cannot grant generic access and then selectively deny a specific ID.
+Generic permissions (for example, `orchestrator.workflow`) take precedence over specific permissions targeting a `workflowId`, (for example, `orchestrator.workflow.greeting`). You cannot grant generic access and then selectively deny a specific ID.
 ====
 
 . Add the following example policies to your CSV file to establish basic user and administrator roles:
 +
-[source,yaml]
+[source,csv]
 ----
 # Minimal user role - can only view and run specific workflows
 p, role:default/workflowUser, orchestrator.workflow.greeting, read, allow
 p, role:default/workflowUser, orchestrator.workflow.use.greeting, update, allow
+
 # Support role - can view all workflows and instances, but not execute
 p, role:default/workflowSupport, orchestrator.workflow, read, allow
 p, role:default/workflowSupport, orchestrator.instanceAdminView, read, allow
+
 # Full admin role - complete access to all Orchestrator functions
 p, role:default/workflowAdmin, orchestrator.workflow, read, allow
 p, role:default/workflowAdmin, orchestrator.workflow.use, update, allow
 p, role:default/workflowAdmin, orchestrator.workflowAdminView, read, allow
 p, role:default/workflowAdmin, orchestrator.instanceAdminView, read, allow
+
 # Assign users to the roles
 g, user:default/example_user, role:default/workflowUser
 ----
-. Enable permissions in your `{my-app-config-file}` file by adding the `orchestrator` plugin to the `rbac` section and set `policyFileReload` to true.
+. In your {product-very-short} `{my-app-config-file}` file, enable permissions by adding the `orchestrator` plugin to the `rbac` section and setting `policyFileReload` to true.
 +
-[source,subs="+attributes,+quotes"]
+[source,yaml,subs="+attributes,+quotes"]
 ----
 permission:
   enabled: true
@@ -61,13 +65,13 @@ permission:
 
 .Verification
 . Log in as a user assigned to the `workflowUser` role.
-. Navigate to the Orchestrator plugin and verify that you can see the workflow in the list.
+. Navigate to the Orchestrator plugin and verify that the workflow appears in the list.
 
 [IMPORTANT]
 ====
-You can view dynamic permissions containing a `workflowId` in the RBAC UI, but you cannot modify them in the interface. Use the policy CSV file or the RBAC API to manage these specific workflow permissions.
+You can view dynamic permissions containing a `workflowId` in the RBAC UI, but you cannot modify them in the interface. You must use the policy CSV file or the RBAC API to manage these specific workflow permissions.
 ====
 
 [role="_additional-resources"]
 .Additional resources
-* For more information on `casbin` rules, see link:https://www.casbin.org/docs/rbac[RBAC documentation].
+* link:https://www.casbin.org/docs/rbac[RBAC documentation].

modules/orchestrator/ref-orchestrator-plugin-permissions.adoc

@@ -4,7 +4,7 @@
 = Orchestrator plugin permissions
 
 The Orchestrator plugin uses the {product} permission mechanism and the Role-Based Access Control (RBAC) plugin to restrict access to backend endpoints.
-Orchestrator supports decoupling visibility (read) from running (update) using specific workflow IDs instead of generic permissions as shown in the following table:
+Orchestrator supports decoupling visibility (read) from running (update) using specific workflow IDs instead of generic permissions.
 
 [cols="20%,15%,15,50%", frame="all", options="header"]
 |===
@@ -13,50 +13,49 @@ Orchestrator supports decoupling visibility (read) from running (update) using s
 |`orchestrator.workflow`
 |named resource
 |read
-|List and read _all_ workflow definitions
+|Lists and reads all workflow definitions.
 
-List and read their instances
+Lists and reads their instances
 
 |`orchestrator.workflow.[workflowId]`
 |named resource
 |read
-|List and read a _single_ workflow definition
+|Lists and reads a specific workflow definition.
 
-List and read instances created for this particular workflow.
+Lists and reads instances created for this particular workflow.
 
 |`orchestrator.workflow.use`
 |named resource
 |update
-|Run or abort _any_ workflow
+|Runs or aborts any workflow.
 
 |`orchestrator.workflow.use.[workflowId]`
 |named resource
 |update
-|Run or abort a _specific_ workflow
+|Runs or aborts a specific workflow.
 
 |`orchestrator.workflowAdminView`
 |named resource
 |read
-|View instance variables and workflow definition editor
+|Views instance variables and the workflow definition editor.
 
 |`orchestrator.instanceAdminView`
 |named resource
 |read
-|View _all_ workflow instances, including those created by other users.
+|Views all workflow instances, including those created by other users.
 |===
 
 [WARNING]
 ====
-Avoid generic permissions for specific control. The system grants access if either a generic permission or a specific one provides it. Granting generic permissions overrides specific denial policies within the same action type as shown:
+Generic permissions override specific denial policies within the same action type. To maintain granular control, avoid granting generic permissions if you intend to restrict specific workflows.
 
 * Granting `orchestrator.workflow` (read) prevents you from denying access to `orchestrator.workflow.[workflowId]` (read).
 * Granting `orchestrator.workflow.use` (update) prevents you from denying access to `orchestrator.workflow.use.[workflowId]` (update).
 ====
 
-The [`workflowId`] must match the unique identifier in your workflow definition file. For example,
-in the workflow definition below, the identifier is `greeting`:
+The [`workflowId`] must match the unique identifier in your workflow definition file. For example, in the workflow definition below, the identifier is `greeting`:
 
-[source,subs="+attributes,+quotes"]
+[source,yaml,subs="+attributes,+quotes"]
 ----
 id: greeting
 version: '1.0'