Why Backstage ownership fails without Group and User entities
Ownership in a Backstage catalog only works when spec.owner points at an entity that exists. In many catalogs it holds a free-text team name such as "payments-team" that matches no record in any directory, so the catalog shows an owner but nobody can route an alert, an approval or a deprecation notice to it. The fix is to load Group and User entities from an organizational data source, so each owner reference resolves to a real record that the catalog can follow. The Software Catalog is one of the core built-in features of Backstage, alongside Software Templates and TechDocs, and it treats ownership as a relation between entities, not as a label. A team needs this work once more than one group owns components, or once any other feature (notifications, access rules or review routing) depends on who owns what.
The practical test is simple. Pick ten components at random, read each spec.owner value, and check whether the catalog contains a Group or User entity with that exact reference. Every miss is a component that cannot be routed. Confirm with your own identity provider and any org data plugin you plan to use which group names, identifiers and membership data it exposes, because the reference format you write in descriptors must match what the provider produces. Note also that the catalog only resolves what it has ingested, so a reference can look correct and still fail if the provider has not run or has filtered out the group.
Plan for the people who leave as well as the teams that exist. A component owned by a User who has left the company is an orphan in practice even when the entity still exists, and the catalog will not fix that on its own. Decide before rollout which group receives reassignments, who approves them, and how often you review components whose owner no longer resolves. Treat these checks as recurring work for the platform team, not a one-time migration task, since team structures change every quarter.
How spec.owner, Group and User entities fit together
Ownership in Backstage is a set of references, not a single field. A component's owner points at a Group or User entity, those entities are populated from an organization data source, and the signed-in identity is matched back to the same entities. If any link in that chain resolves to nothing, the owner shown in the portal is wrong or missing.
The owner field on components and systems
The spec.owner value on a Component or System is a plain entity reference, such as a group name. Backstage does not check at registration time that the target exists in the catalog, so a typo or an unmatched name looks valid in the descriptor. Check each owner against the Group or User entities the catalog actually holds, and treat unresolved owners as a defect to fix before teams rely on ownership reports.
Group entities as the unit of accountability
A Group entity represents a team or other organizational unit that owns software. Groups are usually populated from your identity directory, so their names and membership follow HR and directory changes. Confirm which directory attribute becomes the group name, because renaming a team in the directory can silently break every owner reference that pointed at the old name.
User entities and memberOf links
A User entity records a person and lists the groups they belong to through memberOf. These links let the portal show a person's teams and let group-level owners surface in personal views. Membership depends on the directory sync, so confirm how often it runs and what happens to a user's links when the person leaves the organization.
spec.parent for team hierarchy
A Group can declare a parent through spec.parent, which builds the reporting structure from teams up to divisions. Hierarchy affects how group ownership rolls up in views and reports, so an incorrect parent misstates who is accountable for a set of services. Agree the hierarchy with HR or the directory owner first, then verify that each group's parent resolves to an existing group.
Sign-in identity that references the same entities
When a user signs in, Backstage resolves the authenticated identity to a User entity and its group memberships, which then control what that person sees and can edit. The authentication guidance recommends sign-in resolvers that map every provider to the same identity, so a person who signs in through two providers does not appear as two owners. Test resolvers with real accounts from each provider before rollout.
Entities whose owner has left
When an owning group or user is removed from the directory, the entities they owned keep pointing at a name that no longer resolves. Decide in advance who reassigns these entities, usually the parent group, and how quickly orphaned ownership must be cleared. Review unresolved owners on a schedule so accountability does not drift during reorganizations.
Choosing an org data source and hierarchy approach
This table compares the three ways to populate Group and User entities: a built-in org data provider reading from a directory, hand-written YAML checked into Git, and a custom provider for an internal HR or inventory system. Read each row against your own directory and ownership data, then pick the source that already holds the team structure you need to keep current.
| Option | When it fits | What it requires | Who maintains it |
|---|---|---|---|
| Built-in org data provider from a directory | Your identity provider already holds accurate groups, memberships and manager relationships | A directory with group membership and reporting lines, a read-only service account, and a sign-in resolver that matches the same identities | Platform team for the provider config, identity team for directory data quality |
| Hand-written Group and User YAML in Git | Small organizations, or a pilot where the directory is not yet trusted for team structure | Pull request review for every team change, and a named owner for the repository that holds the org files | Platform team, with changes made by team leads through pull requests |
| Custom provider for an HR or inventory system | HR or an internal inventory is the system of record for people, cost centers and team moves | An API or export from the source system, a provider you write and test, and a schedule for sync | Platform engineering for the code, the HR or inventory team for source data |
| Hierarchy via spec.parent | Teams sit inside departments and leaders need roll-ups by business unit | A reliable parent team for each group, agreed naming, and a rule for who approves restructures | Org owners who approve structure changes, platform team for validation |
| Handling users without a directory record | Contractors, service accounts or former staff still referenced by components | A documented process for placeholder ownership and a report of entities pointing at unknown owners | Platform team reviews the report, owning teams reassign entities |
| Change frequency and drift risk | Teams reorganize often and expect the portal to reflect changes within a short period | Confirm the refresh behavior and any webhook or schedule support with your chosen provider before committing | Whoever runs the sync job, reviewed at each restructure |
| Auditability of membership changes | Assessors need evidence of who owned what on a given date | Retained source records or Git history, and a way to trace an ownership change to an approval | Compliance and platform team jointly |
Setting up groups and users from your directory
This sequence connects your identity directory to the Backstage catalog so that every spec.owner value points to a Group or User entity that exists, sits in the right team hierarchy, and matches the identity a person gets at sign-in.
Confirm the directory source and attribute mapping
Identify which directory holds your team and person records (for example, an LDAP-based directory, an identity provider or a Microsoft Graph tenant) and who owns it on your side. List the attributes you will map to the Group and User entities: a stable unique identifier, a display name, the email address, the group membership and the parent group. Ask your identity team to confirm which attribute is stable across renames, because that value becomes the entity name. Done when you have a written mapping reviewed by both the platform team and the identity owner.
Load Group and User entities from the directory
Configure the org data provider for your directory in the Backstage backend and run a first ingestion. Check the catalog for a sample of teams and people, and confirm that each Group has the expected name, display name and members, and that each User has its email and its memberOf groups populated. Compare counts against the source directory for a small pilot team before expanding to the full organization. Done when the sampled Group and User entities match the source records field by field.
Define spec.parent for the team hierarchy
Set spec.parent on each child Group so the catalog reflects your reporting structure, for example a platform department containing several platform teams. Keep the hierarchy to the levels your owners actually use, because deep trees make ownership views harder to read. Confirm that the parent of every child Group exists and that no Group is its own ancestor. Done when the group view in the catalog shows the expected tree and a parent link resolves from each child Group.
Align sign-in resolvers to one user reference
Review each authentication provider's sign-in resolver with your identity owner so that every provider resolves a person to the same User entity reference. The authentication documentation advises this so that one person signing in with different providers does not create duplicate identities that own different entities. Disable guest access for production and test sign-in with at least two providers using the same test account. Done when both sign-ins land on the same User entity and the signed-in identity shows the same group memberships.
Audit spec.owner values on existing entities
Export the owner value of every entity in the catalog and compare each one against the Group and User references you loaded. Sort the results into three lists: owners that resolve, owners that use a legacy or mistyped name, and owners that point to a person who has left or a team that no longer exists. Ask each owning team to confirm the correct reference for their entities before you change any descriptor. Done when every entity is in one of the three lists and the resolving list covers the entities you intended to keep.
Confirm owner links resolve in the catalog UI
Open a sample of entities from different teams in the catalog UI and follow the owner link on each one. The link should open the expected Group or User page, and the Group page should list the entities it owns. Repeat the check for one nested child Group to confirm that the parent relationship appears. Record any owner that does not resolve and route it back to the owning team for correction. Done when the sampled links resolve in both directions and the unresolved list is empty or has an agreed owner for each item.
Modeling team hierarchy with spec.parent
A flat model is the simplest shape: every team is a Group entity with no spec.parent, and each component points to its team through spec.owner. Ownership views then show one level of teams, and a filter on a group returns exactly the components that group owns. This works well when the organization has a small number of teams that do not roll up into larger units, and it is the easiest model to explain to new catalog maintainers.
- Group per team: Each team gets one Group entity with a stable
metadata.name, which becomes the value teams reference inspec.owner. - No parent links: Without
spec.parent, the Groups sit side by side, so a view of the organization shows a list rather than a tree. - Direct membership: Users reach a Group through
spec.memberOfon the User entity, which the org data provider usually fills in. - Limited roll-up: Reports cannot count all components under a department, because no department exists in the model.
- Easy migration path: Adding
spec.parentlater to an existing Group is a change to one descriptor per team, so starting flat does not lock you in.
Before modeling, confirm that your org data provider supplies the team names you plan to use and that those names will still hold after the next reorganization.
Divisions with squads need a hierarchy, and spec.parent provides it. A squad Group names its division Group as parent, and the division can name a higher unit as its own parent. Ownership views can then roll up from squad to division, so a leader of a division sees the components owned by every squad beneath it. The model answers questions such as which division owns a payment service, provided the parent relations are accurate.
- Parent on every nested Group: Each squad sets
spec.parentto its division, and each division to its department, so the tree has no orphaned branches. - Roll-up depends on accuracy: Reports that count components per division are only as correct as the parent links, so assign these from the authoritative HR or directory source.
- Ownership stays on the leaf: Components keep
spec.ownerpointing at the squad, and the division sees them through the hierarchy rather than through a second owner field. - Depth limits: Decide the maximum number of levels before you start, since deep trees are harder to browse and to keep consistent during reorganizations.
- Reorganization events: Moving a squad to another division changes the parent of one Group, but every component under it moves in the views, so confirm that owners still make sense after the move.
Check whether your directory can supply parent relations for every Group, or whether they must be maintained by hand in the catalog.
In a matrixed organization, a person may belong to a functional group such as security and a delivery group such as a product squad at the same time. A User entity can list several groups in spec.memberOf, so the signed-in person sees ownership that reaches through each membership. The decision is what the owner of a component means: a single owning team, or a team that works on the component together with others. The catalog stores the owner as one reference, so the choice has to be made deliberately.
- One owner per component: Keep
spec.ownerto a single Group, usually the team that accepts pages and changes, and record secondary involvement with other means such as annotations or a separate contact field. - Multiple memberships on users: Users can carry several
memberOfentries, which lets a person see the components of each group they belong to in their ownership views. - Membership is not ownership: A person in a functional group does not automatically own the components of a delivery team, so do not model shared responsibility through
memberOf. - Shadow ownership risk: When users sit in many groups, ownership views can show components that a person touches but does not maintain, which inflates counts and confuses escalation.
- Policy before modeling: Agree with the platform, security and delivery leads which group is accountable for each component kind, then encode that rule consistently.
Test a few real users from each functional area against the views before you roll the model out to the whole catalog.
Security and operational considerations for ownership data
Ownership data is only as trustworthy as the identities behind it. The cards below cover where sign-in, directory sync and offboarding can quietly break the link between a person, a team and the entities they own. Each one names a check to run before ownership is relied on for access or accountability.
Guest access undermines user identity
Guest access lets someone use the portal without signing in through your identity provider, so actions cannot be tied to a catalog User. The authentication guidance advises not offering guest access in production. Check that guest sign-in is disabled in every environment that holds real catalog data, and confirm that every page and API call that writes ownership data requires an authenticated identity.
Resolvers that create duplicate users
A sign-in resolver maps an external identity to a catalog User. If two providers, such as GitHub and Okta, produce different user references for the same person, the catalog ends up with two User entities and ownership splits across them. The authentication guidance advises resolvers that make every provider resolve to the same identity. Test each provider with the same person and confirm one User entity results.
Directory sync exposing group membership
Group and membership data pulled from a directory decides who can act for a team in the portal. A broad sync scope or an over-permissioned service account can expose membership of sensitive groups to every signed-in user. Before syncing, confirm which groups and attributes are read, who can read the resulting Group entities, and that the sync account has read-only rights in the directory.
Stale memberships after offboarding
When someone leaves a team or the company, their directory membership should change, but a catalog that only refreshes on a schedule can keep showing them as a member until the next ingestion cycle. Ask how long a removed membership can persist in the catalog, who is alerted when a departed user still owns entities, and whether disabled accounts stop being able to sign in at all.
Who may edit owner references
Changing spec.owner moves accountability for a component, and so affects who gets notified and who can change it next. If any signed-in user can edit a catalog-info.yaml or a catalog entity, ownership can be reassigned without review. Decide which repositories and teams may change owner fields, route those changes through code review, and confirm that the catalog configuration limits who can write to it.
Keys and resolver configuration under change control
Sign-in resolvers and the identity provider settings they depend on are security-relevant configuration, not cosmetic setup. A change to a resolver can silently alter which identity an external login maps to, and so which owner it inherits. Store these settings in version control with review, document each provider's resolver logic, and rerun the duplicate-user check after every upgrade or configuration change.
What to do with entities whose owner has left
When a person leaves the identity directory, the User entity for them may disappear, but the components they owned keep a spec.owner value that now points at a User or Group that no longer resolves to a living member of a team. The decision to make is per entity, not per person: reassign the entity to a new owning group, mark it for review while someone confirms its status, or keep it in place until a successor is named. Reassignment is the right answer when the team still exists and the service still runs. A review marker suits services whose purpose is unclear. Keeping the entity is defensible only for a short, recorded period, because an entity with no accountable owner weakens the catalog as evidence of who runs what.
Set the rules before the first departure. Agree with your identity and HR owners which events trigger a catalog review, for example a removed group membership or a deactivated account, and document who receives the resulting list. Ask your platform team to confirm how the catalog reports owners that no longer resolve, since the exact behavior depends on your org data provider and version of Backstage. Pick the new owner from the team lead or the group that absorbs the work, not from the departing person's former peers by default. Record each reassignment in the descriptor, through a pull request if the catalog is Git-managed, so the change has an author and a reviewer.
Run a recurring review, at a cadence your change management policy sets, that lists entities whose owner is missing, empty or a group with no members. The catalog team prepares the list, the owning department head approves reassignments, and the security or compliance lead signs off on any entity that handles regulated data. Mechanics for detecting and removing orphans, including the orphan annotation and delete strategies, are covered in the separate orphan handling topic, so this routine should cover only the human decisions and approvals.
Limits and what to confirm in your environment
Ownership in Backstage is only as good as the directory behind it. The items below are the facts to confirm with your identity team and against your Backstage version before you commit to a group and user model, because each one changes which owner references are stable.
Group membership attributes
Confirm which attribute in your directory carries group membership for each user, such as a memberOf list, a group claim in the token, or a separate membership query. The org data provider reads a specific attribute, so a directory that stores membership on the group object rather than the user needs a different query. Ask whether membership is maintained by HR feeds, by administrators, or by team owners, because that decides who fixes a wrong owner.
Nested group flattening
Confirm whether your directory has nested groups and whether a platform team, a squad and a guild should all count as owners of the same component. Decide whether a member of a child group should appear as a member of the parent in Backstage, and whether spec.parent hierarchies should mirror the directory or a simpler org chart. Write the answer down, since changing it later re-points many owner references at once.
Deleted and disabled users
Confirm how your directory represents a departed person: removed from the directory, disabled, or kept in a deactivated state. Each of these affects whether a User entity disappears from the catalog and whether the owner reference on their components becomes an orphan. Ask the identity team how long deactivated accounts stay visible and whether a deletion event can reach Backstage without a manual step.
Backstage version and ownership views
Confirm which Backstage release you run and how its catalog and ownership views treat group and user relations, especially for groups with no members or entities owned by a parent group. Upgrades move these views, so test ownership filters after each bump. Use the release page to confirm the version you target before you test.
Directory data without extra permissions
Confirm that the service account used by the org data provider can read groups, memberships and user attributes without broad administrator rights. Some directories hide membership unless the caller has a specific role, and some only expose it through paged or rate-limited queries. Ask the directory owner for read scope limited to the org tree, and test the query with that account before you plan the schedule.
Questions teams ask before assigning catalog ownership
How much effort does assigning ownership in the Backstage catalog take?
The effort depends mostly on how many teams, services and directory sources you have, and how clean the existing owner data is. Work usually splits into three parts: agreeing who owns what, loading Group and User entities from your directory, and correcting the spec.owner values in each descriptor. Teams with a clear service register and one identity directory move faster than teams where ownership lives in spreadsheets or in people's heads. Ask any partner to size the work from a written inventory of your teams, your directory source and the number of entities that need an owner, because those three inputs drive the estimate.
Can our internal team assign catalog ownership without outside help?
Yes, a platform team with access to the directory and the Git repositories holding catalog-info.yaml files can do this work. The hard part is rarely the YAML. It is getting agreement on team boundaries, deciding how sub-teams roll up through spec.parent, and deciding who approves changes to ownership. Internal teams often underestimate the time needed to chase down owners who have changed roles. If your team already runs the Backstage deployment and understands the sign-in resolver configuration, the remaining work is mostly coordination. If not, a partner can handle the modeling while your team keeps control of the data.
What do we need from our directory owners before this work starts?
You need named owners for the identity directory, with the access and time to answer questions about group structure. Before the build, ask them to confirm which groups represent teams, which represent roles or access, how nested groups are modeled, and how user identifiers match across sign-in providers. Ask for read-only credentials to the directory and a test tenant or sandbox where group imports can run without touching production. The sign-in configuration must map every provider to the same identity, as the Backstage authentication documentation advises, so the directory owners should review that mapping too.
How does spec.owner differ from memberOf in Backstage?
spec.owner on a component, system or API names the one Group or User that is accountable for the entity. memberOf on a User lists the Groups that person belongs to. The first answers who to contact about a service, and the second answers which teams a person is part of, which the sign-in identity uses to decide what they see. Ownership on an entity should point to a Group in most cases, so it survives people leaving the company. Keep the two separate in your model and in your review checklist, because mixing them causes entities to show the wrong owner or grant access to the wrong people.
What happens to our catalog entities when a team is renamed?
Renaming a Group entity changes its reference name, so every spec.owner that pointed to the old name stops matching and those entities lose their owner link. Plan renames as a migration: update the Group entity, change every affected spec.owner and any spec.parent references in the same change, and check that no descriptor still uses the old name. Avoid renaming a team's entity name when only its display title changes, since the display title can be edited without touching the reference. Test the change in a non-production catalog first and confirm that the owner view shows the expected components afterward.
What should happen to entities whose owner has left?
Entities owned by a departed person should be reassigned to a Group, not to another individual, so accountability stays with a team. Find these entities by listing spec.owner values that point to Users no longer present in your directory, then route each one to the responsible team lead for reassignment. Entities that stay unowned for long periods become hard to maintain and audit, so set a review step in the offboarding process. Do not delete an entity just because its owner left, because the service may still run. Orphan handling for entities whose source disappears is a separate task covered elsewhere in this guide.
Does assigning ownership help with compliance evidence?
It can, because a catalog with a named accountable Group for each service gives auditors a way to test asset inventory and change responsibility. Auditors do not accept the catalog on its own, though. They will ask whether the owner data is kept current, who approves changes, and how the directory feed is protected. DeployOpen prepares systems, controls and evidence for compliance assessments, but independent auditors and certification bodies issue any report or attestation. Ask your assessor early which ownership records they expect to see, and confirm the retention and change history for those records in your own environment.
How DeployOpen scopes this ownership work
DeployOpen agrees the ownership scope in writing before any configuration starts. For this work, that scope names the directory source that feeds Group and User entities, the team hierarchy expressed through spec.parent, the sign-in resolver rules that map each identity provider to a catalog user, and the entities whose spec.owner values will be checked. Each of these is a separate decision with its own owner on the client side. Deciding who is responsible for the directory export, who approves the hierarchy, and who handles entities whose owners have left is usually harder than the Backstage configuration itself, so those answers belong in the written scope rather than in a later change request.
The work runs inside your own infrastructure. The Backstage instance, its PostgreSQL database, the directory connection and any read-only service credentials stay in your cloud accounts, data centers or air-gapped network, under your access controls. DeployOpen configures the catalog providers and sign-in resolvers in your environment and tests them against a representative slice of your real organization data before rollout. Credentials for the directory are scoped to read access, and you keep the ability to revoke them. Confirm with your identity team which directory attributes are authoritative for team membership and which ones are not maintained, because the answer determines what the catalog can safely show as an owner.
The handover includes written documentation of the owner conventions: the expected format of spec.owner values, how new teams are added to the hierarchy, how sign-in identities resolve to users, and the procedure for reassigning or retiring orphaned entities. Your team keeps that documentation and the configuration it describes, so the conventions can be maintained after the engagement ends. Ask any implementation partner to show you, before signing, the form this documentation takes and who on your side will own it. DeployOpen does not issue audit reports or certifications for the resulting ownership model; if an assessor needs to test it, they will do so independently.
How DeployOpen delivers Backstage ownership
DeployOpen approaches ownership in the Backstage catalog as a scoped piece of work tied to your organization's identity directory and team structure. We plan the group and user model first, then build the data provider, sign-in resolution and orphan handling against it, and hand the result to your team to run.
How we scope
- Written scope lists which identity source supplies Group and User entities and which teams and hierarchies are in it.
- Scope records how spec.owner values map to existing groups, and which entities need an owner decision before work starts.
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before any build begins.
How we build
- We configure the organization data provider, group and user ingestion, and spec.parent team hierarchies in your Backstage instance.
- We set sign-in resolvers so each identity provider resolves to the same catalog user and ownership references match in the signed-in identity.
- We test ownership on sample entities, including a moved team member and a removed owner, before the configuration reaches production.
How we hand over
- Handover includes configuration, a written ownership model and the runbook for orphaned entities and owner changes.
- Your engineers receive a walkthrough of how groups, users and owner references are checked during a review.
- Documentation records the steps to confirm each change in your own environment, so your team can repeat them later.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Retainer work can cover Backstage version bumps that touch the catalog and org data provider configuration.
- Ask any partner to confirm support scope, response expectations and upgrade handling in writing before signing.
