Merge branch 'backstage:master' into fix-ldap-module-user-mapping
This commit is contained in:
John
@@ -58,6 +58,6 @@ If your Backstage plugin lives outside of the [Backstage main repository](https:
|
||||
|
||||
### Report identified issues
|
||||
|
||||
It’s important to remember that automated checks can only catch a small number of accessibility issues, therefore we also encourage you to conduct manual testing of your plugins using Assistive technology (screen readers, alternative navigation, and screen magnifiers are a few examples).
|
||||
It’s important to remember that automated checks can only catch a small number of accessibility issues, therefore, we also encourage you to conduct manual testing of your plugins using Assistive technology (screen readers, alternative navigation, and screen magnifiers are a few examples).
|
||||
|
||||
If you have identified accessibility issues and don’t have time to contribute a fix, please open an issue over at [Backstage Issues](https://github.com/backstage/backstage/issues) to let us know.
|
||||
|
||||
@@ -26,7 +26,7 @@ opens up for other type of themes, and removes the hardcoded usage of
|
||||
|
||||
To migrate an existing theme, remove the `theme` property and move it over to a
|
||||
new `Provider` component, using `ThemeProvider` from Material UI to provide the new
|
||||
theme, along with `<CssBaseline>`. For example a theme that currently looks like
|
||||
theme, along with `<CssBaseline>`. For example, a theme that currently looks like
|
||||
this:
|
||||
|
||||
```tsx
|
||||
@@ -84,8 +84,8 @@ migrate to your own custom API.
|
||||
First, you'll need to define a new Utility API reference. If you're only using
|
||||
the API for sign-in, you can put the definition in `packages/app/src/apis.ts`.
|
||||
However, if you need to access your auth API inside plugins you you'll need to
|
||||
export it from a common package. If you don't already have one we recommended
|
||||
creating `@internal/apis` and from there export the API reference.
|
||||
export it from a common package. If you don't already have one, we recommend
|
||||
creating `@internal/apis` and from there exporting the API reference.
|
||||
|
||||
```ts
|
||||
// `ProfileInfoApi & BackstageIdentityApi & SessionApi` are required for sign-in
|
||||
@@ -101,7 +101,7 @@ export const acmeAuthApiRef: ApiRef<
|
||||
});
|
||||
```
|
||||
|
||||
Next you'll want to wire up the API inside `packages/app/src/apis.ts`, which
|
||||
Next, you'll want to wire up the API inside `packages/app/src/apis.ts`, which
|
||||
varies depending on which API you're replacing. If you for example are replacing
|
||||
the `oauth2ApiRef`, the factory might look like this:
|
||||
|
||||
|
||||
@@ -166,10 +166,10 @@ the final say in what APIs will be loaded at runtime? The app may override the
|
||||
factories for any of the core or plugin APIs, with the exception of the config,
|
||||
app theme, and identity APIs. These are static APIs that are tied into the
|
||||
[`createApp`](../reference/app-defaults.createapp.md) implementation and
|
||||
therefore not possible to override.
|
||||
therefore, not possible to override.
|
||||
|
||||
Overriding APIs is useful for apps that want to switch out behavior to tailor it
|
||||
to their environment. In some cases plugins, may also export multiple
|
||||
to their environment. In some cases, plugins may also export multiple
|
||||
implementations of the same API, where they each have their own different
|
||||
requirements, for example, backend storage and the surrounding environment.
|
||||
|
||||
|
||||
@@ -49,9 +49,7 @@ auth:
|
||||
scope: ${AUTH_ATLASSIAN_SCOPES}
|
||||
signIn:
|
||||
resolvers:
|
||||
# typically you would pick one of these
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
# See https://backstage.io/docs/auth/atlassian/provider#resolvers for more resolvers
|
||||
- resolver: usernameMatchingUserEntityName
|
||||
```
|
||||
|
||||
|
||||
@@ -25,9 +25,8 @@ auth:
|
||||
region: 'us-west-2'
|
||||
signIn:
|
||||
resolvers:
|
||||
# typically you would pick one of these
|
||||
# See https://backstage.io/docs/auth/aws-alb/provider#resolvers for more resolvers
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
```
|
||||
|
||||
Ensure that you have set the signer correctly. It is also recommended that you restrict your target groups' security policy to only accept connections from that ALB.
|
||||
|
||||
@@ -39,11 +39,8 @@ auth:
|
||||
clientSecret: ${AUTH_BITBUCKET_CLIENT_SECRET}
|
||||
signIn:
|
||||
resolvers:
|
||||
# typically you would pick one of these
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
# See https://backstage.io/docs/auth/bitbucket/provider#resolvers for more resolvers
|
||||
- resolver: userIdMatchingUserEntityAnnotation
|
||||
- resolver: usernameMatchingUserEntityAnnotation
|
||||
```
|
||||
|
||||
The Bitbucket provider is a structure with two configuration keys:
|
||||
|
||||
@@ -41,8 +41,8 @@ auth:
|
||||
# This picks what sign in resolver(s) you want to use.
|
||||
signIn:
|
||||
resolvers:
|
||||
# See https://backstage.io/docs/auth/cloudflare/provider#resolvers for more resolvers
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
```
|
||||
|
||||
This config section must be in place for the provider to load at all.
|
||||
|
||||
@@ -51,8 +51,7 @@ auth:
|
||||
# enterpriseInstanceUrl: ${AUTH_GITHUB_ENTERPRISE_INSTANCE_URL}
|
||||
signIn:
|
||||
resolvers:
|
||||
# Matches the GitHub username with the Backstage user entity name.
|
||||
# See https://backstage.io/docs/auth/github/provider#resolvers for more resolvers.
|
||||
# See https://backstage.io/docs/auth/github/provider#resolvers for more resolvers
|
||||
- resolver: usernameMatchingUserEntityName
|
||||
```
|
||||
|
||||
|
||||
@@ -46,9 +46,7 @@ auth:
|
||||
# callbackUrl: https://${BASE_URL}/api/auth/gitlab/handler/frame
|
||||
signIn:
|
||||
resolvers:
|
||||
# typically you would pick one of these
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
# See https://backstage.io/docs/auth/gitlab/provider#resolvers for more resolvers
|
||||
- resolver: usernameMatchingUserEntityName
|
||||
```
|
||||
|
||||
|
||||
@@ -29,9 +29,7 @@ auth:
|
||||
jwtHeader: x-custom-header # Optional: Only if you are using a custom header for the IAP JWT
|
||||
signIn:
|
||||
resolvers:
|
||||
# typically you would pick one of these
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
# See https://backstage.io/docs/auth/google/gcp-iap-auth#resolvers for more resolvers
|
||||
- resolver: emailMatchingUserEntityAnnotation
|
||||
```
|
||||
|
||||
|
||||
@@ -44,9 +44,7 @@ auth:
|
||||
clientSecret: ${AUTH_GOOGLE_CLIENT_SECRET}
|
||||
signIn:
|
||||
resolvers:
|
||||
# typically you would pick one of these
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
# See https://backstage.io/docs/auth/google/provider#resolvers for more resolvers
|
||||
- resolver: emailMatchingUserEntityAnnotation
|
||||
```
|
||||
|
||||
|
||||
@@ -70,6 +70,14 @@ always be full entity references, as opposed to shorthands like just `jane` or
|
||||
|
||||
## Sign-in Resolvers
|
||||
|
||||
:::warning
|
||||
Be careful when configuring Sign-in resolvers, as they are part of determining who
|
||||
has access to your Backstage instance, and with what identity. Always only configure
|
||||
**a single sign-in resolver for one of your auth providers**. The only reason to have
|
||||
more sign-in resolvers is if you want to allow your users to sign in to Backstage in
|
||||
multiple ways, but it increases the risk of account hijacking.
|
||||
:::
|
||||
|
||||
Signing in a user into Backstage requires a mapping of the user identity from the
|
||||
third-party auth provider to a Backstage user identity. This mapping can vary quite
|
||||
a lot between different organizations and auth providers, and because of that there's
|
||||
@@ -112,19 +120,38 @@ auth:
|
||||
signIn:
|
||||
resolvers:
|
||||
- resolver: usernameMatchingUserEntityName
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
```
|
||||
|
||||
Note that in this instance it lists several resolvers, which means that the
|
||||
framework will try them one by one until one succeeds. If none of them do, the
|
||||
sign in attempt is rejected.
|
||||
|
||||
The list of available resolvers is different for each provider, since they often
|
||||
depend on the information model returned from the upstream provider service.
|
||||
Consult the documentation of the respective provider to find the list.
|
||||
|
||||
In the example above `emailMatchingUserEntityProfileEmail` and `emailLocalPartMatchingUserEntityName` are common to all auth providers and `usernameMatchingUserEntityName` is specific to GitHub.
|
||||
In the example above, the `usernameMatchingUserEntityName` is specific to the
|
||||
GitHub provider, but you could also choose to use the
|
||||
`emailMatchingUserEntityProfileEmail` or `emailLocalPartMatchingUserEntityName`
|
||||
resolvers, which are common to all auth providers.
|
||||
|
||||
:::warning
|
||||
When using the `emailLocalPartMatchingUserEntityName` resolver it is strongly
|
||||
recommended to set the `allowedDomains` option to ensure that only authorized users
|
||||
are able to sign-in.
|
||||
:::
|
||||
|
||||
If you are using the `emailLocalPartMatchingUserEntityName` resolver, it is
|
||||
recommended to also set the `allowedDomains` option, for example:
|
||||
|
||||
```yaml title="Within the provider configuration"
|
||||
auth:
|
||||
providers:
|
||||
github:
|
||||
development:
|
||||
...
|
||||
signIn:
|
||||
resolvers:
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
allowedDomains:
|
||||
- acme.org
|
||||
```
|
||||
|
||||
### Building Custom Resolvers
|
||||
|
||||
@@ -160,8 +187,6 @@ auth:
|
||||
signIn:
|
||||
resolvers:
|
||||
- resolver: usernameMatchingUserEntityName
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
/* highlight-remove-end */
|
||||
```
|
||||
|
||||
@@ -318,6 +343,12 @@ async signInResolver({ profile: { email} }, ctx) {
|
||||
|
||||
### Sign-In without Users in the Catalog
|
||||
|
||||
:::warning
|
||||
Signing in users without verifying that they exist in the catalog can be
|
||||
dangerous. Take care to ensure that your custom resolvers only allow expected
|
||||
users to sign in, for example by checking email domains.
|
||||
:::
|
||||
|
||||
While populating the catalog with organizational data unlocks more powerful ways
|
||||
to browse your software ecosystem, it might not always be a viable or prioritized
|
||||
option. However, even if you do not have user entities populated in your catalog, you
|
||||
|
||||
@@ -66,9 +66,7 @@ auth:
|
||||
azureEasyAuth:
|
||||
signIn:
|
||||
resolvers:
|
||||
# typically you would pick one of these
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
# See https://backstage.io/docs/auth/microsoft/easy-auth#resolvers for more resolvers
|
||||
- resolver: idMatchingUserEntityAnnotation
|
||||
```
|
||||
|
||||
|
||||
@@ -69,10 +69,7 @@ auth:
|
||||
domainHint: ${AZURE_TENANT_ID}
|
||||
signIn:
|
||||
resolvers:
|
||||
# typically you would pick one of these
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
- resolver: emailMatchingUserEntityAnnotation
|
||||
# See https://backstage.io/docs/auth/microsoft/provider#resolvers for more resolvers
|
||||
- resolver: userIdMatchingUserEntityAnnotation
|
||||
```
|
||||
|
||||
@@ -86,6 +83,7 @@ The Microsoft provider is a structure with three mandatory configuration keys:
|
||||
When specified, this reduces login friction for users with accounts in multiple tenants by automatically filtering away accounts from other tenants.
|
||||
For more details, see [Home Realm Discovery](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/home-realm-discovery-policy)
|
||||
- `additionalScopes` (optional): List of scopes for the App Registration, to be requested in addition to the required ones.
|
||||
- `skipUserProfile` (optional): If true, skips loading the user profile even if the `User.Read` scope is present. This is a performance optimization during login and can be used with resolvers that only needs the email address in `spec.profile.email` obtained when the `email` OAuth2 scope is present.
|
||||
|
||||
### Resolvers
|
||||
|
||||
|
||||
@@ -31,9 +31,7 @@ auth:
|
||||
oauth2Proxy:
|
||||
signIn:
|
||||
resolvers:
|
||||
# typically you would pick one of these
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
# See https://backstage.io/docs/auth/oauth2-proxy/provider#resolvers for more resolvers
|
||||
- resolver: forwardedUserMatchingUserEntityName
|
||||
```
|
||||
|
||||
|
||||
@@ -156,8 +156,6 @@ auth:
|
||||
# ...
|
||||
signIn:
|
||||
resolvers:
|
||||
# typically you would pick one of these
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
```
|
||||
|
||||
|
||||
@@ -49,9 +49,7 @@ auth:
|
||||
additionalScopes: ${AUTH_OKTA_ADDITIONAL_SCOPES} # Optional
|
||||
signIn:
|
||||
resolvers:
|
||||
# typically you would pick one of these
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
# See https://backstage.io/docs/auth/okta/provider#resolvers for more resolvers
|
||||
- resolver: emailMatchingUserEntityAnnotation
|
||||
```
|
||||
|
||||
|
||||
@@ -40,9 +40,7 @@ auth:
|
||||
issuer: https://<company>.onelogin.com/oidc/2
|
||||
signIn:
|
||||
resolvers:
|
||||
# typically you would pick one of these
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
# See https://backstage.io/docs/auth/onelogin/provider#resolvers for more resolvers
|
||||
- resolver: usernameMatchingUserEntityName
|
||||
```
|
||||
|
||||
|
||||
@@ -49,10 +49,8 @@ auth:
|
||||
organizationId: ${ORG_ID}
|
||||
signIn:
|
||||
resolvers:
|
||||
# typically you would pick one of these
|
||||
# See https://backstage.io/docs/auth/vmware-cloud/provider#resolvers for more resolvers
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
- resolver: vmwareCloudSignInResolvers
|
||||
```
|
||||
|
||||
Where `APP_ID` refers to the ID retrieved when creating the OAuth App, and
|
||||
@@ -76,7 +74,6 @@ This provider includes several resolvers out of the box that you can use:
|
||||
|
||||
- `emailMatchingUserEntityProfileEmail`: 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 throw a `NotFoundError`.
|
||||
- `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 Note
|
||||
|
||||
|
||||
@@ -884,8 +884,6 @@ auth:
|
||||
signIn:
|
||||
resolvers:
|
||||
- resolver: emailMatchingUserEntityProfileEmail
|
||||
- resolver: emailLocalPartMatchingUserEntityName
|
||||
- resolver: emailMatchingUserEntityAnnotation
|
||||
```
|
||||
|
||||
:::note Note
|
||||
|
||||
@@ -44,7 +44,7 @@ There's additional configuration that you can optionally pass to setup the `conf
|
||||
You can configure these additional options by adding an override for the core service when calling `createBackend` like follows:
|
||||
|
||||
```ts
|
||||
import { rootConfigServiceFactory } from '@backstage/backend-app-api';
|
||||
import { rootConfigServiceFactory } from '@backstage/backend-defaults/rootConfig';
|
||||
|
||||
const backend = createBackend();
|
||||
|
||||
|
||||
@@ -143,21 +143,54 @@ how highlighted terms look you can follow Backstage's guide on how to
|
||||
[Customize the look-and-feel of your App](https://backstage.io/docs/getting-started/app-custom-theme)
|
||||
to create an override with your preferred styling.
|
||||
|
||||
For example, the following will result in highlighted terms to be bold & underlined:
|
||||
For example, using the new MUI V4+V5 unified theming method, the following will result
|
||||
in highlighted words to be bold & underlined:
|
||||
|
||||
```tsx
|
||||
const highlightOverride = {
|
||||
BackstageHighlightedSearchResultText: {
|
||||
highlight: {
|
||||
color: 'inherit',
|
||||
backgroundColor: 'inherit',
|
||||
fontWeight: 'bold',
|
||||
textDecoration: 'underline',
|
||||
```typescript jsx title=packages/app/src/theme/theme.ts
|
||||
import {
|
||||
createBaseThemeOptions,
|
||||
createUnifiedTheme,
|
||||
palettes,
|
||||
UnifiedTheme,
|
||||
} from '@backstage/theme';
|
||||
|
||||
export const myLightTheme: UnifiedTheme = createUnifiedTheme({
|
||||
...createBaseThemeOptions({
|
||||
palette: palettes.light,
|
||||
}),
|
||||
defaultPageTheme: 'home',
|
||||
components: {
|
||||
/** @ts-ignore This is temporarily necessary until MUI V5 transition is completed. */
|
||||
BackstageHighlightedSearchResultText: {
|
||||
styleOverrides: {
|
||||
highlight: {
|
||||
color: 'inherit',
|
||||
backgroundColor: 'inherit',
|
||||
fontWeight: 'bold',
|
||||
textDecoration: 'underline',
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
});
|
||||
```
|
||||
|
||||
```typescript jsx title= packages/app/src/App.tsx
|
||||
|
||||
const app : BackstageApp = createApp({
|
||||
...
|
||||
themes: [{
|
||||
id: 'my-light-theme',
|
||||
title: 'Light Theme',
|
||||
variant: 'light',
|
||||
icon: <LightIcon />,
|
||||
Provider: ({ children }) => (<UnifiedThemeProvider theme={myLightTheme} children={children } />)
|
||||
}]
|
||||
});
|
||||
```
|
||||
|
||||
Obviously if you wanted a dark theme, you would need to provide that as well.
|
||||
|
||||
## How to render search results using extensions
|
||||
|
||||
Extensions for search results let you customize components used to render search result items, It is possible to provide your own search result item extensions or use the ones provided by plugin packages.
|
||||
|
||||
@@ -120,6 +120,36 @@ techdocs:
|
||||
Your Backstage app is now ready to use Google Cloud Storage for TechDocs, to
|
||||
store and read the static generated documentation files.
|
||||
|
||||
### Extending default Storage configuration
|
||||
|
||||
If you need a non-standard configuration of Google Cloud Storage client,
|
||||
`TechdocsPublisherExtensionPoint` is something you should look at.
|
||||
You can register custom `StorageOptions` that will be used to configure the client. To do so, you
|
||||
need to register publisher settings inside your module init, like in the following example:
|
||||
|
||||
```typescript
|
||||
export const gcsPublisherCustomizer = createBackendModule({
|
||||
pluginId: 'techdocs',
|
||||
moduleId: 'gcs-publisher-customizer',
|
||||
register(reg) {
|
||||
reg.registerInit({
|
||||
deps: {
|
||||
techdocsExtensionPoint: techdocsPublisherExtensionPoint,
|
||||
},
|
||||
async init({ techdocsExtensionPoint }) {
|
||||
const customOptions: StorageOptions = {
|
||||
userAgent: 'my-custom-user-agent',
|
||||
};
|
||||
techdocsExtensionPoint.registerPublisherSettings(
|
||||
'googleGcs',
|
||||
customOptions,
|
||||
);
|
||||
},
|
||||
});
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## Configuring AWS S3 Bucket with TechDocs
|
||||
|
||||
**1. Set `techdocs.publisher.type` config in your `app-config.yaml`**
|
||||
|
||||
@@ -51,33 +51,6 @@ Further documentation:
|
||||
|
||||
### Installation with Legacy Backend System
|
||||
|
||||
#### Installation without Events Support
|
||||
|
||||
And then add the entity provider to your catalog builder:
|
||||
|
||||
```ts title="packages/backend/src/plugins/catalog.ts"
|
||||
/* highlight-add-next-line */
|
||||
import { BitbucketCloudEntityProvider } from '@backstage/plugin-catalog-backend-module-bitbucket-cloud';
|
||||
|
||||
export default async function createPlugin(
|
||||
env: PluginEnvironment,
|
||||
): Promise<Router> {
|
||||
const builder = await CatalogBuilder.create(env);
|
||||
/* highlight-add-start */
|
||||
builder.addEntityProvider(
|
||||
BitbucketCloudEntityProvider.fromConfig(env.config, {
|
||||
logger: env.logger,
|
||||
scheduler: env.scheduler,
|
||||
}),
|
||||
);
|
||||
/* highlight-add-end */
|
||||
|
||||
// ..
|
||||
}
|
||||
```
|
||||
|
||||
#### Installation with Events Support
|
||||
|
||||
Please follow the installation instructions at
|
||||
|
||||
- <https://github.com/backstage/backstage/tree/master/plugins/events-backend/README.md>
|
||||
@@ -104,19 +77,17 @@ export default async function createPlugin(
|
||||
env: PluginEnvironment,
|
||||
): Promise<Router> {
|
||||
const builder = await CatalogBuilder.create(env);
|
||||
builder.addProcessor(new ScaffolderEntitiesProcessor());
|
||||
/* 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,
|
||||
tokenManager: env.tokenManager,
|
||||
},
|
||||
);
|
||||
env.eventBroker.subscribe(bitbucketCloudProvider);
|
||||
builder.addEntityProvider(bitbucketCloudProvider);
|
||||
/* highlight-add-end */
|
||||
const { processingEngine, router } = await builder.build();
|
||||
|
||||
@@ -53,11 +53,11 @@ Note that the `UrlReaderService` system operates with a service context and is n
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
In order to use an auth provider to sign in users into Backstage, it needs to be configured with a [sign-in resolver](https://backstage.io/docs/auth/identity-resolver). The sign-in resolver is a sensitive part of configuring Backstage and it is important that it always resolves user identities correctly, and rejects unauthorized users. There are a number of built-in sign-in resolvers that can simplify configuration, or you can implement your own custom sign-in resolver in code, either way it is very important that these resolvers map user identities correctly. You should **always use the minimum number of sign-in resolvers necessary** to avoid risk of account hijacking.
|
||||
|
||||
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.
|
||||
As part of signing in with a sign-in 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.
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -559,6 +559,15 @@ The overrides in a single `package.json` may for example look like this:
|
||||
},
|
||||
```
|
||||
|
||||
## Caching
|
||||
|
||||
Caching is used sparingly throughout the Backstage build system. It is always used as a way to squeeze out a little bit of extra performance, rather than requirement to keep things fast. The following is a list of places where optional caching is available:
|
||||
|
||||
- **TypeScript** - The default `tsconfig.json` used by Backstage projects has `incremental` set to `true`, which enables local caching of type checking results. It is however generally not recommended in CI, where `yarn tsc:full` is preferred, which sets `--incremental false`.
|
||||
- **Testing** - The `backstage-cli repo test` command has a `--successCache` flag that enables caching of successful test results. This is done at the package level, meaning that if a package has not been changed since the last test run and it was successful, the testing will be skipped. This is recommended to be used in CI, but not during local development.
|
||||
- **Linting** - The `backstage-cli repo lint` command has a `--successCache` flag that enables caching of successful linting results. This is done at the package level, meaning that if a package has not been changed since the last lint run and it was successful, the linting will be skipped. This is recommended to be used in CI, but not during local development.
|
||||
- **Webpack** - It is possible to enable experimental caching of frontend package builds using the `BACKSTAGE_CLI_EXPERIMENTAL_BUILD_CACHE` environment variable. This will enable the Webpack filesystem cache.
|
||||
|
||||
### Debugging Jest Tests
|
||||
|
||||
For your productivity working with unit tests it's quite essential to have your debugging configured in IDE. It will help you to identify the root cause of the issue faster.
|
||||
|
||||
Reference in New Issue
Block a user