Why TechDocs visibility is open by default in Backstage
By default, every TechDocs site in your Backstage portal is visible to all users, so any person who can sign in can read internal runbooks and architecture documents unless you configure catalog view permissions. Treat this as a deliberate step you must take before publishing sensitive docs, not as something the portal will protect for you. The Backstage threat model documents this default, and it applies even when your sign-in provider already limits who reaches the portal.
Restrict visibility when the documentation itself is sensitive: runbooks that include internal hostnames or recovery steps, architecture notes for regulated systems that hold personal, financial or health data, security design documents, or pages written for one business unit that should not reach others. Multi-business-unit portals are the most common case, because a single sign-in can reach users from several units who should not see each other's docs. Write down which document classes need restriction before you configure anything, since the answer decides whether you need permission policies at all.
Confirm three things with your team before publishing. First, which sign-in identities can reach the portal, including any guest access left enabled. Second, which catalog entities own the sensitive docs, because TechDocs visibility follows the entity. Third, whether anyone can read the generated site storage directly, since the portal is not the only path to the files. Your policy design in the permission framework depends on these answers, and the TechDocs architecture makes clear that only the TechDocs backend should read that storage directly.
Visibility options and when each fits
This table compares three ways to limit who can read TechDocs: leaving the default all-users visibility, restricting catalog view permissions that TechDocs follows, and separating the most sensitive docs into their own portal or entity segment. Read each row against your own documentation classes to find the lowest-effort option that still protects what matters. The main takeaway is that the permission option only works if catalog read access and storage access are both controlled.
| Option | Effort to set up | What it protects | Main trade-off |
|---|---|---|---|
| Default all-users visibility | None beyond sign-in configuration | Little: any signed-in user can open any TechDocs site | Fine for non-sensitive engineering docs, but exposes everything the portal indexes |
| Catalog permissions that TechDocs follows | Moderate: enable the permission framework, write policies on users and groups, test before rollout | Docs attached to restricted catalog entities, provided catalog view rules and storage access are both locked down | Search results and cached responses must respect the same rules, so verify both before trusting the restriction |
| Separate portal instance or entity-level segmentation | High: separate deployment, sign-in, storage and catalog for the sensitive set | Strongest separation for the most sensitive docs, since users outside the group never reach the instance | Duplicated operations, upgrades and backups, and cross-links between the two portals break |
| Restricted storage bucket access only | Low to moderate: scope bucket credentials to techdocs-backend | Blocks direct reads of generated sites, but not portal-level viewing | Does not control who sees a page inside Backstage, so it complements rather than replaces catalog rules |
Setting up catalog-scoped TechDocs access
This sequence moves TechDocs from its default all-users visibility to access that follows catalog permissions, so each team's documentation opens only for the people allowed to see the owning entity. Each step ends with a check you can run before the next one starts.
Inventory entities with sensitive documentation
List every catalog entity that has a TechDocs site and mark the ones whose docs hold internal architecture, incident runbooks, security configuration or customer data. Your platform team and the owning teams should review the list together, since they know what the docs contain. Record which entities can stay visible to all users. The output is a short register of restricted entities with their owners. You know this step is done when every entity with a docs site appears in the register with a visibility decision.
Define groups and entity ownership
Confirm that each restricted entity has an owner set in its descriptor, and that the owner refers to a group that exists in the catalog. Those groups should come from your identity directory through the sign-in resolver, so membership changes in the directory reach Backstage without manual edits. Ask the identity team to confirm how group membership is resolved at sign-in and how often it refreshes in your setup. You know this step is done when a sample of restricted entities shows a valid owner group and a test user's group membership appears in the catalog.
Enable the permission framework
Turn on the Backstage permission framework in the backend so catalog and TechDocs requests are evaluated by a policy instead of the default allow-all behavior. Keep the change in a non-production environment first, and make sure the policy file is under version control with the rest of your configuration. Expect the first build of the policy to deny more than you intend, so plan a review window before production. You know this step is done when the backend starts with the framework enabled and a read request from a test user returns a decision rather than an open result.
Write catalog read policies for restricted entities
Write a policy that allows catalog read permissions for restricted entities only when the requesting user belongs to the owner group or an approved group, and deny all other requests. TechDocs follows these catalog view permissions, so the same rule governs the docs page for each entity. Keep the rules keyed to entity ownership and group membership rather than to individual users, which makes the policy easier to review. You know this step is done when the policy file lists each restricted entity's rule and the reviewers have signed off on it.
Confirm TechDocs reads go through the backend
Check that TechDocs content is served by the TechDocs backend, which applies the catalog permission check, and that no other service or user path reads the storage bucket directly. Review the storage bucket policy with your cloud or infrastructure team so only the backend identity can read the generated sites, and that CI writes with a separate identity. Confirm this against the TechDocs architecture and your own deployment rather than assuming it. You know this step is done when a direct request to the bucket for a restricted site is refused for every identity except the backend.
Test denial and access for each group
Sign in as a test user from each group and open the docs page for a restricted entity owned by another group. The page should show a denial, and the same user should see the docs for an entity owned by their own group. Repeat the check for a user with no group membership and for an unauthenticated visitor if guest access is off. Record the results in a test matrix that the reviewers keep with the policy. You know this step is done when every combination in the matrix matches the expected result and a non-member gets a denial on a restricted entity's docs page.
Verify the reader sanitizes generated HTML
Access control decides who can open a page, but the TechDocs frontend also sanitizes the generated HTML because it does not trust that HTML. Test this with a sample page that contains a script element or an unsafe attribute and confirm the reader does not run it. Ask your security team to include this check in the hardening review so it is repeated after upgrades. You know this step is done when the test page renders without executing injected markup and the result is saved with the test matrix.
Roll out and monitor policy changes
Promote the policy to production after the test matrix passes, and assign an owner to review changes to the policy file, the group sources and the bucket permissions. Ask each owning team to confirm that its restricted docs open for the right people in production. Plan a repeat of the test matrix after backend upgrades and after changes to the identity directory. You know this step is done when the policy is in production, each owning team has confirmed access, and the change owner and retest trigger are written in your operations runbook.
Why the reader sanitizes HTML and what that does not protect
The TechDocs frontend sanitizes the HTML it renders from generated documentation because it does not trust that content. The Backstage threat model treats generated markup as something that could carry malicious elements, so the reader strips or neutralizes script-capable markup before it reaches a user's browser. This protects the people viewing docs from injected code. It does not decide who is allowed to see a page in the first place, and it should never be counted as part of your visibility model.
Sanitization and catalog permissions answer different questions. The permissions you configure for catalog view decide whether a user can reach a TechDocs page at all, and the default of all users seeing all TechDocs stays in place until you change it. A sanitized page that an unauthorized user can load is still a disclosure of internal documentation. Plan the two controls separately, test each one with a user from a team that should be blocked, and confirm with your own test cases that a blocked user gets no content from the reader, the API or the storage bucket.
Sanitization also has limits you should review in your own content. Custom addons and any raw HTML written into MkDocs pages run inside the rendering path you are trusting, so changes to them deserve the same review as code changes. Confirm which addons your build installs, who can merge changes to docs repositories that contain raw HTML or addon configuration, and whether your CI pipeline can publish without a second reviewer. Treat those reviews as part of the security boundary, not as documentation housekeeping.
Securing the storage bucket and backend path
Catalog permissions only govern what the Backstage UI and API return. The generated documentation also sits in object storage and in the browser, so those layers need their own controls. The cards below cover who can reach the bucket, how CI and the backend are separated, and what else can leak restricted content.
Limit bucket read access to techdocs-backend
Only techdocs-backend should read TechDocs storage directly, so grant read credentials to that backend identity and no one else. Remove any broad read policy on the bucket, such as a group or account-wide grant, that would let a person or other service fetch a site without passing through catalog permission checks. Confirm the exact policy syntax for your storage provider and test it with a principal that is not the backend.
Split CI write and backend read credentials
The pipeline that builds and publishes documentation needs write access, and the backend needs read access. Issue two separate identities with different permissions so a compromised CI runner cannot read sites it does not publish and the backend cannot overwrite them. Rotate both credentials on their own schedule and record which pipeline holds write access.
Audit who can reach the bucket
Review bucket policies, access keys, public access settings and bucket-level sharing links outside Backstage. Check for any public read setting, leftover developer keys, and service accounts that no longer have an owner. Ask your storage team to confirm that access logging is on so you can answer who read which objects during a review.
Keep the frontend sanitizer enabled
The TechDocs frontend sanitizes generated HTML because it does not trust that HTML. Do not disable that behavior to fix a rendering problem in a site, and do not add custom scripts or raw HTML pages that bypass it. Track Backstage releases so sanitizer fixes reach your deployment, since the versioning policy backports high and critical vulnerability fixes to recent releases.
Check search and cache for leaks
A restricted document can still expose its title or excerpt through the search index or a cached response. Test as a user without read access: search for a restricted page title and a unique phrase from its body, then check cached endpoints for the same content. Confirm that search collators and cache keys respect the same entity permissions before you enable TechDocs for a wider audience.
Questions teams ask before restricting TechDocs
How much effort does restricting TechDocs visibility take?
The effort depends mainly on how many entities hold sensitive documentation, how well your group model matches the teams that own those entities, and how much testing you do before rollout. A small set of entities owned by one well-defined group is a contained change. A catalog where ownership is unclear, or where many entities need different audiences, takes longer because each entity's owner and reader list must be decided first. Permission policy work is one-time, while reviewing new sensitive entities and keeping policies current recurs. Ask any partner to break the quote into catalog review, policy authoring, testing and storage verification, so you can see which part your own team can absorb.
What does the work need from our team?
You need three things: people who own catalog entities and can say who should read each one, identity group data that the catalog and sign-in can resolve, and an administrator who can review access to the object storage bucket that holds generated TechDocs. Without clear entity ownership, a policy will either expose too much or block teams that need their own docs. Group data must come from your identity provider in a form Backstage can use at sign-in, so confirm that group membership is available before you write policies. Storage admin access is needed to confirm that only the TechDocs backend reads the bucket directly, since the TechDocs architecture expects that.
Can our own team restrict TechDocs visibility without a partner?
A team with Backstage experience, an identity administrator and storage access can usually do the work in-house, and many do. A partner adds value when the sensitive set is large, when group data is messy, or when you need the change documented as evidence for a review. Whichever route you pick, the risky step is testing. Write the scope in writing first, whether internally or with a partner, so the entity list, the groups and the verification steps are agreed before anyone edits production configuration.
How long does it take to confirm that the restriction works?
Confirmation takes as long as it takes to test each audience against each sensitive entity. For each group, you should sign in as a representative user and check that allowed documentation loads, that restricted documentation is hidden in the catalog and returns no content when opened directly, and that search results do not leak titles or snippets. You should also confirm that the storage bucket is not readable by anyone other than the TechDocs backend. The number of groups and sensitive entities sets the length of this pass, so it is best measured against your own catalog rather than assumed.
Does HTML sanitization make restricting TechDocs unnecessary?
No. Sanitization protects users from malicious markup inside documentation, because the TechDocs frontend does not trust generated HTML. It does not decide who is allowed to read a page. By default, all TechDocs are visible to all users unless catalog view permissions are configured, so a sanitized page can still be read by anyone who can reach the portal. Treat sanitization and access control as two separate controls, and verify both.
Which parts of the setup need the most checking after go-live?
Ongoing checks matter most when new entities are registered, when groups are renamed or restructured, and when the storage configuration or backend credentials change. Each change can silently widen or narrow visibility. Review the policy after any identity change, confirm that new sensitive entities inherit the intended restriction, and recheck the bucket permissions after infrastructure work. Ask any partner what retainer or handover covers these recurring reviews.
Will restricting access support our compliance evidence?
Restricting access produces configuration and test records that can support an assessment, but DeployOpen does not issue audit reports, attestations or certifications. Independent auditors and certification bodies make those determinations. What you can prepare is a clear list of sensitive entities, the policy that governs them, the group mapping, the test results and the storage access review. Confirm with your auditor which of these artifacts they expect before the work starts.
How DeployOpen scopes and delivers TechDocs access control
DeployOpen plans and implements TechDocs visibility inside your own Backstage deployment, so that catalog read permissions decide who sees each site. The work covers the permission model, the reader and storage paths, and the tests that prove a restricted site stays restricted. Engagements are fixed-scope, with the scope agreed in writing before work starts.
How we scope
- Inventory which TechDocs sites exist and which catalog entities own them today.
- Agree which teams and groups may read each documentation set, in writing.
- Confirm how your identity provider groups resolve to Backstage users at sign-in.
How we build
- Replace the all-users default with catalog view permissions that TechDocs follows.
- Verify that the TechDocs frontend keeps HTML sanitization enabled in your build.
- Restrict storage bucket access so only techdocs-backend reads the generated sites.
How we hand over
- Document each permission rule, the group it maps to, and the entity it protects.
- Provide test cases showing allowed and denied reads for representative users.
- Walk your platform and security teams through the runbook for adding new docs sets.
How we support
- Review access changes when new teams, entities or storage locations are added.
- Re-test visibility after Backstage upgrades that touch permissions or TechDocs.
- Ongoing support and continuous testing are available as a retainer agreed in writing.
