From 6f353445dc4259d9b66215d89978f1b7af56e6a4 Mon Sep 17 00:00:00 2001
From: Vincenzo Scamporlino <vincenzos@spotify.com>
Date: Thu, 13 Apr 2023 20:57:45 +0200
Subject: [PATCH] docs: scaffolder permissions

Signed-off-by: Vincenzo Scamporlino <vincenzos@spotify.com>
---
 ...uthorizing-parameters-steps-and-actions.md | 113 ++++++++++++++++++
 microsite/sidebars.json                       |   1 +
 2 files changed, 114 insertions(+)
 create mode 100644 docs/features/software-templates/authorizing-parameters-steps-and-actions.md

diff --git a/docs/features/software-templates/authorizing-parameters-steps-and-actions.md b/docs/features/software-templates/authorizing-parameters-steps-and-actions.md
new file mode 100644
index 0000000000..874f30b0d5
--- /dev/null
+++ b/docs/features/software-templates/authorizing-parameters-steps-and-actions.md
@@ -0,0 +1,113 @@
+---
+id: authorizing-parameters-steps-and-actions
+title: 'Authorizing parameters, steps and actions'
+description: How to authorize part of a template
+---
+
+The scaffolder plugin integrates with the Backstage [permission framework](../../permissions/overview), which allows you to control access to certain parameters and steps in your templates based on the user executing the template.
+
+### Authorizing parameters and steps
+
+To mark specific parameters or steps as requiring permission, add the backstage:permissions property to the parameter or step with one or more tags. For example:
+
+```yaml
+apiVersion: scaffolder.backstage.io/v1beta3
+kind: Template
+metadata:
+  name: my_custom_template
+  parameters:
+    - title: Provide some simple information
+      properties:
+        title:
+          title: Title
+          type: string
+    - title: Extra information
+      properties:
+        description:
+          title: Description
+          type: string
+      backstage:permissions:
+        tags:
+          - secret
+  steps:
+    - id: step1
+      name: First log
+      action: debug:log
+      input:
+        message: hello
+    - id: step2
+      name: Log message
+      action: debug:log
+      input:
+        message: hello
+      backstage:permissions:
+        tags:
+          - secret
+
+parameters:
+  - title: Simple information
+    properties:
+      input:
+        title: Title
+        type: string
+    backstage:permissions:
+      tags:
+        - secret
+  - title: Simple information
+    properties:
+      description:
+        title: Description
+        type: string
+    backstage:permissions:
+      tags:
+        - secret
+  steps:
+    - id: step1
+      name: Log message
+      action: debug:log
+      input:
+        message: hello
+      backstage:permissions:
+        tags:
+          - secret
+```
+
+In this example, the `description` parameter and the `step2` step are marked with the `secret` tag.
+
+To conditionally authorize parameters and steps based on the user executing the template, [edit your permission policy](../../permissions/writing-a-policy), by targeting `templateParameterReadPermission` and `templateStepReadPermission` permissions, which are provided by the scaffolder plugin. For example:
+
+```ts
+import {
+  templateParameterReadPermission,
+  templateStepReadPermission,
+} from '@backstage/plugin-scaffolder-common/alpha';
+import {
+  createScaffolderTemplateConditionalDecision,
+  scaffolderTemplateConditions,
+} from '@backstage/plugin-scaffolder-backend/alpha';
+
+class ExamplePermissionPolicy implements PermissionPolicy {
+  async handle(
+    request: PolicyQuery,
+    user?: BackstageIdentityResponse,
+  ): Promise<PolicyDecision> {
+    if (
+      isPermission(request.permission, templateParameterReadPermission) ||
+      isPermission(request.permission, templateStepReadPermission)
+    ) {
+      if (user?.identity.userEntityRef === 'user:default/spiderman')
+        return createScaffolderTemplateConditionalDecision(request.permission, {
+          not: scaffolderTemplateConditions.hasTag({ tag: 'secret' }),
+        });
+    }
+
+    return {
+      result: AuthorizeResult.ALLOW,
+    };
+  }
+}
+```
+
+In this example, the user `spiderman` is not authorized to read parameters or steps marked with the `secret` tag.
+
+By combining this feature with restricting the ingestion of templates in the Catalog as recommended in our threat model, you can create a solid system to restrict certain actions.
diff --git a/microsite/sidebars.json b/microsite/sidebars.json
index ec6c68fa94..55e7ca4df9 100644
--- a/microsite/sidebars.json
+++ b/microsite/sidebars.json
@@ -109,6 +109,7 @@
           "features/software-templates/writing-custom-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/testing-scaffolder-alpha",
           "features/software-templates/migrating-from-v1beta2-to-v1beta3"
         ]