Merge branch 'master' of https://github.com/backstage/backstage into add-additional-scaffolder-permissions
This commit is contained in:
Frank Kong
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 52 KiB After Width: | Height: | Size: 490 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 201 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 166 KiB |
@@ -71,7 +71,11 @@ This provider includes several resolvers out of the box that you can use:
|
||||
- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
|
||||
- `usernameMatchingUserEntityName`: Matches the username from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
|
||||
|
||||
> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
:::note Note
|
||||
|
||||
The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
|
||||
:::
|
||||
|
||||
If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.
|
||||
|
||||
|
||||
@@ -170,6 +170,5 @@ backend.add(customAuth);
|
||||
The body of the sign-in resolver is up to you to write! The example code above
|
||||
is just a copy of what `emailMatchingUserEntityProfileEmail` does. The `info`
|
||||
parameter contains all of the results of the sign-in attempt so far. The `ctx`
|
||||
context [has several useful
|
||||
functions](https://backstage.io/docs/reference/plugin-auth-node.authresolvercontext/)
|
||||
context [has several useful functions](https://backstage.io/docs/reference/plugin-auth-node.authresolvercontext/)
|
||||
for issuing tokens in various ways.
|
||||
|
||||
@@ -43,13 +43,12 @@ auth:
|
||||
# enterpriseInstanceUrl: ${AUTH_GITHUB_ENTERPRISE_INSTANCE_URL}
|
||||
signIn:
|
||||
resolvers:
|
||||
# typically you would pick one of these
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
# Matches the GitHub username with the Backstage user entity name.
|
||||
# See https://backstage.io/docs/auth/github/provider#resolvers for more resolvers.
|
||||
- resolver: usernameMatchingUserEntityName
|
||||
```
|
||||
|
||||
The GitHub provider is a structure with three configuration keys:
|
||||
The GitHub provider is a structure with these configuration keys:
|
||||
|
||||
- `clientId`: The client ID that you generated on GitHub, e.g.
|
||||
`b59241722e3c3b4816e2`
|
||||
@@ -60,6 +59,9 @@ The GitHub provider is a structure with three configuration keys:
|
||||
initiating an OAuth flow, e.g.
|
||||
`https://your-intermediate-service.com/handler`. Only needed if Backstage is
|
||||
not the immediate receiver (e.g. one OAuth app for many backstage instances).
|
||||
- `signIn`: The configuration for the sign-in process, including the **resolvers**
|
||||
that should be used to match the user from the auth provider with the user
|
||||
entity in the Backstage catalog (typically a single resolver is sufficient).
|
||||
|
||||
### Resolvers
|
||||
|
||||
@@ -69,7 +71,11 @@ This provider includes several resolvers out of the box that you can use:
|
||||
- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
|
||||
- `usernameMatchingUserEntityName`: Matches the username from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
|
||||
|
||||
> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
:::note
|
||||
|
||||
The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
|
||||
:::
|
||||
|
||||
If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.
|
||||
|
||||
|
||||
@@ -70,7 +70,11 @@ This provider includes several resolvers out of the box that you can use:
|
||||
- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
|
||||
- `usernameMatchingUserEntityName`: Matches the username from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
|
||||
|
||||
> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
:::note Note
|
||||
|
||||
The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
|
||||
:::
|
||||
|
||||
If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.
|
||||
|
||||
|
||||
@@ -50,7 +50,11 @@ This provider includes several resolvers out of the box that you can use:
|
||||
- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
|
||||
- `emailMatchingUserEntityAnnotation`: Matches the email address from the auth provider with the User entity where the value of the `google.com/email` annotation matches. If no match is found it will throw a `NotFoundError`.
|
||||
|
||||
> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
:::note Note
|
||||
|
||||
The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
|
||||
:::
|
||||
|
||||
If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.
|
||||
|
||||
|
||||
@@ -64,7 +64,11 @@ This provider includes several resolvers out of the box that you can use:
|
||||
- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
|
||||
- `emailMatchingUserEntityAnnotation`: Matches the email address from the auth provider with the User entity where the value of the `google.com/email` annotation matches. If no match is found it will throw a `NotFoundError`.
|
||||
|
||||
> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
:::note Note
|
||||
|
||||
The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
|
||||
:::
|
||||
|
||||
If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.
|
||||
|
||||
|
||||
@@ -5,8 +5,7 @@ description: An introduction to Backstage user identities and sign-in resolvers
|
||||
---
|
||||
|
||||
:::info
|
||||
This documentation is written for [the new backend
|
||||
system](../backend-system/index.md) which is the default since Backstage
|
||||
This documentation is written for [the new backend system](../backend-system/index.md) which is the default since Backstage
|
||||
[version 1.24](../releases/v1.24.0.md). If you are still on the old backend
|
||||
system, you may want to read [its own article](./identity-resolver--old.md)
|
||||
instead, and [consider migrating](../backend-system/building-backends/08-migrating.md)!
|
||||
@@ -31,15 +30,13 @@ testing purposes and quickly getting started locally, but is not safe for use in
|
||||
production and that particular provider will refuse to work there.
|
||||
|
||||
Because of this, one of the early things you want to do when standing up your
|
||||
Backstage instance is to choose a production ready auth provider. See [the auth
|
||||
overview page](./index.md) for a full list of providers and how to install and
|
||||
Backstage instance is to choose a production ready auth provider. See [the auth overview page](./index.md) for a full list of providers and how to install and
|
||||
configure them.
|
||||
|
||||
## Backstage User Identity
|
||||
|
||||
A user identity within Backstage is built up from two main pieces of
|
||||
information: a user [entity
|
||||
reference](../features/software-catalog/references.md), and a set of ownership
|
||||
information: a user [entity reference](../features/software-catalog/references.md), and a set of ownership
|
||||
references. When a user signs in, a Backstage token is generated which is then
|
||||
used to identify the user within the Backstage ecosystem.
|
||||
|
||||
@@ -194,8 +191,7 @@ backend.add(import('@backstage/plugin-auth-backend-module-github-provider'));
|
||||
backend.add(customAuth);
|
||||
```
|
||||
|
||||
Check out [the naming patterns
|
||||
article](../backend-system/architecture/07-naming-patterns.md) for what rules
|
||||
Check out [the naming patterns article](../backend-system/architecture/07-naming-patterns.md) for what rules
|
||||
apply regarding how to form valid IDs. In this example we also put the module
|
||||
declaration directly in `packages/backend/src/index.ts` but that's just for
|
||||
simplicity. You can place it anywhere you like, including in other packages, and
|
||||
@@ -244,8 +240,7 @@ async signInResolver(info, ctx) {
|
||||
If you throw an error in the sign in resolver function, the sign in attempt is
|
||||
immediately rejected, and the error details are presented in the user interface.
|
||||
|
||||
The `ctx` context [has several useful
|
||||
functions](https://backstage.io/docs/reference/plugin-auth-node.authresolvercontext/)
|
||||
The `ctx` context [has several useful functions](https://backstage.io/docs/reference/plugin-auth-node.authresolvercontext/)
|
||||
for issuing tokens in various ways.
|
||||
|
||||
### Custom Ownership Resolution
|
||||
|
||||
+16
-8
@@ -10,12 +10,16 @@ configure Backstage to have any number of authentication providers, but only
|
||||
one of these will typically be used for sign-in, with the rest being used to provide
|
||||
access to external resources.
|
||||
|
||||
> NOTE: Identity management and the Sign-In page in Backstage is NOT a method for blocking
|
||||
> access for unauthorized users. The identity system only serves to provide a personalized
|
||||
> experience and access to a Backstage Identity Token, which can be passed to backend plugins.
|
||||
> This also means that your Backstage backend APIs are by default unauthenticated.
|
||||
> Thus, if your Backstage instance is exposed to the Internet, anyone can access
|
||||
> information in the Backstage. You can learn more [here](../overview/threat-model.md#integrator-responsibilities).
|
||||
:::note Note
|
||||
|
||||
Identity management and the Sign-In page in Backstage is NOT a method for blocking
|
||||
access for unauthorized users. The identity system only serves to provide a personalized
|
||||
experience and access to a Backstage Identity Token, which can be passed to backend plugins.
|
||||
This also means that your Backstage backend APIs are by default unauthenticated.
|
||||
Thus, if your Backstage instance is exposed to the Internet, anyone can access
|
||||
information in the Backstage. You can learn more [here](../overview/threat-model.md#integrator-responsibilities).
|
||||
|
||||
:::
|
||||
|
||||
## Built-in Authentication Providers
|
||||
|
||||
@@ -141,8 +145,12 @@ const app = createApp({
|
||||
});
|
||||
```
|
||||
|
||||
> NOTE: You can configure sign-in to use a redirect flow with no pop-up by adding
|
||||
> `enableExperimentalRedirectFlow: true` to the root of your `app-config.yaml`
|
||||
:::note Note
|
||||
|
||||
You can configure sign-in to use a redirect flow with no pop-up by adding
|
||||
`enableExperimentalRedirectFlow: true` to the root of your `app-config.yaml`
|
||||
|
||||
:::
|
||||
|
||||
## Sign-In with Proxy Providers
|
||||
|
||||
|
||||
@@ -84,7 +84,11 @@ This provider includes several resolvers out of the box that you can use:
|
||||
- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
|
||||
- `emailMatchingUserEntityAnnotation`: Matches the email address from the auth provider with the User entity where the value of the `microsoft.com/email` annotation matches. If no match is found it will throw a `NotFoundError`.
|
||||
|
||||
> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
:::note Note
|
||||
|
||||
The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
|
||||
:::
|
||||
|
||||
If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.
|
||||
|
||||
@@ -103,6 +107,5 @@ hosts:
|
||||
- `login.microsoftonline.com`, to get and exchange authorization codes and access
|
||||
tokens
|
||||
- `graph.microsoft.com`, to fetch user profile information (as seen
|
||||
in [this source
|
||||
code](https://github.com/seanfisher/passport-microsoft/blob/0456aa9bce05579c18e77f51330176eb26373658/lib/strategy.js#L93-L95)).
|
||||
in [this source code](https://github.com/seanfisher/passport-microsoft/blob/0456aa9bce05579c18e77f51330176eb26373658/lib/strategy.js#L93-L95)).
|
||||
If this host is unreachable, users may see an `Authentication failed, failed to fetch user profile` error when they attempt to log in.
|
||||
|
||||
@@ -40,7 +40,11 @@ This provider includes several resolvers out of the box that you can use:
|
||||
- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
|
||||
- `forwardedUserMatchingUserEntityName`: Matches the value in the `x-forwarded-user` header from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
|
||||
|
||||
> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
:::note Note
|
||||
|
||||
The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
|
||||
:::
|
||||
|
||||
If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.
|
||||
|
||||
|
||||
@@ -75,7 +75,11 @@ This provider includes several resolvers out of the box that you can use:
|
||||
- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
|
||||
- `emailMatchingUserEntityAnnotation`: Matches the email address from the auth provider with the User entity where the value of the `okta.com/email` annotation matches. If no match is found it will throw a `NotFoundError`.
|
||||
|
||||
> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
:::note Note
|
||||
|
||||
The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
|
||||
:::
|
||||
|
||||
If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.
|
||||
|
||||
|
||||
@@ -6,8 +6,7 @@ description: This section describes service to service authentication works, bot
|
||||
---
|
||||
|
||||
:::info
|
||||
This documentation is written for [the new backend
|
||||
system](../backend-system/index.md) which is the default since Backstage
|
||||
This documentation is written for [the new backend system](../backend-system/index.md) which is the default since Backstage
|
||||
[version 1.24](../releases/v1.24.0.md). If you are still on the old backend
|
||||
system, you may want to read [its own article](./service-to-service-auth--old.md)
|
||||
instead, and [consider migrating](../backend-system/building-backends/08-migrating.md)!
|
||||
|
||||
@@ -12,14 +12,11 @@ Cloud Console and within a Backstage app required to enable this capability.
|
||||
## Create an OAuth App in the VMware Cloud Console
|
||||
|
||||
1. Log in to the [VMware Cloud Console](https://console.cloud.vmware.com).
|
||||
1. Navigate to [Identity & Access Management > OAuth
|
||||
Apps](https://console.cloud.vmware.com/csp/gateway/portal/#/consumer/usermgmt/oauth-apps)
|
||||
and click the [Owned
|
||||
Apps](https://console.cloud.vmware.com/csp/gateway/portal/#/consumer/usermgmt/oauth-apps/owned-apps/view)
|
||||
1. Navigate to [Identity & Access Management > OAuth Apps](https://console.cloud.vmware.com/csp/gateway/portal/#/consumer/usermgmt/oauth-apps)
|
||||
and click the [Owned Apps](https://console.cloud.vmware.com/csp/gateway/portal/#/consumer/usermgmt/oauth-apps/owned-apps/view)
|
||||
tab -- if you are not an Organization Owner or Administrator but only a
|
||||
Member, you will not see this nav entry unless the **Developer** check box is
|
||||
selected for your role (see the [Organization roles and
|
||||
permissions](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-C11D3AAC-267C-4F16-A0E3-3EDF286EBE53.html#organization-roles-and-permissions-0)
|
||||
selected for your role (see the [Organization roles and permissions](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-C11D3AAC-267C-4F16-A0E3-3EDF286EBE53.html#organization-roles-and-permissions-0)
|
||||
docs for details).
|
||||
1. Click **Create App**, choose 'Web/Mobile app' and click **Continue**.
|
||||
1. Use default settings except:
|
||||
@@ -161,8 +158,7 @@ auth:
|
||||
```
|
||||
|
||||
Where `APP_ID` refers to the ID retrieved when creating the OAuth App, and
|
||||
`ORG_ID` is the [long ID of the
|
||||
Organization](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-CF9E9318-B811-48CF-8499-9419997DC1F8.html#view-the-organization-id-1)
|
||||
`ORG_ID` is the [long ID of the Organization](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-CF9E9318-B811-48CF-8499-9419997DC1F8.html#view-the-organization-id-1)
|
||||
in VMware Cloud for which you wish to enable sign-in.
|
||||
|
||||
Note that VMware Cloud requires OAuth Apps to use
|
||||
@@ -180,6 +176,10 @@ This provider includes several resolvers out of the box that you can use:
|
||||
- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
|
||||
- `vmwareCloudSignInResolvers`: Matches the email address from the auth provider with the User entity that has a matching `spec.profile.email`. If no match is found it will sign in the user without associating with a catalog user.
|
||||
|
||||
> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
:::note Note
|
||||
|
||||
The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
|
||||
:::
|
||||
|
||||
If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.
|
||||
|
||||
@@ -6,8 +6,12 @@ sidebar_label: Overview
|
||||
description: Building backends using the new backend system
|
||||
---
|
||||
|
||||
> NOTE: If you have an existing backend that is not yet using the new backend
|
||||
> system, see [migrating](./08-migrating.md).
|
||||
:::note Note
|
||||
|
||||
If you have an existing backend that is not yet using the new backend
|
||||
system, see [migrating](./08-migrating.md).
|
||||
|
||||
:::
|
||||
|
||||
This section covers how to set up and customize your own Backstage backend. It covers some aspects of how backend instances fit into the larger system, but for a more in-depth explanation of the role of backends in the backend system, see [the architecture section](../architecture/02-backends.md).
|
||||
|
||||
|
||||
@@ -201,10 +201,14 @@ const legacyPlugin = makeLegacyPlugin(
|
||||
After this, your backend will know how to instantiate your thing on demand and
|
||||
place it in the legacy plugin environment.
|
||||
|
||||
> NOTE: If you happen to be dealing with a service ref that does NOT have a
|
||||
> default implementation, but rather has a separate service factory, then you
|
||||
> will also need to import that factory and pass it to the `services` array
|
||||
> argument of `createBackend`.
|
||||
:::note Note
|
||||
|
||||
If you happen to be dealing with a service ref that does NOT have a
|
||||
default implementation, but rather has a separate service factory, then you
|
||||
will also need to import that factory and pass it to the `services` array
|
||||
argument of `createBackend`.
|
||||
|
||||
:::
|
||||
|
||||
## Cleaning Up the Plugins Folder
|
||||
|
||||
@@ -216,10 +220,14 @@ maintained by the Backstage maintainers, you may find that they have already
|
||||
been migrated to the new backend system. This section describes some specific
|
||||
such migrations you can make.
|
||||
|
||||
> NOTE: For each of these, note that your backend still needs to have a
|
||||
> dependency (e.g. in `packages/backend/package.json`) to those plugin packages,
|
||||
> and they still need to be configured properly in your app-config. Those
|
||||
> mechanisms still work just the same as they used to in the old backend system.
|
||||
:::note Note
|
||||
|
||||
For each of these, note that your backend still needs to have a
|
||||
dependency (e.g. in `packages/backend/package.json`) to those plugin packages,
|
||||
and they still need to be configured properly in your app-config. Those
|
||||
mechanisms still work just the same as they used to in the old backend system.
|
||||
|
||||
:::
|
||||
|
||||
### The App Plugin
|
||||
|
||||
@@ -452,7 +460,7 @@ catalog:
|
||||
/* highlight-add-end */
|
||||
```
|
||||
|
||||
To migrate `GithubMultiOrgEntityProvider` and `GithubOrgEntityProvider` to the new backend system, add a reference to `@backstage/plugin-catalog-backend-module-github-org`.
|
||||
To migrate `GithubMultiOrgEntityProvider` or `GithubOrgEntityProvider` to the new backend system, add a reference to `@backstage/plugin-catalog-backend-module-github-org`.
|
||||
|
||||
```ts title="packages/backend/src/index.ts"
|
||||
backend.add(import('@backstage/plugin-catalog-backend/alpha'));
|
||||
@@ -461,20 +469,79 @@ backend.add(import('@backstage/plugin-catalog-backend-module-github-org'));
|
||||
/* highlight-add-end */
|
||||
```
|
||||
|
||||
If you were providing a `schedule` in code, this now needs to be set via configuration.
|
||||
All other Github configuration in `app-config.yaml` remains the same.
|
||||
##### GithubOrgEntityProvider
|
||||
|
||||
If you were using `GithubOrgEntityProvider` you might have been configured in code like this:
|
||||
|
||||
```ts title="packages/backend/src/plugins/catalog.ts"
|
||||
// The org URL below needs to match a configured integrations.github entry
|
||||
// specified in your app-config.
|
||||
builder.addEntityProvider(
|
||||
GithubOrgEntityProvider.fromConfig(env.config, {
|
||||
id: 'production',
|
||||
orgUrl: 'https://github.com/backstage',
|
||||
logger: env.logger,
|
||||
schedule: env.scheduler.createScheduledTaskRunner({
|
||||
frequency: { minutes: 60 },
|
||||
timeout: { minutes: 15 },
|
||||
}),
|
||||
}),
|
||||
);
|
||||
```
|
||||
|
||||
This now needs to be set via configuration. The options defined above are now set in `app-config.yaml` instead as shown below:
|
||||
|
||||
```yaml title="app-config.yaml"
|
||||
catalog:
|
||||
/* highlight-add-start */
|
||||
providers:
|
||||
githubOrg:
|
||||
yourProviderId:
|
||||
# ...
|
||||
/* highlight-add-start */
|
||||
- id: production
|
||||
githubUrl: 'https://github.com',
|
||||
orgs: ['backstage']
|
||||
schedule:
|
||||
frequency: PT30M
|
||||
timeout: PT3M
|
||||
/* highlight-add-end */
|
||||
timeout: PT15M
|
||||
/* highlight-add-end */
|
||||
```
|
||||
|
||||
##### GithubMultiOrgEntityProvider
|
||||
|
||||
If you were using `GithubMultiOrgEntityProvider` you might have been configured in code like this:
|
||||
|
||||
```ts title="packages/backend/src/plugins/catalog.ts"
|
||||
// The GitHub URL below needs to match a configured integrations.github entry
|
||||
// specified in your app-config.
|
||||
builder.addEntityProvider(
|
||||
GithubMultiOrgEntityProvider.fromConfig(env.config, {
|
||||
id: 'production',
|
||||
githubUrl: 'https://github.com',
|
||||
// Set the following to list the GitHub orgs you wish to ingest from. You can
|
||||
// also omit this option to ingest all orgs accessible by your GitHub integration
|
||||
orgs: ['org-a', 'org-b'],
|
||||
logger: env.logger,
|
||||
schedule: env.scheduler.createScheduledTaskRunner({
|
||||
frequency: { minutes: 60 },
|
||||
timeout: { minutes: 15 },
|
||||
}),
|
||||
}),
|
||||
);
|
||||
```
|
||||
|
||||
This now needs to be set via configuration. The options defined above are now set in `app-config.yaml` instead as shown below:
|
||||
|
||||
```yaml title="app-config.yaml"
|
||||
catalog:
|
||||
/* highlight-add-start */
|
||||
providers:
|
||||
githubOrg:
|
||||
- id: production
|
||||
githubUrl: 'https://github.com',
|
||||
orgs: ['org-a', 'org-b'],
|
||||
schedule:
|
||||
frequency: PT30M
|
||||
timeout: PT15M
|
||||
/* highlight-add-end */
|
||||
```
|
||||
|
||||
If you were providing transformers, these can be configured by extending `githubOrgEntityProviderTransformsExtensionPoint`
|
||||
@@ -821,7 +888,11 @@ auth:
|
||||
- resolver: emailMatchingUserEntityAnnotation
|
||||
```
|
||||
|
||||
> Note: the resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
:::note Note
|
||||
|
||||
The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
|
||||
|
||||
:::
|
||||
|
||||
#### Auth Plugin Modules and Their Resolvers
|
||||
|
||||
@@ -1078,7 +1149,11 @@ backend.add(import('@backstage/plugin-search-backend/alpha'));
|
||||
/* highlight-add-end */
|
||||
```
|
||||
|
||||
> Note: this will use the Lunr search engine which stores its index in memory
|
||||
:::note Note
|
||||
|
||||
This will use the Lunr search engine which stores its index in memory.
|
||||
|
||||
:::
|
||||
|
||||
#### Search Engines
|
||||
|
||||
@@ -1167,7 +1242,11 @@ backend.add(
|
||||
/* highlight-add-end */
|
||||
```
|
||||
|
||||
> Note: The above example includes a default allow-all policy. If that is not what you want, do not add the second line and instead investigate one of the options below.
|
||||
:::note Note
|
||||
|
||||
The above example includes a default allow-all policy. If that is not what you want, do not add the second line and instead investigate one of the options below.
|
||||
|
||||
:::
|
||||
|
||||
#### Custom Permission Policy
|
||||
|
||||
|
||||
@@ -73,8 +73,7 @@ items.
|
||||
Backend modules are used to extend [plugins](../architecture/04-plugins.md) or other modules with
|
||||
additional features or change existing behavior. They must always be installed
|
||||
in the same backend instance as the plugin or module that they extend, and may only extend a single plugin and modules from that plugin at a time.
|
||||
Modules interact with their target plugin or module using the [extension
|
||||
points](../architecture/05-extension-points.md) registered by the plugin, while also being
|
||||
Modules interact with their target plugin or module using the [extension points](../architecture/05-extension-points.md) registered by the plugin, while also being
|
||||
able to depend on the [services](../architecture/03-services.md) of the target plugin.
|
||||
That last point is worth reiterating: injected `plugin` scoped services will be
|
||||
the exact
|
||||
@@ -157,8 +156,7 @@ the database. They will run on the same logical database instance as the target
|
||||
plugin, so care must be taken to choose table names that do not risk colliding
|
||||
with those of the plugin. A recommended naming pattern is `<package
|
||||
name>__<table name>`, for example the `@backstage/backend-tasks` package creates
|
||||
tables named `backstage_backend_tasks__<table>`. If you use the default [`Knex`
|
||||
migration facilities](https://knexjs.org/guide/migrations.html), you will also
|
||||
tables named `backstage_backend_tasks__<table>`. If you use the default [`Knex` migration facilities](https://knexjs.org/guide/migrations.html), you will also
|
||||
want to make sure that it uses similarly prefixed migration state tables for its
|
||||
internal bookkeeping needs, so they do not collide with the main ones used by
|
||||
the plugin itself. You can do this as follows:
|
||||
@@ -179,8 +177,7 @@ There are several ways of configuring and customizing plugins and modules.
|
||||
Whenever you want to allow modules to configure your plugin dynamically, for
|
||||
example in the way that the catalog backend lets catalog modules inject
|
||||
additional entity providers, you can use the extension points mechanism. This is
|
||||
described in detail with code examples in [the extension points architecture
|
||||
article](../architecture/05-extension-points.md), while the following is a more
|
||||
described in detail with code examples in [the extension points architecture article](../architecture/05-extension-points.md), while the following is a more
|
||||
slim example of how to implement an extension point for a plugin:
|
||||
|
||||
```ts
|
||||
@@ -249,7 +246,5 @@ export const examplePlugin = createBackendPlugin({
|
||||
});
|
||||
```
|
||||
|
||||
Before adding custom configuration options, make sure to read [the configuration
|
||||
docs](../../conf/index.md), in particular the section on [defining configuration
|
||||
for your own plugins](../../conf/defining.md) which explains how to establish a
|
||||
Before adding custom configuration options, make sure to read [the configuration docs](../../conf/index.md), in particular the section on [defining configuration for your own plugins](../../conf/defining.md) which explains how to establish a
|
||||
configuration schema for your specific plugin.
|
||||
|
||||
@@ -21,8 +21,7 @@ collective term for backend [plugins](../architecture/04-plugins.md) and
|
||||
|
||||
The function returns an HTTP server instance which can be used together with
|
||||
e.g. `supertest` to easily test the actual REST service surfaces of plugins who
|
||||
register routes with [the HTTP router service
|
||||
API](../core-services/01-index.md).
|
||||
register routes with [the HTTP router service API](../core-services/01-index.md).
|
||||
|
||||
```ts
|
||||
import { mockServices, startTestBackend } from '@backstage/backend-test-utils';
|
||||
|
||||
@@ -141,8 +141,12 @@ browser at `http://localhost:7007`
|
||||
|
||||
## Multi-stage Build
|
||||
|
||||
> NOTE: The `.dockerignore` is different in this setup, read on for more
|
||||
> details.
|
||||
:::note Note
|
||||
|
||||
The `.dockerignore` is different in this setup, read on for more
|
||||
details.
|
||||
|
||||
:::
|
||||
|
||||
This section describes how to set up a multi-stage Docker build that builds the
|
||||
entire project within Docker. This is typically slower than a host build, but is
|
||||
@@ -293,10 +297,14 @@ browser at `http://localhost:7007`
|
||||
|
||||
## Separate Frontend
|
||||
|
||||
> NOTE: This is an optional step, and you will lose out on the features of the
|
||||
> `@backstage/plugin-app-backend` plugin. Most notably the frontend configuration
|
||||
> will no longer be injected by the backend, you will instead need to use the
|
||||
> correct configuration when building the frontend bundle.
|
||||
:::note Note
|
||||
|
||||
This is an optional step, and you will lose out on the features of the
|
||||
`@backstage/plugin-app-backend` plugin. Most notably the frontend configuration
|
||||
will no longer be injected by the backend, you will instead need to use the
|
||||
correct configuration when building the frontend bundle.
|
||||
|
||||
:::
|
||||
|
||||
It is sometimes desirable to serve the frontend separately from the backend,
|
||||
either from a separate image or for example a static file serving provider. The
|
||||
|
||||
@@ -13,8 +13,12 @@ This documentation shows common examples that may be useful when deploying
|
||||
Backstage for the first time, or for those without established deployment
|
||||
practices.
|
||||
|
||||
> Note: The _easiest_ way to explore Backstage is to visit the
|
||||
> [live demo site](https://demo.backstage.io).
|
||||
:::note Note
|
||||
|
||||
The _easiest_ way to explore Backstage is to visit the
|
||||
[live demo site](https://demo.backstage.io).
|
||||
|
||||
:::
|
||||
|
||||
At Spotify, we deploy software generally by:
|
||||
|
||||
|
||||
@@ -107,10 +107,14 @@ $ echo -n "backstage" | base64
|
||||
YmFja3N0YWdl
|
||||
```
|
||||
|
||||
> Note: Secrets are base64-encoded, but not encrypted. Be sure to enable
|
||||
> [Encryption at Rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/)
|
||||
> for the cluster. For storing secrets in Git, consider
|
||||
> [SealedSecrets or other solutions](https://learnk8s.io/kubernetes-secrets-in-git).
|
||||
:::note Note
|
||||
|
||||
Secrets are base64-encoded, but not encrypted. Be sure to enable
|
||||
[Encryption at Rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/)
|
||||
for the cluster. For storing secrets in Git, consider
|
||||
[SealedSecrets or other solutions](https://learnk8s.io/kubernetes-secrets-in-git).
|
||||
|
||||
:::
|
||||
|
||||
The secrets can now be applied to the Kubernetes cluster:
|
||||
|
||||
|
||||
@@ -198,8 +198,7 @@ in namespace `NAMESPACE` and it has adequate
|
||||
[permissions](#role-based-access-control), here are some sample procedures to
|
||||
procure a long-lived service account token for use with this provider:
|
||||
|
||||
- On versions of Kubernetes [prior to
|
||||
1.24](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.24.md#no-really-you-must-read-this-before-you-upgrade-1),
|
||||
- On versions of Kubernetes [prior to 1.24](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.24.md#no-really-you-must-read-this-before-you-upgrade-1),
|
||||
you could get an (automatically-generated) token for a service account with:
|
||||
|
||||
```sh
|
||||
@@ -209,8 +208,7 @@ procure a long-lived service account token for use with this provider:
|
||||
| base64 --decode
|
||||
```
|
||||
|
||||
- For Kubernetes 1.24+, as described in [this
|
||||
guide](https://kubernetes.io/docs/concepts/configuration/secret/#service-account-token-secrets),
|
||||
- For Kubernetes 1.24+, as described in [this guide](https://kubernetes.io/docs/concepts/configuration/secret/#service-account-token-secrets),
|
||||
you can obtain a long-lived token by creating a secret:
|
||||
|
||||
```sh
|
||||
@@ -235,8 +233,7 @@ procure a long-lived service account token for use with this provider:
|
||||
If a cluster has `authProvider: serviceAccount` and the `serviceAccountToken`
|
||||
field is omitted, Backstage will ignore the configured URL and certificate data,
|
||||
instead attempting to access the Kubernetes API via an in-cluster client as in
|
||||
[this
|
||||
example](https://github.com/kubernetes-client/javascript/blob/master/examples/in-cluster.js).
|
||||
[this example](https://github.com/kubernetes-client/javascript/blob/master/examples/in-cluster.js).
|
||||
|
||||
##### `clusters.\*.oidcTokenProvider` (optional)
|
||||
|
||||
|
||||
@@ -7,12 +7,10 @@ description: Interacting with the Kubernetes API in Backstage plugins
|
||||
|
||||
[Contributors](https://backstage.io/docs/overview/glossary#backstage-user-profiles) wanting to
|
||||
create developer portal experiences based on data from Kubernetes (e.g. for
|
||||
interacting with [Custom
|
||||
Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
|
||||
interacting with [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
|
||||
beyond the default behaviors of the existing Kubernetes plugin) can leverage the
|
||||
Kubernetes backend plugin's proxy endpoint to allow them to make arbitrary
|
||||
requests to the [REST
|
||||
API](https://kubernetes.io/docs/reference/using-api/api-concepts/).
|
||||
requests to the [REST API](https://kubernetes.io/docs/reference/using-api/api-concepts/).
|
||||
|
||||
Here is a snippet fetching namespaces using the `KubernetesBackendClient` library
|
||||
|
||||
@@ -31,8 +29,7 @@ await kubernetesApi.proxy(CLUSTER_NAME, '/api/v1/namespaces');
|
||||
The proxy will interpret the
|
||||
[`Backstage-Kubernetes-Cluster`](https://backstage.io/docs/reference/plugin-kubernetes-backend.header_kubernetes_cluster)
|
||||
header as the name of the cluster to target. This name will be compared to each cluster
|
||||
returned by all the configured [cluster
|
||||
locators](https://backstage.io/docs/features/kubernetes/configuration#clusterlocatormethods)
|
||||
returned by all the configured [cluster locators](https://backstage.io/docs/features/kubernetes/configuration#clusterlocatormethods)
|
||||
-- the first cluster whose [`name` field](https://backstage.io/docs/features/kubernetes/configuration#clustersname) matches
|
||||
the value in the header will be targeted.
|
||||
|
||||
@@ -48,12 +45,10 @@ The proxy expects a `KubernetesAuthTranslator` to be provided that is used to de
|
||||
## Authentication
|
||||
|
||||
The proxy has no provisions for mTLS, so it cannot be used to connect to
|
||||
clusters using the [x509 Client
|
||||
Certs](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#x509-client-certs)
|
||||
clusters using the [x509 Client Certs](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#x509-client-certs)
|
||||
authentication strategy.\
|
||||
The current `/proxy` Implementation expects a
|
||||
[Bearer
|
||||
token](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#putting-a-bearer-token-in-a-request)
|
||||
[Bearer token](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#putting-a-bearer-token-in-a-request)
|
||||
to be provided as a `Backstage-Kubernetes-Authorization` header for a target cluster. This token will be used as the `Authorization` header when forwarding a request to a target cluster.
|
||||
|
||||
## How to disable the proxy endpoint via PermissionPolicy
|
||||
@@ -104,8 +99,7 @@ even if a valid ID token was attached that a cluster would authorize.
|
||||
|
||||
## Other known limitations
|
||||
|
||||
The proxy as it was released in [Backstage
|
||||
1.9](https://github.com/backstage/backstage/blob/master/docs/releases/v1.9.0-changelog.md#patch-changes-15)
|
||||
The proxy as it was released in [Backstage 1.9](../../releases/v1.9.0-changelog.md#patch-changes-15)
|
||||
has a known bug:
|
||||
|
||||
- [#15901](https://github.com/backstage/backstage/issues/15901) - it cannot
|
||||
|
||||
@@ -40,8 +40,7 @@ browse the catalog at `http://localhost:3000`.
|
||||
|
||||
## Adding components to the catalog
|
||||
|
||||
The source of truth for the components in your software catalog are [metadata
|
||||
YAML files](descriptor-format.md) stored in source control (GitHub, GitHub
|
||||
The source of truth for the components in your software catalog are [metadata YAML files](descriptor-format.md) stored in source control (GitHub, GitHub
|
||||
Enterprise, GitLab, ...). Repositories can include one or multiple metadata
|
||||
files. Usually the metadata file is located in the repository root. This is not
|
||||
a formal requirement & metadata files can be placed anywhere in the repository.
|
||||
|
||||
@@ -120,6 +120,9 @@ product or use-case, share the same entity types in their APIs, and integrate
|
||||
well with each other. Other domains could be “Content Ingestion”, “Ads” or
|
||||
“Search”.
|
||||
|
||||
In case of a large organization, it might make sense to further group domains
|
||||
in a hierarchy, where a domain can be a subdomain of another domain.
|
||||
|
||||
## Other
|
||||
|
||||
### Location
|
||||
|
||||
@@ -103,3 +103,17 @@ from `backstage/packages/app/src/App.tsx`:
|
||||
```
|
||||
|
||||
After the change, you should no longer see the button.
|
||||
|
||||
## Previewing and Executing Previous Template Tasks
|
||||
|
||||
Each execution of a template is treated as a unique task, identifiable by its own unique ID. To view a list of previously executed template tasks, navigate to the "Create" page and access the "Task List" from the context menu (represented by the vertical ellipsis, or 'kebab menu', icon in the upper right corner).
|
||||
|
||||
|
||||
|
||||
If you wish to re-run a previously executed template, navigate to the template tasks page. Locate the desired task and select the "Start Over" option from the context menu.
|
||||
|
||||
|
||||
|
||||
This action will initiate a new execution of the selected template, pre-populated with the same parameters as the previous run, but these parameters can be edited before re-execution.
|
||||
|
||||
In the event of a failed template execution, the "Start Over" option can be used to re-execute the template. The parameters from the original run will be pre-filled, but they can be adjusted as needed before retrying the template.
|
||||
|
||||
@@ -22,10 +22,10 @@ In order to override an app extension, you must create a new extension and add i
|
||||
|
||||
In the example below, we create a file that exports custom extensions for the app's `light` and `dark` themes:
|
||||
|
||||
```tsx title="packages/app/src/themes.ts"
|
||||
```tsx title="packages/app/src/themes.tsx"
|
||||
import {
|
||||
createThemeExtension,
|
||||
createExtensionOverrides
|
||||
createExtensionOverrides,
|
||||
} from '@backstage/frontend-plugin-api';
|
||||
import { apertureThemes } from './themes';
|
||||
import { ApertureLightIcon, ApertureDarkIcon } from './icons';
|
||||
@@ -59,8 +59,8 @@ const apertureDarkTheme = createThemeExtension({
|
||||
});
|
||||
|
||||
// Creating an extension overrides preset
|
||||
export createExtensionOverrides({
|
||||
extensions: [apertureLightTheme, apertureDarkTheme]
|
||||
export default createExtensionOverrides({
|
||||
extensions: [apertureLightTheme, apertureDarkTheme],
|
||||
});
|
||||
```
|
||||
|
||||
@@ -96,8 +96,11 @@ We recommend that plugin developers share the extension IDs in their plugin docu
|
||||
|
||||
Imagine you have a plugin with the ID `'search'`, and the plugin provides a page extension that you want to fully override with your own custom component. To do so, you need to create your page extension with an explicit `namespace` option that matches that of the plugin that you want to override, in this case `'search'`. If the existing extension also has an explicit `name` you'd need to set the `name` of your override extension to the same value as well.
|
||||
|
||||
```tsx title="packages/app/src/search.ts"
|
||||
import { createPageExtension } from '@backstage/frontend-plugin-api';
|
||||
```tsx title="packages/app/src/search.tsx"
|
||||
import {
|
||||
createPageExtension,
|
||||
createExtensionOverrides,
|
||||
} from '@backstage/frontend-plugin-api';
|
||||
|
||||
// Creating a custom search page extension
|
||||
const customSearchPage = createPageExtension({
|
||||
@@ -108,7 +111,7 @@ const customSearchPage = createPageExtension({
|
||||
loader: () => import('./SearchPage').then(m => m.<SearchPage/>),
|
||||
});
|
||||
|
||||
export createExtensionOverrides({
|
||||
export default createExtensionOverrides({
|
||||
extensions: [customSearchPage]
|
||||
});
|
||||
```
|
||||
@@ -137,7 +140,7 @@ Sometimes you just need to quickly create a new extension and not overwrite an a
|
||||
|
||||
Imagine you want to create a page that is currently only used by your application, like an Institutional page, for example. You can use overrides to extend the Backstage app to render it. To do so, simply create a page extension and pass it to the app as an override:
|
||||
|
||||
```tsx title="packages/app/src/App.ts"
|
||||
```tsx title="packages/app/src/App.tsx"
|
||||
import { createApp } from '@backstage/frontend-app-api';
|
||||
import {
|
||||
createPageExtension,
|
||||
|
||||
@@ -28,9 +28,11 @@ integrations:
|
||||
token: ${GHE_TOKEN}
|
||||
```
|
||||
|
||||
> Note: A public GitHub provider is added automatically at startup for
|
||||
> convenience, so you only need to list it if you want to supply a
|
||||
> [token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token).
|
||||
:::note Note
|
||||
|
||||
A public GitHub provider is added automatically at startup for convenience, so you only need to list it if you want to supply a [token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token).
|
||||
|
||||
:::
|
||||
|
||||
Directly under the `github` key is a list of provider configurations, where you
|
||||
can list the various GitHub-compatible providers you want to be able to fetch
|
||||
|
||||
@@ -308,8 +308,7 @@ const githubOrgProvider = GithubOrgEntityProvider.fromConfig(env.config, {
|
||||
});
|
||||
```
|
||||
|
||||
Once you have imported the emails you can resolve users in your [sign-in
|
||||
resolver](../../auth/github/provider.md) using the catalog entity search via email
|
||||
Once you have imported the emails you can resolve users in your [sign-in resolver](../../auth/github/provider.md) using the catalog entity search via email
|
||||
|
||||
```typescript title="packages/backend/src/plugins/auth.ts"
|
||||
ctx.signInWithCatalogUser({
|
||||
|
||||
@@ -45,7 +45,7 @@ Next add the basic configuration to `app-config.yaml`
|
||||
catalog:
|
||||
providers:
|
||||
githubOrg:
|
||||
id: github
|
||||
id: production
|
||||
githubUrl: https://github.com
|
||||
orgs: ['organization-1', 'organization-2', 'organization-3']
|
||||
schedule:
|
||||
@@ -90,7 +90,7 @@ Directly under the `githubOrg` is a list of configurations, each entry is a stru
|
||||
|
||||
- `id`: A stable id for this provider. Entities from this provider will be associated with this ID, so you should take care not to change it over time since that may lead to orphaned entities and/or conflicts.
|
||||
- `githubUrl`: The target that this provider should consume
|
||||
- `orgs` (optional): The list of the GitHub orgs to consume. By default wil consume all accessible orgs on the given GitHub instance (support for GitHub App integration only).
|
||||
- `orgs` (optional): The list of the GitHub orgs to consume. If you only list a single org the generated group entities will use the `default` namespace, otherwise they will use the org name as the namespace. By default the provider will consume all accessible orgs on the given GitHub instance (support for GitHub App integration only).
|
||||
- `schedule`: The refresh schedule to use, matches the structure of [`TaskScheduleDefinitionConfig`](https://backstage.io/docs/reference/backend-tasks.taskscheduledefinitionconfig/)
|
||||
|
||||
### Events Support
|
||||
|
||||
@@ -19,9 +19,11 @@ integrations:
|
||||
token: ${GITLAB_TOKEN}
|
||||
```
|
||||
|
||||
> Note: A public GitLab provider is added automatically at startup for
|
||||
> convenience, so you only need to list it if you want to supply a
|
||||
> [token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html).
|
||||
:::note Note
|
||||
|
||||
A public GitLab provider is added automatically at startup for convenience, so you only need to list it if you want to supply a [token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html).
|
||||
|
||||
:::
|
||||
|
||||
Directly under the `gitlab` key is a list of provider configurations, where you
|
||||
can list the GitLab providers you want to fetch data from. Each entry is a
|
||||
|
||||
+58
-64
@@ -6,93 +6,87 @@ description: Roadmap of Backstage
|
||||
|
||||
## The Backstage Roadmap
|
||||
|
||||
Backstage is currently under rapid development. This page details the project's
|
||||
public roadmap, the result of ongoing collaboration between the core maintainers
|
||||
and the broader Backstage community.
|
||||
Backstage is still under rapid development, and this page details the project's
|
||||
public roadmap. This not a complete list of all work happening in and around the
|
||||
project, it only highlights the highest priority initiatives worked on by the
|
||||
core maintainers.
|
||||
|
||||
The Backstage roadmap lays out both [“what's next”](#whats-next) and ["future
|
||||
work"](#future-work). With "next" we mean features planned for release within
|
||||
the ongoing quarter from July through September 2022. With "future" we mean
|
||||
features on the radar, but not yet scheduled.
|
||||
## 2024 Fall Roadmap
|
||||
|
||||
| [What's next](#whats-next) | [Future work](#future-work) |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| [Backend Services (MVP)](#backend-services-mvp) <br/> [Backstage Security Audit](#backstage-security-audit) <br/> [Backstage Threat Model](#backstage-threat-model) <br/> [Software Catalog pagination](#software-catalog-pagination) <br/> [More SIGs](#more-sigs) | Ease of onboarding <br/> Composable Homepage 1.0 <br/> Creator experience <br/> GraphQL <br/> Telemetry |
|
||||
The initiatives listed below are planned for release within the next half-year, starting in May 2024. The roadmap is updated every 6 months, and the next update is planned for November 2024.
|
||||
|
||||
The long-term roadmap (12 - 36 months) is not detailed in the public roadmap.
|
||||
Third-party contributions are also not currently included in the roadmap. Let us
|
||||
know about any ongoing developments and we're happy to include them here as
|
||||
well.
|
||||
### Backend System 1.0
|
||||
|
||||
## What's next
|
||||
The goal of this initiative is the stable 1.0 release of the [new backend system](../backend-system/index.md).
|
||||
This includes ensuring that all documentation is up to date, and includes API
|
||||
reviews and refactoring efforts to ensure that what is released is both stable
|
||||
and evolvable. You can follow along with this work in the [meta issue](https://github.com/backstage/backstage/issues/24493).
|
||||
|
||||
The feature set below is planned for the ongoing quarter, and grouped by theme.
|
||||
The list order doesn't necessarily reflect priority, and the development/release
|
||||
cycle will vary based on maintainer schedules.
|
||||
As part of this initiative, there will also be an exploration on how to
|
||||
simplify extension of backend services. It is not currently possible to augment
|
||||
backend services through declarative integration, they are instead only
|
||||
customizable through complete replacement. This also limits the ability to
|
||||
modularize services and scale ownership of the implementations. The goal is to
|
||||
provide a more flexible and scalable way to extend backend services.
|
||||
|
||||
### Backend Services (MVP)
|
||||
### New Frontend System - Ready for Adoption
|
||||
|
||||
To better scale and maintain the Backstage instances, a backend services system
|
||||
is planned to be introduced as part of the software architecture. This layer of
|
||||
backend services will help in decoupling the various modules (e.g. Catalog and
|
||||
Scaffolder) from the frontend experience.
|
||||
The [new fronted system](../frontend-system/index.md) still needs more work, and
|
||||
the next milestone is to improve it to the point where there is enough
|
||||
confidence in the design to start encouraging adoption in the community. You can
|
||||
follow along with this work in the [meta issue](https://github.com/backstage/backstage/issues/19545).
|
||||
This milestone also includes reaching and executing [rollout phase 2](https://github.com/backstage/backstage/issues/19545#issuecomment-1766069146).
|
||||
|
||||
After the experimentation and design happened in the past quarter, soon we plan to release a first version to start providing the first benefits to adopters and developers.
|
||||
Once the initial milestone is reached, the goal is to also build out broader
|
||||
support for the new frontend system in the core plugins.
|
||||
|
||||
### Backstage Security Audit
|
||||
|
||||
This is the continuation of the initiative started in the previous quarters. This
|
||||
quarter will see the publication of the report describing the outcome of the
|
||||
audit, together the first fixes and the development of some of the changes
|
||||
required to address the vulnerabilities.
|
||||
This is the second security audit of the Backstage project. It is done together,
|
||||
and with the support of the [Cloud Native Computing Foundation (CNCF)](https://www.cncf.io/).
|
||||
This time the audit will in particular focus on the recently introduced
|
||||
[authentication system](https://github.com/backstage/backstage/tree/master/beps/0003-auth-architecture-evolution),
|
||||
but also cover other parts of the project.
|
||||
|
||||
This initiative is the first of a broader Security Strategy for Backstage. The
|
||||
purpose of the Security Audit is to involve third-party companies in auditing
|
||||
the platform. The benefit for the adopters is clear: we want Backstage to be as
|
||||
secure as possible, and we want to make it reliable through a specific
|
||||
initiative.
|
||||
### Plugin Metadata
|
||||
|
||||
This initiative is done together with, and with the support of, the [Cloud
|
||||
Native Computing Foundation (CNCF)](https://www.cncf.io/).
|
||||
The goal of this initiative is to provide better machine readable metadata for
|
||||
Backstage packages, available both at runtime, at build-time and as part of
|
||||
package registries. We want to surface information such as what packages make up
|
||||
a particular plugin, what features it provides, and more generally laying the
|
||||
foundation for an evolvable plugin metadata system.
|
||||
|
||||
### Backstage Threat Model
|
||||
### MUI v5 Green-light
|
||||
|
||||
This is another (relevant) initiative planned to make Backstage a secure product for the adopters. The goals of this initiative are:
|
||||
Material-UI v4 is still the officially supported version of MUI in Backstage.
|
||||
While we have heard that adopters have had success using MUI 5, this is still an
|
||||
untested path with known bugs. The goal of this initiative is to iron out any
|
||||
remaining issues or gaps, and then provide a green light for migration to MUI 5.
|
||||
|
||||
1. Understand where security investment and attention is needed.
|
||||
2. Guide the upcoming security audit.
|
||||
3. Communicate expectations to Backstage adopters and inform and attract security researchers.
|
||||
### Configuration Improvements
|
||||
|
||||
The planned artifacts are:
|
||||
This initiative aims to improve the configuration experience and reliability in
|
||||
Backstage. Areas for improvement include the way that configuration schema is
|
||||
loaded, the way that plugins access configuration that is not owned by them, how
|
||||
plugins read configuration, and how configuration visibility is handled.
|
||||
|
||||
- Concise high level threat model that will be included as part of the Backstage security documentation.
|
||||
- Granular threat model created in conjunction with the security audit to inform further security investment areas for Backstage.
|
||||
### Versioned Documentation
|
||||
|
||||
### Software Catalog pagination
|
||||
The goal of this initiative is to provide versioned documentation at
|
||||
[backstage.io](https://backstage.io). This lets us provide documentation that is
|
||||
both up-to-date while at the same time not ahead of the latest release.
|
||||
|
||||
Today adopters with a big catalog (with several thousands of software components) might not have an ideal end-user experience when viewing the `/catalog` page. The issue is related to how the entities are fetched by the frontend. In order to provide a better end-user experience the pagination of the catalog’s entities needs to be enforced. Some experimentation is already completed but in this quarter we plan to continue, and hopefully complete, this relevant enhancement.
|
||||
### Rework Pull Request & Issue Process
|
||||
|
||||
### More SIGs
|
||||
Our current review and issue triage process is centered around either core- or
|
||||
project area maintainers. The goal of this initiative is to make it simpler for
|
||||
more members of the community to be involved and contribute to this process.
|
||||
|
||||
In the last quarter we launched the [Catalog SIG (Special Interest Group)](https://github.com/backstage/community/tree/main/sigs/sig-catalog) to better coordinate the increasing number of contributions to the project. We think that this is the proper path to follow to engage more with the contributors. For this reason we will launch other SIGs dedicated to the most interesting topics for the community.
|
||||
### Catalog Observability
|
||||
|
||||
## Future work
|
||||
|
||||
The following feature list doesn't represent a commitment to develop, and the
|
||||
list order doesn't reflect any priority or importance, but these features are on
|
||||
the maintainers' radar, with clear interest expressed by the community.
|
||||
|
||||
- **Ease of onboarding:** A faster (with less development) and easier setup of
|
||||
Backstage and the most relevant/adopted plugins.
|
||||
- **Composable Homepage 1.0:** Driving this to 1.0 by adding some composable
|
||||
components.
|
||||
- **Creator experience:** Provide a better Backstage user experience through
|
||||
visual guidelines and templates, especially navigation across plug-ins and
|
||||
portal functionalities.
|
||||
- **[GraphQL](https://graphql.org/) support:** Introduce the ability to query
|
||||
Backstage backend services with a standard query language for APIs.
|
||||
- **Telemetry:** To efficiently generate logging and metrics in such a way that
|
||||
adopters can get insights so that Backstage can be monitored and improved.
|
||||
The goal of this initiative is to provide better tools for debugging catalog
|
||||
ingestion issues and to more generally reduce friction for setting up and
|
||||
maintaining the software catalog.
|
||||
|
||||
## How to influence the roadmap
|
||||
|
||||
|
||||
@@ -14,21 +14,28 @@ The Backstage trust model is divided into three groups with different trust leve
|
||||
|
||||
An **internal user** is an authenticated user that generally belongs to the organization of a particular Backstage deployment. These users are trusted to the extent that they are not expected to compromise the availability of Backstage, but they are not trusted to not compromise data confidentiality or integrity.
|
||||
|
||||
An **integrator** is a user responsible for configuring and maintaining an instance of Backstage. Integrators are fully trusted, since they operate the system and database and therefore have root access to the host system. Additional measures can be taken by adopters of Backstage in order to restrict or observe the access of this group, but that falls outside of the current scope of Backstage.
|
||||
An **operator** is a user responsible for configuring and maintaining an instance of Backstage. Operators are fully trusted, since they operate the system and database and therefore have root access to the host system. Additional measures can be taken by adopters of Backstage in order to restrict or observe the access of this group, but that falls outside of the current scope of Backstage.
|
||||
|
||||
Another group of de facto integrators is internal and external code contributors. When installing Backstage plugins you should vet them just like any other package from an external source. While it’s possible to limit the impact of for example a supply chain attack by splitting the deployment into separate services with different plugins, the Backstage project itself does not aim to prevent these kinds of attacks or in any other way sandbox or limit the access of plugins.
|
||||
A **builder** is an internal or external code contributor and end up having a similar level of access as operators. When installing Backstage plugins you should vet them just like any other package from an external source. While it’s possible to limit the impact of for example a supply chain attack by splitting the deployment into separate services with different plugins, the Backstage project itself does not aim to prevent these kinds of attacks or in any other way sandbox or limit the access of plugins.
|
||||
|
||||
An **external user** is a user that does not belong to the other two groups, for example a malicious actor outside of the organization. The security model of Backstage currently assumes that this group does not have any direct access to Backstage, and it is the responsibility of each adopter of Backstage to make sure this is the case.
|
||||
|
||||
## Integrator Responsibilities
|
||||
## Operator Responsibilities
|
||||
|
||||
As an integrator of Backstage you yourself are responsible for protecting your Backstage installation from external and unauthorized access. The sign-in system in Backstage does not exist to limit access, only to inform the system of the identity of the user. There are some plugins that have more fine-grained access control through the permissions system, but the primary purpose of that system is to restrict access to resources for internal users rather than Backstage as a whole. A common and recommended way to protect a Backstage deployment from unauthorized access is to deploy it behind an authenticating proxy such as AWS’s ALB, GCP’s IAP, or Cloudflare Access.
|
||||
:::info
|
||||
This section assumes that you are using the
|
||||
[new backend system](../backend-system/index.md) and at least Backstage release [version 1.24](../releases/v1.24.0.md). Before that Backstage did not come with built-in protection against unauthorized access and you were required to deploy it in a protected environment.
|
||||
:::
|
||||
|
||||
Other responsibilities include protecting the integrity of configuration files as it may otherwise be possible to introduce vulnerable configurations, as well as the confidentiality of configured secrets related to Backstage as these typically include authentication details to third party systems.
|
||||
Backstage is primarily designed to be deployed in a protected environment rather than being exposed to the public internet. From a confidentiality and integrity perspective, Backstage is designed to protect against unauthorized access to data and to ensure that data is not tampered with. However, Backstage does not provide more than rudimentary protection against denial of service attacks, and it is the responsibility of the operator to ensure that the Backstage deployment is protected against such attacks. A common and recommended way to protect a Backstage deployment from unauthorized access is to deploy it behind an authenticating proxy such as AWS’s ALB, GCP’s IAP, or Cloudflare Access.
|
||||
|
||||
The integrator is ultimately responsible for auditing usage of internal and external plugins as these run on the host system and have access to configuration and secrets. When installing plugins from sources like NPM, you should vet these in the same way that you would vet any other package installed from that source.
|
||||
Users that are signed-in in to Backstage generally have full access to all information and actions. If more fine-grained control is required, the [permissions system](../permissions/overview.md) should be enabled and configured to restrict access as necessary.
|
||||
|
||||
The integrator is also responsible for maintaining the resolved NPM dependencies of their Backstage project. This involves ensuring that `yarn.lock` receives updated versions of packages that have vulnerabilities, when those fixed versions are in range of what the Backstage packages request in their respective `package.json` files. This is commonly done by employing automated tooling such as [Dependabot](https://dependabot.com/), [Snyk](https://snyk.io/), and/or [Renovate](https://docs.renovatebot.com/) on your own repository. When fixed versions exist that are _not_ in range of what Backstage packages request, or when larger operations such as switching out an entire dependency for another one is required, maintainers collaborate with contributors to try to address those dependency declarations in the main project as soon as possible.
|
||||
An operator is responsible for protecting the integrity of configuration files as it may otherwise be possible to introduce vulnerable configurations, as well as the confidentiality of configured secrets related to Backstage as these typically include authentication details to third party systems.
|
||||
|
||||
The operator is ultimately responsible for auditing usage of internal and external plugins as these run on the host system and have access to configuration and secrets. When installing plugins from sources like NPM, you should vet these in the same way that you would vet any other package installed from that source.
|
||||
|
||||
The operator is also responsible for maintaining the resolved NPM dependencies of their Backstage project. This involves ensuring that `yarn.lock` receives updated versions of packages that have vulnerabilities, when those fixed versions are in range of what the Backstage packages request in their respective `package.json` files. This is commonly done by employing automated tooling such as [Dependabot](https://dependabot.com/), [Snyk](https://snyk.io/), and/or [Renovate](https://docs.renovatebot.com/) on your own repository. When fixed versions exist that are _not_ in range of what Backstage packages request, or when larger operations such as switching out an entire dependency for another one is required, maintainers collaborate with contributors to try to address those dependency declarations in the main project as soon as possible.
|
||||
|
||||
## Common Backend Configuration
|
||||
|
||||
@@ -44,21 +51,23 @@ Note that the `UrlReader` system operates with a service context and is not inte
|
||||
|
||||
Backstage provides authentication of users through the `auth` plugin, which primarily acts as an authorization server for different OAuth 2.0 provider integrations. These integrations can both serve the purpose of signing users into Backstage, as well as providing delegated access to external resources, and are all subject to the common concerns of implementing secure OAuth 2.0 authorization servers. All auth provider integrations are disabled by default, and need to be enabled through configuration in order to be used. For each Backstage installation it is recommended to only enable the minimal set of providers that are in use by that instance.
|
||||
|
||||
It is not within scope of the `auth` backend to protect against unauthorized access, that is something that needs to be handled at a deployment level. See the [Integrator Responsibilities](#integrator-responsibilities) section for more information.
|
||||
|
||||
In order to use an auth provider to sign in users into Backstage, it needs to be configured with an [Identity resolver](https://backstage.io/docs/auth/identity-resolver), which is a custom callback implemented in code. The identity resolver is a sensitive part of configuring Backstage and it is important that it always resolves user identities correctly, based on information provided by the authentication provider. There are a number of built-in identity resolvers that can simplify configuration, and it is important that these all resolve users in a secure way, regardless of how they are used.
|
||||
|
||||
Backstage also supports authentication through an authenticating reverse proxy such as [AWS ALB](https://aws.amazon.com/elasticloadbalancing/application-load-balancer/), where the user identity is read from the incoming proxied decorated request. The following proxy auth providers verify the signature of incoming requests, and are therefore safe to deploy with direct access by users: `awsAlb`, `cfAccess`, and `gcpIap`. Providers like `oauth2Proxy` do not verify the incoming request and can therefore be spoofed by a malicious internal user to supply the `auth` backend with forged identity information. It’s therefore highly recommended to restrict access to the `oauth2Proxy` endpoints, or use a different provider.
|
||||
|
||||
As part of signing in with an identity resolver, a Backstage Token is issued containing the resolved user identity. The tokens are asymmetrically signed JSON Web Tokens, with the public keys available to any service that wishes to verify a token. The signing keys are rotated continuously and are unique to each installation of Backstage, meaning that Backstage Tokens are not shared across installations. The token contains claims for the user identity and ownership information, which can be used to determine what Backstage resources are owned by that user or group. It is important that this token can not be forged outside of the `auth` plugin, with the exception of other plugins deployed in the same backend service or sharing the same database. For a high-security deployment, the `auth` backend should therefore be deployed in a separate service with its own database.
|
||||
|
||||
The token is used to prove the identity of the user within the Backstage system, and is used throughout Backstage plugins to control access. It is important that the ownership resolution logic is consistent across the entire Backstage ecosystem, with no possibility of misinterpreting the ownership information.
|
||||
|
||||
For cross-backend communication, the Backstage Token is typically forwarded or, in strict backend-to-backend communication without a user party, the backend itself issues a service token based on a pre-shared secret which is then validated on the receiving end. There are no unique service identities tied to these tokens at this point, meaning the tokens can be used across all services in a Backstage installation. This is something that we aim to improve in the future.
|
||||
One of the claims in a user token is the User Identity Proof or `uip`. This is an additional signature of the token that allows for offline token transformation. By replacing the original signature with the `uip` the token is still proof of a user identity, but it no longer acts as a full access token and will be rejected by most plugin endpoints. Plugins can explicitly allow use of this limited token where required, but this should only be used when necessary when a full token is not available, and ideally just for read-only access. Use-cases for limited users tokens include cookie authentication of static assets, storage of user identity proofs in a database, and similar.
|
||||
|
||||
Backstage also supports authentication through a proxy where the user identity is read from the incoming request from the proxy, which has been decorated by an authenticating reverse proxy such as [AWS ALB](https://aws.amazon.com/elasticloadbalancing/application-load-balancer/). The following proxy auth providers verify the signature of incoming requests, and are therefore safe to deploy with direct access by users: `awsAlb`, `cfAccess`, and `gcpIap`. Providers like `oauth2Proxy` does not verify the incoming request and can therefore be spoofed by a malicious internal user to supply the `auth` backend with forged identity information. It’s therefore highly recommended to restrict access to the `oauth2Proxy` endpoints, or use a different provider.
|
||||
The communication across backend plugins uses a similar authentication scheme to the user authentication. Each backend plugin generates and publishes its own set of keys that it uses to sign its tokens, and the public keys are shared with all other plugins for verification. The expected location of each plugin's published JWKS is determined by the `DiscoveryService` implementation in the backend, which means that it is vital for any custom implementation of that service to be careful with user input. The tokens signed by each plugin contain both the source and target plugin ID, which means that the token can not be reused to access other plugins.
|
||||
|
||||
When forwarding a user identity in a call across backend plugins only the limited user token with `uip` is used, wrapped in a new service token that is signed by the calling plugin. This means that the receiving plugin can trust the user identity, but it is not able to make further calls on behalf of the user except for with the plugins that it is authorized to call. That is except for any endpoints in other plugins that accept limited user tokens, which is a reason to avoid accepting them when possible.
|
||||
|
||||
## Catalog
|
||||
|
||||
Integrators should configure [catalog rules](https://backstage.io/docs/features/software-catalog/configuration#catalog-rules) to limit the allowed entity kinds that users can define. In general it is best to restrict definition of User, Group, and Template entities so that internal users cannot register additional ones. Template entities define actions that are executed on the backend hosts, and while the goal is for these actions to be secure regardless of input, it is still a more sensitive context and it is recommended that you protect it with additional checks. It is very important to not allow registration of User and Group entities if you ingest and rely on these as organizational data in your catalog. Doing so could otherwise open up for the ability to impersonate users and confuse group membership information. You should always ingest organizational data using a statically configured catalog location or an entity provider reading from a trusted source. The entities emitted directly by an entity provider are always trusted and rules are not applied to them, but any entities produced further down the chain are still subject to the rules.
|
||||
Operators should configure [catalog rules](https://backstage.io/docs/features/software-catalog/configuration#catalog-rules) to limit the allowed entity kinds that users can define. In general it is best to restrict definition of User, Group, and Template entities so that internal users cannot register additional ones. Template entities define actions that are executed on the backend hosts, and while the goal is for these actions to be secure regardless of input, it is still a more sensitive context and it is recommended that you protect it with additional checks. It is very important to not allow registration of User and Group entities if you ingest and rely on these as organizational data in your catalog. Doing so could otherwise open up for the ability to impersonate users and confuse group membership information. You should always ingest organizational data using a statically configured catalog location or an entity provider reading from a trusted source. The entities emitted directly by an entity provider are always trusted and rules are not applied to them, but any entities produced further down the chain are still subject to the rules.
|
||||
|
||||
The Catalog does not aim to protect against resource exhaustion attacks in its default setup. If you need to prevent your internal users from being able to register large amounts of entities, then it is recommended to disable entity registration and use a different approach for discovering entities. One way to mitigate any resource exhaustion attacks is to only allow the catalog to read from trusted SCM sources that have an audit trail. Catalog currently lacks limits for entity hierarchy depth and entity size, which we hope to address in the future.
|
||||
|
||||
@@ -68,11 +77,11 @@ By default all internal users are allowed to create and delete entities. If this
|
||||
|
||||
By default, Scaffolding jobs execute directly on the host machine, including any actions defined in the template. Because the Scaffolder templates are considered a more sensitive area it is recommended to control access to create and update templates to trusted parties. Template execution is intended to be secure regardless of input, but we still recommend this additional layer of protection. The string templating is executed in a [node VM sandbox](https://github.com/laverdet/isolated-vm) to mitigate the possibility of remote code execution attacks.
|
||||
|
||||
The Scaffolder often has elevated permissions to for example create repositories in a Github organization. The integrator should therefore be cautious of Scaffolder Templates that for example delete or update existing resources as the user input is typically user defined and can therefore delete or modify resources maliciously or by mistake.
|
||||
The Scaffolder often has elevated permissions to for example create repositories in a Github organization. The operator should therefore be cautious of Scaffolder Templates that for example delete or update existing resources as the user input is typically user defined and can therefore delete or modify resources maliciously or by mistake.
|
||||
|
||||
One strategy that allows you to reduce the access that the Scaffolder service has is to rely on user credentials when executing actions. For example, a GitHub App integration could be configured with read-only permissions, with a separate user OAuth token used to create repositories. This requires that your users have access to create repositories in the first place.
|
||||
|
||||
The integrator should audit installed scaffolding actions just like any other plugin package. It is also important to verify that installed actions fall in line with your own security requirements, as some actions might be intended for more relaxed environments.
|
||||
The operator should audit installed scaffolding actions just like any other plugin package. It is also important to verify that installed actions fall in line with your own security requirements, as some actions might be intended for more relaxed environments.
|
||||
|
||||
By default all internal users are allowed to execute templates in the scaffolder. If this does not fit your organization's needs it is recommended to enable and configure the [permission](https://backstage.io/docs/permissions/overview) system to restrict these operations.
|
||||
|
||||
|
||||
@@ -144,7 +144,11 @@ export const rules = { isOwner };
|
||||
|
||||
`makeCreatePermissionRule` is a helper used to ensure that rules created for this plugin use consistent types for the resource and query.
|
||||
|
||||
> Note: To support custom rules defined by Backstage integrators, you must export `createTodoListPermissionRule` from the backend package and provide some way for custom rules to be passed in before the backend starts, likely via `createRouter`.
|
||||
:::note Note
|
||||
|
||||
To support custom rules defined by Backstage integrators, you must export `createTodoListPermissionRule` from the backend package and provide some way for custom rules to be passed in before the backend starts, likely via `createRouter`.
|
||||
|
||||
:::
|
||||
|
||||
We have created a new `isOwner` rule, which is going to be automatically used by the permission framework whenever a conditional response is returned in response to an authorized request with an attached `resourceRef`.
|
||||
Specifically, the `apply` function is used to understand whether the passed resource should be authorized or not.
|
||||
|
||||
@@ -69,8 +69,7 @@ installed, may be captured.
|
||||
| `discover` | The title of the search result that was clicked on | The `value` is the result rank. A `to` attribute is also provided. |
|
||||
| `not-found` | The path of the resource that resulted in a not found page | Fired by at least TechDocs. |
|
||||
|
||||
If there is an event you'd like to see captured, please [open an
|
||||
issue](https://github.com/backstage/backstage/issues/new?assignees=&labels=enhancement&template=feature_template.md&title=[Analytics%20Event]:%20THE+EVENT+TO+CAPTURE) describing the event you want to see and the questions it
|
||||
If there is an event you'd like to see captured, please [open an issue](https://github.com/backstage/backstage/issues/new?assignees=&labels=enhancement&template=feature_template.md&title=[Analytics%20Event]:%20THE+EVENT+TO+CAPTURE) describing the event you want to see and the questions it
|
||||
would help you answer. Or jump to [Capturing Events](#capturing-events) to learn how
|
||||
to contribute the instrumentation yourself!
|
||||
|
||||
|
||||
@@ -60,8 +60,7 @@
|
||||
|
||||
This change makes the dependence explicit, and removes the burden on
|
||||
OAuth2-based providers which require an ID token (e.g. this is done by various
|
||||
default [auth
|
||||
handlers](https://backstage.io/docs/auth/identity-resolver/#authhandler)) to add
|
||||
default [auth handlers](https://backstage.io/docs/auth/identity-resolver/#authhandler)) to add
|
||||
`openid` to their default scopes. _That_ could carry another indirect benefit:
|
||||
by removing `openid` from the default scopes for a provider, grants for
|
||||
resource-specific access tokens can avoid requesting excess ID token-related
|
||||
|
||||
@@ -25,8 +25,7 @@
|
||||
|
||||
This change makes the dependence explicit, and removes the burden on
|
||||
OAuth2-based providers which require an ID token (e.g. this is done by various
|
||||
default [auth
|
||||
handlers](https://backstage.io/docs/auth/identity-resolver/#authhandler)) to add
|
||||
default [auth handlers](https://backstage.io/docs/auth/identity-resolver/#authhandler)) to add
|
||||
`openid` to their default scopes. _That_ could carry another indirect benefit:
|
||||
by removing `openid` from the default scopes for a provider, grants for
|
||||
resource-specific access tokens can avoid requesting excess ID token-related
|
||||
|
||||
@@ -27,8 +27,7 @@ native dependency, and as such needs to be built during `yarn` installation, on
|
||||
the exact architecture that it then executes on. For those who compile and run
|
||||
Backstage on stripped-down environments, you will want to ensure that you have
|
||||
the build basics present, e.g. `build-essential` or similar corresponding to
|
||||
your operating system of choice. The `isolated-vm` repo has [some further
|
||||
information](https://github.com/laverdet/isolated-vm#requirements) about the
|
||||
your operating system of choice. The `isolated-vm` repo has [some further information](https://github.com/laverdet/isolated-vm#requirements) about the
|
||||
build environment requirements.
|
||||
|
||||
There is a [CVE-2022-39266](https://www.cve.org/CVERecord?id=CVE-2022-39266)
|
||||
@@ -65,8 +64,7 @@ covers of your catalog instance, finding those pesky unprocessed entities that
|
||||
may be stuck in limbo because of an otherwise tricky-to-debug validation issue
|
||||
or similar.
|
||||
|
||||
Check out [the plugin’s
|
||||
README](https://github.com/backstage/backstage/blob/master/plugins/catalog-unprocessed-entities/README.md)
|
||||
Check out [the plugin’s README](https://github.com/backstage/backstage/blob/master/plugins/catalog-unprocessed-entities/README.md)
|
||||
for details and installation instructions.
|
||||
|
||||
Contributed by [@alde](https://github.com/alde) in
|
||||
@@ -176,8 +174,7 @@ Contributed by [@sblausten](https://github.com/sblausten) in
|
||||
|
||||
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](https://backstage.io/docs/getting-started/keeping-backstage-updated).
|
||||
[keeping Backstage updated](https://backstage.io/docs/getting-started/keeping-backstage-updated).
|
||||
|
||||
## Links and References
|
||||
|
||||
@@ -185,11 +182,9 @@ Below you can find a list of links and references to help you learn about and
|
||||
start using this new release.
|
||||
|
||||
- [Backstage official website](https://backstage.io/),
|
||||
[documentation](https://backstage.io/docs/), and [getting started
|
||||
guide](https://backstage.io/docs/getting-started/)
|
||||
[documentation](https://backstage.io/docs/), and [getting started guide](https://backstage.io/docs/getting-started/)
|
||||
- [GitHub repository](https://github.com/backstage/backstage)
|
||||
- Backstage's [versioning and support
|
||||
policy](https://backstage.io/docs/overview/versioning-policy)
|
||||
- Backstage's [versioning and support policy](https://backstage.io/docs/overview/versioning-policy)
|
||||
- [Community Discord](https://discord.gg/backstage-687207715902193673) for
|
||||
discussions and support
|
||||
- [Changelog](https://github.com/backstage/backstage/tree/master/docs/releases/v1.15.0-changelog.md)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,83 @@
|
||||
---
|
||||
id: v1.27.0
|
||||
title: v1.27.0
|
||||
description: Backstage Release v1.27.0
|
||||
---
|
||||
|
||||
These are the release notes for the v1.27.0 release of [Backstage](https://backstage.io/).
|
||||
|
||||
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
|
||||
|
||||
### Backend System Deprecations
|
||||
|
||||
As part of the [work towards a stable 1.0 release of the new backend system](https://github.com/backstage/backstage/issues/24493), we will deprecate and move or remove several utilities from `@backstage/backend-common`. This release contains a few of these deprecations, with more to be expected in the future. The long-term goal is to completely deprecate and remove the `@backstage/backend-common` package.
|
||||
|
||||
### Hierarchical Domains
|
||||
|
||||
The Backstage System Model has been tweaked with the addition of a hierarchy of `Domain` entities. The change includes a new `spec.subdomainOf` property on the `Domain` entity, which can be used to express that a domain has a `partOf` (and conversely, `hasPart`) relation toward another domain.
|
||||
|
||||
Contributed by [@dawngerpony](https://github.com/dawngerpony) and [@janogonzalez](https://github.com/janogonzalez) in [#17125](https://github.com/backstage/backstage/pull/17125).
|
||||
|
||||
### Scaffolder workspace serialization
|
||||
|
||||
Added experimental support for serialization of workspaces in the scaffolder. By serializing the workspace, it is possible to re-run the task in a non-sticky way. This means that the task can be restored and retried on a different scaffolder task worker.
|
||||
|
||||
To enable this feature, set the `EXPERIMENTAL_workspaceSerialization` option to `true` in the `scaffolder` section of the `app-config.yaml` file:
|
||||
|
||||
```yaml
|
||||
scaffolder:
|
||||
EXPERIMENTAL_workspaceSerialization: true
|
||||
```
|
||||
|
||||
Contributed by [@acierto](https://github.com/acierto) in [#24570](https://github.com/backstage/backstage/pull/24570).
|
||||
|
||||
### Scaffolder `notification:send` action
|
||||
|
||||
The new `notification:send` action allows sending notifications from templates. This can be used to send notifications to users when executing a template. Please note that the notifications system is still under development.
|
||||
|
||||
To install this action, add the new module to your backend:
|
||||
|
||||
```diff
|
||||
+ backend.add(import('@backstage/plugin-scaffolder-backend-module-notifications'));
|
||||
```
|
||||
|
||||
Contributed by [@drodil](https://github.com/drodil) in [#24588](https://github.com/backstage/backstage/pull/24588).
|
||||
|
||||
### Backend Authentication
|
||||
|
||||
The requirement to configure a secret for backend authentication in production has been removed. It is now only needed if you rely on the [legacy authentication mechanism](https://backstage.io/docs/auth/service-to-service-auth#external-callers-legacy). If you don’t configure any secrets you will also not be able to generate tokens with the `TokenManager` service, although use of this service is discouraged as it has been replaced by the `AuthService`.
|
||||
|
||||
### User Authentication
|
||||
|
||||
The `auth` backend plugin now provides an `authOwnershipResolutionExtensionPoint` that lets you override the default ownership resolution used by sign-in resolvers. This allows you to customize this logic for all sign-in resolvers without replacing them.
|
||||
|
||||
Contributed by [@drodil](https://github.com/drodil) in [#22765](https://github.com/backstage/backstage/pull/22765).
|
||||
|
||||
### Events support for GitLab Entity and Org Discovery
|
||||
|
||||
The `GitlabDiscoveryEntityProvider` and `GitlabOrgDiscoveryEntityProvider` can now be configured to receive events from GitLab. This allows for the automatic discovery of entities in Backstage when groups or users are created or updated in GitLab.
|
||||
|
||||
Contributed by [@elaine-mattos](https://github.com/elaine-mattos) in [#23373](https://github.com/backstage/backstage/pull/23373).
|
||||
|
||||
## 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](https://backstage.io/docs/getting-started/keeping-backstage-updated).
|
||||
|
||||
## 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](https://backstage.io/), [documentation](https://backstage.io/docs/), and [getting started guide](https://backstage.io/docs/getting-started/)
|
||||
- [GitHub repository](https://github.com/backstage/backstage)
|
||||
- Backstage's [versioning and support policy](https://backstage.io/docs/overview/versioning-policy)
|
||||
- [Community Discord](https://discord.gg/backstage-687207715902193673) for discussions and support
|
||||
- [Changelog](https://github.com/backstage/backstage/tree/master/docs/releases/v1.27.0-changelog.md)
|
||||
- Backstage [Demos](https://backstage.io/demos), [Blog](https://backstage.io/blog), [Roadmap](https://backstage.io/docs/overview/roadmap) and [Plugins](https://backstage.io/plugins)
|
||||
|
||||
Sign up for our [newsletter](https://info.backstage.spotify.com/newsletter_subscribe) if you want to be informed about what is happening in the world of Backstage.
|
||||
@@ -883,8 +883,7 @@
|
||||
### Patch Changes
|
||||
|
||||
- 8f7b1835df: Updated dependency `msw` to `^0.41.0`.
|
||||
- 811ff4bcf4: Updated `swagger-ui-react` to 4.11.1 in order to address a [XSS
|
||||
vulnerability](https://github.com/advisories/GHSA-hqq7-2q2v-82xq) in `@braintree/sanitize-url`
|
||||
- 811ff4bcf4: Updated `swagger-ui-react` to 4.11.1 in order to address a [XSS vulnerability](https://github.com/advisories/GHSA-hqq7-2q2v-82xq) in `@braintree/sanitize-url`
|
||||
- Updated dependencies
|
||||
- @backstage/plugin-catalog@1.3.0
|
||||
- @backstage/plugin-catalog-react@1.1.1
|
||||
|
||||
@@ -24,9 +24,7 @@
|
||||
- 1fe6823bb5: Updated dependency `eslint-plugin-jest` to `^27.0.0`.
|
||||
|
||||
Note that this major update to the Jest plugin contains some breaking changes.
|
||||
This means that some of your tests may start seeing some new lint errors. [Read
|
||||
about them
|
||||
here](https://github.com/jest-community/eslint-plugin-jest/blob/main/CHANGELOG.md#2700-2022-08-28).
|
||||
This means that some of your tests may start seeing some new lint errors. [Read about them here](https://github.com/jest-community/eslint-plugin-jest/blob/main/CHANGELOG.md#2700-2022-08-28).
|
||||
|
||||
These are mostly possible to fix automatically. You can try to run `yarn backstage-cli repo lint --fix` in your repo root to have most or all of them
|
||||
corrected.
|
||||
|
||||
@@ -7,9 +7,7 @@
|
||||
- 1fe6823bb5: Updated dependency `eslint-plugin-jest` to `^27.0.0`.
|
||||
|
||||
Note that this major update to the Jest plugin contains some breaking changes.
|
||||
This means that some of your tests may start seeing some new lint errors. [Read
|
||||
about them
|
||||
here](https://github.com/jest-community/eslint-plugin-jest/blob/main/CHANGELOG.md#2700-2022-08-28).
|
||||
This means that some of your tests may start seeing some new lint errors. [Read about them here](https://github.com/jest-community/eslint-plugin-jest/blob/main/CHANGELOG.md#2700-2022-08-28).
|
||||
|
||||
These are mostly possible to fix automatically. You can try to run `yarn backstage-cli repo lint --fix` in your repo root to have most or all of them
|
||||
corrected.
|
||||
|
||||
@@ -926,8 +926,7 @@
|
||||
|
||||
Migrating to the stable version of `react-router` is optional for the time
|
||||
being. But if you want to do the same for your existing repository, please
|
||||
follow [this
|
||||
guide](https://backstage.io/docs/tutorials/react-router-stable-migration).
|
||||
follow [this guide](https://backstage.io/docs/tutorials/react-router-stable-migration).
|
||||
|
||||
- e05e0f021b: Update versions of packages used in the create-app template, to match those in the main repo
|
||||
|
||||
|
||||
@@ -319,8 +319,7 @@
|
||||
|
||||
Migrating to the stable version of `react-router` is optional for the time
|
||||
being. But if you want to do the same for your existing repository, please
|
||||
follow [this
|
||||
guide](https://backstage.io/docs/tutorials/react-router-stable-migration).
|
||||
follow [this guide](https://backstage.io/docs/tutorials/react-router-stable-migration).
|
||||
|
||||
- e05e0f021b: Update versions of packages used in the create-app template, to match those in the main repo
|
||||
|
||||
|
||||
+7
-15
@@ -22,24 +22,20 @@ backend needs to be supplied with a location analyzer for this use case to
|
||||
continue to function.
|
||||
|
||||
If you want to make use of this feature, check out the installation instructions
|
||||
in [the
|
||||
changelog](https://github.com/backstage/backstage/blob/master/plugins/catalog-import/CHANGELOG.md#090).
|
||||
in [the changelog](https://github.com/backstage/backstage/blob/master/plugins/catalog-import/CHANGELOG.md#090).
|
||||
|
||||
Contributed by [@kissmikijr](https://github.com/kissmikijr) in
|
||||
[#13800](https://github.com/backstage/backstage/pull/13800)
|
||||
|
||||
### Permission Rule Changes
|
||||
|
||||
When defining permission rules, it's now necessary to provide a [Zod
|
||||
Schema](https://github.com/colinhacks/zod) that specifies the parameters the
|
||||
When defining permission rules, it's now necessary to provide a [Zod Schema](https://github.com/colinhacks/zod) that specifies the parameters the
|
||||
rule expects. This has been added to help better describe the parameters in the
|
||||
response of the metadata endpoint and to validate the parameters before a rule
|
||||
is executed. The signatures of the rule methods (`apply` and `toQuery`) have
|
||||
changed slightly as well.
|
||||
|
||||
You can read more about this in [the permissions
|
||||
documentation](https://backstage.io/docs/permissions/overview) and [the
|
||||
changelog](https://github.com/backstage/backstage/blob/master/plugins/permission-node/CHANGELOG.md#070).
|
||||
You can read more about this in [the permissions documentation](https://backstage.io/docs/permissions/overview) and [the changelog](https://github.com/backstage/backstage/blob/master/plugins/permission-node/CHANGELOG.md#070).
|
||||
|
||||
### Migration: `jest` v29
|
||||
|
||||
@@ -64,8 +60,7 @@ Newly created Backstage repositories now use the stable version 6 of
|
||||
|
||||
Migrating to the stable version of `react-router` is optional for the time
|
||||
being; Backstage has support for both versions. But if you want to do the same
|
||||
for your existing repository, please follow [this
|
||||
guide](https://backstage.io/docs/tutorials/react-router-stable-migration).
|
||||
for your existing repository, please follow [this guide](https://backstage.io/docs/tutorials/react-router-stable-migration).
|
||||
Support for the beta version will be removed in a later release.
|
||||
|
||||
### Support for `__mocks__` and `__testUtils__` directories
|
||||
@@ -100,8 +95,7 @@ This release does not contain any security fixes.
|
||||
|
||||
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](https://backstage.io/docs/getting-started/keeping-backstage-updated).
|
||||
[keeping Backstage updated](https://backstage.io/docs/getting-started/keeping-backstage-updated).
|
||||
|
||||
## Links and References
|
||||
|
||||
@@ -109,11 +103,9 @@ Below you can find a list of links and references to help you learn about and
|
||||
start using this new release.
|
||||
|
||||
- [Backstage official website](https://backstage.io/),
|
||||
[documentation](https://backstage.io/docs/), and [getting started
|
||||
guide](https://backstage.io/docs/getting-started/)
|
||||
[documentation](https://backstage.io/docs/), and [getting started guide](https://backstage.io/docs/getting-started/)
|
||||
- [GitHub repository](https://github.com/backstage/backstage)
|
||||
- Backstage's [versioning and support
|
||||
policy](https://backstage.io/docs/overview/versioning-policy)
|
||||
- Backstage's [versioning and support policy](https://backstage.io/docs/overview/versioning-policy)
|
||||
- [Community Discord](https://discord.gg/backstage-687207715902193673) for discussions and support
|
||||
- [Changelog](https://github.com/backstage/backstage/tree/master/docs/releases/v1.7.0-changelog.md)
|
||||
- Backstage [Demos](https://backstage.io/demos),
|
||||
|
||||
@@ -65,13 +65,19 @@ You can now start your Backstage instance as usual, using `yarn dev`.
|
||||
|
||||
## Production Setup
|
||||
|
||||
In your `Dockerfile` add the `--require` flag which points to the `instrumentation.js` file
|
||||
In your `Dockerfile`, copy `instrumentation.js` file into the root of the working directory.
|
||||
|
||||
```Dockerfile
|
||||
COPY --chown=${NOT_ROOT_USER}:${NOT_ROOT_USER} packages/backend/src/instrumentation.js ./
|
||||
```
|
||||
|
||||
And then add the `--require` flag that points to the file to the CMD array.
|
||||
|
||||
```Dockerfile
|
||||
// highlight-remove-next-line
|
||||
CMD ["node", "packages/backend", "--config", "app-config.yaml"]
|
||||
// highlight-add-next-line
|
||||
CMD ["node", "--require", "./src/instrumentation.js", "packages/backend", "--config", "app-config.yaml"]
|
||||
CMD ["node", "--require", "./instrumentation.js", "packages/backend", "--config", "app-config.yaml"]
|
||||
```
|
||||
|
||||
If you need to disable/configure some OpenTelemetry feature there are lots of [environment variables](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/) which you can tweak.
|
||||
|
||||
Reference in New Issue
Block a user