Why securing Backstage software templates and scaffolder actions matters
Templates are the part of a Backstage portal where a developer's click turns into infrastructure. The scaffolder runs a template's steps in order, and each step is an *action* that does real work: fetching skeleton content, creating a repository on a Git platform, registering entities in the catalog, or calling a CI or cloud API. The risk surface is the set of actions the scaffolder can run, and the credentials those actions carry. A template that looks like a form to the person filling it in can, in effect, create repositories, pipelines and cloud resources under whatever identity the scaffolder uses. Before a production portal lets more authors publish templates, the platform team should be able to answer which actions are installed, who may author templates that call them, and whose credentials each step uses.
The main decision is whose identity a template acts as. If every run uses a shared service credential with broad rights, a single template can do far more than the user who ran it, and the audit trail will show only the service account. Moving toward user-scoped tokens, so each action runs with the rights of the person who started the scaffolding job, makes permissions match the requester's own access. That change touches the sign-in design, the token flow and the Git and cloud integrations, so confirm early which of your providers can supply delegated tokens and which can only offer application credentials. Also check where the scaffolder runs. Actions execute on the Backstage backend host, so a poorly reviewed custom action can reach anything that host can reach.
Hardening should happen before the template catalog grows, because later changes break existing templates and erode trust in the portal. Treat the start of broader template authorship as the trigger: inventory the installed actions and their owners, restrict who may publish or modify templates, and confirm how the scaffolder's own credentials are stored and rotated. Ask your Backstage project lead or an implementation partner to show the current scaffolder permission model in the version you run, because permission handling has changed across releases and should be verified against the documentation for your release line rather than assumed.
Which scaffolder risks to reduce first
Scaffolder actions run server-side and can call internal systems, so a template is closer to code than to configuration. The risks below share one root cause: a template author or installed action inherits more credential and host reach than the task needs. Work through them in order, because the first two decide how far the others can spread.
Templates running on the Backstage host
Scaffolder steps execute inside the Backstage backend process, so a template that runs arbitrary commands or reads local files can reach anything that process can reach. This includes the config directory, mounted secrets and the network segments the pod can address. Check which actions your templates call, whether any execute shell commands, and what the backend container can read from its filesystem and network. The fix is to shrink the backend's reach, not to trust template reviews alone.
Elevated shared scaffolder credentials
When every template run uses one service account with broad rights to Git, cloud and CI, a single misused template grants that account's full reach. The shared credential also hides who initiated an action, which weakens audit trails. Inventory every token the scaffolder reads from configuration, list the systems each one can write to, and decide which of them must exist at all. Reducing this set usually does more for risk than any single template change.
Actions inheriting broad user tokens
Some setups pass the signed-in user's token into actions so that Git commits and pull requests carry the user's identity. That is correct for attribution but gives an action every permission the user holds, including ones the template never needs. Confirm which actions receive user tokens, the scopes those tokens carry, and whether a template author can read or log them. Aim for the narrowest scope that still records the requesting user.
Unreviewed installed actions
Custom and community scaffolder actions are code packages that run with the backend's privileges, and they can be added by a dependency update as easily as by a deliberate change. Keep a written list of installed actions, the package and version behind each, and the owner who approved it. Review new actions and upgrades in the same change process as the rest of the backend code, and remove any action no template uses.
Template authors with too much reach
Anyone who can merge a template change can alter what the scaffolder does, so template authorship is effectively deployment rights. Define which teams may author or edit templates, require review by the platform team for changes that add actions or credentials, and restrict who can run sensitive templates through permission policies. Check the repository branch protection and the catalog permissions on templates, not only the code itself.
Template changes outside review
A template stored in a repository that accepts direct pushes can change behavior without anyone reading the diff. Templates also pull in fetched skeleton content that may run through other steps. Confirm where each template is registered, who can push to that location, and whether the catalog location rules allow a template to be added from an unreviewed source. Route template locations through the same protected branches used for application code.
User tokens or shared service credentials for scaffolder runs
A shared service account is a single credential, often a GitHub App, a bot user or a cloud service principal, that the scaffolder uses for every template run. It is the simplest model to configure because one token sits in the backend configuration and every action uses it. The cost is that the credential usually needs enough rights to create repositories, push code and grant access for any team that might run a template, so its permissions tend to grow over time.
- Attribution gap: Repositories and resources appear as created by the bot, so the audit log shows the service account, not the person who clicked Create.
- Broad blast radius: A leaked token exposes every repository and project the account can reach, not only the ones a single template needs.
- Permission creep: Teams add rights for one template and rarely remove them, so the account drifts away from least privilege.
- Rotation impact: Rotating the credential affects every template and every integration that shares it, which pushes teams to rotate less often.
- Cloud reach: A service principal that provisions cloud resources can often do so in more accounts or subscriptions than any one requester should reach.
Check which repositories, groups and cloud scopes the shared credential can reach today, and confirm whether anyone outside the platform team can read its secret.
With user tokens, the scaffolder acts with the identity and permissions of the person who started the run. Source control creates the repository as that user, and cloud actions run within that user's granted roles. This keeps authorization close to the people who already have rights, so a template cannot grant more access than its requester holds. The trade-off is that the portal must obtain and handle delegated tokens correctly, and some actions need a different path when the user lacks rights.
- Clear attribution: Commits, repository creation and cloud changes are recorded against the requesting person.
- Smaller blast radius: A stolen token carries only the rights of one user and expires under that user's session policy.
- Natural least privilege: Users who cannot create repositories in an organization cannot create them through a template either.
- Session handling work: Tokens must be refreshed, scoped and revoked correctly, and the flow must handle users who sign in through a different provider than the target system.
- Edge cases: Some automation, such as creating an organization-level secret or a shared project, may still need a service identity, so plan the exceptions explicitly.
Confirm that your Backstage sign-in and each target provider can issue user-level tokens with the scopes the templates need, and test with a user who has only the rights they should have.
The practical choice depends on which providers in your organization support user-level tokens for the operations your templates perform. Source control platforms differ in how they issue delegated tokens, whether they offer fine-grained scopes, and whether an app installation acts on behalf of a user. Cloud providers differ in whether a federated or delegated identity can be used for provisioning, and in how they record which principal made a change. Some operations may be supported for one provider and not another, so the answer is rarely global.
- Inventory per provider: List each source control and cloud target a template touches and record which token types it accepts.
- Scope mapping: Compare the scopes a user token needs for each template action with what the provider offers for delegated tokens.
- Mixed models: Many organizations use user tokens where supported and a tightly limited service identity elsewhere, documented per action.
- Vendor confirmation: Check each provider's current documentation and your own tenant settings, since token policies are often set by administrators.
- Fallback behavior: Decide whether a run should fail or fall back to a service identity when a user token is unavailable, and record that decision.
Ask each provider's administrators which token types your organization has enabled, then document the decision per action before any template is published.
Hardening sequence for templates and actions
This sequence turns an unreviewed scaffolder into a known set of actions, templates and authors, with each permission traced to a named owner. Each step ends with a check you can record as evidence before the next step begins.
Inventory installed actions and templates
Platform engineering lists every scaffolder action registered in the backend, including custom actions and any actions added by installed plugins, and lists every template entity in the catalog with its owner and source location. Record the action name, the package that registers it, and what it can touch, such as Git hosts, cloud APIs, the filesystem or internal services. Done when the inventory is stored in version control and every action has a named owner. Confirm the exact registration method for your Backstage version in the scaffolder documentation before you start.
Review and remove unused actions
For each action in the inventory, the platform team checks which templates call it, when it last ran, and whether its package is still maintained. Actions with no callers are removed from the backend along with their package dependency, and actions that run arbitrary commands or write outside a defined path are flagged for a security review before they stay. Done when the backend builds without the removed actions, the template catalog shows no references to them, and the review decisions are recorded per action.
Confirm where template steps execute
Engineers map each template's steps to the process that runs them, because the scaffolder runs inside the backend process on the host unless you move execution elsewhere. Identify which templates use shell-capable or filesystem-writing actions and decide whether they can run in an isolated container or a separate runner for your environment. Done when you have a written statement of where each class of template executes, the isolation boundary you chose, and a note on what the backend process can read, such as its configuration and secrets.
Move template runs to user-scoped credentials
Where the integration supports it, change the scaffolder so that actions use the signed-in user's token for Git hosts and cloud APIs rather than a shared service credential with broad rights. Keep a service credential only for actions that must run without a user, and scope it to the minimum operations those templates need. Done when a test run as a user with limited rights fails on resources they cannot access, and the audit trail attributes the created repository to that user. Confirm the supported token flow for each integration with its vendor documentation.
Restrict who can author and publish templates
Set permission policies so only a named group can create, edit or register Template entities, and so catalog locations that can add templates are limited to a reviewed repository. Require a code review on the template repository before a change is published to the catalog. Done when a user outside the authoring group cannot register or modify a template in a test environment, and a template change without an approved review does not appear in the catalog.
Test templates and permission checks together
Run each production template against a non-production target using a test identity and a test organization, then repeat the run with an identity that lacks the rights it should not have. Record which runs succeed, which are denied, and which produce unexpected side effects in logs or created resources. Done when every template passes its expected-success and expected-denial cases, and the results are saved with the template version tested. Repeat this check after each Backstage upgrade and after each change to an action.
Questions teams ask before securing scaffolder actions
Who does the work of securing scaffolder actions?
The work is usually split between the platform team that owns the Backstage instance, the identity administrators who own sign-in and group data, and the Git administrators who own the repositories and tokens templates write to. Someone must own the template catalog and the decision about which authors may publish templates, because most of the risk sits in custom actions and the credentials they receive. DeployOpen can plan and implement the scaffolder changes, but your platform owner keeps accountability for what runs in production after handover. Confirm early who approves changes to custom actions and who can grant template authoring rights.
Can our in-house team secure Backstage templates without a partner?
Yes, if the team already runs Backstage in production and has someone comfortable with the scaffolder backend, Node.js and the permission framework. The work is mostly configuration, code review of custom actions and process changes, so it does not require specialist tooling. A partner adds value when the team lacks time to review every installed action, needs an independent test of the controls, or must produce evidence for an assessment. Ask your team to inventory current templates and actions first, since that inventory sets the size of the job.
What drives the cost of this work up or down?
The main drivers are the number of templates and custom scaffolder actions already in use, how many of those actions call external systems with credentials, and how many Git platforms and identity providers the templates touch. Costs rise when templates were written by many authors without review, when shared service credentials are embedded in actions, or when the team must rebuild user token flows for each integration. Costs fall when the catalog of templates is small, actions are already in a reviewed repository, and identity groups are clean. Ask any quote to list each template and action in scope, the systems each one reaches, and whether testing is included.
What does the work need from our identity and Git administrators?
Identity administrators need to confirm which groups map to template authors, template users and approvers, and that sign-in resolves each user to a consistent identity. Git administrators need to confirm which repositories templates publish to, which token types the platform supports, and how scopes and branch protection are set. Both teams must agree on whether scaffolder actions should use the signed-in user's token rather than a shared service account, because that choice determines the scopes they must issue. Expect a short review cycle with each team for access decisions, and ask for those decisions in writing before build starts.
How long does it take to verify that the controls work?
Verification time depends on how many templates and actions exist and how many permission paths need testing. For each template, you should run it as an author, as a permitted user and as an unpermitted user, then confirm that actions receive only the credentials they need and that denied runs leave a record. Plan additional time for the audit trail, since you must show that events from scaffolder runs reach your log store. Ask a proposal to state how many test cases it covers and what is retested after an upgrade, rather than accepting a single duration for the whole engagement.
How do Backstage upgrades affect our custom scaffolder actions?
Upgrades can change the scaffolder API, the action input schema and the packages that custom actions import, so each action should be treated as code that must be retested with every version bump. Backstage moves all @backstage packages together using yarn backstage-cli versions:bump, and the Backstage Upgrade Helper shows template changes between versions, so start there when reviewing actions. Keep actions in a repository with its own tests so breakage shows up in CI rather than in a developer's first run. Confirm with your platform owner which Backstage release line you follow, since the main line ships monthly and the next line ships weekly.
Does the scaffolder change how audit records are produced?
Scaffolder runs produce task logs, but the records you need for security review depend on how the instance is configured. Confirm whether your auditor service captures template executions, which user started each run, and which actions were called, and whether those events reach your SIEM. Do not assume that task logs alone satisfy an audit request, because they may not record denied attempts or credential use. Ask for a sample audit event from a test run as part of acceptance.
Ongoing controls for templates after go-live
Templates and scaffolder actions change after launch, through new template versions, action upgrades and credential changes. Four controls run in parallel to keep that drift visible, each with a named owner. Together they make sure every change to what a template can do is reviewed, recorded and tied to the Backstage release line you run.
Review template and action changes in source control
Keep every template definition and custom action in a Git repository with required review from the platform team for changes that add actions, widen parameters or alter credentials. Owner: the platform engineering lead. Check that protected branches block direct pushes, that the catalog only registers templates from the reviewed branch, and that a changed template carries a new version rather than silently replacing the old one. Review is the control that catches a new action before a team runs it.
Audit action installs after each upgrade
Each Backstage upgrade can change which scaffolder actions are registered, and each custom or community action package is a dependency with its own version. Owner: the Backstage application maintainer. After every bump, list the installed actions from the scaffolder backend, compare the list with the approved inventory, and remove any action no template uses. Upgrades move all @backstage packages together, so this check belongs in the same change window.
Monitor scaffolder runs for unusual behavior
Scaffolder runs record who started a task, which template ran, and which actions executed. Owner: the security operations team, with platform engineers on call. Review failed runs, runs by users outside the expected groups, and runs that write to repositories or cloud accounts outside the template's stated purpose. Route these events to the same place as your other Backstage audit data so a suspicious template run is investigated alongside the user who triggered it.
Rotate integration credentials on a schedule
Templates that create repositories or cloud resources need credentials, and those credentials should be scoped to that work and rotated. Owner: the identity or platform security team, with the template owner named in the catalog. Check that each credential is held outside app-config files, that its scope matches the actions that use it, and that rotation does not depend on one person. Rotating after any change to a template that touches the credential is a practical trigger.
Tie reviews to the patch window
Security fixes are backported to releases from the last 6 months when feasible, and high and critical fixes are always backported to those releases. Owner: the Backstage application maintainer. Set the review cadence so that a monthly main release and weekly next releases are assessed against your installed version within the six-month window. A template or action that falls outside a supported release line should be upgraded or retired before the window closes.
How the work is scoped and handed over
Every engagement on Backstage scaffolder security starts from a written scope that names the templates, custom and installed actions, and credential paths in scope. For this work, that means listing each template in the catalog that runs fetch:template, publish:* or custom actions, every action registered in the scaffolder backend, and each place a template receives a token, such as a shared integration credential in app-config.yaml or a user OAuth token passed through the sign-in flow. The scope also states which Git platforms and catalog locations are included, because the same template often publishes to more than one of them. Deliverables are agreed in writing before work begins, so the reader knows what they will receive and in what form.
The written scope should also say who approves changes to templates and actions after handover, and which environments are covered (for example, a production portal only, or staging as well). Ask for a named owner on your side for each decision that changes a credential path or an action's permissions, since those decisions shape the work more than any single configuration change. Timelines are set in the same written scope once the inventory is complete, so ask for the dependency list first: which templates depend on which integration tokens, and which teams must test changes before they ship.
Handover covers two artifacts. The first is the action inventory: each installed scaffolder action, the package and version it comes from, the permissions it needs, the credentials it reads, and the templates that call it. The second is a set of runbooks for the controls introduced during the work, including how to add or review a custom action, how to rotate any remaining shared credential, how to revoke a user token, and how to respond when a template misbehaves. Confirm with the vendor how the scaffolder's permission framework and action access controls are documented for your installed Backstage version before you rely on a runbook step, since those APIs change across releases. Ask that the inventory be kept in version control so it stays current after the engagement ends.
How DeployOpen works on this
DeployOpen plans and implements Backstage template hardening inside your own infrastructure, starting from a written inventory of the templates, actions and credentials your portal already uses. The work is scoped in writing before it starts, built against your identity and Git setup, and handed over with documentation your platform team can run without us.
How we scope
- Inventory every template, custom action and installed scaffolder action your portal currently exposes
- Map which credentials each action uses today, including any shared service tokens
- Agree in writing which template authors, groups and publishing paths are in scope
- Engagements are fixed-scope, with deliverables and timelines confirmed before work begins
How we build
- Move template execution and credential use toward per-user tokens where your sign-in provider supports it
- Restrict installed actions to a reviewed allow list and remove unused or unowned ones
- Restrict template authorship and publishing through your Git platform's review controls
- Test each changed template end to end in a non-production Backstage instance before rollout
How we hand over
- Written record of the template and action inventory, credential changes and reasons for each
- Runbook for adding a new action, reviewing a template change and rotating scaffolder credentials
- Configuration and code delivered to your repositories, under your ownership
- Walkthrough with the platform and security teams on what changed and what to monitor
How we support
- Ongoing support and upgrades are available as a retainer, scoped separately from the build
- Retainers can cover review of new templates and actions as your teams add them
- Continuous security testing of the portal is available as a separate scope
- Confirm with us which Backstage release line and Node.js version your portal will run before scoping
