@spotify/backstage-plugin-rbac-backend

Spotify Plugins for Backstage: Role-Based Access Control (RBAC) - Backend

The RBAC plugin works with the Backstage permission framework to provide support for role-based access control in Backstage. The Backstage permission framework is a system in the open-source Backstage project, which allows granular control of access to specific resources or actions. The permission framework is currently supported in the Catalog and TechDocs, with other core features soon to come. In the future, we’ll encourage third-party plugin authors to add permission support too — which can be done without changes to the Backstage core.

Permissions are controlled in a Backstage instance through a policy. 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. Without the RBAC plugin, integrators must implement their own policies from scratch, or adapt reusable policies written by others.

The RBAC plugin allows you to control permissions in Backstage without writing code. Instead, you can manage your policy using the RBAC interface integrated with Backstage. Once you publish the changes to your policy, they will be reflected immediately.

With the RBAC plugin, you manage the permissions in your Backstage instance by assigning users and groups to roles, and configuring the rules that should apply for each role. You can use powerful matching features to keep your policy short, or supply granular decisions for each available permission and role.

Prerequisites

The RBAC plugin depends on a few other Backstage systems and features. It's possible that your Backstage instance already have some portion of these steps set up. If any of these are not yet set up, you'll need to set them up before installing RBAC.

1. Complete Spotify plugin bundle setup

This package is a Backstage plugin and is part of the “Spotify Plugins for Backstage” bundle. In order for you to use this plugin, you must purchase a license key at https://backstage.spotify.com/. After purchasing a license key, follow the instructions on https://backstage.spotify.com/account before continuing.

2. Check your Backstage version

Please ensure your Backstage version matches the supported version shown under the installation instructions on https://backstage.spotify.com/account, and always check compatibility before updating Backstage.

3. Enable backend-to-backend authentication

Backend-to-backend authentication lets backend code in Backstage securely verify that a given request originates from another part of the backend, rather than from a user. This is useful for tasks like indexing catalog entities for search. This type of request shouldn’t be permissioned, so this feature must be enabled before turning on permissions.

To set up backend-to-backend authentication, follow the setup instructions in the backstage.io docs.

4. Supply an identity resolver to populate group membership on sign in

Like many other parts of Backstage, both the permission framework and the RBAC policy rely on group membership. This allows the RBAC configuration to have groups as members of a role, rather than exhaustively listing each person in the desired groups.

Group membership is also useful for policy decisions — for example, allowing someone to act on an entity when they are a member of the group that owns it.

When populating groups, include any groups that you plan to assign an RBAC role, and any groups that have a corresponding catalog entity.

The IdentityResolver docs on backstage.io describe the process for resolving group membership on sign in. If you can see a reference to a sensible entity and groups on your Backstage profile, you're ready to go.

5. Set up the permission framework

Before you can use RBAC, you’ll need to set up the permission framework in Backstage. Since we'll be replacing the policy with the dynamic one supplied by RBAC, you don't need to complete the steps associated with policy authoring -- you can stop once you've enabled and tested the permissions system.

Installation

1. Getting the plugin

Add the RBAC packages as dependencies to your Backstage instance:

yarn workspace backend add @spotify/backstage-plugin-rbac-backend

2. Configure RBAC administrator users

The ability to view and adjust the RBAC policy configuration is granted to a fixed set of users and groups specified by the configuration property permission.rbac.authorizedUsers. Any other users visiting /rbac will see an error.

Add the entity references for the Backstage users and groups who should be permitted to configure RBAC to your app-config.yaml as follows:

permission:
  enabled: true
  rbac:
    authorizedUsers:
      - group:default/admins
      - user:default/alice
      - user:default/bob

3. Configure permissioned plugins

In order for the RBAC UI to aggregate information about the available permissions in Backstage, it's necessary to provide a list of plugins which include permissions in the RBAC configuration. At time of writing, the only first-party Backstage plugin which includes permissions is catalog. If you're using third-party or in-house plugins which include permissions, you should include those plugins as well.

  permission:
    enabled: true
+   permissionedPlugins:
+     - catalog
    rbac:
      authorizedUsers:
        - group:default/admins
        - user:default/alice
        - user:default/bob

4. Install RBAC backend

The RBAC backend handles storing policy configuration in the database and exposing it to the RBAC UI and to the RBAC policy running inside the permission framework.

• Add the following to a new file, packages/backend/src/plugins/rbac.ts:

  import { createRouter } from '@spotify/backstage-plugin-rbac-backend';
  import { Router } from 'express';
  import type { PluginEnvironment } from '../types';
  
  export default function createPlugin(
    env: PluginEnvironment,
  ): Promise<Router> {
    return createRouter(env);
  }
  

• Wire up the RBAC backend in packages/backend/src/index.ts. You’ll need to import the module from the previous step, create a plugin environment, and add the router to the express app:

    // packages/backend/src/index.ts
  
    import proxy from './plugins/proxy';
    import techdocs from './plugins/techdocs';
    import search from './plugins/search';
    import permission from './plugins/permission';
  + import rbac from './plugins/rbac';
  
    /* ... */
  
    const techdocsEnv = useHotMemoize(module, () => createEnv('techdocs'));
    const searchEnv = useHotMemoize(module, () => createEnv('search'));
    const appEnv = useHotMemoize(module, () => createEnv('app'));
    const permissionEnv = useHotMemoize(module, () => createEnv('permission'));
  + const rbacEnv = useHotMemoize(module, () => createEnv('rbac'));
  
    /* ... */
  
    apiRouter.use('/techdocs', await techdocs(techdocsEnv));
    apiRouter.use('/proxy', await proxy(proxyEnv));
    apiRouter.use('/search', await search(searchEnv));
    apiRouter.use('/permission', await permission(permissionEnv));
  + apiRouter.use('/rbac', await rbac(rbacEnv));
  

5. Install RBAC frontend

From here, follow the RBAC frontend documentation in order to finish your installation of RBAC.