Merge pull request #14196 from backstage/permissions/docs

Updated permissions documentation to match paramsSchema changes

docs/permissions/custom-rules.md

@@ -14,12 +14,18 @@ Plugins should export a rule factory that provides type-safety that ensures comp
 import type { Entity } from '@backstage/plugin-catalog-model';
 import { createCatalogPermissionRule } from '@backstage/plugin-catalog-backend/alpha';
 import { createConditionFactory } from '@backstage/plugin-permission-node';
+import { z } from 'zod';
 
 export const isInSystemRule = createCatalogPermissionRule({
   name: 'IS_IN_SYSTEM',
   description: 'Checks if an entity is part of the system provided',
   resourceType: 'catalog-entity',
-  apply: (resource: Entity, systemRef: string) => {
+  paramsSchema: z.object({
+    systemRef: z
+      .string()
+      .describe('SystemRef to check the resource is part of'),
+  }),
+  apply: (resource: Entity, { systemRef }) => {
     if (!resource.relations) {
       return false;
     }
@@ -28,7 +34,7 @@ export const isInSystemRule = createCatalogPermissionRule({
       .filter(relation => relation.type === 'partOf')
       .some(relation => relation.targetRef === systemRef);
   },
-  toQuery: (systemRef: string) => ({
+  toQuery: ({ systemRef }) => ({
     key: 'relations.partOf',
     values: [systemRef],
   }),
@@ -85,14 +91,14 @@ class TestPermissionPolicy implements PermissionPolicy {
     if (isResourcePermission(request.permission, 'catalog-entity')) {
       return createCatalogConditionalDecision(
         request.permission,
--       catalogConditions.isEntityOwner(
--         user?.identity.ownershipEntityRefs ?? [],
--       ),
+-       catalogConditions.isEntityOwner({
+-         claims: user?.identity.ownershipEntityRefs ?? [],
+-       }),
 +       {
 +         anyOf: [
-+           catalogConditions.isEntityOwner(
-+             user?.identity.ownershipEntityRefs ?? []
-+           ),
++           catalogConditions.isEntityOwner({
++             claims: user?.identity.ownershipEntityRefs ?? []
++           }),
 +           isInSystem('interviewing')
 +         ]
 +       }

docs/permissions/plugin-authors/03-adding-a-resource-permission-check.md

@@ -84,6 +84,7 @@ Create a new `plugins/todo-list-backend/src/service/rules.ts` file and append th
 ```typescript
 import { makeCreatePermissionRule } from '@backstage/plugin-permission-node';
 import { TODO_LIST_RESOURCE_TYPE } from '@internal/plugin-todo-list-common';
+import { z } from 'zod;
 import { Todo, TodoFilter } from './todos';
 
 export const createTodoListPermissionRule = makeCreatePermissionRule<
@@ -95,10 +96,13 @@ export const isOwner = createTodoListPermissionRule({
   name: 'IS_OWNER',
   description: 'Should allow only if the todo belongs to the user',
   resourceType: TODO_LIST_RESOURCE_TYPE,
-  apply: (resource: Todo, userId: string) => {
+  paramsSchema: z.object({
+    userId: z.string().describe('User ID to match on the resource')
+  })
+  apply: (resource: Todo, { userId }) => {
     return resource.author === userId;
   },
-  toQuery: (userId: string) => {
+  toQuery: ({ userId }) => {
     return {
       property: 'author',
       values: [userId],
@@ -223,7 +227,9 @@ Let's go back to the permission policy's handle function and try to authorize ou
 +   if (isPermission(request.permission, todoListUpdatePermission)) {
 +     return createTodoListConditionalDecision(
 +       request.permission,
-+       todoListConditions.isOwner(user?.identity.userEntityRef),
++       todoListConditions.isOwner({
++         userId: user?.identity.userEntityRef ?? '',
++       }),
 +     );
 +   }
 +

docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data.md

@@ -144,7 +144,9 @@ import {
 +   ) {
       return createTodoListConditionalDecision(
         request.permission,
-        todoListConditions.isOwner(user?.identity.userEntityRef),
+        todoListConditions.isOwner({
+          userId: user?.identity.userEntityRef
+        }),
       );
     }
 ```

docs/permissions/writing-a-policy.md

@@ -70,9 +70,9 @@ Let's change the policy to the following:
 -       };
 +       return createCatalogConditionalDecision(
 +         request.permission,
-+         catalogConditions.isEntityOwner(
-+           user?.identity.ownershipEntityRefs ?? [],
-+         ),
++         catalogConditions.isEntityOwner({
++           claims: user?.identity.ownershipEntityRefs ?? [],
++         }),
 +       );
       }
 
@@ -119,9 +119,9 @@ class TestPermissionPolicy implements PermissionPolicy {
 +   if (isResourcePermission(request.permission, 'catalog-entity')) {
       return createCatalogConditionalDecision(
         request.permission,
-        catalogConditions.isEntityOwner(
-          user?.identity.ownershipEntityRefs ?? [],
-        ),
+        catalogConditions.isEntityOwner({
+          claims: user?.identity.ownershipEntityRefs ?? [],
+        }),
       );
     }