permissions: add new PermissionIntegrationsService #28400

Rugvip · 2025-01-08T11:33:42Z

Hey, I just made a Pull Request!

This adds a new PermissionIntegrationsService that replaces the existing createPermissionIntegrationRouter as well as all extensions points used to add custom rules. It removes the need to manually wire up the integrations router, and also allows for plugin modules to install additional permissions, permission rules, and even resource types.

Naming-wise I've gone with PermissionIntegrationsService for now, but open to other options. Some other ones that I considered:

PermissionsIntegrationService
PermissionRegistrationService
PermissionMetadataService

I figured that keeping "integrations" in there minimizes confusion in the migration from createPermissionIntegrationRouter, and is an alright name for the future too. As for PermissionIntegrationsService vs PermissionsIntegrationService I figured we're dealing with multiple integrations so PermissionIntegrationsService makes more sense, but then again this does look a bit nicer:

permissions: coreServices.permissions,
permissionsIntegration: coreServices.permissionsIntegration,

Thoughts on that? 😁

✔️ Checklist

A changeset describing the change and affected packages. (more info)
Added or updated documentation
Tests for new functionality and regression tests for bug fixes
Screenshots attached (for UI changes)
All your commits have a Signed-off-by line in the message. (more info)

backstage-goalie · 2025-01-08T11:34:16Z

Important

This PR includes changes that affect public-facing API. Please ensure you are adding/updating documentation for new features or behavior.

Changed Packages

Package Name	Package Path	Changeset Bump	Current Version
@backstage/backend-defaults	packages/backend-defaults	patch	`v0.7.0`
@backstage/backend-plugin-api	packages/backend-plugin-api	patch	`v1.1.1`
@backstage/backend-test-utils	packages/backend-test-utils	minor	`v1.2.1`
@backstage/plugin-catalog-backend-module-unprocessed	plugins/catalog-backend-module-unprocessed	patch	`v0.5.4`
@backstage/plugin-catalog-backend	plugins/catalog-backend	minor	`v1.30.0`
@backstage/plugin-catalog-node	plugins/catalog-node	patch	`v1.15.1`
@backstage/plugin-permission-node	plugins/permission-node	patch	`v0.8.7`

CptnFizzbin

Looking forward to using this 🎉

CptnFizzbin · 2025-01-08T15:57:49Z

docs/permissions/custom-rules.md


 1. We will be using the `@backstage/plugin-catalog-node` package as it contains the extension point we need. Run this to add it:

   ```bash title="from your Backstage root directory"
   yarn --cwd packages/backend add @backstage/plugin-catalog-node
   ```

-2. Next create a `catalogPermissionRules.ts` file in the `packages/backend/src/extensions` folder.
+2. Next create a `catalogPermissionRules.ts` file in the `packages/backend/src/modules` folder.


suggestion: since there may be a lot of files related to permissions (and most deployments are likely to have a permission policy), it might be good to encourage grouping things under packages/backend/src/permissions instead of generic 'extensions' or 'modules' folders:

packages/backend/src + permissions + rules // inventory of all custom permission rules for plugins | + catalogPermissionRules.ts | + scaffolderPermissionRules.ts + policy.ts // App specific permission policy file + module.ts // Permission backend module

I'd push back on this, ideally you should be creating a dedicated backend module for this and that's been the recommendation. We also have been using the extensions folder in other places in the documentation so this would be a pattern people are following already for smaller things.

In a perfect world I would have had time to finish this PR #27391 that would create a permissions module for you making the docs and process a lot better!

docs/permissions/custom-rules.md

docs/backend-system/core-services/permissionIntegrations.md

benjdlambert · 2025-01-08T17:17:53Z

I was never a fan of permissions integrations 😅 hot take: is there a reason we can't just group this into the permissions service, is there a lot of value in keeping these things separate?

Otherwise permissionRules, or permissionBindings or something?

Parsifal-M

Looks cool 😄 - Maybe I need to read it again tomorrow when I'm less tired, but in the context of the to-do plugin does this really show the benefits of this feature? Or is it worth adding more examples later on perhaps, I probably just need to read the guides in full instead of just the changes 😅

Edit: Ok I see now 👍

Kudos!

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

docs/backend-system/core-services/permissionIntegrations.md

Rugvip · 2025-01-09T11:16:09Z

@benjdlambert I kinda like permissionsRegistry, as discussed with Freben so gonna try switching to that. I started out by adding to the permissions service, but it's a very different type of usage so I figured it was best to keep separate. There's also a potential dependency issue where it might be useful to have it be possible for the HTTP router service to depend on the permissions service.

vinzscam

this is great! Can we see how catalog-backend-module-unprocessed looks like? Asking because it's a corner case where a module brings new endpoints with extra permissions into the plugin. It would be great to see if the new service fits this use case

Rugvip · 2025-01-09T14:41:52Z

@vinzscam absolutely! f45cb90

vinzscam · 2025-01-09T15:32:09Z

@vinzscam absolutely! f45cb90

🤯

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

…resource type Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

…rvice Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

CptnFizzbin

LGTM, I'll work on updating Scaffolder to use this new service

freben

Aight, just little nits, solid work

...es/backend-defaults/src/entrypoints/permissionsRegistry/permissionsRegistryServiceFactory.ts

packages/backend-plugin-api/src/services/definitions/PermissionsRegistryService.ts

freben · 2025-01-14T16:05:50Z

plugins/permission-node/src/integration/createPermissionIntegrationRouter.ts

-      ].map(i => [i.name, i]),
-    ).values(),
-  );
+): express.Router & {


alright, i guess why not - keeps it compatible

plugins/permission-node/src/integration/createPermissionIntegrationRouter.ts

Co-authored-by: Fredrik Adelöw <freben@gmail.com> Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

github-actions · 2025-01-15T09:18:03Z

Thank you for contributing to Backstage! The changes in this pull request will be part of the 1.36.0 release, scheduled for Tue, 18 Feb 2025.

Rugvip added the area:permission Related to the Permission Project Area label Jan 8, 2025

Rugvip requested review from a team and backstage-service as code owners January 8, 2025 11:33

Rugvip requested review from benjdlambert and vinzscam January 8, 2025 11:33

github-actions bot added documentation Improvements or additions to documentation area:catalog Related to the Catalog Project Area labels Jan 8, 2025

Rugvip force-pushed the rugvip/permission-integrations branch from 7ccf933 to f769700 Compare January 8, 2025 11:38

CptnFizzbin reviewed Jan 8, 2025

View reviewed changes

Parsifal-M reviewed Jan 8, 2025

View reviewed changes

docs/permissions/plugin-authors/03-adding-a-resource-permission-check.md Outdated Show resolved Hide resolved

docs/backend-system/core-services/permissionIntegrations.md Outdated Show resolved Hide resolved

Rugvip force-pushed the rugvip/permission-integrations branch 2 times, most recently from 143010a to 0330bc8 Compare January 9, 2025 11:00

Rugvip force-pushed the rugvip/permission-integrations branch from 0330bc8 to dbed1bd Compare January 9, 2025 11:42

vinzscam reviewed Jan 9, 2025

View reviewed changes

Rugvip added 7 commits January 10, 2025 10:06

permission-node: refactor integration router to be mutable

049d5d4

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

backend-plugin-api: added PermissionsIntegrationsService definition

9ddfd94

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

backend-defaults: implement permissionIntegrations service

a19cb2b

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

permissions: add support for adding permission rules separately from …

45e0c1d

…resource type Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

backend-test-utils: added mocks for permissions integrations service

dd05a97

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

catalog-backend: add support for permission integrations service + test

8805f93

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

catalog-node: deprecate catalogPermissionExtensionPoint

4a941e7

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

Rugvip added 5 commits January 10, 2025 10:06

docs/permissions: update to use new integrations service

521dedd

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

docs/backend-system/core-services: add permissionIntegrations

7fa6441

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

docs/backend/core-services/permissionIntegrations: add migration guide

dfe6e29

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

permissions: rename permissionIntegrations to permissionsRegistry

cf6bd48

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

catalog-backend-module-unprocessed: switch to permissions registry se…

4e073c7

…rvice Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

Rugvip force-pushed the rugvip/permission-integrations branch from f45cb90 to 4e073c7 Compare January 10, 2025 09:06

Rugvip added the merge-after-release This is a bit too scary to merge until after the next release label Jan 10, 2025

Rugvip mentioned this pull request Jan 10, 2025

Draft: Feature(Scaffolder): Update to use Permissions Registry Service #28053

Closed

5 tasks

CptnFizzbin approved these changes Jan 10, 2025

View reviewed changes

freben approved these changes Jan 14, 2025

View reviewed changes

Rugvip and others added 3 commits January 14, 2025 17:33

Apply suggestions from code review

1505fdd

Co-authored-by: Fredrik Adelöw <freben@gmail.com> Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

backend-plugin-api: update entity ref link in permission registry docs

be65d91

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

permission-node: update error message for missing permission rules

088f289

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

Rugvip enabled auto-merge January 15, 2025 08:58

Rugvip merged commit 116cd46 into master Jan 15, 2025
32 checks passed

Rugvip deleted the rugvip/permission-integrations branch January 15, 2025 09:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

permissions: add new PermissionIntegrationsService #28400

permissions: add new PermissionIntegrationsService #28400

Rugvip commented Jan 8, 2025

backstage-goalie bot commented Jan 8, 2025 •

edited

Loading

CptnFizzbin left a comment

CptnFizzbin Jan 8, 2025

awanlin Jan 8, 2025

benjdlambert commented Jan 8, 2025

Parsifal-M left a comment •

edited

Loading

Rugvip commented Jan 9, 2025

vinzscam left a comment

Rugvip commented Jan 9, 2025

vinzscam commented Jan 9, 2025

CptnFizzbin left a comment

freben left a comment

freben Jan 14, 2025

github-actions bot commented Jan 15, 2025

permissions: add new PermissionIntegrationsService #28400

permissions: add new PermissionIntegrationsService #28400

Conversation

Rugvip commented Jan 8, 2025

Hey, I just made a Pull Request!

✔️ Checklist

backstage-goalie bot commented Jan 8, 2025 • edited Loading

Changed Packages

CptnFizzbin left a comment

Choose a reason for hiding this comment

CptnFizzbin Jan 8, 2025

Choose a reason for hiding this comment

awanlin Jan 8, 2025

Choose a reason for hiding this comment

benjdlambert commented Jan 8, 2025

Parsifal-M left a comment • edited Loading

Choose a reason for hiding this comment

Rugvip commented Jan 9, 2025

vinzscam left a comment

Choose a reason for hiding this comment

Rugvip commented Jan 9, 2025

vinzscam commented Jan 9, 2025

CptnFizzbin left a comment

Choose a reason for hiding this comment

freben left a comment

Choose a reason for hiding this comment

freben Jan 14, 2025

Choose a reason for hiding this comment

github-actions bot commented Jan 15, 2025

backstage-goalie bot commented Jan 8, 2025 •

edited

Loading

Parsifal-M left a comment •

edited

Loading