Why Backstage needs a real permission policy before rollout
A Backstage portal that holds service ownership, documentation, software templates and possibly Kubernetes views is only as safe as the rule that decides who can act on each of them. This page answers one question: how do you replace the allow-all default with an authorization policy that reflects your teams and data, and how do you prove that policy works before people depend on it. Without that change, any signed-in user can read, modify or trigger almost anything the portal exposes, and the portal becomes a shared surface with no owner-level controls.
Authentication and authorization answer different questions. Authentication establishes who the user is, which is the job of the sign-in providers and the sign-in resolvers that map each provider's identity to a catalog user. Authorization decides whether that identity may perform a specific action on a specific resource. The Backstage permission framework is the mechanism for the second question: plugins ask it whether an action is allowed, and a policy you write answers. Confirm the current policy interface and permission names in the Backstage authentication documentation and the permissions documentation for your Backstage version before designing rules against them.
A team usually needs this work when the portal serves more than one business unit, when catalog entries or TechDocs contain regulated or confidential information, or when a software template performs write actions such as creating repositories or provisioning infrastructure. Illustrative example: a template that creates a repository and a cloud resource should not be runnable by every user who can sign in. Before rollout, list which actions have effects outside Backstage, decide which groups own which entities, and plan test cases that confirm allowed and denied outcomes for each role.
Permission configuration options and when each fits
This table compares the main ways a team can configure Backstage permissions, from the default allow-all behavior to rules based on groups and catalog ownership. Read each row for the situations where the option fits and the trade-off it carries. The main takeaway is that group-based policies combined with accurate catalog ownership cover most production needs, but only if sign-in resolves groups correctly and every policy is tested before rollout.
| Option | When it fits | Trade-off |
|---|---|---|
| Allow-all behavior in non-production only | Sandboxes, local development and evaluation portals that hold no sensitive catalog data | Any signed-in user can read and change everything, so this setting must never carry over into production configuration |
| Custom policy class per deployment | Organizations with specific rules, such as limiting template use or edits to owning teams | Your team writes, tests and maintains policy code, and must recheck it at each Backstage upgrade |
| Policies keyed on individual users | Small portals with a few named administrators or a short list of exceptions | Grants go stale as people change roles, and the list becomes hard to audit as the organization grows |
| Policies keyed on group membership | Most organizations that already manage teams in an identity directory | Depends on groups resolving correctly at sign-in; missing or wrong groups silently deny or grant access |
| Decisions based on catalog ownership | Rules such as owners of a component may edit its entity and its docs | Only as accurate as owner fields in catalog descriptors; unowned entities need an explicit fallback rule |
| Groups for roles, ownership for entities | Larger catalogs where roles are shared across teams but changes must stay with owners | More rules to test, and the two sources can disagree, so precedence must be written down |
| Sign-in resolver mapping to one identity | Any deployment with more than one identity provider or a directory that holds group data | Each provider must resolve to the same user identity, or group-based rules apply to the wrong person |
| Guest access in production | Short-lived demos only, outside any environment that holds real catalog data | Authentication guidance advises against it in production because guest sessions bypass the identity your rules depend on |
Writing policies on users and groups
Once permissions are enabled, every request is decided by the policies you write, so the design of users and groups matters as much as the code. The six decisions below connect group structure, catalog ownership, templates, visibility and unaffiliated users into one access model you can test before rollout.
Mirror the organization in groups
Map policy groups to the teams that actually own services, such as platform, payments or data engineering, rather than to job titles or individual managers. Group membership is resolved at sign-in through your sign-in resolver, so confirm which directory attribute feeds each group and that the names are stable. Renames in the directory will change access in Backstage, so decide who owns that mapping before the first policy goes live.
Decide who edits team entities
Catalog entities carry an owner reference, and a sound default is that only members of the owning group can update or unregister an entity they own, while everyone else gets read access. Write this as a conditional rule on the entity owner rather than a list of named users, so it holds as teams change. Test it with a user from a different team to confirm the edit is denied.
Restrict template execution
Software templates can create repositories, open pull requests and call external systems, so running a template is a higher-risk permission than viewing one. Decide which groups may execute each template, and keep platform-owned templates limited to the platform group. Illustrative example: a sandbox template open to all engineers while a template that provisions production accounts is limited to the cloud team.
Limit Kubernetes and docs visibility
Visibility of workloads and documentation should follow the same team boundaries as catalog edits, otherwise a user who cannot see a service can still read its runbook or pod status. Decide whether a user sees a service's Kubernetes resources only when they belong to the owning team, and confirm that TechDocs and Kubernetes views honor the same catalog read decision.
Fewer broad rules or many narrow ones
Fine-grained rules per entity type and action are precise and easy to audit for sensitive areas, but they multiply quickly and become hard to review and test. A small set of broad rules, such as allow read for all authenticated users and allow write for the owning group, is easier to reason about but may grant more than intended. Most teams start broad, then add narrow rules only where a risk review justifies them.
Handle users in no group
Users who sign in without any group membership need an explicit answer, because a default that allows everything or denies everything will surprise someone. Decide whether unaffiliated users get read-only catalog access or none, and confirm how contractors, service accounts and users removed from the directory are treated. Check this case in your test suite before rollout, since it is the most common gap in first policies.
Setup sequence: enable permissions, resolve groups, then test
This sequence turns Backstage from an allow-all portal into one where catalog access follows group membership from your identity provider. Each step leaves a check you can run before moving to the next, so the policy reaches production only after it has been exercised against representative users.
Confirm the Backstage version and upgrade path
The platform engineering lead checks which Backstage release line the instance runs and whether it is still inside the supported window before changing authorization. Backstage moves all @backstage packages together through yarn backstage-cli versions:bump, and the Backstage Upgrade Helper shows template changes between versions, so plan any version bump as a separate change. Confirm the Node.js version against the two adjacent even-numbered releases the versioning policy supports. Check: the instance builds and starts on the current version, and the team has written down the target version and the upgrade steps it will use.
Enable the permission framework in configuration
Backend engineers turn on the permission framework in the backend configuration and register the permission policy module that will evaluate requests. Until a real policy replaces the default, the instance may still allow everything, so this step should be reviewed as a change to the authorization boundary. Keep guest access off for production, as the authentication documentation advises. Check: the backend starts with the permission module loaded, and a request from a signed-in user reaches the policy layer and is logged as an authorization decision rather than silently allowed.
Resolve group membership at sign-in
Identity engineers configure the sign-in resolver for each identity provider so that group membership from the directory is written into the Backstage user identity. The authentication documentation advises that every provider resolve to the same identity, so a user who signs in with two providers should not end up as two users with different groups. Map directory groups to catalog Group entities with the same names the policy will reference. Check: sign in as a test user from each group, then confirm in the catalog that the user entity lists the expected group memberships and that a user with no group sees none.
Write the initial policy for catalog read and write
The team writes a first policy that covers catalog read and catalog write, the two permissions most teams need to scope first. Keep the initial rules few and readable: for example, members of an owning group can edit entities they own, and everyone signed in can read entities. Decide explicitly what happens to requests the policy does not match, and choose a default deny for anything not covered by a rule. Check: the policy file is in version control, has a named reviewer, and every rule has a comment stating the group or condition it relies on.
Test the policy against representative users
Platform engineers write automated tests that run the policy against sample users and group sets, covering the cases that matter most: an owner editing their own component, a user editing another team's component, a user with no groups, and a user in several groups. The tests should run in CI on every change to the policy or to the group mapping. Include at least one test for each permission the policy handles, so a missing rule fails the build. Check: the test suite passes in CI, and a deliberately broken rule causes a failure that names the case it breaks.
Roll out to a staging instance
The team deploys the same configuration and policy to a staging Backstage with a copy of the identity provider groups, or a representative subset. Testers sign in with accounts from each group and walk through the catalog pages, editing flows and any templates that touch catalog entities. Record every denied action that a real user needs, and decide whether it reflects a missing rule or a group that was never assigned. Check: each tester completes the agreed set of tasks, and every unexpected denial is either fixed in the policy or documented as intended.
Promote the policy to production
Once staging checks pass, the same versioned configuration and policy are promoted to production through the normal change process, with a rollback plan that restores the previous configuration. Watch the authorization decision logs and sign-in events for the first working period, and confirm with the identity team that group membership is resolving for real users. Check: production users in each group can perform their expected actions, denied requests in the logs match the rules that were meant to deny them, and the rollback has been confirmed to work on a non-production copy.
Resolving group membership at sign-in by identity provider
Source control platforms are often the first identity source teams wire up, and their group model is different from a directory. Group membership in these providers usually means organization teams or group memberships, which are not always returned in the sign-in token by default. Your resolver therefore has to either request the right scopes or query the provider for memberships after authentication, then translate those values into Backstage group entity references.
- Team and group names: Decide whether policies key on the team slug, the team display name or a numeric ID, and keep that choice consistent across the catalog.
- Nested structures: Confirm whether nested teams or subgroups flow through to your resolver, since flattening them changes who receives access.
- Scope requests: Check which OAuth scopes the provider needs in order to return membership data, and document them alongside your configuration.
- Personal accounts: Users outside any organization will have no team memberships, so define the default they receive.
- Token refresh: Membership changes made after sign-in only take effect at the next resolution, so note how often users must sign in again.
Confirm each provider's group claim or membership lookup in the official Backstage authentication documentation before writing the resolver.
Enterprise directories usually carry group membership as a claim in the identity token, which makes them the most direct source for policy mapping. The practical work is deciding which identifier the resolver trusts, because directories expose both human-readable names and stable object identifiers, and names can change while identifiers do not. Overage handling also matters when a user belongs to a large number of groups, since some providers omit the list and expect a separate lookup.
- Object identifiers: Map policies to stable group IDs where the provider offers them, and keep a readable name in the catalog for reviewers.
- Group filtering: Limit the groups emitted to the application so unrelated memberships do not widen Backstage access.
- Large memberships: Confirm how the provider signals a truncated group list and whether your resolver must call a directory API.
- Application assignment: Some directories restrict sign-in to assigned users or groups, which can reduce what reaches the resolver.
- Nested groups: Determine whether the directory flattens nested memberships before emitting them.
Confirm the group claim name, identifier format and overage behavior for your tenant in the official Backstage authentication documentation before you test policies against real sign-ins.
Generic OpenID Connect providers are configured by your own identity team, so the group claim name and content are whatever that team chose. Backstage cannot assume a standard name for group membership, which means the resolver must read the claim your provider actually sends. Treat the claim contract as something you define with the identity team and record in writing, since a silent change upstream can remove access for many users at once.
- Claim name: Agree on the claim that carries groups and confirm it appears in the ID token or user info response.
- Claim shape: Check whether groups arrive as a list, a delimited string or nested objects, because the resolver code depends on it.
- Empty claims: Decide what happens when the claim is missing, and do not fall back to broader access.
- Identity mapping: Keep the user entity reference and the group references derived from the same claim source.
- Change control: Ask the identity team to notify you before renaming or restructuring group claims.
Before building the resolver, decode a sample token from a test account and confirm the exact claim structure in the Backstage authentication documentation.
When a deployment offers several providers, each one must produce the same kind of group reference so that a policy written once applies to every sign-in path. Without that discipline, a user who signs in with one provider may receive different permissions than the same person using another. The authentication guidance recommends that all providers resolve to the same identity, so group handling belongs in a shared design rather than in each provider's code.
- Shared reference format: Define one naming convention for group entity references and enforce it in every resolver.
- Single source of truth: Where a person can sign in several ways, decide which provider's groups are authoritative.
- Catalog alignment: Confirm that group entities in the catalog exist under the references your resolvers produce.
- Testing matrix: Test one user per provider against the same policy and record the resulting decisions.
- Guest access: Do not offer guest sign-in in production, since it bypasses this mapping entirely.
Review the sign-in resolver for each provider side by side, and confirm the outcome with the team that owns each identity source.
Security and operational risks to control
Backstage authorization fails quietly when defaults, identity mapping and change control drift apart. The cards below pair each risk with a control you can verify before and after rollout.
Silent allow-all defaults
Until permissions are enabled and a policy is wired in, Backstage does not restrict what signed-in users can read or change, so a portal can look secured while every action is allowed. Confirm in configuration that the permission framework is enabled and that your policy class is the one loaded at startup. Then test with a user who should be denied, not only with an administrator who should be allowed. A portal that loads without errors can still allow everything.
Stale group membership
Permissions that depend on groups are only as current as the group data Backstage holds. When someone changes teams, the old group can keep access until the catalog ingests the change or the next sign-in refreshes it. Decide how group membership is resolved at sign-in, how often the catalog syncs from your directory, and who is accountable when a transfer does not propagate. Test a transfer with a real account before you rely on the policy.
Guest access left enabled
A guest sign-in path lets people reach the portal without an identity that your directory controls, which breaks the link between a permission decision and a named person. The authentication guidance advises against offering guest access in production. Check the sign-in configuration in each environment, and confirm that no development setting was carried into production. Verify that every provider resolves to the same user identity so audit records point to one person.
Unreviewed policy changes
Policy code is access control, so a change that widens permissions should pass the same review as any other change to authorization logic. Store policies in version control, require a second reviewer, and run permission tests in the pipeline before deployment. Ask who can edit the group mapping and the policy file in production, since either change can grant access without touching the policy itself.
Plugins that bypass checks
A third-party or in-house plugin can read catalog data or call backend endpoints without going through the permission checks you wrote for core features. Before installing a plugin, review which backend routes it exposes and whether it calls the permission API. Test each plugin's routes with a denied user, and treat any route that returns data without a check as a blocking defect until it is fixed.
Gaps in audit records
Authorization decisions are only useful as evidence if you can later show who asked for what and what the policy returned. Confirm that your deployment logs sign-in events, denied requests and changes to permission configuration, and that logs are retained and sent to a store your security team can search. Ask your auditors which records they will sample before you decide what to keep.
Testing policies before rollout
What should our test users include before we roll out Backstage permission policies?
Test users should cover every real combination of role and group your organization uses, not just a platform admin and one developer. Include a user from each team that owns catalog entities, a member of each group the policies reference, a user with no group membership, a user who belongs to several groups, and a contractor or guest-style account if one will exist. Resolve each test identity through the same sign-in resolver your production provider uses, so the test reflects how group membership actually arrives at sign-in. Keep the list in version control next to the policy code so reviewers can see which identities were exercised and which were left out.
How do we check that deny cases actually deny?
Write a test for each action you intend to block, and assert the denial explicitly rather than only checking that allowed actions still work. For example, a user outside the owning group should be refused an edit to a catalog entity they do not own, and a user without a read grant should not see a TechDocs page tied to a restricted entity. Deny tests catch the most common failure in this area: a policy that returns allow by default for a case nobody thought about. Also test the boundary, such as a user who holds the right group but a different role, because a rule that checks only one condition often grants more than intended.
How should we test ownership-based rules?
Ownership rules depend on catalog data, so test them with catalog fixtures that include an entity owned by each test team, an entity with no owner, and an entity whose owner reference points at a group that does not exist. Then check that a member of the owning group gets the expected access, a member of another group does not, and orphaned entities fall back to the default you chose. Ownership tests fail quietly when catalog ingestion changes the owner field format, so include at least one test that runs against entities ingested from your real source of truth, not only hand-written YAML. Confirm the exact ownership field and reference format against the Backstage permissions documentation for your release.
How do we review changes to policies before they ship?
Treat policy code like application code: changes go through a pull request, a named security reviewer approves them, and the test suite must pass before merge. Require the author to describe which identities and actions the change affects, and to add or update a deny test for every new allow. Keep a short change log that records why each rule exists and who requested it, because auditors and future maintainers will ask. Where possible, run the new policy in a staging instance with production-like group data for a period before enabling it for everyone, and compare access for a sample of users between the old and new versions.
How do we keep policy tests current through Backstage upgrades?
Pin the policy tests to the same Backstage release line as the rest of the portal, and run them as part of every upgrade branch, since permission API types and plugin permission names can change between releases. Upgrades move all @backstage packages together with the version bump command, and the Backstage Upgrade Helper shows the template changes to review. After each bump, rerun the full identity matrix and confirm that any new plugin permissions added by upgraded or newly installed plugins have an explicit rule, not an implicit default. Schedule a recurring review of the test list whenever groups are renamed or new teams are created in your identity provider.
Can our own team write and test these policies, or do we need a partner?
Your team can write and test policies if it has someone comfortable with TypeScript, the Backstage permissions API, and your identity provider's group model. The work that usually takes longer than expected is mapping which groups and ownership relations your organization really has, agreeing on default deny behavior with security and compliance owners, and building a repeatable test matrix. DeployOpen plans and implements this kind of work as a fixed-scope engagement, with scope, deliverables and timelines agreed in writing before work starts. Ask any provider for a written list of the identities, actions and plugins covered by the tests, and for who maintains the suite after handover.
What does it cost to test permission policies, and what drives the effort?
No supplied figure sets this cost, so the effort depends on your own inputs. The main drivers are the number of groups and roles in your identity provider, how many plugins and entity types need explicit rules, how many ownership relationships exist, and whether tests run in CI against real catalog data or only against fixtures. Test setup is largely one-time work, while the matrix grows as teams and plugins are added and must be maintained through each upgrade. When requesting a quote, ask the provider to break effort into policy design, test authoring, CI integration, staging validation and ongoing maintenance, so you can see what recurs.
Limits to confirm in your environment
Permission policies are only as reliable as the plugins, identity data and release process beneath them. The four checks below cover what each layer can and cannot enforce in your installed version, so you know where policies will hold and where they will not before you roll them out.
Plugin permission support
Not every plugin checks permissions on every endpoint, and coverage differs between built-in and community plugins. For each plugin your teams use, confirm in the installed version which actions are authorized and which routes are still open to any signed-in user. Treat an unchecked route as unprotected until you have tested it with a non-admin account. Record the results in a coverage list you can revisit at each upgrade.
Group data from your identity provider
Policies that target groups need group membership to arrive at sign-in. Confirm that your identity provider sends the group claims or directory data Backstage needs, including nested groups, and that group names are stable identifiers rather than display names. Ask whether membership changes take effect at the next sign-in or only after a token refresh, since that sets how quickly a removed engineer loses access.
Sign-in resolver behavior
The resolver decides which catalog user and group memberships a session carries. If it maps groups incorrectly or falls back to a guest identity, a policy can grant access to the wrong people without any error. Use one identity for each person across providers, and confirm in a test environment that a sample user receives exactly the groups you expect. Keep guest access off for production.
Release cadence and policy drift
Backstage ships a main release line monthly and a next line weekly, so permission APIs and plugin behavior can change between your upgrades. Confirm which release line your team tracks, who reviews release notes for permission changes, and how often you re-run your policy test suite. A policy that passed on one release can behave differently after a bump, so the test suite should run as part of every upgrade.
Catalog ownership data quality
Group-based policies are only as accurate as the owner fields on catalog entities. Review a sample of components and check that each spec.owner points to a real group, that stale or departed owners are flagged, and that systems without an owner are listed rather than left open to everyone. Ask who maintains ownership data and how changes in your directory reach the catalog, because this data often lags behind org changes.
How long does Backstage permission setup take and what does it cost?
Is there a fixed price for setting up Backstage permissions?
DeployOpen does not publish a price list. Each engagement is quoted from a written scope, and most are fixed-scope, so the price follows from the groups, policies, plugins and test coverage agreed before work starts. Backstage itself is open source under the Apache License 2.0 with no paid edition from the project, so the cost is the people and environments needed to do the work, not a license fee for the framework. Ask for the quote to list each component separately so you can see what is one-time and what recurs.
What drives the effort of a Backstage permission project?
The main drivers are the number of groups and roles you need to express, how complex your identity provider setup is, how many policies you must write and maintain, how many plugins need permission rules, and how deeply you test before rollout. Each of these multiplies the others: a large group structure with several plugins and nested team ownership takes far more policy design and test cases than a flat model covering only the catalog. Ask the provider to break the effort down along these five lines.
How does the identity provider affect the cost of permission setup?
A single, well-understood provider with clean group data is the simplest case. Complexity grows when group membership lives in more than one directory, when group names differ between the provider and the catalog, or when sign-in resolvers must map every provider to the same identity. The authentication documentation advises that all providers resolve to the same identity, so this mapping work is real effort. Confirm early which directories hold group membership and who controls them.
Can our own team set up Backstage permissions without a partner?
Yes, a team with Backstage and identity experience can do it in-house. The work is policy design, TypeScript configuration, group resolution at sign-in and test writing, which needs engineers who understand both the portal and your directory. Teams without that combination often find the group mapping and test depth take longer than expected. A partner is most useful when you want the design reviewed, the tests written to a scope you can audit, or capacity to run the rollout alongside your normal work.
What do we need to provide during a permission engagement?
Expect to provide identity administrators who can explain and export group membership, catalog owners who confirm which teams own which entities, and a staging Backstage instance that matches production sign-in. Access to the identity provider's test users and a named decision-maker for policy disputes also shorten the work. Without a staging instance, policies cannot be tested safely before rollout, so ask whether staging is in scope or must be supplied by you.
What recurs after permissions go live?
Policy maintenance recurs. New teams, renamed groups, new plugins and new catalog entity types all require policy changes and test updates. Backstage upgrades also recur: the versioning policy ships a main release monthly and a next release weekly, and high and critical vulnerabilities are backported to releases from the last six months where feasible. Each upgrade can change permission APIs or plugin behavior, so test coverage must be rerun. Ask whether support and upgrade work is included or sold as a separate retainer.
What should we ask for in a fixed-scope quote for Backstage permissions?
Ask for the list of groups and roles in scope, the named plugins and entity types covered by policies, the identity providers and resolvers involved, the number of test cases and the test levels, the staging environment and who provides it, the rollout steps and rollback plan, and the handover documents. Also ask which items are one-time and which recurs, what is excluded, and how changes found during testing are priced. A written scope with these items lets you compare providers on the same basis.
What does a test depth decision cost us?
Test depth is a direct cost lever. Basic tests cover the most common allow and deny decisions for catalog reads and writes. Deeper tests cover group inheritance, ownership edge cases, scaffolder actions and plugin-specific rules, and they need realistic catalog data. Illustrative example: a policy that allows only owners to edit a service needs tests for the owner, a member of a parent group, a user from another team and an unauthenticated caller. Each added case adds effort, so agree the test list in the scope before work begins.
How DeployOpen scopes and delivers Backstage permissions
DeployOpen scopes Backstage permissions as a fixed-scope engagement. Before any code changes, the policy model, the identity mapping and the test plan are agreed in writing, so the written scope states which plugins and permissions are covered, which groups and roles exist in your identity provider, which sign-in resolver maps users to catalog entities, and what the acceptance tests prove. Deliverables and timelines follow from that document, and a quote follows from the same written scope. Ask for the scope to name the permission policy module, the test suites and the environments that must pass before rollout, so disagreements are settled before the build rather than during it.
Delivery happens inside your infrastructure. The Backstage instance, its PostgreSQL databases, the permission policy code and the test harness run in the cloud accounts, data centers or air-gapped network you already operate, and the policy changes move through your own source control and deployment pipeline. Confirm with DeployOpen which access it needs during the build, how credentials are issued and revoked, and who on your side approves changes to the policy file. DeployOpen prepares the evidence of how access was designed and tested, but it does not issue audit reports or certifications; independent auditors and certification bodies make that determination.
Permissions change after launch as teams, groups and plugins change, and Backstage releases move quickly. DeployOpen offers retainers for upgrades, continuing policy review and regression testing against new plugin versions, which suit organizations that want the same team to keep the policy aligned with the identity model. Ask whether a retainer covers reviews of new group structures, changes to the sign-in resolver and re-runs of the permission test suite after each Backstage upgrade. A one-time build and an ongoing retainer carry different cost components, so ask for each to be quoted separately.
