RBAC backend plugin for Backstage

This plugin seamlessly integrates with the Backstage permission framework to empower you with robust role-based access control capabilities within your Backstage environment.

The Backstage permission framework is a core component of the Backstage project, designed to provide meticulous control over resource and action access. Our RBAC plugin harnesses the power of this framework, allowing you to tailor access permissions without the need for coding. Instead, you can effortlessly manage your access policies through User interface embedded within Backstage or via the configuration files.

With the RBAC plugin, you'll have the means to efficiently administer permissions within your Backstage instance by assigning them to users and groups.

Prerequisites

Before you dive into utilizing the RBAC plugin for Backstage, there are a few essential prerequisites to ensure a seamless experience. Please review the following requirements to make sure your environment is properly set up

Setup Permision Framework

To effectively utilize the RBAC plugin, you must have the Backstage permission framework in place. If you're using the Red Hat Developer Hub, some of these steps may have already been completed for you. However, for other Backstage application instances, please verify that the following prerequisites are satisfied:

You need to set up the permission framework in Backstage.Since this plugin provides a dynamic policy that replaces the traditional one, there's no need to create a policy manually. Please note that one of the requirements for permission framework is enabling the service-to-service authentication. Ensure that you complete these authentication setup steps as well.

Identity resolver

The permission framework, and consequently, this RBAC plugin, rely on the concept of group membership. To ensure smooth operation, please follow the Sign-in identities and resolvers documentation. It's crucial that when populating groups, you include any groups that you plan to assign permissions to.

Installation

To integrate the RBAC plugin into your Backstage instance, follow these steps.

Installing the plugin

Add the RBAC plugin packages as dependencies by running the following command.

yarn workspace backend add @janus-idp/backstage-plugin-rbac-backend

NOTE: If you are using Red Hat Developer Hub backend plugin is pre-installed and you do not need this step.

Configuring the Backend

Old Backend System

To connect the RBAC framework to your backend use the PolicyBuilder class in your backend permissions plugin (typically packages/backend/src/plugins/permissions.ts) as follows:

/* highlight-add-start */
import { Router } from 'express';

import {
  PluginIdProvider,
  PolicyBuilder,
} from '@janus-idp/backstage-plugin-rbac-backend';

import { PluginEnvironment } from '../types';

export default async function createPlugin(
  env: PluginEnvironment,
  pluginIdProvider: PluginIdProvider,
): Promise<Router> {
  return PolicyBuilder.build(
    {
      config: env.config,
      logger: env.logger,
      discovery: env.discovery,
      identity: env.identity,
      permissions: env.permissions,
    },
    pluginIdProvider,
  );
}
/* highlight-add-end */

Secondly, in your backend router (typically packages/backend/src/index.ts) add a route for /permission specifying the list of plugin id's that support permissions:

// ...
/* highlight-add-next-line */
import permission from './plugins/permissions';

async function main() {
  // ...
  /* highlight-add-next-line */
  const permissionEnv = useHotMemoize(module, () => createEnv('permission'));

  // ...
  /* highlight-add-start */
  apiRouter.use(
    '/permission',
    await permission(permissionEnv, {
      // return list static plugin which supports Backstage permissions.
      getPluginIds: () => ['catalog', 'scaffolder', 'permission'],
    }),
  );
  /* highlight-add-end */
}

New Backend System

The RBAC plugin supports the integration with the new backend system.

Add the RBAC plugin to the packages/backend/src/index.ts file.

backend.add(import('@janus-idp/backstage-plugin-rbac-backend'));

Configure policy admins

The RBAC plugin empowers you to manage permission policies for users and groups with a designated group of individuals known as policy administrators. These administrators are granted access to the RBAC plugin's REST API and user interface as well as the ability to read from the catalog.

You can specify the policy administrators in your application configuration as follows:

permission:
  enabled: true
  rbac:
    admin:
      users:
        - name: user:default/alice
        - name: group:default/admins

The RBAC plugin also enables you to grant users the title of 'super user,' which provides them with unrestricted access throughout the Backstage instance.

You can specify the super users in your application configuration as follows:

permission:
  enabled: true
  rbac:
    admin:
      superUsers:
        - name: user:default/alice
        - name: user:default/mike

For more information on the available API endpoints accessible to the policy administrators, refer to the API documentation.

Configuring policies via file

The RBAC plugin also allows you to import policies from an external file. These policies are defined in the Casbin rules format, known for its simplicity and clarity. For a quick start, please refer to the format details in the provided link.

Here's an example of an external permission policies configuration file named rbac-policy.csv:

p, role:default/team_a, catalog-entity, read, deny
p, role:default/team_b, catalog.entity.create, create, deny

g, user:default/bob, role:default/team_a

g, group:default/team_b, role:default/team_b

NOTE: When you add a role in the permission policies configuration file, ensure that the role is associated with at least one permission policy with the allow effect.

You can specify the path to this configuration file in your application configuration:

permission:
  enabled: true
  rbac:
    policies-csv-file: /some/path/rbac-policy.csv

Also, there is an additional configuration value that allows for the reloading of the CSV file without the need to restart.

permission:
  enabled: true
  rbac:
    policies-csv-file: /some/path/rbac-policy.csv
    policyFileReload: true

For more information on the available permissions within Showcase and RHDH, refer to the permissions documentation.

We also have a fairly strict validation for permission policies and roles based on the originating role's source information, refer to the api documentation.

Configuring Database Storage for policies

The RBAC plugin offers the option to store policies in a database. It supports two database storage options:

• sqlite3: Suitable for development environments.
• postgres: Recommended for production environments.

Ensure that you have already configured the database backend for your Backstage instance, as the RBAC plugin utilizes the same database configuration.

Optional maximum depth

The RBAC plugin also includes an option max depth feature for organizations with potentially complex group hierarchy, this configuration value will ensure that the RBAC plugin will stop at a certain depth when building user graphs.

permission:
  enabled: true
  rbac:
    maxDepth: 1

The maxDepth must be greater than 0 to ensure that the graphs are built correctly. Also the graph will be built with a hierarchy of 1 + maxDepth.