Releases · backstage/backstage

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.