Backstage LDAP and Active Directory org data

How Backstage imports Active Directory and LDAP org data

Most catalogs start with owners typed by hand into catalog-info.yaml files, and within a year those names no longer match the directory. The LDAP entity provider solves this by reading users and groups from Active Directory, OpenLDAP or FreeIPA on a schedule and writing them into the Backstage catalog as User and Group entities. Ownership fields then point at people and teams that the identity system already maintains, so a departure or a team move in the directory flows into the portal on the next run rather than waiting for someone to edit files. Org data import is a separate job from sign-in. Authentication decides who can log in to Backstage and which identity they present, while the LDAP provider only populates the catalog with the people and groups that owners can reference. The two can point at the same directory, but they are configured independently, and a user can appear in the catalog without being able to sign in. Plan both together so that sign-in resolvers map each login to the same catalog user the provider created, otherwise ownership and identity drift apart again. Before you write any configuration, confirm the provider name, the config keys, the bind and search settings, and the custom transformer API against the Backstage LDAP documentation for the release line you run, because no LDAP-specific fact was available for this page. Check the Backstage authentication documentation for the sign-in side, and treat the directory schema, the bind account and the group filters as decisions your directory team must sign off on before the catalog import goes live.

What you need before connecting Backstage to a directory

Connecting Backstage to an LDAP directory is a read-only import, but it depends on decisions made before any configuration file is touched. The cards below cover the Backstage release, the bind account, transport security, network reach, the org scope and the approvals that have to be in place first.

A supported Backstage release line

Confirm that your instance runs on a release line the versioning policy still supports. Main releases ship monthly and next releases ship weekly, and the policy ties Node.js support to specific even-numbered runtimes. As of Backstage 1.46.0 that means Node.js 22 and 24, so check the policy again before you plan the upgrade window, not after the LDAP import is live.

A read-only bind account

The backend authenticates to the directory with a bind account that only needs to read users and groups under the search base. Ask the directory owner to grant read access to the required attributes and nothing more. The account should not be a personal administrator login, and its password must be stored as a secret that the backend reads at runtime, never committed to the app configuration.

A known search base

Decide the distinguished name where user and group searches start, and which organizational units sit beneath it. Write the base down with the directory owner, because a base that is too broad imports service accounts and retired staff, while one that is too narrow silently produces an empty catalog. Test the base with an LDAP search tool from the Backstage host before you configure anything.

LDAPS or StartTLS with a trusted CA chain

Use an encrypted channel for the bind and every search. LDAPS on port 636 or StartTLS on the standard port both work, but the backend must trust the full certificate chain of the directory controllers. Ask for the issuing CA bundle, add it to the container or host trust store, and verify the hostname matches each controller. Plain LDAP sends the bind password in a form that should never leave a controlled network.

Network paths to the directory controllers

Confirm that the Backstage backend can reach every directory controller it will query, on the chosen LDAP port, from the network where it runs. Check firewall rules, DNS resolution for the controller names and any proxy or egress policy on the cluster. Test from the same pod, container or host that runs the backend, because a path that works from a workstation often fails from inside the cluster.

Org scope and directory owner approval

Decide which OUs, groups and attributes define the people Backstage should show as owners, such as an enabled-account filter or a named group of engineering staff. Write the filters into the change request and get the directory owner to approve the bind account scope in writing. Backstage ingests whatever the bind account can read, so the scope agreed here sets the reach of the import.

Configure the LDAP entity provider in sequence

This sequence takes a Backstage instance from no directory connection to a verified import of users and groups from Active Directory, OpenLDAP or FreeIPA. Each step is checked before the next one starts, so a fault shows up at the step that caused it rather than as missing owners in the catalog.

Create a scoped read-only bind account
The directory administrator creates a dedicated service account that Backstage uses only to search and read entries. It should have read access to the user and group containers you plan to import and no write or administrative rights. Confirm the account's distinguished name and password are stored outside the configuration file, in a secret your deployment can inject. The step is done when the administrator can confirm the account exists, is not interactive, and has no membership in privileged groups.
Verify TLS and DNS from the backend host
Run the checks from the host or container where the Backstage backend runs, not from your workstation, because that is the network path the import will use. Confirm the directory hostname resolves to the expected controllers, and that the LDAPS or StartTLS connection completes with a certificate chain your backend trusts. Ask your directory team which controller or load balancer name to use and whether the certificate covers it. The step is done when a TLS handshake to the chosen endpoint succeeds from the backend host.
Test a search with the bind account
Before any Backstage configuration, run a directory search from the backend host using the bind account and the base you intend to use. Use an LDAP client command-line tool or a simple script with the same credentials. Check that a known user and a known group return with the attributes you need, such as a unique identifier, display name, email and manager or membership attributes. The step is done when the search returns your test entries and fails for an account outside the scope you set.
Set search bases and filters in configuration
Add the LDAP provider to the Backstage app configuration with the target directory URL, the bind account reference, separate search bases for users and groups, and filters that limit each to the populations your catalog should hold. Keep filters narrow at first, for example excluding disabled or service accounts, so the first import is small enough to inspect. The configuration keys should be checked against the current Backstage LDAP plugin documentation for your version. The step is done when the backend starts without configuration errors and the provider reports it loaded.
Map attributes to User and Group entities
Decide which directory attributes populate the entity name, display name, email, profile picture, group membership and manager fields. Vendor differences matter here: Active Directory commonly uses attributes such as sAMAccountName and memberOf, while OpenLDAP and FreeIPA use other attribute names and group models. Record the mapping in a table that the directory team reviews. The step is done when each entity field has a named source attribute and the team agrees which attribute is the stable unique key.
Run one manual refresh and inspect entities
Trigger a single refresh of the LDAP provider rather than waiting for the schedule. Then query the catalog for one known user and one known group, and check that their names, emails, group memberships and parent relationships match the directory. Also look for duplicate users, groups without members and entities that landed under unexpected namespaces. Record the counts and the errors in the backend logs. The step is done when the two test entities are correct and the log shows no unresolved mapping errors.
Set the refresh schedule and timeouts
Once the single refresh is clean, configure the recurring schedule with a frequency your directory team accepts and set timeouts that the largest expected directory query can finish within. Confirm the backend does not overlap runs and that a failed run leaves the previous entities in place. Ask the directory team whether the import load falls within their monitoring thresholds. The step is done when two scheduled runs complete without errors and the catalog still shows the test user and group with the same values.

Directory attributes mapped to catalog fields

This table compares how the core Backstage User and Group fields map to attributes in Active Directory, OpenLDAP and FreeIPA. Use the placeholders as a starting point and confirm each exact attribute name against your own directory schema before the first import. The main takeaway is that the unique identifier must be stable across renames, which rules out fields such as display name or email.

Backstage field	Active Directory	OpenLDAP	FreeIPA
Unique identifier (must be unique and stable)	objectGUID, read as a stable GUID value, not sAMAccountName	entryUUID or a dedicated stable attribute chosen by the directory owner	ipaUniqueID or the entry's stable UUID, confirmed with the IdM admin
Login or metadata name (can change)	sAMAccountName, common for sign-in but reused and renamed in practice	uid or cn, confirm which one is unique in your tree	uid, which is unique within the IdM domain
Display name	displayName, may include titles or locale variants	cn or displayName, depending on schema	cn or displayName
Email	mail or userPrincipalName, confirm which one matches your sign-in identity	mail, confirm whether it is multi-valued	mail, confirm the primary address policy
Group membership	member on group objects, or memberOf on users, confirm which direction your import reads	member or uniqueMember, depending on the groupOfNames or groupOfUniqueNames class	member, including nested groups, confirm how nesting is resolved
Parent group (hierarchy)	Nested membership of parent groups, or an organizational unit path, confirm with the AD owner	Usually a flat group list unless you model hierarchy with a custom attribute	Nested groups are supported, confirm which groups are used as parents
Stable across renames?	objectGUID yes, sAMAccountName and mail no	entryUUID yes, uid and mail usually no	ipaUniqueID yes, uid and mail usually no
Confirm before first import	Attribute names, GUID handling, nested group rules and disabled account filtering	Schema objectClass, multi-valued attributes and group class used	Whether nested groups are included, and which identifier IdM already uses for sign-in

Securing the bind account and the imported data

The LDAP provider reads your directory with a bind account and writes what it reads into the catalog, so the controls below cover that account, the connection, the search scope, sign-in behavior and monitoring. Each one limits what an attacker or a misconfiguration could expose through the org data feed.

Least-privilege read-only bind account

Create a dedicated bind account that can read only the user and group attributes the provider maps, and nothing that allows writes or password resets. Store its secret in your secrets manager and inject it into the Backstage backend at runtime, never in app-config.yaml committed to a repository. Plan a rotation schedule for that secret and confirm with your directory team how a rotation reaches the running backend, since a stale password causes silent sync failures. Ask whether the account can be locked to a single source address.

LDAPS or StartTLS with validation

Carry the bind and every directory query over LDAPS or StartTLS, and keep certificate validation enabled so the backend only trusts the directory certificate chain you have installed. Disabling validation to get a connection working in a test lab is a common route to production, so make it a checklist item. For FreeIPA, Active Directory and OpenLDAP the certificate authority and hostname differ, so confirm the exact name the directory presents before you set the URL. Plaintext binds expose the bind password on the network.

Search scope limited to the org subtree

Set the user and group search bases to the organizational units that hold people who should own catalog entities, and filter out service accounts, disabled accounts and contractor groups you do not want as owners. A wide base such as the directory root imports every principal, including accounts that never belong in a portal. Review the imported user count after the first sync against your expected headcount, and treat a large jump as a configuration problem to investigate before it reaches users.

No guest access and one sign-in resolver

Turn off guest sign-in in production, because an anonymous session has no identity to match against imported users and widens what the portal exposes. Configure the sign-in resolvers so each enabled provider resolves to the same User entity that the directory feed created, using a shared identifier such as the directory username or email. Without that mapping, a person who signs in through a second provider can end up with a second identity and lose ownership they should keep. Confirm the resolver logic against the Backstage authentication guidance before you enable a second provider.

Monitoring schedule failures and directory access

Track each scheduled ingestion run for failures, partial results and unusually large deletions, and forward backend logs to your central logging system. Ask your directory team to enable and retain bind and search logs for the Backstage account so you can see which queries it runs and from where. Alert when a run fails repeatedly, because stale org data leaves ownership pointing at people who have left. Record who changed the search bases, mapping rules or bind account, since those changes shape which identities the portal trusts.

How Active Directory, OpenLDAP and FreeIPA differ

Active Directory is Microsoft's directory service, usually deployed as a forest of one or more domains. For a Backstage import, the main design questions concern the account used to read the directory, how group membership is expressed, and how queries behave when they reach beyond the domain you configure.

Bind account: Plan a read-only service account limited to the organizational units that hold the users and groups you want to import. Confirm which units it can read and how its password rotation will be handled.
Membership attributes: AD records membership on the group object and can report it on the user through a back-link attribute. Confirm which attributes your import expects for users and for groups, and test them on a small organizational unit first.
Referral handling: Searches across a multi-domain forest can return referrals to other domain controllers. Confirm whether your LDAP client follows referrals, because a referral that is not followed can hide users who live in another domain.
Nested groups: Groups can contain other groups, and the nesting depth determines which users an import sees. Confirm whether nested membership is resolved during the import or must be flattened by configuration.
Transport and ports: Confirm which port and TLS mode your domain controllers require, and whether trust relationships change which objects are visible to the bind account.

Check each item against a test organizational unit that contains known nested groups before you point the import at the whole forest.

OpenLDAP is a flexible directory server, and its layout depends heavily on the schema and overlays each organization chose. Two servers that both run OpenLDAP can expose users and groups in very different ways, so the import mapping has to follow your directory tree rather than a general pattern.

User schema: Users may be modeled with inetOrgPerson, posixAccount or a site-specific auxiliary class. Confirm which attributes hold the login name, email address and display name in your tree.
Group object classes: Groups may use groupOfNames, groupOfUniqueNames, posixGroup or a custom class, and each stores its members in a different form. Confirm the class in use before writing the mapping.
Membership values: Some schemas list members as distinguished names and others as login names. Confirm the value format the membership attribute holds, since a mismatch produces groups with no members.
Overlays: A memberOf overlay, when installed, places group back-references on user entries. Confirm whether your server has the overlay and who maintains it, because a missing overlay changes how membership is read.
Bind and search base: Confirm the bind DN format, the search bases for users and groups, and whether the server requires LDAPS or StartTLS.

Export a sample of user and group entries with ldapsearch and compare them with the mapping before the first scheduled run.

Common import failures and how to fix them

This table pairs common LDAP and Active Directory import failures with their likely cause, the check that confirms it and the fix. Work down the causes in order, since bind and TLS problems stop every later step. Confirm each check against the directory and the Backstage backend logs before changing configuration.

Failure	Likely cause and check	Fix
Bind fails with invalid credentials	The bind DN is wrong, the bind password has changed or expired, or the account is locked. Confirm by binding with the same DN and password from a host that can reach the server, and check the directory's account state and the backend log entry for the bind.	Correct the bind DN in the provider config, rotate the password into your secrets store, and ask the directory team for a non-expiring service account with read-only scope.
TLS certificate chain errors	The directory presents a certificate chained to an internal CA that the Backstage container does not trust, or the hostname does not match. Confirm with an TLS handshake test from the same container image and read the certificate error in the backend log.	Add the internal root and intermediate CA to the trust bundle used by the backend image, and use the hostname that appears in the certificate subject or SAN.
Search returns no users	The search base or filter points outside the OU that holds the accounts, or the filter excludes disabled or nested accounts. Confirm by running the same base and filter with an LDAP search tool and comparing the counts with the backend log.	Widen the base DN to the parent OU, adjust the user filter to the object classes your directory uses, and test the filter before the next scheduled import.
Duplicate users after an identifier change	The entity reference is built from a mutable attribute such as a display name, email or UPN, so a rename creates a second user. Confirm by comparing the entity names in the catalog with the account attributes in the directory for the same person.	Map the entity name to a stable attribute such as the account name or a unique ID, then clean up the duplicates by removing the orphaned entities and reimporting.
Groups load without members	Membership is stored in different attributes by vendor, for example member on Active Directory versus memberUid on POSIX groups in OpenLDAP or FreeIPA, or members are listed by DN where the mapping expects a login name. Confirm by reading one group entry directly and comparing its membership attribute with the group mapping.	Set the group member attribute and the user reference format for your vendor, and test with one group before running a full import.
Stale users remain after leaving the directory	Users who are disabled or deleted in the directory stay in the catalog because the import does not remove entities it no longer finds, or the orphan setting is off. Confirm by checking whether the account still exists in the directory and whether the entity still has an owner link.	Set the provider's removal behavior to match your policy, review orphaned ownership before deleting, and reassign ownership for any services that depended on the departed user.

Questions teams ask before importing directory data

How much effort does an LDAP or Active Directory import into Backstage take?

Effort depends mostly on the state of the directory and how much the catalog needs from it, not on the Backstage configuration itself. A small directory with clean user and group attributes and one or two organizational units is a bounded piece of work. Effort rises with the number of OUs and nested group structures, with inconsistent attributes such as missing manager links or duplicate account names, and with custom transformers that reshape users or groups before they reach the catalog. Ask for a written scope that lists the directory types, the number of OUs, the attributes you need, and whether custom transformers are expected, because those inputs determine the quote.

Can our own team import directory data into Backstage without a partner?

Yes, a team that already runs Backstage and has directory administration skills can configure the LDAP entity provider itself. The work involves a read-only bind account, a search base and filters, attribute mapping and a schedule, which are documented in the Backstage catalog configuration. Teams without experience in directory schemas often underestimate attribute quality issues and vendor differences between Active Directory, OpenLDAP and FreeIPA. A partner is most useful when the directory is messy, when several sources must agree, or when the team needs the import tested and documented before it reaches production.

What do we need from the directory owner and the Backstage admins?

The directory owner must provide a bind account with read access to the search base, confirm which OUs and groups hold people who should appear in the catalog, and explain how attributes such as the user principal name, mail and manager are populated. The Backstage admins must decide the entity naming convention, the schedule, who can approve changes to the mapping, and where the bind credential is stored. Both sides should agree on a test OU before the full import so that unexpected users or groups are caught early. Ask each side to name an owner for changes after go-live.

How long does the first full import take to settle, and how often should it run?

The duration of the first full import depends on the number of users and groups, the directory response times, and how many entities the catalog must process afterward. No timing figure is available for this topic, so confirm expected run times in a test environment with a representative sample before setting the production schedule. The schedule should be frequent enough that joiners, leavers and group changes appear in a reasonable window, and long enough that the directory is not queried more often than your directory team allows. Plan a validation pass after the first run to compare catalog counts with the directory.

Does importing users and groups replace our sign-in configuration?

No. Importing org data from LDAP or Active Directory populates catalog users and groups so ownership and group membership can be referenced. It does not authenticate anyone into Backstage. Sign-in is configured separately through an authentication provider and sign-in resolvers, which map a verified identity to a catalog user. The Backstage authentication documentation advises that every provider resolve to the same identity and that guest access not be offered in production. Both pieces need to agree on the user reference format, so plan them together even though they are configured separately.

What happens to existing ownership when a user or group identifier changes?

If the entity reference for a user or group changes, catalog entities that point to the old reference can lose their owner, which shows up as orphaned or unowned components. Identifiers chosen during the import, such as the account name or mail address, should be stable and unique, so decide the naming rule before the first run. Test a rename or an account move in the test OU and check which entities change. Agree on a remediation step with service owners, because an automatic transformer can fix many references but cannot know the correct owner of every component.

How DeployOpen works on this

DeployOpen plans and builds the Backstage LDAP org data import inside your own infrastructure, starting from your directory layout and the attributes your catalog ownership needs. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.

How we scope

Map which directory types, base distinguished names and groups feed Backstage users and group ownership.
Confirm the bind account, its read-only permissions and the network path from the Backstage backend.
Agree in writing which attributes, schedules and custom transformers are in scope and what is excluded.

How we build

Configure the LDAP entity provider with attribute mapping and filters for your directory, tested on a non-production tenant first.
Write and test any custom transformers against sample entries from your directory before enabling the schedule.
Verify group membership, user relationships and orphan handling in the catalog against known test accounts.

How we hand over

Deliver configuration, attribute mapping, schedule settings and transformer code in your version control system.
Document the bind account rotation steps, the directory vendor differences we handled and the verification checks.
Walk your platform and identity teams through troubleshooting for failed syncs and unexpected catalog entries.

How we support

Ongoing support, upgrades and continuous testing are available as retainers after handover.
Retainers can cover Backstage version bumps that touch the LDAP provider and changes to your directory schema.
Ask us to confirm the support boundaries, response expectations and change process in the written scope.