npm package: @oandriie/plugin-rbac-backend
Description: This plugin seamlessly integrates with the [Backstage permission framework](https://backstage.io/docs/permissions/overview/) to empower you with robust role-based access control capabilities within your Backstage environment.
Author: Red Hat
Latest version: 7.8.2

# RBAC backend plugin for Backstage

This plugin seamlessly integrates with the [Backstage permission framework](https://backstage.io/docs/permissions/overview/) 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 Permission Framework

**NOTE**: This section is only relevant if you are still on the old backend system.

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](https://backstage.io/docs/permissions/getting-started/).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](https://backstage.io/docs/auth/service-to-service-auth/#setup). 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](https://backstage.io/docs/auth/identity-resolver/) 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.

```SHELL
yarn workspace backend add @backstage-community/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

#### 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 and remove the Allow All Permission policy module.

```diff
// permission plugin
backend.add(import('@backstage/plugin-permission-backend'));
- backend.add(
-    import('@backstage/plugin-permission-backend-module-allow-all-policy'),
-  );
+ backend.add(import('@backstage-community/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:

```YAML
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:

```YAML
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](./docs/apis.md).

### Configure default role

You can optionally assign a default role to all authenticated users by using `defaultPermissions.defaultRole`.
This ensures that every authenticated user receives the specified role in addition to any other roles they may have.
You can also define baseline permissions for that role using `defaultPermissions.basicPermissions`.
This is especially useful when using [Sign-In without Users in the Catalog](https://backstage.io/docs/auth/identity-resolver/#sign-in-without-users-in-the-catalog).

```YAML
permission:
  rbac:
    defaultPermissions:
      defaultRole: role:default/my-default-role
      basicPermissions:
        - permission: catalog.entity.read
          action: read
          effect: allow
        - permission: catalog-entity
          action: read
        - permission: catalog.entity.create
          action: create
```

If configured, the RBAC backend will automatically include the default role in each authenticated user's roles and evaluate the configured `basicPermissions` for that role.
When `defaultPermissions.defaultRole` is set, `defaultPermissions.basicPermissions` must contain at least one permission entry.

### Configure plugins with permission

In order for the RBAC UI to display the available permissions provided by installed plugins, you must supply the corresponding list of plugin IDs. There are two ways to achieve this:

- Application configuration(`app-config.yaml`)
- REST API

#### Configure plugins with Application configuration

You can specify the plugins with permissions in your application configuration as follows:

```YAML
permission:
  enabled: true
  rbac:
    pluginsWithPermission:
      - catalog
      - scaffolder
      - permission
    admin:
      users:
        - name: user:default/alice
        - name: group:default/admins
```

#### Configure plugins with REST API

You can specify the plugins with permissions using the corresponding [REST API](./docs/apis.md#plugin-ids-that-support-the-backstage-permission-framework).

Curl Examples:

Get the object containing the list of plugin IDs:

```
curl -X GET "http://localhost:7007/api/permission/plugins/id" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" -v
```

Add more plugin IDs:

```
curl -X POST "http://localhost:7007/api/permission/plugins/id" \
  -d '{ "ids": [ "permission", "scaffolder" ] }' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" -v
```

Remove plugin IDs:

```
curl -X DELETE "http://localhost:7007/api/permission/plugins/id" \
  -d '{ "ids": [ "permission", "scaffolder" ] }' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" -v
```

Notice: The REST API does not allow deletion of plugin IDs that were provided via application configuration, in order to prevent an inconsistent state after a deployment restart. These ID values can only be removed through the configuration file.

For more information on the available permissions, refer to the [RBAC permissions documentation](./docs/permissions.md).

### 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](https://casbin.org/docs/category/the-basics), 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`:

```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:

```YAML
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.

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

For more information on the available permissions, refer to the [RBAC permissions documentation](./docs/permissions.md).

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](./docs/apis.md).

### Configuring conditional policies via file

The RBAC plugin allows you to import conditional policies from an external file. User can defined conditional policies for roles created with the help of the policies-csv-file. Conditional policies should be defined as object sequences in the YAML format.

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

```YAML
permission:
  enabled: true
  rbac:
    conditionalPoliciesFile: /some/path/conditional-policies.yaml
    policies-csv-file: /some/path/rbac-policy.csv
```

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

```YAML
permission:
  enabled: true
  rbac:
    conditionalPoliciesFile: /some/path/conditional-policies.yaml
    policies-csv-file: /some/path/rbac-policy.csv
    policyFileReload: true
```

This feature supports nested conditional policies.

Example of the conditional policies file:

```yaml
---
result: CONDITIONAL
roleEntityRef: role:default/test
pluginId: catalog
resourceType: catalog-entity
permissionMapping:
  - read
  - update
conditions:
  rule: IS_ENTITY_OWNER
  resourceType: catalog-entity
  params:
    claims:
      - group:default/team-a
      - group:default/team-b
---
result: CONDITIONAL
roleEntityRef: role:default/test
pluginId: catalog
resourceType: catalog-entity
permissionMapping:
  - delete
conditions:
  rule: IS_ENTITY_OWNER
  resourceType: catalog-entity
  params:
    claims:
      - group:default/team-a
```

Information about condition policies format you can find in the doc: [Conditional policies documentation](./docs/conditions.md). There is only one difference: yaml format compare to json. But yaml and json are back convertiable.

### 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.

```YAML
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.

More information about group hierarchy can be found in the doc: [Group hierarchy](./docs/group-hierarchy.md).

### Optional RBAC provider module support

We also include the ability to create and load in RBAC backend plugin modules that can be used to make connections to third part access management tools. For more information, consult the [RBAC Providers documentation](./docs/providers.md).

### Optional configuration to control policy decision precedence

Controls the evaluation order between permission policies (basic) and conditional policies for resource permissions.

- Default: `conditional` (conditional policies take precedence when present)
- Set to `basic` to evaluate basic permission policy first

```YAML
permission:
  enabled: true
  rbac:
    policyDecisionPrecedence: basic # or conditional
```