These are the release notes for the v1.28.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

BREAKING: Proxy backend plugin protected by default

The proxy backend plugin is now protected by Backstage auth, by default. Unless specifically configured (see below), all proxy endpoints will reject requests immediately unless a valid Backstage user or service token is passed along with the request. This aligns the proxy with how other Backstage backends behave out of the box, and serves to protect your upstreams from unauthorized access.

Here's an example of how to configure:

  proxy:
    endpoints:
      '/pagerduty':
        target: https://api.pagerduty.com
+       credentials: require
        headers:
          Authorization: Token token=${PAGERDUTY_TOKEN}

There are three credentials settings:

• require: Callers need Backstage credentials. These are not forwarded to the target.
• forward: Callers need Backstage credentials, which are forwarded to the target.
• dangerously-allow-unauthenticated: No Backstage credentials needed. Target can apply its own checks. Incoming tokens of any sort will be allowed but ignored, and will also be forwarded if allowedHeaders: ['Authorization'] is included.

The new default is require, replacing the old dangerously-allow-unauthenticated. This means some previously permitted requests may now result in 401 Unauthorized responses. This does not apply if backend.auth.dangerouslyDisableDefaultAuthPolicy is set to true.

For proxy endpoints still requiring unauthenticated access, add credentials: dangerously-allow-unauthenticated in your app-config.

See the proxy documentation for more information.

BREAKING: Gerrit integration breaking changes

• The workdir argument have been removed from The GerritUrlReader constructor;
• The Gerrit readTree implementation will now only use the Gitiles api, so the support for using git to clone the repo has been removed;
• The gitilesBaseUrl is now mandatory for the Gerrit integration and the ability to override this requirement using the DISABLE_GERRIT_GITILES_REQUIREMENT environment variable has been removed.

Contributed by @anicke in #25123.

BREAKING: Github integration breaking changes

• Removed deprecated code from when casing was changed from GitHub to Github nearly two years ago. The following items have been removed:
  • getGitHubFileFetchUrl (use getGithubFileFetchUrl instead)
  • GitHubIntegrationConfig (use GithubIntegrationConfig instead)
  • GitHubIntegration (use GithubIntegration instead)
  • readGitHubIntegrationConfig (use readGithubIntegrationConfig instead)
  • readGitHubIntegrationConfigs (use readGithubIntegrationConfigs instead)
  • replaceGitHubUrlType (use replaceGithubUrlType instead)

Contributed by @awanlin in #25100.

BREAKING: OAuth Scope Updates

The way that OAuth-based auth providers handle scopes has received several updates. There is now a new .additionalScopes configuration for all OAuth providers, which can be used to request additional scopes for all sessions. Many providers already had a similar configuration, but in most cases this did not work correctly as scopes requested by the client would override the configured set.

Many providers now also have a set of required scopes that will always be present. This is in contrast to the previous solution where the client would be responsible for including a set of baseline scopes.

A bug has also been fixed in the handling of persistent scopes, which could break session refresh for some providers, such as GitHub.

BREAKING: User Info service

Limited-access user tokens (as used in cookies) no longer contain the ent ownership claim. This is notably used by TechDocs and the app-backend. If you use those services, you may want to log out and in again.

Background: As part of the previous auth improvements, we added the coreServices.userInfo service. This service can extract user details from incoming credentials - notably the so-called ent claim with its ownership information.

In this release, the auth backend part of this has been implemented, such that the information returned by your sign-in resolver gets persisted and can be acquired after the fact. With this in place, we could finally start slimming down on token sizes, starting with the cookie tokens. Unfortunately this has to be done in such a way that it’s breaking in the short term.

If any issues persist, try clearing your cookies, and then reach out to us on Discord or with an issue if necessary.

Contributed by @kuangp in #24729.

New Backend System API movement towards 1.0 release

As part of finalizing the New Backend System, we are restructuring the out-of-the-box functionality a bit. As part of this release, you will see a large amount of deprecations on the @backstage/backend-common package (which will be deleted in a future release), and also on the @backstage/backend-app-api package (which is just being slimmed down to its essentials). Instead, you will see that the @backstage/backend-defaults package has received new subpath exports that neatly arrange all of these factories and default implementations.

As an example, the rootLoggerServiceFactory export on @backstage/backend-app-api has been deprecated, and should now be imported from @backstage/backend-defaults/rootLogger. Most other deprecations follow the same pattern. Each deprecated symbol should have a deprecation message on it, which clearly states from where you should now be importing that particular functionality instead.

This rearrangement was one of the crucial final pieces for settling the API surfaces of this backend system! We hope you’ll find it neater and clearer to understand.

Please update deprecated imports in your own repo code as soon as convenient, to avoid the breaking changes in future releases when these symbols are finally removed.

You will also note that backend features (plugins and modules) no longer are returned as functions, which simplifies interacting with features! You may see this in your editor in the form of deprecations, whose message tells you to remove the trailing parentheses.

Your code may be changed in the following way as an example:

 await startTestBackend({
   features: [
     // service - stays unchanged
     eventsServiceFactory(),
     // module - remove parentheses
-    catalogModuleBitbucketCloudEntityProvider(),
+    catalogModuleBitbucketCloudEntityProvider,

In related news, we have unified some type names. The UrlReader types are now properly prefixed with the service name, so you’ll see that for example ReadTreeOptions is now UrlReaderServiceReadTreeOptions. Functions better follow the proper naming convention for their arguments, for example BackendPluginConfig now becoming CreateBackendPluginOptions.

Package Metadata - Important for Package Publishers!

All @backstage/* packages now include a new set of metadata in package.json that helps associate related plugin packages with each other. This metadata is also required for all packages published through the @backstage/cli to the Backstage ecosystem. For this purpose, a new --publish flag has been added to the repo fix command. You can read more about this requirement and how to generate the metadata in the documentation section on Metadata for Published Packages.

Other Auth Improvements

The OneLogin auth implementation now lives in its own module, @backstage/plugin-auth-backend-module-onelogin-provider.

In some special use cases such as when you have read-replica databases, you may desire to not use the builtin zero-config plugin-to-plugin auth system that stores keys in the database. For those cases, there is now a new static mode where you supply key pairs in config that are used for this purpose. The howto is in the docs.

There is also a new general jwks external access method for those of you who want to externally call Backstage plugins using already-established token flows! Check out the docs. Contributed by @ryan-hanchett in #24681.

Scaffolder ui:widget: password notice

Using ui:widget: password does not treat the input as a secret in the Scaffolder, and can lead to exposing some secrets in plaintext, this implementation has been overridden to provide warnings to users that mistakenly use this component and will now render a warning message along with rendering the input in plaintext for additional indication.

Please use the ui:field: Secret option instead, as is mentioned in the using secrets documentation.

New Scaffolder Permissions

The Scaffolder plugin has been upgraded to include additional permissions:

• scaffolder.task.create
• scaffolder.task.cancel
• scaffolder.task.read

The new permissions allow you to control who should have read or write access to tasks.

Contributed by @Zaperex in #24518.

Route bindings via app-config

It is now possible to configure route bindings through static configuration, using the app.routes.bindings key. For example:

app:
  routes:
    bindings:
      catalog.createComponent: catalog-import.importPage

Is the equivalent of the following:

const app = createApp({
  // ...
  bindRoutes({ bind }) {
    bind(catalogPlugin.externalRoutes, {
      createComponent: catalogImportPlugin.routes.importPage,
    });
  },
});

Additionally, the following default targets have been added for external routes.

• For catalog:
  • createComponent binds to the Scaffolder page.
  • viewTechDoc binds to the TechDocs entity documentation page.
  • createFromTemplate binds to the Scaffolder selected template page
• For scaffolder:
  • registerComponent binds to the catalog import page.
  • viewTechDoc binds to the TechDocs entity documentation page.

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.

Test utilities

There is now a TestCaches class in @backstage/backend-test-utils that functions just like TestDatabases. This may help in testing out cache based flows against actual cache implementations, using testcontainers if available!

Notifications improvements

The notifications system has received numerous updates, including the ability to perform in-flight processing of notifications. The related signals subsystem now also powers real time updates of the user settings plugin. Thanks to the notifications maintainers for their tireless efforts in this exciting area!

Links and References

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

• Backstage official website, documentation, and getting started guide
• GitHub repository
• Backstage's versioning and support policy
• Community Discord for discussions and support
• Changelog
• Backstage Demos, Blog, Roadmap and Plugins

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

Big shoutout to all 64 of you amazing folks who chipped in on this release 🙏: @acierto, @adityak60, @adsk-mukul, @alexef, @andrei-ivanovici, @anicke, @aramissennyeydd, @awanlin, @benjdlambert, @benjidotsh, @bethgriggs, @brianphillips, @brunobastosg, @camilaibs, @cjlee01, @cmoulliard, @davidfestal, @debsmita1, @drodil, @dweber019, @elaine-mattos, @erik-adsk, @fabian-m-95, @freben, @grantila, @huggingpixels, @ismailmmd, @jeevaramanathan, @johanhammar, @jslott2sigma, @julien-hery, @kalleericson, @kissmikijr, @kuangp, @maetis, @marcpalm, @marcuseide, @mareklibra, @mario-mui, @matteosilv, @mclarke47, @npiyush97, @nurbaysymbat, @parsifal-m, @piatkiewicz, @raffitamizian, @rbillon59, @rewixe, @Rugvip, @ryan-hanchett, @sblausten, @snowblitzer, @stanislav-c, @stephenglass, @stijnbrouwers, @suniljose25, @tcardonne, @vadave, @veenarm, @vinisdl, @vinzscam, @waldirmontoya25, @ydayagi, @Zaperex