backstage-permissions

Backstage permissions

Add real authorization to a Backstage instance: permission definitions, a policy that decides, and backend enforcement points that obey. The UI never enforces anything.

Preconditions

• Repo uses the new backend system (createBackend, backend.add()). Detect first; the legacy backend wiring for permissions is different and unsupported on current lines.
• Frontend generation known (NFS: createApp from @backstage/frontend-defaults, createFrontendPlugin, blueprints, /alpha exports — vs legacy createPlugin, <FlatRoutes>). It changes where UI checks are placed, not whether they matter.
• backstage.json release line known; permission APIs moved (see step 5) and the installed packages are the source of truth, not memory.
• You know which principal the endpoint serves: end users, service-to-service, or both.
• Assume yarn from the repo root unless the repo says otherwise.

Procedure

1. Survey what exists. Grep for permission: in app-config*.yaml, @backstage/plugin-permission-backend and @backstage/plugin-permission-backend-module-allow-all-policy in packages/backend/src/index.ts, and existing PermissionPolicy implementations under packages/backend/src/extensions/. See backstage-repo-discovery.
2. Enable the framework. Set permission.enabled: true in app-config.yaml and register backend.add(import('@backstage/plugin-permission-backend')). With enabled: false the framework short-circuits to ALLOW and your policy is never called — every check you write is dead code until this flag is on.
3. Define permissions in the plugin's -common package, never the backend package — the frontend imports them too. Use createPermission from @backstage/plugin-permission-common: a unique dotted name (<plugin>.<resource>.<action>), attributes: { action: 'create' | 'read' | 'update' | 'delete' }, and export a <plugin>Permissions array so integrators can enumerate them.
4. Choose basic vs resource. A basic permission asks "may this user do X at all" (creation, where no resource exists yet). A resource permission adds resourceType and can be answered per-object. Resource type strings are global across the instance — namespace them.
5. Register with the permissions registry. In the plugin's register/init, take coreServices.permissionsRegistry and call addPermissions([...]). For resource permissions call addResourceType({ resourceRef, permissions, rules, getResources }), where resourceRef comes from createPermissionResourceRef and getResources maps refs to objects (returning undefined for missing ones). This service replaced createPermissionIntegrationRouter; if the repo still uses that function, migrate it. Read the installed @backstage/backend-plugin-api types for the exact shapes before writing.
6. Enforce in every backend route that mutates or exposes protected data. Get credentials with httpAuth.credentials(req, { allow: ['user'] }), then permissions.authorize([{ permission, resourceRef }], { credentials }), and throw NotAllowedError from @backstage/errors on AuthorizeResult.DENY. One check per route, at the top, before any read or write.
7. For lists and paginated reads, use authorizeConditional. On AuthorizeResult.CONDITIONAL, convert the returned conditions into your storage filter with createConditionTransformer(permissionsRegistry.getPermissionRuleset(resourceRef)) and push the filter into the query. Never fetch everything and filter in memory.
8. Write the policy as a backend module. createBackendModule({ pluginId: 'permission', moduleId: 'permission-policy' }), depend on policyExtensionPoint from @backstage/plugin-permission-node/alpha, and call policy.setPolicy(new YourPolicy()) in init. Implement PermissionPolicy.handle(request, user): narrow with isPermission(request.permission, somePermission) for one permission, or isResourcePermission(request.permission, 'catalog-entity') to cover a whole family. Make the catch-all return explicit and deliberate — that single line is your instance's default posture.
9. Return conditional decisions for ownership. For the catalog, use createCatalogConditionalDecision(request.permission, catalogConditions.isEntityOwner({ claims: user?.info.ownershipEntityRefs ?? [] })) — conditions from @backstage/plugin-catalog-backend/alpha, permissions from @backstage/plugin-catalog-common/alpha. Conditional decisions are only valid for resource permissions; returning one for a create-style permission is an error.
10. Add custom rules only when no existing rule fits. createPermissionRule from @backstage/plugin-permission-node with name, description, resourceRef, a zod paramsSchema, apply (in-memory predicate) and toQuery (storage filter). apply and toQuery must express the same predicate or conditional reads and single-resource checks will disagree. Wrap with createConditionFactory for use in policies and register via permissionsRegistry.addPermissionRules in a backend module.
11. Reflect, do not enforce, in the UI. usePermission({ permission, resourceRef }) from @backstage/plugin-permission-react returns { loading, allowed }; use it to disable or hide controls. RequirePermission wraps a route element. On NFS, wrap inside the component supplied to the page extension rather than editing App.tsx routes. Omitting resourceRef for a resource permission yields allowed: false, and results are stale-while-revalidate — never branch on either for security.
12. Remove the allow-all module (@backstage/plugin-permission-backend-module-allow-all-policy) from packages/backend/src/index.ts once a real policy is registered. Two policy providers is a startup failure, and leaving allow-all wins silently in some orders.
13. Test the denied path first. Unit-test the policy by calling handle() directly with a constructed permission and user, asserting DENY and asserting the exact conditions object for conditional cases. Route-test with the backend test utils' permissions mock (mockServices.permissions.mock()) with authorize resolved to DENY and assert HTTP 403 — an allow-only test suite proves nothing.