Skip to main content

v1.26.0

These are the release notes for the v1.26.0 release of Backstage.

A huge thanks to the whole team of maintainers and contributors as well as the amazing Backstage Community for the hard work in getting this release developed and done.

Highlights​

Auth Improvements​

All of the main parts of BEP-0003, and its efforts for making backends secure by default, are now in place! Our BackstageCon lightning talk about auth gives some additional context and details.

  • Backstage user tokens issued by the auth backend will now have a new uip claim. This claim is a separate identity proof that is used internally for limited user identification needs such as cookies or service on-behalf-of tokens, without having to pass through the real user token and its full authorization power.
  • Plugin to plugin auth is now properly scoped and backed by a zero-configuration public key signature scheme. We have also added on-behalf-of tokens to carry the user identity safely in upstream requests, thanks to the identity proof mechanism mentioned above.
  • Plugins such as TechDocs that need to expose cookie based endpoints now issue their own private plugin scoped cookies by leveraging the same identity proof mechanism, making it impossible to abuse cookies for requests to other plugins that happened to be co-deployed on the same domain.
  • Making requests to your backend plugins from external callers has also been made easier than ever with a new configuration section that, in addition to the legacy service tokens, lets you configure static tokens as well. This system was made extensible so that more auth methods can be added going forward.

Note that if you have scaled your Backstage deployment to three or more distinct backends, you must take care to update the backend with the most central plugins first, i.e the ones with fewest outbound calls. The new automated plugin service auth does use feature detection to determine the authentication method, but is only able to do so for a single hop. What this means in practice is that if you’re using the permission backend plugin you should update that instance first, followed by the catalog.

Note also that the plugin service auth system uses the plugin database to store asymmetric keys. This means that any plugin that wants to make requests to other plugins now must have a database (and also accept incoming HTTP requests on the JWKS endpoint). For most adopters this will not require any action since the default setup auto-creates logical databases as needed. But if you have custom or locked-down setups, you may in rare cases encounter the need to create additional plugin databases.

App Backend​

The app-backend plugin is now able to protect the main application bundle and only serve a limited public bundle to unauthenticated users. This is enabled by adding a src/index-public-experimental.tsx entry point to your app package, which will only be used in production builds. This is still an experimental feature, but if you want to know more or try it out, check out the pull request where it was added.

New Backend System​

  • Modules are no longer loaded unless the associated plugin is present.
  • A new initialization option for service factories has been added, allowing service creators to override whether the service is lazily or eagerly initialized.
  • The /api/:pluginId path is now reserved for plugin traffic and can no longer be configured in the http router service. Requests towards /api/:pluginId that don’t match any registered plugin will now return a 404.
  • A sweeping change has been made across all plugins to correctly use the LoggerService instead of the old Winston logger (Contributed by @drodil in #24224). For most users this will be transparent, but some users of the old backend system will notice, and will want to remove the winston compatibility wrapper.

New Auth Modules​

Several more auth providers have been migrated to be implemented as standalone modules, adding support for them in the new backend system. The migrated providers are Cloudflare Access, Azure Easy Auth (@yaegashi in #23909), and Bitbucket (@pjungermann in #24287). If you detect any issues, please reach out on Discord or open an issue.

OpenAPI Tooling​

A new lint rule has been added to the @backstage/repo-tools repo schema openapi lint command, which enforces that allowReserved: true is set for all URL parameters. This is because the default encoding is unnecessarily strict and doesn’t for example permit + as an encoding of spaces.

Two new fuzz commands have also been added, for the repo schema openapi and package schema openapi group for fuzzing plugins. This can help find bugs in your application code through auto-generated schema-compliant inputs. For more information on the underlying library this leverages, take a look at the docs.

Events System Improvement for the New Backend System​

The events system should now be accessed via a dependency on the exported eventsServiceRef instead of the old EventBroker and EventSubscriber patterns, in the new backend system. Because of this, if you are still on the old backend system, you may note some minor changes in how the GitHub catalog providers are constructed. See the pull request for more details and links to the updated installation instructions.

Contributed by @pjungermann in #24260

Catalog Error Events​

Entity processing errors that happen in the catalog used to be sent to the local logger. This led to sometimes large amounts of noise, and the logs often aren’t easy to inspect in production. In this release, they are instead sent to the events system. If you want to retain the logging behavior, you can do so by subscribing to the topic; see the pull request for details.

Contributed by @punkle in #23022

Kubernetes Proxy breaking change​

The KubernetesProxy now requires the DiscoveryService to be passed to its constructor if you are on the old backend system.

Security Fixes​

This release does not contain any security fixes.

Upgrade path​

We recommend that you keep your Backstage project up to date with this latest release. For more guidance on how to upgrade, check out the documentation for keeping Backstage updated.

Below you can find a list of links and references to help you learn about and start using this new release.

Sign up for our newsletter if you want to be informed about what is happening in the world of Backstage.