paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[Doc] Removed Mentions of the New Backend System

Browse Source 
Signed-off-by: Andre Wanlin <awanlin@spotify.com>
This commit is contained in:
Andre Wanlin
2026-02-28 11:22:02 -06:00
parent 5879bd8760
commit 5142f60de3
36 changed files with 25 additions and 511 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/auth/auth0/provider.md
-7
View File
@@ -5,13 +5,6 @@ sidebar_label: Auth0
description: Adding Auth0 as an authentication provider in Backstage
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/auth/auth0/provider--old.md)
instead, and [consider migrating](../../backend-system/building-backends/08-migrating.md)!
:::
The Backstage `core-plugin-api` package comes with an Auth0 authentication
provider that can authenticate users using OAuth.
docs/auth/bitbucketServer/provider.md
-7
View File
@@ -5,13 +5,6 @@ sidebar_label: Bitbucket Server
description: Adding Bitbucket Server OAuth as an authentication provider in Backstage
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/auth/bitbucketServer/provider--old.md)
instead, and [consider migrating](../../backend-system/building-backends/08-migrating.md)!
:::
The Backstage `core-plugin-api` package comes with a Bitbucket Server authentication provider that can authenticate
users using Bitbucket Server. This does **NOT** work with Bitbucket Cloud.
docs/auth/guest/provider.md
-4
View File
@@ -19,10 +19,6 @@ This provider should only ever be enabled for `development`. To prevent unauthor
### Backend
:::note
This will only work with the new backend system. There is no support for this in the old backend.
:::
Add the `@backstage/plugin-auth-backend-module-guest-provider` to your backend installation.
```sh title="From your Backstage root directory"
docs/auth/identity-resolver.md
-7
View File
@@ -4,13 +4,6 @@ title: Sign-in Identities and Resolvers
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
[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](https://github.com/backstage/backstage/blob/v1.37.0/docs/auth/identity-resolver--old.md)
instead, and [consider migrating](../backend-system/building-backends/08-migrating.md)!
:::
By default, every Backstage auth provider is configured only for the use-case of
access delegation. This enables Backstage to request resources and actions from
external systems on behalf of the user, for example re-triggering a build in CI.
docs/auth/index.md
+2 -2
View File
@@ -12,7 +12,7 @@ access to external resources.
:::note Note
Identity management and the Sign-In page in Backstage will only block external access when using the new backend system, without setting `backend.auth.dangerouslyDisableDefaultAuthPolicy` in configuration. Even so, the frontend bundle is not protected from external access, protecting it requires the use of the [experimental public entry point](https://backstage.io/docs/tutorials/enable-public-entry/). You can learn more about this in the [Threat Model](../overview/threat-model.md#operator-responsibilities).
Identity management and the Sign-In page in Backstage will block external access by default, without setting `backend.auth.dangerouslyDisableDefaultAuthPolicy` in configuration. Even so, the frontend bundle is not protected from external access, protecting it requires the use of the [experimental public entry point](https://backstage.io/docs/tutorials/enable-public-entry/). You can learn more about this in the [Threat Model](../overview/threat-model.md#operator-responsibilities).
:::
@@ -461,7 +461,7 @@ providerFactories: {
},
```
In the new backend system you can leverage the `authProvidersExtensionPoint` for this:
You can leverage the `authProvidersExtensionPoint` for this:
```ts
// your-auth-plugin-module.ts
docs/auth/oidc.md
-7
View File
@@ -4,13 +4,6 @@ title: OIDC provider from scratch
description: This section shows how to enable and use the Backstage OIDC provider.
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/auth/oidc--old.md)
instead, and [consider migrating](../backend-system/building-backends/08-migrating.md)!
:::
This section shows how to enable and use the Backstage OIDC provider.
## Summary
docs/auth/service-to-service-auth.md
+1 -98
View File
@@ -4,13 +4,6 @@ title: Service to Service Auth
description: This section describes service to service authentication works, both internally within Backstage plugins and when external callers want to make requests.
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/auth/service-to-service-auth--old.md)
instead, and [consider migrating](../backend-system/building-backends/08-migrating.md)!
:::
This article describes how _service-to-service auth_ works in Backstage, both
between Backstage backend plugins and for external callers who want to make
requests to them. This is in contrast to _user and user-to-service auth_ which
@@ -20,7 +13,7 @@ Each section describes one distinct type of auth flow.
## Standard Plugin-to-Plugin Auth
Backstage plugins that use the new backend system and handle credentials using
Backstage plugins that use the backend system and handle credentials using
the `auth` and `httpAuth` service APIs are secure by default, without requiring
any configuration. They generate self-signed tokens automatically for making
requests to other Backstage backend plugins, and the receivers use the caller's
@@ -228,96 +221,6 @@ calling Backstage plugins:
Authorization: Bearer eyJhbG...
```
## Legacy Tokens
Plugins and backends that are _not_ on the new backend system use a legacy token
flow, where shared static secrets in your app-config are used for signing and
verification. If you are on the new backend system and are not using legacy
plugins using the compatibility wrapper, you can skip this section.
### Configuration (legacy)
In local development, there is no need to configure anything for this auth
method. But in production, you must configure at least one legacy type external
access method:
```yaml title="in e.g. app-config.production.yaml"
backend:
auth:
externalAccess:
- type: legacy
options:
secret: my-secret-key-catalog
subject: legacy-catalog
- type: legacy
options:
secret: my-secret-key-scaffolder
subject: legacy-scaffolder
```
The old style keys config is also supported as an alternative, but please
consider using the new style above instead:
```yaml title="in e.g. app-config.production.yaml"
backend:
auth:
keys:
- secret: my-secret-key-catalog
- secret: my-secret-key-scaffolder
```
The secrets must be any base64-encoded random data, but for security reasons
should be sufficiently long so as not to be easy to guess by brute force. You
can for example generate them on the command line:
```shell
node -p 'require("crypto").randomBytes(24).toString("base64")'
```
The subjects must be strings without whitespace. They are used for identifying
each caller, and become part of the credentials object that request recipient
plugins get.
In both of the examples we showed two secrets being specified, but the minimum
is one. The order is significant: the first one is always used for signing of
outgoing requests to other backend plugins, while all of the keys are used for
verification. This is useful if you want to be able to have unique keys per
deployment if you are using split deployments of Backstage. Then each deployment
lists its own signing secret at the top, and only adds the secrets for those
other deployments that it wants to permit to call it.
For most organizations, we recommend leaving it at just one key and
[migrating](../backend-system/building-backends/08-migrating.md) to the new
backend system as soon as possible instead of experimenting with multiple legacy
secrets.
### External Callers (legacy)
For legacy Backstage backend plugins, the above configuration is enough. But
external callers who wish to make requests using this flow must generate tokens
according to the following rules.
The token must be a JWT with a `HS256` signature, using the raw base64 decoded
value of the configured key as the secret. It must also have the following
payload:
- `sub`: the exact string "backstage-server"
- `exp`: one hour from the time it was generated, in epoch seconds
:::note Note
The JWT must encode the `alg` header as a protected header, such as with
[setProtectedHeader](https://github.com/panva/jose/blob/main/docs/classes/jwt_sign.SignJWT.md#setprotectedheader).
:::
The caller then passes along the JWT token with requests in the `Authorization`
header:
```yaml
Authorization: Bearer eZv5o+fW3KnR3kVabMW4ZcDNLPl8nmMW
```
## Access Restrictions
Each `externalAccess` entry may optionally have an `accessRestrictions` key,
docs/backend-system/architecture/01-index.md
+2 -2
View File
@@ -2,12 +2,12 @@
id: index
title: Backend System Architecture
sidebar_label: Overview
description: The structure and architecture of the new Backend System and its component parts
description: The structure and architecture of the Backend System and its component parts
---
## Building Blocks
This section introduces the high-level building blocks upon which this new
This section introduces the high-level building blocks upon which this
system is built. These are all concepts that exist in our current system in one
way or another, but they have all been lifted up to be first class concerns in
the new system. Regardless of whether you are setting up your own backstage
docs/backend-system/building-backends/01-index.md
+1 -1
View File
@@ -2,7 +2,7 @@
id: index
title: Building Backends
sidebar_label: Overview
description: Building backends using the new backend system
description: Building backends using the backend system
---
:::note Note
docs/backend-system/building-plugins-and-modules/01-index.md
+1 -8
View File
@@ -2,16 +2,9 @@
id: index
title: Building Backend Plugins and Modules
sidebar_label: Overview
description: Building backend plugins and modules using the new backend system
description: Building backend plugins and modules using the backend system
---
:::note Note
If you have an existing backend and/or backend plugins that are not yet
using the new backend system, see [migrating](./08-migrating.md).
:::
This section covers how to build your own backend [plugins](../architecture/04-plugins.md) and
[modules](../architecture/06-modules.md). They are sometimes collectively referred to as
backend _features_, and are the building blocks that adopters add to their
docs/features/kubernetes/authenticationstrategy.md
+1 -1
View File
@@ -157,7 +157,7 @@ export class AwsIamStrategy implements AuthenticationStrategy {
Sometimes you need to add a new way to authenticate against a kubernetes cluster not support by default by Backstage. This is how integrators can bring their own kubernetes auth strategies through the use of the [`addAuthStrategy`](https://github.com/backstage/backstage/blob/57397e7d6d2d725712c439f4ab93f2ac6aa27bf8/plugins/kubernetes-backend/src/service/KubernetesBuilder.ts#L211) method on `KubernetesBuilder` or through the [AuthStrategyExtensionPoint](https://github.com/backstage/backstage/blob/57397e7d6d2d725712c439f4ab93f2ac6aa27bf8/plugins/kubernetes-backend/src/plugin.ts#L112). So, on the following sections, we are going to introduce a new AuthStrategy for [Pinniped][1], an authentication service for Kubernetes clusters.
### Custom Pinniped auth strategy in the new backend system
### Custom Pinniped auth strategy in the backend system
To add a new AuthStrategy, we need to create a new Pinniped [backend module](../../backend-system/building-plugins-and-modules/01-index.md#modules) to extend the Kubernetes-Backend plugin. The Pinniped module will interact with the Kubernetes-Backend plugin through the [extension points](../../backend-system/architecture/05-extension-points.md) registered by the plugin. The Kubernetes-Backend plugin [registers](https://github.com/backstage/backstage/blob/ebe7afad9d19f279469168ca0d4feceb92c1ad36/plugins/kubernetes-backend/src/plugin.ts#L155) multiple extension points like `kubernetesObjectsProvider`, `kubernetesClusterSupplier`, `kubernetesFetcher`, `kubernetesServiceLocator` and the `kubernetesAuthStrategy`.
docs/features/software-templates/authorizing-scaffolder-template-details.md
+7 -60
View File
@@ -6,7 +6,13 @@ description: How to authorize parts of a template and authorize scaffolder task
The scaffolder plugin integrates with the Backstage [permission framework](../../permissions/overview.md), which allows you to control access to certain parameters and steps in your templates based on the user executing the template. It also allows you to control access to scaffolder tasks.
### Authorizing parameters and steps
:::tip
To better understand the following examples make sure to review the [Writing a permission policy](./../permissions/writing-a-policy.md)) documentation before moving forward.
:::
## Authorizing parameters and steps
To mark specific parameters or steps as requiring permission, add the `backstage:permissions` property to the parameter or step with one or more tags. For example:
@@ -288,62 +294,3 @@ All other users are granted permissions to perform/access the following actions/
- Read scaffolder tasks and their associated events/logs for tasks created by the user.
Although the rules exported by the scaffolder are simple, combining them can help you achieve more complex use cases.
### Authorizing in the New Backend System
Instead of the changes in `permission.ts` noted in the above example you will make them in your `index.ts`. You will need to create a module where your permission policy will get added. Here is a very simplified example of how to do that:
```ts title="packages/backend/src/index.ts"
import { createBackendModule } from '@backstage/backend-plugin-api';
import {
PolicyDecision,
AuthorizeResult,
} from '@backstage/plugin-permission-common';
import {
PermissionPolicy,
PolicyQuery,
PolicyQueryUser,
} from '@backstage/plugin-permission-node';
import { policyExtensionPoint } from '@backstage/plugin-permission-node/alpha';
class ExamplePermissionPolicy implements PermissionPolicy {
async handle(
request: PolicyQuery,
user?: PolicyQueryUser,
): Promise<PolicyDecision> {
// Various scaffolder permission checks ...
return {
result: AuthorizeResult.ALLOW,
};
}
}
const customPermissionBackendModule = createBackendModule({
pluginId: 'permission',
moduleId: 'allow-all-policy',
register(reg) {
reg.registerInit({
deps: { policy: policyExtensionPoint },
async init({ policy }) {
policy.setPolicy(new ExamplePermissionPolicy());
},
});
},
});
const backend = createBackend();
// Other plugins...
/* highlight-add-start */
backend.add(import('@backstage/plugin-permission-backend'));
backend.add(customPermissionBackendModule);
/* highlight-add-end */
```
:::note Note
The `ExamplePermissionPolicy` here could be the one from the [Authorizing parameters and steps](#authorizing-parameters-and-steps) example or from the [Authorizing actions](#authorizing-actions) example. It would work the same way for both of them.
:::
docs/features/software-templates/builtin-actions.md
+1 -1
View File
@@ -32,7 +32,7 @@ Here's how to add an action module, first you need to run this command:
yarn --cwd packages/backend add @backstage/plugin-scaffolder-backend-module-github
```
Then you need to add it to your backend, this is a simplified new backend system for example purposes:
Then you need to add it to your backend, this is a simplified backend system for example purposes:
```ts title="/packages/backend/src/index.ts"
import { createBackend } from '@backstage/backend-defaults';
docs/features/techdocs/getting-started.md
-3
View File
@@ -95,9 +95,6 @@ That's it! Now, we need the TechDocs Backend plugin for the frontend to work.
## Adding TechDocs Backend plugin
:::note
These instructions are for the new backend system. For setting this up in the old backend system, see [here](https://github.com/backstage/backstage/blob/v1.36.1/docs/features/techdocs/getting-started.md)
:::
First we need to install the `@backstage/plugin-techdocs-backend` package.
```bash title="From your Backstage root directory"
docs/features/techdocs/how-to-guides.md
+2 -2
View File
@@ -852,9 +852,9 @@ and publish the documentation for them. If the value of the `company.com/techdoc
annotation is anything other than `'local'`, the user is responsible for publishing
documentation to the appropriate location in the TechDocs external storage.
### Hybrid build strategy using the New Backend System
### Hybrid build strategy using the Backend System
To setup a hybrid build strategy using the New Backend System you'll follow the same steps as above but for Step 4 you will need to do the following:
To setup a hybrid build strategy using the Backend System you'll follow the same steps as above but for Step 4 you will need to do the following:
```ts title="packages/backend/src/index.ts"
const backend = createBackend();
docs/integrations/aws-s3/discovery.md
-4
View File
@@ -5,10 +5,6 @@ sidebar_label: Discovery
description: Automatically discovering catalog entities from an AWS S3 Bucket
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/integrations/aws-s3/discovery--old.md) instead, and [consider migrating](../../backend-system/building-backends/08-migrating.md)!
:::
The AWS S3 integration has a special entity provider for discovering catalog
entities located in an S3 Bucket. If you have a bucket that contains multiple
catalog files, and you want to automatically discover them, you can use this
docs/integrations/azure-blobStorage/discovery.md
-4
View File
@@ -5,10 +5,6 @@ sidebar_label: Discovery
description: Automatically discovering catalog entities from an Azure Blob Storage account
---
:::info
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).
:::
The Azure Blob Storage account integration has a special entity provider for discovering catalog
entities located in a storage account container. If you have a container that contains multiple
catalog files, and you want to automatically discover them, you can use this
docs/integrations/azure/discovery.md
-4
View File
@@ -5,10 +5,6 @@ sidebar_label: Discovery
description: Automatically discovering catalog entities from repositories in an Azure DevOps organization
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/integrations/azure/discovery--old.md) instead, and [consider migrating](../../backend-system/building-backends/08-migrating.md)!
:::
The Azure DevOps integration has a special entity provider for discovering catalog entities within an Azure DevOps. The provider will crawl your Azure DevOps organization and register entities matching the configured path. This can be useful as an alternative to static locations or manually adding things to the catalog.
This guide explains how to install and configure the Azure DevOps Entity Provider (recommended) or the Azure DevOps Processor.
docs/integrations/azure/org.md
-4
View File
@@ -5,10 +5,6 @@ sidebar_label: Org Data
description: Importing users and groups from Microsoft Entra ID into Backstage
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/integrations/azure/org--old.md) instead, and [consider migrating](../../backend-system/building-backends/08-migrating.md)!
:::
The Backstage catalog can be set up to ingest organizational data - users and
teams - directly from a tenant in Microsoft Entra ID via the
Microsoft Graph API.
docs/integrations/bitbucketCloud/discovery.md
+2 -55
View File
@@ -39,9 +39,9 @@ package.
yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-bitbucket-cloud
```
### Installation with New Backend System
Then add the following to your backend:
```ts
```ts title="packages/backend/src/index.ts"
// optional if you want HTTP endpoints to receive external events
// backend.add(import('@backstage/plugin-events-backend'));
// optional if you want to use AWS SQS instead of HTTP endpoints to receive external events
@@ -63,59 +63,6 @@ Further documentation:
- <https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-aws-sqs/README.md>
- <https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-bitbucket-cloud/README.md>
### Installation with Legacy Backend System
Please follow the installation instructions at
- <https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md>
- <https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-bitbucket-cloud/README.md>
Additionally, you need to decide how you want to receive events from external sources like
- [via HTTP endpoint](https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md)
- [via an AWS SQS queue](https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-aws-sqs/README.md)
- [via Google Pub/Sub](https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-google-pubsub/README.md)
- [via a Kafka topic](https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-kafka/README.md)
Set up your provider
```ts title="packages/backend/src/plugins/catalog.ts"
import { CatalogBuilder } from '@backstage/plugin-catalog-backend';
/* highlight-add-start */
import { BitbucketCloudEntityProvider } from '@backstage/plugin-catalog-backend-module-bitbucket-cloud';
/* highlight-add-end */
import { ScaffolderEntitiesProcessor } from '@backstage/plugin-scaffolder-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
const builder = await CatalogBuilder.create(env);
/* highlight-add-start */
const bitbucketCloudProvider = BitbucketCloudEntityProvider.fromConfig(
env.config,
{
auth: env.auth,
catalogApi: new CatalogClient({ discoveryApi: env.discovery }),
events: env.events,
logger: env.logger,
scheduler: env.scheduler,
},
);
builder.addEntityProvider(bitbucketCloudProvider);
/* highlight-add-end */
const { processingEngine, router } = await builder.build();
await processingEngine.start();
return router;
}
```
**Attention:**
`catalogApi` and `tokenManager` are required at this variant
compared to the one without events support.
## Configuration
To use the entity provider, you'll need a [Bitbucket Cloud integration set up](locations.md).
docs/integrations/bitbucketServer/discovery.md
+2 -6
View File
@@ -5,10 +5,6 @@ sidebar_label: Discovery
description: Automatically discovering catalog entities from repositories in Bitbucket Server
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/integrations/bitbucketServer/discovery--old.md) instead, and [consider migrating](../../backend-system/building-backends/08-migrating.md)!
:::
The Bitbucket Server integration has a special entity provider for discovering
catalog files located in Bitbucket Server.
The provider will search your Bitbucket Server account and register catalog files matching the configured path
@@ -25,9 +21,9 @@ dependency to `@backstage/plugin-catalog-backend-module-bitbucket-server` to you
yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-bitbucket-server
```
### Installation with New Backend System
Then add the following to your backend:
```ts
```ts title="packages/backend/src/index.ts"
// optional if you want HTTP endpojnts to receive external events
// backend.add(import('@backstage/plugin-events-backend'));
// optional if you want to use AWS SQS instead of HTTP endpoints to receive external events
docs/integrations/gerrit/discovery.md
-4
View File
@@ -5,10 +5,6 @@ sidebar_label: Discovery
description: Automatically discovering catalog entities from Gerrit repositories
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/integrations/gerrit/discovery--old.md) instead, and [consider migrating](../../backend-system/building-backends/08-migrating.md)!
:::
The Gerrit integration has a special entity provider for discovering catalog entities
from Gerrit repositories. The provider uses the "List Projects" API in Gerrit to get
a list of repositories and will automatically ingest all `catalog-info.yaml` files
docs/integrations/github/discovery.md
-4
View File
@@ -5,10 +5,6 @@ sidebar_label: Discovery
description: Automatically discovering catalog entities from repositories in a GitHub organization or App
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/integrations/github/discovery--old.md) instead, and [consider migrating](../../backend-system/building-backends/08-migrating.md)!
:::
## GitHub Provider
The GitHub integration has a discovery provider for discovering catalog
docs/integrations/github/org.md
-4
View File
@@ -5,10 +5,6 @@ sidebar_label: Org Data
description: Importing users and groups from a GitHub organization into Backstage
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/integrations/github/org--old.md) instead, and [consider migrating](../../backend-system/building-backends/08-migrating.md)!
:::
The Backstage catalog can be set up to ingest organizational data - users and
teams - directly from an organization in GitHub or GitHub Enterprise. The result
is a hierarchy of
docs/integrations/gitlab/discovery.md
+1 -84
View File
@@ -23,8 +23,6 @@ the gitlab catalog plugin:
yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-gitlab
```
### Installation with New Backend System
Then add the following to your backend initialization:
```ts title="packages/backend/src/index.ts"
@@ -51,87 +49,6 @@ Further documentation:
- [Events Plugin](https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md)
- [GitLab Module for the Events Plugin](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-gitlab/README.md)
### Installation with Legacy Backend System (skip if you are using Backstage v1.31.0 or later)
#### Installation without Events Support
Add the segment below to `packages/backend/src/plugins/catalog.ts`:
```ts title="packages/backend/src/plugins/catalog.ts"
/* highlight-add-next-line */
import { GitlabDiscoveryEntityProvider } from '@backstage/plugin-catalog-backend-module-gitlab';
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
const builder = await CatalogBuilder.create(env);
/* highlight-add-start */
builder.addEntityProvider(
...GitlabDiscoveryEntityProvider.fromConfig(env.config, {
logger: env.logger,
// optional: alternatively, use scheduler with schedule defined in app-config.yaml
schedule: env.scheduler.createScheduledTaskRunner({
frequency: { minutes: 30 },
timeout: { minutes: 3 },
}),
// optional: alternatively, use schedule
scheduler: env.scheduler,
}),
);
/* highlight-add-end */
// ..
}
```
#### Installation with Events Support
Please follow the installation instructions at
- [Events Plugin](https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md)
- [GitLab Module for the Events Plugin](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-gitlab/README.md)
Additionally, you need to decide how you want to receive events from external sources like
- [via HTTP endpoint](https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md)
- [via an AWS SQS queue](https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-aws-sqs/README.md)
- [via Google Pub/Sub](https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-google-pubsub/README.md)
- [via a Kafka topic](https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-kafka/README.md)
Set up your provider
```ts title="packages/backend/src/plugins/catalog.ts"
import { CatalogBuilder } from '@backstage/plugin-catalog-backend';
/* highlight-add-next-line */
import { GitlabDiscoveryEntityProvider } from '@backstage/plugin-catalog-backend-module-gitlab';
import { ScaffolderEntitiesProcessor } from '@backstage/plugin-scaffolder-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
const builder = await CatalogBuilder.create(env);
builder.addProcessor(new ScaffolderEntitiesProcessor());
/* highlight-add-start */
const gitlabProvider = GitlabDiscoveryEntityProvider.fromConfig(env.config, {
logger: env.logger,
// optional: alternatively, use scheduler with schedule defined in app-config.yaml
schedule: env.scheduler.createScheduledTaskRunner({
frequency: { minutes: 30 },
timeout: { minutes: 3 },
}),
// optional: alternatively, use schedule
scheduler: env.scheduler,
events: env.events,
});
builder.addEntityProvider(gitlabProvider);
/* highlight-add-end */
const { processingEngine, router } = await builder.build();
await processingEngine.start();
return router;
}
```
## Configuration
To use the discovery provider, you'll need a GitLab integration
@@ -140,7 +57,7 @@ to the catalog configuration.
:::note Note
If you are using the New Backend System, the `schedule` has to be setup in the config, as shown below.
The `schedule` has to be setup in the config, as shown below.
:::
docs/integrations/gitlab/org.md
+1 -89
View File
@@ -29,8 +29,6 @@ As this provider is not one of the default providers, you will first need to ins
yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-gitlab @backstage/plugin-catalog-backend-module-gitlab-org
```
### Installation with New Backend System
Then add the following to your backend initialization:
```ts title="packages/backend/src/index.ts
@@ -58,92 +56,6 @@ Further documentation:
- [Events Plugin](https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md)
- [GitLab Module for the Events Plugin](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-gitlab/README.md)
### Installation with Legacy Backend System
#### Installation without Events Support
Add the plugin to the plugin catalog `packages/backend/src/plugins/catalog.ts`:
```ts
/* packages/backend/src/plugins/catalog.ts */
/* highlight-add-next-line */
import { GitlabOrgDiscoveryEntityProvider } from '@backstage/plugin-catalog-backend-module-gitlab';
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
const builder = await CatalogBuilder.create(env);
/** ... other processors and/or providers ... */
/* highlight-add-start */
builder.addEntityProvider(
...GitlabOrgDiscoveryEntityProvider.fromConfig(env.config, {
logger: env.logger,
// optional: alternatively, use scheduler with schedule defined in app-config.yaml
schedule: env.scheduler.createScheduledTaskRunner({
frequency: { minutes: 30 },
timeout: { minutes: 3 },
}),
// optional: alternatively, use schedule
scheduler: env.scheduler,
}),
);
/* highlight-add-end */
// ..
}
```
#### Installation with Events Support
Please follow the installation instructions at
- [Events Plugin](https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md)
- [GitLab Module for the Events Plugin](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-gitlab/README.md)
Additionally, you need to decide how you want to receive events from external sources like
- [via HTTP endpoint](https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md)
- [via an AWS SQS queue](https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-aws-sqs/README.md)
- [via Google Pub/Sub](https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-google-pubsub/README.md)
- [via a Kafka topic](https://github.com/backstage/backstage/tree/master/plugins/events-backend-module-kafka/README.md)
Set up your provider
```ts title="packages/backend/src/plugins/catalog.ts"
import { CatalogBuilder } from '@backstage/plugin-catalog-backend';
/* highlight-add-next-line */
import { GitlabOrgDiscoveryEntityProvider } from '@backstage/plugin-catalog-backend-module-gitlab';
import { ScaffolderEntitiesProcessor } from '@backstage/plugin-scaffolder-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
const builder = await CatalogBuilder.create(env);
builder.addProcessor(new ScaffolderEntitiesProcessor());
/* highlight-add-start */
const gitlabOrgProvider = GitlabOrgDiscoveryEntityProvider.fromConfig(
env.config,
{
logger: env.logger,
// optional: alternatively, use scheduler with schedule defined in app-config.yaml
schedule: env.scheduler.createScheduledTaskRunner({
frequency: { minutes: 30 },
timeout: { minutes: 3 },
}),
// optional: alternatively, use schedule
scheduler: env.scheduler,
events: env.events,
},
);
builder.addEntityProvider(gitlabOrgProvider);
/* highlight-add-end */
const { processingEngine, router } = await builder.build();
await processingEngine.start();
return router;
}
```
## Configuration
To use the entity provider, you'll need a [Gitlab integration set up](https://backstage.io/docs/integrations/gitlab/locations).
@@ -163,7 +75,7 @@ will be those visible to the account which provisioned the token.
:::note Note
If you are using the New Backend System, the `schedule` has to be setup in the config, as shown below.
The `schedule` has to be setup in the config, as shown below.
:::
docs/overview/threat-model.md
+1 -1
View File
@@ -25,7 +25,7 @@ An **external user** is a user that does not belong to the other three groups, f
:::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.
[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.
:::
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.
docs/permissions/custom-rules.md
-4
View File
@@ -4,10 +4,6 @@ title: Defining custom permission rules
description: How to define custom permission rules for existing resources
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/permissions/custom-rules--old.md) instead, and [consider migrating](../backend-system/building-backends/08-migrating.md)!
:::
For some use cases, you may want to define custom [rules](../references/glossary.md#rule-permission-plugin) in addition to the ones provided by a plugin. In the [previous section](./writing-a-policy.md) we used the `isEntityOwner` rule to control access for catalog entities. Let's extend this policy with a custom rule that checks what [system](https://backstage.io/docs/features/software-catalog/system-model#system) an entity is part of.
## Define a custom rule
docs/permissions/getting-started.md
-4
View File
@@ -4,10 +4,6 @@ title: Getting Started
description: How to get started with the permission framework as an integrator
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/permissions/getting-started--old.md) instead, and [consider migrating](../backend-system/building-backends/08-migrating.md)!
:::
Backstage integrators control permissions by writing a policy. In general terms, a policy is simply an async function which receives a request to authorize a specific action for a user and (optional) resource, and returns a decision on whether to authorize that permission. Integrators can implement their own policies from scratch, or adopt reusable policies written by others.
## Prerequisites
docs/permissions/plugin-authors/01-setup.md
-4
View File
@@ -4,10 +4,6 @@ title: 1. Tutorial setup
description: How to get started with the permission framework as a plugin author
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/permissions/plugin-authors/01-setup--old.md) instead, and [consider migrating](../../backend-system/building-backends/08-migrating.md)!
:::
The following tutorial is designed to help plugin authors add support for permissions to their plugins. We'll add support for permissions to example `todo-list` and `todo-list-backend` plugins, but the process should be similar for other plugins!
The rest of this page is focused on adding the `todo-list` and `todo-list-backend` plugins to your Backstage instance. If you want to add support for permissions to your own plugin instead, feel free to skip to the [next section](./02-adding-a-basic-permission-check.md).
docs/permissions/plugin-authors/02-adding-a-basic-permission-check.md
-4
View File
@@ -4,10 +4,6 @@ title: 2. Adding a basic permission check
description: Explains how to add a basic permission check to a Backstage plugin
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/permissions/plugin-authors/02-adding-a-basic-permission-check--old.md) instead, and [consider migrating](../../backend-system/building-backends/08-migrating.md)!
:::
If the outcome of a permission check doesn't need to change for different [resources](../../references/glossary.md#resource-permission-plugin), you can use a _basic permission check_. For this kind of check, we simply need to define a permission, and call `authorize` with it.
For this tutorial, we'll use a basic permission check to authorize the `create` endpoint in our todo-backend. This will allow Backstage integrators to control whether each of their users is authorized to create todos by adjusting their [permission policy](../../references/glossary.md#policy-permission-plugin).
docs/permissions/plugin-authors/03-adding-a-resource-permission-check.md
-4
View File
@@ -4,10 +4,6 @@ title: 3. Adding a resource permission check
description: Explains how to add a resource permission check to a Backstage plugin
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/permissions/plugin-authors/03-adding-a-resource-permission-check--old.md) instead, and [consider migrating](../../backend-system/building-backends/08-migrating.md)!
:::
When performing updates (or other operations) on specific [resources](../../references/glossary.md#resource-permission-plugin), the permissions framework allows for the decision to be based on characteristics of the resource itself. This means that it's possible to write policies that (for example) allow the operation for users that own a resource, and deny the operation otherwise.
## Creating the update permission
docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data.md
-4
View File
@@ -4,10 +4,6 @@ title: 4. Authorizing access to paginated data
description: Explains how to authorize access to paginated data in a Backstage plugin
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data--old.md) instead, and [consider migrating](../../backend-system/building-backends/08-migrating.md)!
:::
Authorizing `GET /todos` is similar to the update endpoint, in that it should be possible to authorize access based on the characteristics of each resource. However, we'll need to authorize a list of resources for this endpoint.
One possible solution may leverage the batching functionality to authorize all of the todos, and then returning only the ones for which the decision was `ALLOW`:
docs/permissions/writing-a-policy.md
-4
View File
@@ -4,10 +4,6 @@ title: Writing a permission policy
description: How to write your own permission policy as a Backstage integrator
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/permissions/writing-a-policy--old.md) instead, and [consider migrating](../backend-system/building-backends/08-migrating.md)!
:::
In the [previous section](./getting-started.md), we were able to set up the permission framework and make a simple change to our `TestPermissionPolicy` to confirm that policy is indeed wired up correctly.
That policy looked like this:
docs/plugins/backend-plugin.md
-6
View File
@@ -38,12 +38,6 @@ cd plugins/carmen-backend
yarn start
```
:::note Note
This documentation assumes you are using the latest version of Backstage and the new backend system. If you are not, please upgrade and migrate your backend using the [Migration Guide](../backend-system/building-backends/08-migrating.md)
:::
This will think for a bit, and then say `Listening on :7007`. In a different
terminal window, now run
docs/plugins/integrating-search-into-plugins.md
-4
View File
@@ -4,10 +4,6 @@ title: Integrating Search into a plugin
description: How to integrate Search into a Backstage plugin
---
:::info
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](https://github.com/backstage/backstage/blob/v1.37.0/docs/plugins/integrating-search-into-plugins--old.md) instead, and [consider migrating](../backend-system/building-backends/08-migrating.md)!
:::
The Backstage Search Platform was designed to give plugin developers the APIs
and interfaces needed to offer search experiences within their plugins, while
abstracting away (and instead empowering application integrators to choose) the