How Backstage gets Entra ID users and groups into the catalog
A platform team often finds that catalog owners do not match the directory: a service lists an owner who left the company, or a team group in Entra ID has no counterpart in Backstage. The supported method for closing that gap is the Microsoft Graph org data ingestion in the Backstage catalog backend, which is separate from sign-in. Ingestion reads users and groups from your tenant and writes them to the catalog as User and Group entities with membership relations, so ownership fields point at people and teams that exist in the directory. Ingestion does not authenticate anyone. A user can appear in the catalog without ever being able to log in, and sign-in is configured through a different provider and resolver chain. Backstage is an open source framework released under the Apache License 2.0, and the project does not offer a paid edition. The Microsoft Graph ingestion module is part of that same codebase, so the cost of the feature is the engineering time to configure, operate and maintain it. Your team, or a partner you engage, owns the app registration in Entra ID, the permission grants, the filters that decide which users and groups enter the catalog, and the schedule that keeps them current. Confirm the current module name, its configuration keys and the Graph permissions it requires against the Backstage documentation for your release line, since these details change between versions. Before you enable anything, decide which population belongs in the catalog. Filters on users and groups determine whether guest accounts, disabled accounts or every security group in the tenant get imported, and a broad filter can flood the catalog with entities nobody owns. Write down the group types that represent teams and the attributes that feed ownership, then test the filters against a copy of the tenant or a subset of groups. Treat the result as the input for your sign-in resolver design as well, because a user who is in the catalog but resolves to a different identity at login will create the ownership mismatch you set out to fix.
What you need in Entra ID and in your Backstage repository before ingesting
Entra ID ingestion depends on three things set up before any configuration: an app registration with the right Microsoft Graph permissions, credentials stored where the backend can read them, and a Backstage version that supports the plugin you plan to use. Each card below is a decision or check to settle before you touch the catalog.
App registration in Entra ID
Create a dedicated app registration in the tenant that holds your people and groups, and do not reuse the app used for sign-in. Keeping the two apart lets you rotate, scope and audit the directory reader without touching how staff log in. Record the tenant ID and the application (client) ID, and confirm with your Entra administrators which tenant is the system of record if you operate more than one.
Microsoft Graph application permissions
The ingestion needs read access to users, groups and user photos through application permissions, not delegated ones, because the backend runs without a signed-in person. Request only the read permissions for users, groups and photos, then confirm the exact permission names against the current Microsoft Graph documentation and the Backstage plugin documentation for your version, since names change over time.
Admin consent for the tenant
Application permissions take effect only after a Global Administrator or a Privileged Role Administrator grants admin consent in the Entra admin center. Agree the consent request in writing with the tenant owner before the ingestion work starts, because the grant is the step most often delayed. Keep the consent record with your change documentation.
Client secret or certificate storage
The tenant ID and client credentials should live in your secret store and reach the backend as environment variables or mounted secrets, never in the catalog repository or app-config committed to Git. Decide who can read the secret, how often it rotates and what happens when it expires, because an expired secret stops ingestion silently until someone notices stale users.
Outbound access from the backend to Microsoft Graph
The Backstage backend must reach Microsoft Graph and the Entra login endpoints over HTTPS through any egress proxy, firewall or DNS policy you run. Confirm the hostnames and ports with your network team and test them from the same runtime that hosts the backend, not from a laptop, because container and cluster egress rules often differ.
Backstage version and plugin package versions
Pick the plugin package versions that match your Backstage release, and move them together with the rest of the @backstage packages. The versioning policy supports two adjacent even-numbered Node.js releases, which are Node.js 22 and 24 as of Backstage 1.46.0, so check your runtime against that line. Confirm the package names and versions in the Backstage release notes for the release you run before you install anything.
Configure Entra ID ingestion in the Backstage catalog
This sequence connects Backstage to Microsoft Entra ID through Microsoft Graph so that users and groups load into the Software Catalog as entities that match the tenant. Each step ends with a check that the data arrived as intended before you move on.
Install the Microsoft Graph org data module
The platform engineer who owns the Backstage backend adds the Microsoft Graph org data catalog module to the backend package, then rebuilds and restarts the backend so the module loads. Confirm the package version matches the Backstage release line your instance runs, since the @backstage packages are meant to move together. Check that the backend starts without module resolution errors and that the catalog logs show the Microsoft Graph provider registering at startup. Do not proceed until the backend boots cleanly with the module present.
Register the Entra ID app and grant permissions
A directory administrator registers an application in the Entra ID tenant, creates a client secret or certificate, and grants the application permissions that the Microsoft Graph org data module documents for reading users and groups. Ask your identity team to confirm the exact permission names against the current module documentation rather than copying them from older examples, and have an administrator grant admin consent. Check the grant in the Entra ID portal, showing consent status for every listed permission. The app should have read-only access to directory data and no sign-in configuration attached to it.
Add the provider block to app-config
The Backstage administrator adds a Microsoft Graph provider block under the catalog providers section of the app configuration, setting the tenant identifier, client identifier and a reference to the client secret. Store the secret in an environment variable or your secrets manager and reference it by name, never as a literal value in the committed file. Check that the configuration validates when the backend starts and that the provider reports a successful connection to Microsoft Graph in the logs. A misspelled key or an unset variable should fail here, so resolve those errors before adding filters.
Set user and group query filters
The administrator sets user and group filters in the provider block so only the intended population enters the catalog, for example limiting users to enabled accounts in a defined set of groups or departments. Filters are written against the attributes Microsoft Graph exposes, so confirm the query syntax and attribute names in the module documentation and test them in Graph Explorer with the same account before use. Check the filter by counting the users it returns in Entra ID and comparing that count with the number of User entities after the first sync. Mismatches usually point to a filter that is broader or narrower than the intent.
Configure photo loading if needed
If profile photos should appear on user cards, the administrator enables photo loading in the provider configuration and confirms that the app registration has the permission needed to read profile photos. Photos add a Graph request per user, so ask the owner of the tenant whether that load and the stored image data are acceptable before enabling it for a large population. Check one known user after the sync: the User entity should show the photo, and the backend logs should show no repeated photo fetch failures. Leave this step off if photos are not required.
Choose the ingestion schedule
The administrator sets the schedule for the provider, including how often a full read runs and how long a run may take before it times out. Choose an interval that matches how quickly joiners, leavers and group changes must appear in the portal, and ask the identity team how often the directory changes. Check the schedule in the scheduler configuration and confirm the next run time in the backend logs. Avoid setting a very short interval until the first full sync has completed and its duration is known.
Run the first full sync and verify membership
The administrator triggers the first full ingestion, either by waiting for the schedule or by running the provider manually, and watches the backend logs until the run reports completion. Then open the catalog and confirm that User and Group entities appear with the expected names and relationships. For a test group, compare its member list in Entra ID with the members shown on the Backstage Group entity and the user entities linked to it. Membership that matches on the test group and the filtered user count is the sign that ingestion is correct. Record the test group and the result so the check can be repeated after each configuration change.
How full and incremental ingestion differ for large tenants
A full read asks Microsoft Graph for every user and group that matches your filters on each run, then reconciles the result against what the catalog already holds. Delta-style incremental ingestion instead asks Graph only for objects that changed since the last successful read, using change tracking that the provider and Graph must both support. The difference matters most in large tenants, where a full read on every schedule can take long enough to overlap the next run and load the Graph API heavily. Before you design the schedule, confirm in the current Backstage documentation for the Microsoft Entra ID org data provider whether incremental mode is supported, which release introduced it, and what it requires, such as specific Graph permissions, a stored cursor, or a particular provider configuration. Do not assume the behavior from the LDAP or Okta providers, which work differently.
Filters and scheduling are the two levers you control whatever the mode. Narrow user and group filters reduce the object count before ingestion starts, which is usually a larger saving than tuning the interval. Work with your Entra ID administrators to agree which groups are catalog-relevant, such as those that own services or teams, and exclude guest, service and disabled accounts if your filter design allows it. Set the schedule so that a run finishes well before the next one starts, and test the duration in a non-production tenant copy or a filtered pilot before you commit to an interval. Record the run time, object counts and any Graph throttling responses so you can justify the schedule to your identity team.
Removal behavior needs an explicit decision. When a user or group leaves the filter scope or is deleted in Entra ID, the Backstage catalog only reflects that change if the provider's reconciliation marks the entity as removed and the catalog processes the removal. Confirm how the provider handles orphaned users and groups, how long they remain visible, and whether ownership references on services and teams are cleared or left dangling. Plan for a review of entities that lose their owner, because an offboarded engineer can still appear as the owner of a component until someone reassigns it. Test one deliberate removal in a pilot tenant and verify the catalog state before relying on the schedule in production.
How Entra ID attributes map to Backstage user and group entities
This table compares each Microsoft Entra ID attribute the org data import reads with the Backstage User or Group field it fills and the relation it drives. Read the last column first: values that feed ownership references or sign-in resolution must match exactly on both sides, or catalog owners will not resolve to the signed-in identity.
| Entra ID field | Backstage entity and field | Role in the catalog | Match or check before go-live |
|---|---|---|---|
| userPrincipalName | User, metadata.name (after normalization) | Default user reference used in owner fields | Confirm the sign-in resolver maps to the same value so owners and signed-in users are one identity |
| User, spec.profile.email | Contact and notification address shown on the user page | Check for shared or missing mailboxes; blank values leave the profile incomplete | |
| displayName | User, spec.profile.displayName | Name shown in catalog lists and ownership views | Consistent naming in the tenant avoids duplicate-looking entries |
| jobTitle | User, spec.profile.jobTitle (optional) | Context on the user profile page | Often empty in large tenants; treat as informational only |
| manager | User, spec.memberOf or manager relation | Reporting line used for group and team hierarchy | Only as reliable as the directory data; confirm the import reads it in your version |
| photo | User, spec.profile.picture via Graph photo endpoint | Avatar on the user profile | Requires the photo read permission; consider the size and load cost on large tenants |
| displayName (group) | Group, metadata.name and spec.profile.displayName | Team name used as a group owner reference | Group names are converted to safe identifiers, so check for collisions after conversion |
| Group membership (members) | Group, spec.members and User spec.memberOf | Drives team ownership of components and access to catalog entries | Membership filters decide which users and groups appear; unmatched members are skipped |
| Group ID (objectId) | Not a default catalog field | Stable reference for matching across renames | Confirm your import configuration before relying on it as a key |
Securing the Entra ID connection and the data it brings in
The Entra ID connection to Microsoft Graph runs as an application, not as a signed-in user, so the permissions granted to that application define everything it can read. Start from the smallest set of application permissions that the catalog ingestion needs, then have a directory administrator review and grant admin consent in writing. Treat each added permission as a decision that someone must be able to justify later, because the catalog team will be tempted to request broader read access to solve a single missing field.
- Request only what ingestion reads: list the user and group properties the catalog will map, and confirm that each one maps to a permission before adding it.
- Avoid tenant-wide write rights: the catalog only reads directory objects, so any write or directory-management permission should be treated as a finding.
- Record the consent: keep the approval, the requester, and the permission list in the change record, and re-check after every app registration edit.
- Separate the sign-in app from the ingestion app: a shared registration gives the sign-in path directory reach it does not need.
Before go-live, compare the granted permissions in the Entra admin center against the written list, and confirm that no delegated permission was granted by mistake.
The connection authenticates with a client secret or a certificate, and that credential is the most likely path for an attacker to reach the directory. Store it in the secrets mechanism your organization already operates, not in a repository or a plain configuration file, and inject it into the Backstage backend at runtime. Certificates are generally easier to rotate without shared secret values in transit, but either option needs an owner, an expiry date and a tested replacement procedure. The general guidance in the Backstage security documentation on secrets and keys applies here, and this connection should be inventoried with the other credentials Backstage holds.
- Pick a store with access logging: use a vault or cloud secret manager that records reads, so unexpected retrieval is visible.
- Set an owner and an expiry: every credential has a named owner and a calendar date for rotation.
- Rotate without downtime: plan overlapping validity so the old and new credentials both work during the switch.
- Keep it out of logs: confirm that configuration dumps and error output do not print the secret.
- Revoke on departure: the credential should be replaced when the people who handled it change roles.
Ask your Entra and secrets platform owners to confirm the rotation interval and the audit log retention before you accept the design.
Filters decide which users and groups enter the catalog, and they are the main control for keeping the imported data proportionate to its purpose. A catalog needs the people who own and operate services, not the whole tenant. Scope the user and group filters to the groups that carry ownership, and document why each filter exists so that a future change can be reviewed against that purpose. A narrow filter also limits the blast radius if the connection is misused.
- Filter groups by purpose: select only the groups used for team ownership, such as those that map to service owners.
- Exclude service and guest accounts: decide explicitly whether non-employee and service identities belong in the catalog.
- Review membership changes: a group that is widened later will silently import more people, so review filter changes like code.
- Test with a sample tenant or group: confirm the imported set before enabling the full ingestion schedule.
- Document the rationale: keep a short note linking each filter to the ownership model it supports.
Confirm with your identity team which group naming and attribute conventions make a filter reliable, since filters based on attributes that users can edit are weaker than those controlled by administrators.
Profile photos and manager relationships are personal data, and loading them changes the sensitivity of the catalog. Photos reveal identity and appearance, and manager chains expose reporting structures that many organizations treat as internal-only. Decide whether each attribute is needed for the portal's purpose before enabling it, and then apply the same access rules to the catalog as to the directory itself. Involve your privacy or data protection contact, because the lawful basis and retention rules that apply to the source directory also apply to the copy in Backstage.
- Justify each attribute: photos and manager links should have a stated use, such as showing ownership to users who need it.
- Control who can read the catalog: the catalog's visibility and the authorization model determine who sees these fields.
- Plan retention and deletion: imported users who leave the directory should be removed from the catalog on a defined schedule.
- Limit exports: check whether the catalog API or search exposes these fields to callers beyond the portal.
- Keep the copy consistent with the source: a correction in Entra should flow into the catalog without manual editing.
Confirm with your privacy and legal contacts whether photo loading is permitted in each jurisdiction where your staff work, before the field is turned on.
Why Entra ID users or groups are missing from the catalog
This table lists the failures that most often leave Entra ID users or groups out of the Backstage catalog, with the cause and fix for each. Work through the rows in order, since a missing admin consent or a wrong permission type blocks everything below it. Confirm the exact error text against your Backstage backend logs before changing configuration.
| Symptom | Likely cause | Fix |
|---|---|---|
| No users or groups are created at all | Admin consent has not been granted for the Microsoft Graph application permissions that the ingestion needs | Have a tenant administrator grant consent for the application in Entra ID, then restart the backend and run the scheduled ingestion again |
| Ingestion runs but returns an access error | The permissions were granted as delegated permissions, which act on behalf of a signed-in user, instead of application permissions, which the scheduled job needs | Remove the delegated grants, add the required application permissions for users and groups, and grant consent again |
| Expected groups are absent from the catalog | A group filter or the group type setting excludes them, such as security groups versus Microsoft 365 groups, or a filter on display name or ID that does not match | Review the group filter in the org data configuration against the group types in your tenant, then check the backend logs for the count of groups returned |
| Users appear but their group memberships are incomplete | Nested group membership is not expanded by the ingestion, so members who belong only through a child group do not appear under the parent | Confirm how your configuration resolves nested groups, and if needed model the parent and child relationship in the catalog explicitly or flatten the membership in your source data |
| Users are created without profile photos | The photo request failed, often because the permission for reading user photos was not granted or the user has no photo set in Entra ID | Confirm the photo permission is granted with consent, check the logs for the Graph response code on photo requests, and accept that users without photos will remain without one |
| Ingestion stops working after a period of normal operation | The client secret used for the Entra ID application has expired, so token requests fail until a new secret is configured | Check the expiry date of the client secret in the app registration, create a replacement, store it in your secrets manager, update the backend configuration, and set an expiry reminder |
| Changes in Entra ID do not appear in the catalog | The schedule has not run since the change, the frequency is too low for your needs, or an incremental run is not picking up the modified objects | Confirm the last successful run in the logs, check the schedule frequency, and if your tenant is large, confirm your incremental ingestion settings and run a full resynchronization to compare results |
| Users are present but cannot own entities | Users were ingested with an identifier that does not match the user reference used in catalog ownership fields | Check the entity reference format in the descriptors against the ingested user names, and align the resolver and naming settings so ownership references resolve |
Questions teams ask before ingesting Entra ID data into Backstage
What does Entra ID org data work cost, and what drives the effort?
Cost depends on the written scope, not on a list price. The main drivers are tenant size, how many users and groups must be filtered out, whether profile photos are loaded, how closely group ownership must match the catalog model, and how much sign-in alignment is needed. Each driver adds design, testing and review work. Your side pays for internal time from a tenant administrator, a Backstage owner and whoever approves group ownership rules. Ask any quote to break out discovery, filter design, testing against test groups, scheduling and handover documentation, and to state which items are one-time and which recur, such as secret rotation and upgrades.
How long does an Entra ID org data import take to set up?
Duration follows scope. A narrow import limited to a small set of groups usually moves faster than a full tenant import with photos, custom filters and incremental ingestion for a large tenant. Time is also spent waiting on administrators to grant application permissions and admin consent, and on reviewing which groups should become catalog owners. Ask for a schedule tied to written milestones, and confirm which steps depend on your tenant administrators' availability rather than on the build itself.
What must our team provide before the work starts?
You need three things: a tenant administrator who can review and grant the Microsoft Graph application permissions and admin consent, a named Backstage owner who decides how users and groups map to catalog entities, and a set of test groups in a non-production tenant or with clearly marked accounts. Your team should also confirm which groups represent teams, which are mail or security groups to exclude, and who approves changes to filters. Without these decisions made early, rework tends to follow.
Can our own engineers build this without a partner?
Yes, if your team has Backstage plugin experience, access to a Microsoft Entra ID tenant with an administrator willing to consent, and time to test filters against real data. The work is mostly configuration of the Microsoft Graph org data module, plus careful testing of user and group filters and photo handling. Teams often underestimate the testing and the rules for which groups become owners. A partner is useful when you want the design reviewed, the rollout staged and the handover documented. Confirm the Backstage version you run before choosing the approach.
Does importing org data replace Entra ID sign-in configuration?
No. Importing users and groups populates the catalog so ownership is visible, but it does not authenticate anyone. Sign-in is configured separately through an authentication provider and sign-in resolvers. The two must still agree so that the identity a user signs in with resolves to the same catalog user that the import created. The Backstage authentication documentation advises that every provider resolve to the same identity and that guest access not be offered in production, so plan both pieces together while keeping their configuration separate.
What recurring work follows an Entra ID import?
The import needs ongoing care. Client secrets or certificates used for Microsoft Graph access must be rotated on a schedule your security policy sets. Filters need review when your group structure changes, and incremental ingestion settings need checking as the tenant grows. Backstage itself moves on a monthly main release line and a weekly next line, and upgrades should bump all @backstage packages together with yarn backstage-cli versions:bump, with the Backstage Upgrade Helper showing template changes. Plugin compatibility should be re-tested at each upgrade.
Who is responsible if a group ownership rule puts the wrong team in charge?
Responsibility is set in the written scope. Typically your team owns the decisions about which Entra ID groups represent owning teams, and the implementation partner, if one is engaged, owns the correctness of the filter and mapping configuration against the agreed rules. Ask any provider to state in writing who approves the mapping, how test results are recorded and how corrections are handled after go-live. Catalog ownership errors affect incident routing and access reviews, so the approval step matters.
Where org data ends and sign-in configuration begins
Org data ingestion and sign-in are two separate configurations, and the boundary between them decides whether your catalog makes sense to the people who use it. The entity provider that reads users and groups from Microsoft Entra ID through Microsoft Graph fills the catalog with User and Group entities. The Microsoft sign-in provider is a different component that authenticates people to Backstage. Enabling one does not configure the other, so a team can have working sign-in with an empty catalog, or a fully populated catalog that nobody can use to log in.
The link between the two is the sign-in resolver. Backstage's authentication documentation advises configuring resolvers so every provider resolves to the same identity, which means a person who signs in through Entra ID must map to the same catalog user that the org data ingestion created. If the resolver matches on a different attribute than the entity provider uses to name users, you get duplicate users, ownership that points at the wrong record, or sign-ins that fall back to a placeholder identity. Confirm which attribute your provider uses as the entity name and which attribute the resolver matches on, and make sure they agree before both go live. Before you enable either side in a shared environment, confirm several things with your identity team: which tenant and directory are authoritative, whether users in the directory match the people who should appear in the portal, and whether guest accounts or service accounts should be excluded. Also confirm that guest access is off for production, as the authentication documentation recommends. Test sign-in with at least one account from each relevant group, then check that the resolved user in the catalog has the expected memberships and ownership. Keeping the two configurations documented side by side makes later changes to either one far easier to review.
How DeployOpen scopes and delivers Entra ID org data for Backstage
DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside your own infrastructure, including Backstage. For Entra ID org data, we treat the catalog population work as its own deliverable, kept separate from sign-in, so ownership in the catalog matches the directory your teams already use.
How we scope
- Engagements are fixed-scope, with the Entra ID tenant, permissions and filters agreed in writing before work starts.
- We confirm which users and groups must appear in the catalog, and which are excluded by filter.
- We record who approves Microsoft Graph application permissions and how they are reviewed over time.
How we build
- We configure the Microsoft Graph org data provider in your Backstage instance, using the credentials your tenant administrators approve.
- We set user and group filters, photo loading and ingestion schedules, and test them against a representative sample of your directory.
- We check incremental ingestion behavior for large tenants, including how deleted or moved users are handled in the catalog.
How we hand over
- You receive configuration, a written record of permissions, filters and schedules, and the runbook your operators will use.
- We document how to verify catalog users and groups against Entra ID after each change, so your team can repeat the check.
- We walk your engineers through upgrade impacts on the org data module before you move to a new Backstage release line.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, scoped in writing against your Backstage version.
- Retainers can cover routine version bumps, reviews of Graph permission changes and fixes for catalog ingestion errors.
- Ask any provider to confirm how they handle directory changes, credential rotation and sign-in resolver alignment with the catalog.
