Restricting who can register entities in the Backstage catalog starts with knowing who can write
Restricting catalog registration in Backstage is a security and data-integrity question before it is a convenience question. Whoever can register a User, Group or Template can change who appears to own a service, which people the portal treats as members of a team, and which scaffolder templates create new infrastructure. The first decision is to map every path that writes to the catalog: location entries in the app configuration, catalog providers that read from source control or identity directories, the catalog UI's register flow, and the catalog API. Each path has different authors and different controls, and a team that tightens only one of them will usually find the others still open. The Software Catalog is one of the core built-in features of Backstage, so most organizations will keep it, and this page covers only the catalog-side rules and permission-side controls that decide who may write.
Registration needs tighter rules when the portal feeds something that matters outside itself. Typical triggers are a catalog used as evidence for asset inventory or ownership reviews, templates that provision accounts or repositories, or Users and Groups that are imported from an identity directory and then used in access decisions. In those cases, ask who is allowed to add or remove each kind of entity, through which path, and who reviews the change. Write those answers down before changing any configuration. A practical starting point is a short register listing each entity kind, each write path, the team that owns it, and the approval that a change needs. Confirm the exact behavior of each setting against the release you run, because the catalog and permission APIs have changed across Backstage versions and the Backstage authentication documentation covers identity mapping, which affects who ends up as a User.
Which control fits which registration risk
This table compares the four main ways to limit who can add Users, Groups and Templates to the Backstage catalog. Read each row as a separate layer: catalog rules constrain what a location may register, permission policies constrain who may create or delete, read-only mode removes writes altogether, and trusted organization data sources decide where identity data comes from. The main takeaway is that no single control covers every path, so confirm each one against the Backstage version you run.
| Control | What it limits | When it fits | What to confirm before relying on it |
|---|---|---|---|
| Catalog rules per location | Which entity kinds each catalog location may register, such as allowing Components but blocking User or Template entities from a given source | Stopping a repository or provider from pushing kinds it should never own, for example Users from an application repo | Confirm the rule applies to every ingestion path, including entity providers and API-submitted entities, in your version |
| Permission policy for catalog create and delete | Which authenticated users or service principals may create, update or delete catalog entities through the API and UI | Restricting entity writes to a platform team while keeping read access open to all engineers | Confirm the catalog permissions you enable and that your policy denies write actions for ordinary users in your version |
| Read-only mode | Blocks writes to the catalog so entities can only be read, leaving existing data unchanged | Freezing the catalog during an incident, audit or migration window | Confirm which write paths are blocked and whether ingestion from providers still runs in your version |
| Trusted organization data sources | Limits User and Group data to a directory you already govern, such as your identity provider, rather than user-supplied descriptors | Keeping identity records aligned with the source of truth for sign-in and ownership | Confirm the resolver and provider settings map identities to one source, and that guest access is off in production |
| Authentication resolvers | Ensures each sign-in provider resolves to the same catalog identity, so one user cannot create a second identity | Preventing duplicate or spoofed User entities across providers | Confirm resolver configuration for every enabled provider and test with a sample of each sign-in method |
| Template authoring access | Who can publish or change Template entities that scaffold new components | Controlling which templates reach engineers and what actions they run | Confirm how template registration is permissioned and how template sources are locked to approved repositories in your version |
Setting up registration rules in order
This sequence moves a Backstage catalog from open registration to a state where only trusted sources and permitted roles can create Users, Groups, Templates and other entities, with each change confirmed before the next one starts.
Inventory current locations and registration paths
Before changing anything, list every catalog location in app-config, every entity provider, every API or UI path that can create or delete entities, and every sign-in method in use. Record who owns each path and which kinds it can produce. Confirm the list by comparing it against the catalog's current contents, so that any entity source you did not expect shows up now rather than after you tighten the rules. The inventory is done when every path has an owner and a stated purpose.
Decide allowed kinds for each source
For each location or provider on the inventory, decide which entity kinds it may supply. Typically, service repositories should supply Components, APIs and Systems, while only a trusted organization source should supply User and Group entities. Templates should come from a reviewed repository. Write the decision as a table so the catalog rules and the review owner are visible. The step closes when every source has an explicit allow list and nothing is left on a default.
Remove guest access and anonymous registration
Turn off any guest sign-in that is enabled outside a test environment, because the authentication documentation advises against guest access in production. Confirm that unauthenticated requests cannot reach catalog write endpoints. Verify by signing out and attempting a registration request, which should be rejected. Keep a record of the configuration change and the rejected request so the audit trail shows the control was active from this point.
Configure sign-in resolvers for one identity per user
Set a sign-in resolver for each identity provider so that every provider maps a person to the same catalog User entity. If two providers create two identities for one person, a user may gain or lose rights depending on how they signed in. Test by signing in through each provider with the same person and checking that a single User entity is referenced. Done when the resolver output is identical across providers for that test account.
Apply permission policy to catalog create and delete
Write a permission policy that grants catalog entity creation and deletion only to named roles or groups, and denies both to everyone else. Scope the policy to the entity kinds decided earlier. Test with a non-privileged test user: attempt to register a Template or Group through the UI and API, and confirm each request is denied. Then test with a privileged user and confirm the same request succeeds. Record both results.
Enable read-only mode where registration must stop
For environments that should only display the catalog, such as a period of migration or an incident, enable the read-only setting for the catalog so no writes are accepted by any path. Confirm the setting by attempting a write from an authorized account and checking that it fails with the expected error. Check that read operations still work, since teams need to keep finding services during the freeze.
Move Users and Groups to a trusted organization source
Replace hand-written or template-created User and Group entities with an ingestion source that reads from your directory of record, such as your identity provider or HR-backed directory. Restrict the source to read-only access on the directory side and confirm that the catalog rejects User or Group changes from other locations. Verify by changing a group membership in the trusted directory and confirming the catalog reflects it, then trying to edit the same group from a repository file and confirming the edit is refused or overwritten.
Confirm the audit trail for denied and allowed writes
Check that denied and successful catalog writes are recorded with the acting identity, the entity kind and the time. Use the auditor service or the logs available in your deployment, and confirm they reach the system where your security team reviews events. Repeat one denied and one allowed registration and find both records. The sequence is complete when the audit records match the test results from the earlier steps.
How the rules differ for open, federated and locked-down portals
In this model, engineers register their own services, components and APIs, and the portal is the place where ownership is recorded. The aim is to let teams move quickly while keeping the catalog trustworthy enough that other teams can rely on it. Most of the control here comes from restricting which kinds of entities a location may create, so that a service descriptor cannot quietly add a User or Group. Permission policies still matter because they decide who may delete an entity they do not own.
- Allowed kinds per location: Limit each catalog location to the kinds its owners should create, such as Component, API and Resource, and leave User and Group to a separate source.
- Owner-scoped delete: Allow deletion only for entities whose owner matches the requester's group membership, and review the permission policy before enabling it.
- Descriptor review in the repository: Require code review on the files that hold entity descriptors so changes to ownership are visible to a second person.
- Orphan handling: Decide who removes entities whose source disappears, since self-service registration without cleanup creates stale ownership records.
- Self-service guardrails: Publish a short guide on which fields owners must fill in and which values the platform team will reject.
Before opening this model, confirm with your identity team which group claims the portal receives, because owner checks depend on them.
In this model, the platform team controls Users and Groups, which are imported from the identity directory, while application teams still register their own components. The main risk is that a team could create a User or Group entity that claims a membership it does not have, which can then grant it access to ownership or permission decisions that rely on the catalog. Controls focus on making the directory the only source of people and on denying create operations for those kinds to everyone except the ingestion process.
- Directory as the only person source: Configure the directory provider to populate Users and Groups, and deny the create permission for those kinds to application roles.
- Restricted locations for people data: Ensure no general-purpose location is allowed to produce User or Group entities.
- Read access for owners: Keep read access broad so teams can see who owns what, while write access stays with the ingestion process.
- Change control on the directory: Changes to group membership happen in the identity system, so the portal inherits the same review and approval path.
- Testing with a non-production directory: Verify that a test user cannot be created through a descriptor before the rule is relied on.
The trade-off is slower correction: a team that needs a group renamed waits on the directory owner rather than editing a file. Confirm the directory provider's attribute mapping with your identity owners before go-live.
In this model, the catalog is a source of evidence for asset inventory and ownership, and the goal is that its contents reflect what was approved and nothing else. Read-only mode removes write paths from the portal so that records can be inspected without being changed through the interface. Changes then flow through a controlled process such as a reviewed repository or an approved import, and the portal shows the result. This model trades almost all self-service for a stable, reviewable record.
- Read-only mode for the portal: Use the read-only setting so users cannot register or edit entities through the interface, and confirm it applies to the API as well as the UI.
- Controlled import path: Route all changes through a single reviewed pipeline, with the pipeline's own service identity holding write rights.
- Snapshot and retention: Keep dated copies of the catalog so auditors can see what existed at a given time, and confirm the retention period with your compliance lead.
- Access logging: Make sure reads and attempted writes are captured by the audit mechanism you use for the portal.
- Clear ownership of exceptions: Name who may approve an emergency change and how it is recorded afterwards.
Ask the auditor which evidence format they expect before you design the snapshots, because the portal does not produce audit reports on its own.
Security risks when registration is left open
Backstage lets authenticated users add entities to the catalog, and the catalog drives ownership, templates and access decisions. When registration is left open, a single account can distort who owns what, what a template executes and which repositories the portal trusts. The cards below name each risk, the control that closes it and the team that should own that control.
Impersonated owners through User and Group entities
A user who can register a User or Group entity can claim to be a team lead or an owning group. Other teams then see that name on Components, receive notifications for it and may approve changes on its behalf. Control: a permission policy that denies create and update of User and Group kinds to ordinary users, with those kinds populated only by an identity provider ingestion source. Owner: the identity or platform team. Check that no user-facing permission grants catalog.entity.create for these kinds.
Templates that run actions the author should not control
A Template entity describes steps the scaffolder executes on the Backstage host, so registering one is close to registering code. An author who can add a Template may reach actions, secrets or repositories that were never meant for them. Control: restrict Template registration to a reviewed location and a small set of maintainers, and keep scaffolder permissions separate from catalog permissions. Owner: the platform team, with template reviews handled as a change process. Read the template hardening topic for the scaffolder side of this risk.
Locations pointing at untrusted repositories
Anyone able to register a Location can point the catalog at a repository they control, and every entity in it is then ingested as if it were trusted. Entries can also carry misleading metadata that looks like it came from an approved source. Control: catalog rules that allow only the kinds needed for each location type, and an explicit allow list of repository hosts and paths for URL-based locations. Owner: the platform team, with the source control team confirming which organization paths are approved.
Deletion of entities other teams depend on
If users can delete entities, one removal can orphan Components, break dependency links and hide services from search and ownership views. Deletion is often more disruptive than registration because it removes evidence that other teams rely on. Control: a permission policy that limits catalog.entity.delete to the owning team or to platform administrators, combined with a review step before unregistering a location. Owner: the platform team. Confirm how orphaned entities are reported in your environment before relying on that signal.
Sign-in resolvers that trust unverified claims
A sign-in resolver maps a provider identity to a Backstage user. If the resolver accepts a claim the provider has not verified, or if a provider can create a new identity with an arbitrary name, the attacker becomes a catalog user with that identity's access. The authentication documentation advises that every provider resolve to the same identity and that guest access stay out of production. Control: a resolver that matches only verified identifiers against entities already in the catalog. Owner: the identity team, with the platform team reviewing the resolver code.
Limits and what to confirm in your environment
Catalog registration controls depend on configuration keys, permission names, identity attributes and entity providers that change between Backstage releases and deployments. The cards below list the items to verify against the official documentation and in a test environment before you treat any restriction as in force.
Exact keys and permission names
Confirm the configuration keys for catalog rules and the permission names for create and delete against the documentation for the Backstage version you run. Names and defaults can change between releases, so a policy written for one version may silently match nothing on another. Check the permission name for each kind you intend to restrict, and test each one with a user who should be denied.
Identity attributes for resolvers
Find out whether your identity provider sends the attributes your sign-in resolver needs to map a user to a catalog User and Group. If group claims are missing, optional, or only present for some accounts, the resolver may create no membership, or the wrong one. Confirm the claim names with a real test login, not from the provider's documentation alone, and confirm that every provider resolves to the same identity.
External entity providers and permissions
Entity providers that ingest from source control or directories write entities through their own path. Confirm whether permission policy applies to that ingestion, or only to requests made through the catalog API. If it does not, a rule that blocks users from creating Templates may still allow the provider to load them. Test with a provider that is switched on, then check which entities appear and who owns them.
Read-only mode coverage
Confirm whether read-only mode blocks every write path your teams use, including the catalog API, the UI, scaffolder runs and any custom plugin that writes entities. A mode that blocks one path can leave others open. List each write path your organization depends on, then attempt each one in a test environment with the mode enabled and record the result.
Deletion and orphan handling
Confirm how the catalog treats an entity whose source no longer lists it, and whether a user can delete an entity that a provider manages. Orphaned entities can remain visible, keep their ownership, and still appear in reports used as evidence of inventory. Ask whether deletes are permitted for entities from each source, and define who reviews orphans and on what schedule.
Questions teams ask before restricting Backstage catalog registration
How much effort does restricting catalog registration take?
Effort depends mainly on how many registration paths you have, how many locations feed the catalog, and whether you use custom entity kinds. Each path needs an owner, a decision on which kinds it may register, and a permission rule for create and delete. A portal with one Git integration and a short list of kinds is a small change. A portal with several discovery sources, custom kinds and many teams registering their own components takes longer to map and test. Ask any partner to base its quote on a written inventory of locations, kinds and identity sources.
What drives the cost of this work up or down?
The main drivers are the number of catalog locations, the identity provider and how cleanly its groups map to Backstage users, the number of custom entity kinds, and how many templates depend on registration. Costs are one-time for the design, rule setup and testing, and recurring only when you add locations, kinds or teams that need new rules. Ask for the quote to separate design, implementation, testing and handover, and to state which items are included in the fixed scope.
Can our in-house team restrict catalog registration without a partner?
Yes, if your team already runs Backstage and understands its permission framework and catalog configuration. The work needs someone who can read the app configuration, write permission policies, and test them against a non-production portal. It also needs time from whoever administers your identity provider, because group membership drives who can register what. Teams without recent Backstage operating experience often find the testing and rollout steps take the longest, so a partner review of the rules before production can be worth considering.
What do we need to provide before the work starts?
You need administrative access to the identity provider so groups and their membership can be checked, read access to the Backstage configuration and repositories that hold catalog locations, and a non-production Backstage instance that mirrors production sign-in. You also need a named owner for each registration path, such as a platform team for Templates, an HR-driven feed for Users, and a service team for components. Without those owners, nobody can approve which kinds a path may register, and the rules stall.
How long does verification in a staging portal take?
The time depends on scope, so there is no standard duration. It grows with the number of registration paths to test, the number of roles and groups in the permission rules, and whether you test delete and update behavior as well as create. Verification should cover a user who may register, one who may not, and an automated source that tries to register a kind it should not. Ask the partner to show how they will test each path in the written plan.
Will restricting registration break our software templates?
It can, if a template creates an entity kind or writes to a location that the new rules no longer allow. Templates that register components usually keep working when the component kind is allowed for the team's location. Templates that register Users, Groups or other Templates need a deliberate decision. Before enforcing new rules, list every template and the kinds it writes, then confirm with each owner which registrations remain valid. Test the scaffolder in staging with a user from each team.
What happens to entities that already exist in the catalog?
Restricting future registration generally does not remove entities that are already in the catalog, but you should confirm how your version handles existing entities from locations that are no longer allowed. Check which entities came from which location, whether any ingestion sources will remove entities that disappear from a source, and how orphaned entities are reported. Plan a review of existing Users, Groups and Templates against your trusted data sources before enforcing the new rules, and agree on who removes anything that should not be there.
What changes for developers and platform owners after the rules are in place
Once registration is restricted, developers stop adding their own services to the catalog directly. A new service, a template change or a team's ownership record goes through a reviewed path instead, usually a pull request to the catalog repository that the platform team or a named code owner approves before the location is ingested. For a developer who used to register an entity in a few minutes, this is the most visible change, and it should be explained before the rules go live rather than discovered when a registration is rejected. Platform owners take on a different job: they review Users and Groups from the trusted organizational source (the directory or identity provider configured as the only origin for those kinds), not from hand-edited YAML, and they treat the permission policy's decisions on create and delete as the record of who may change the catalog.
The friction is predictable, so plan for it. Expect the first wave of questions about ownership of existing components, about why a Template change takes longer than a service change, and about where an approval request goes. Reduce the delay by publishing a short, written contribution path with named reviewers, a stated service expectation agreed with the platform team, and a template for the descriptor so reviewers check the content instead of reformatting it. Do not solve the delay by adding a broad allow rule for a team or by letting a shared service account register entities for everyone. Confirm with your own change process whether catalog changes must already be recorded as tickets, because that decides how the review evidence is kept.
Audit evidence is the main gain. Each accepted change leaves a commit with an author, a reviewer and a timestamp in the catalog repository, and the ingestion logs show which location produced each entity. Ask your team to confirm how long those repository and log records are retained, who can read them, and whether the audit events your Backstage instance emits can be correlated with them during an investigation. Review the approval path after the first quarter of use: note which reviews were slow, which descriptors were rejected for the same reason, and whether any team is pressing for a faster route. Changes to the rules themselves should go through the same review, so the control stays as strict as it was when it was written.
How DeployOpen scopes and delivers catalog registration controls
DeployOpen approaches registration control as a written, fixed-scope piece of work: which entity kinds each location may register, who may create and delete them, and which sources are trusted for people and groups. The work is planned, built in a non-production environment, tested against both the catalog and the permission policy, and handed over with the configuration and runbook your team needs to keep it in place.
How we scope
- Inventory every location, provider and API path that can currently create Users, Groups or Templates in your Backstage catalog.
- Agree in writing which kinds each source may register, and who approves changes to those rules.
- Define the read-only mode, permission policy and trusted organization data sources that will be in place at handover.
How we build
- Apply catalog rules for allowed kinds per location in a non-production Backstage instance first.
- Write permission policy changes for create and delete, and test denied and allowed requests for each role.
- Check that organization data from your identity directory arrives through the trusted source and not through hand-written descriptors.
How we hand over
- Deliver the configuration, policy code and test cases in your own source control, so changes go through review.
- Document the registration model, the approval path for new kinds and a rollback procedure for each change.
- Walk your platform and security teams through the tests so they can rerun them after future Backstage upgrades.
How we support
- Engagements are fixed-scope, and scope, deliverables and timelines are agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing of the registration controls are available as a retainer.
- Ask for the written scope to name the Backstage version, the identity source and the environments covered before you sign.
