From 9a0c4795b7a9dc5b31e088bec4e3e8b127d6ccb7 Mon Sep 17 00:00:00 2001
From: Frank Kong <frkong@redhat.com>
Date: Wed, 8 May 2024 13:39:52 -0400
Subject: [PATCH] docs(scaffolder-backend): update documentation with new
 scaffolder permissions

Signed-off-by: Frank Kong <frkong@redhat.com>
---
 ...der-tasks-parameters-steps-and-actions.md} | 67 +++++++++++++++++--
 microsite/sidebars.json                       |  2 +-
 2 files changed, 63 insertions(+), 6 deletions(-)
 rename docs/features/software-templates/{authorizing-parameters-steps-and-actions.md => authorizing-scaffolder-tasks-parameters-steps-and-actions.md} (77%)

diff --git a/docs/features/software-templates/authorizing-parameters-steps-and-actions.md b/docs/features/software-templates/authorizing-scaffolder-tasks-parameters-steps-and-actions.md
similarity index 77%
rename from docs/features/software-templates/authorizing-parameters-steps-and-actions.md
rename to docs/features/software-templates/authorizing-scaffolder-tasks-parameters-steps-and-actions.md
index 072f750a14..76bbf39d30 100644
--- a/docs/features/software-templates/authorizing-parameters-steps-and-actions.md
+++ b/docs/features/software-templates/authorizing-scaffolder-tasks-parameters-steps-and-actions.md
@@ -1,10 +1,10 @@
 ---
-id: authorizing-parameters-steps-and-actions
-title: 'Authorizing parameters, steps and actions'
-description: How to authorize part of a template
+id: authorizing-scaffolder-tasks-parameters-steps-and-actions
+title: 'Authorizing scaffolder tasks parameters, steps and actions'
+description: How to authorize part of a template and authorize scaffolder task access
 ---
 
-The scaffolder plugin integrates with the Backstage [permission framework](../../permissions/overview.md), which allows you to control access to certain parameters and steps in your templates based on the user executing the template.
+The scaffolder plugin integrates with the Backstage [permission framework](../../permissions/overview.md), which allows you to control access to certain parameters and steps in your templates based on the user executing the template. It also allows you to control access to scaffolder tasks.
 
 ### Authorizing parameters and steps
 
@@ -174,7 +174,64 @@ class ExamplePermissionPolicy implements PermissionPolicy {
 }
 ```
 
-Although the rules exported by the scaffolder are simple, combining them can help you achieve more complex cases.
+### Authorizing scaffolder tasks
+
+The scaffolder plugin also exposes permissions that can restrict access to tasks, task logs, task creation, and task cancellation. This can be useful if you want to control who has access to the scaffolder.
+
+```ts title="packages/src/backend/plugins/permissions.ts"
+/* highlight-add-start */
+import {
+  taskCancelPermission,
+  taskCreatePermission,
+  taskReadPermission,
+} from '@backstage/plugin-scaffolder-common/alpha';
+/* highlight-add-end */
+
+class ExamplePermissionPolicy implements PermissionPolicy {
+  async handle(
+    request: PolicyQuery,
+    user?: BackstageIdentityResponse,
+  ): Promise<PolicyDecision> {
+    /* highlight-add-start */
+    if (isPermission(request.permission, taskCreatePermission)) {
+      if (user?.identity.userEntityRef === 'user:default/spiderman') {
+        return {
+          result: AuthorizeResult.ALLOW,
+        };
+      }
+    }
+    if (isPermission(request.permission, taskCancelPermission)) {
+      if (user?.identity.userEntityRef === 'user:default/spiderman') {
+        return {
+          result: AuthorizeResult.ALLOW,
+        };
+      }
+    }
+    if (isPermission(request.permission, taskReadPermission)) {
+      if (user?.identity.userEntityRef === 'user:default/spiderman') {
+        return {
+          result: AuthorizeResult.ALLOW,
+        };
+      }
+    }
+    /* highlight-add-end */
+
+    return {
+      result: AuthorizeResult.DENY,
+    };
+  }
+}
+```
+
+In the provided example permission policy, we only grant the `spiderman` user permissions to perform/access the following actions/resources:
+
+- Read all scaffolder tasks and their associated events/logs.
+- Cancel any ongoing scaffolder tasks.
+- Trigger software templates, which effectively creates new scaffolder tasks.
+
+Any other user would be denied access to these actions/resources.
+
+Although the rules exported by the scaffolder are simple, combining them can help you achieve more complex use cases.
 
 ### Authorizing in the New Backend System
 
diff --git a/microsite/sidebars.json b/microsite/sidebars.json
index 6d9ba3a680..f2fc4afdaa 100644
--- a/microsite/sidebars.json
+++ b/microsite/sidebars.json
@@ -129,7 +129,7 @@
           "features/software-templates/writing-tests-for-actions",
           "features/software-templates/writing-custom-field-extensions",
           "features/software-templates/writing-custom-step-layouts",
-          "features/software-templates/authorizing-parameters-steps-and-actions",
+          "features/software-templates/authorizing-scaffolder-tasks-parameters-steps-and-actions",
           "features/software-templates/migrating-to-rjsf-v5",
           "features/software-templates/migrating-from-v1beta2-to-v1beta3"
         ]