paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 32 Packages Projects Releases Wiki Activity

Update custom permission rule naming and files

Browse Source 
Signed-off-by: stanleyn <stanleyn@spotify.com>
This commit is contained in:
stanleyn
2023-12-15 13:36:41 +00:00
parent 79bff053f1
commit 620b944314
1 changed files with 28 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/permissions/custom-rules.md
+28 -33
View File
@@ -8,9 +8,10 @@ For some use cases, you may want to define custom [rules](./concepts.md#resource
## Define a custom rule
Plugins should export a rule factory that provides type-safety that ensures compatibility with the plugin's backend. The catalog plugin exports `createCatalogPermissionRule` from `@backstage/plugin-catalog-backend/alpha` for this purpose. Note: the `/alpha` path segment is temporary until this API is marked as stable. For this example, we'll define the rule in `packages/backend/src/customPermissionRules/isInSystem.ts`, but you can put it anywhere that's accessible by your `backend` package.
Plugins should export a rule factory that provides type-safety that ensures compatibility with the plugin's backend. The catalog plugin exports `createCatalogPermissionRule` from `@backstage/plugin-catalog-backend/alpha` for this purpose. Note: the `/alpha` path segment is temporary until this API is marked as stable. For this example, we'll define the rule and create a condition in `permissions.ts`.
```typescript title="packages/backend/src/customPermissionRules/isInSystem.ts"
```typescript title="packages/backend/src/plugins/permission.ts"
...
import type { Entity } from '@backstage/catalog-model';
import { createCatalogPermissionRule } from '@backstage/plugin-catalog-backend/alpha';
import { createConditionFactory } from '@backstage/plugin-permission-node';
@@ -40,43 +41,15 @@ export const isInSystemRule = createCatalogPermissionRule({
}),
});
export const isInSystemRuleFactory = createConditionFactory(isInSystemRule);
const isInSystem = createConditionFactory(isInSystemRule);
```
For a more detailed explanation on defining rules, refer to the [documentation for plugin authors](./plugin-authors/03-adding-a-resource-permission-check.md#adding-support-for-conditional-decisions).
## Provide the rule during plugin setup
Now that we have a custom rule defined, we need provide it to the catalog plugin. This step is important because the catalog plugin will use the rule's `toQuery` and `apply` methods while evaluating conditional authorize results. There's no guarantee that the catalog and permission backends are running on the same server, so we must explicitly link the rule to ensure that it's available at runtime.
The api for providing custom rules may differ between plugins, but there should typically be some integration point during the creation of the backend router. For the catalog, this integration point is exposed via `CatalogBuilder.addPermissionRules`.
```typescript title="packages/backend/src/plugins/catalog.ts"
import { CatalogBuilder } from '@backstage/plugin-catalog-backend';
import { isInSystemRule } from '../customPermissionRules/isInSystem';
...
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
const builder = await CatalogBuilder.create(env);
builder.addPermissionRules(isInSystemRule);
...
return router;
}
```
The new rule is now ready for use in a permission policy!
## Use the rule in a policy
Let's bring this all together by extending the example policy from the previous section.
Still in the `permissions.ts` file, let's use the condition we just created in our `TestPermissionPolicy`.
```ts title="packages/backend/src/plugins/permission.ts"
...
/* highlight-add-next-line */
import { isInSystemRuleFactory } from '../customPermissionRules/isInSystem';
class TestPermissionPolicy implements PermissionPolicy {
async handle(
@@ -97,7 +70,7 @@ class TestPermissionPolicy implements PermissionPolicy {
catalogConditions.isEntityOwner({
claims: user?.identity.ownershipEntityRefs ?? []
}),
isInSystemRuleFactory({ systemRef: 'interviewing' }),
isInSystem({ systemRef: 'interviewing' }),
]
}
/* highlight-add-end */
@@ -107,8 +80,30 @@ class TestPermissionPolicy implements PermissionPolicy {
return { result: AuthorizeResult.ALLOW };
}
}
```
## Provide the rule during plugin setup
Now that we have a custom rule defined and added to our policy, we need provide it to the catalog plugin. This step is important because the catalog plugin will use the rule's `toQuery` and `apply` methods while evaluating conditional authorize results. There's no guarantee that the catalog and permission backends are running on the same server, so we must explicitly link the rule to ensure that it's available at runtime.
The api for providing custom rules may differ between plugins, but there should typically be some integration point during the creation of the backend router. For the catalog, this integration point is exposed via `CatalogBuilder.addPermissionRules`.
```typescript title="packages/backend/src/plugins/catalog.ts"
import { CatalogBuilder } from '@backstage/plugin-catalog-backend';
/* highlight-add-next-line */
import { isInSystemRule } from '../customPermissionRules/isInSystem';
...
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
const builder = await CatalogBuilder.create(env);
/* highlight-add-next-line */
builder.addPermissionRules(isInSystemRule);
...
return router;
}
```
The updated policy will allow catalog entity resource permissions if any of the following are true: