Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(rbac): add documentation for api and known permissions #1000

Merged
merged 1 commit into from
Dec 8, 2023
Merged

docs(rbac): add documentation for api and known permissions #1000

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 27 additions & 10 deletions plugins/rbac-backend/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,12 @@ To effectively utilize the RBAC plugin, you must have the Backstage permission f

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.

Note: Red Hat Developer Hub users enjoy the benefit of Permission Framework and backend-to-backend authentication being enabled by default

### Configuring the Backend

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:

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

import {
Expand All @@ -48,18 +47,32 @@ export default async function createPlugin(
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:

```ts
apiRouter.use(
'/permission',
await permission(permissionEnv, {
// return list static plugin which supports Backstage permissions.
getPluginIds: () => ['catalog', 'scaffolder', 'permission'],
}),
);
// ...
/* 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 */
}
```

### Identity resolver
Expand Down Expand Up @@ -96,6 +109,8 @@ permission:
- name: group:default/admins
```

For more information on the available API endpoints, refer to the [API documentation](./docs/apis.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.
Expand All @@ -104,7 +119,7 @@ Here's an example of an external permission policies configuration file named `r

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

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

Expand All @@ -128,6 +143,8 @@ permission:
policies-csv-file: /some/path/rbac-policy.csv
```

For more information on the available permissions within Showcase and RHDH, refer to the [permissions documentation](./docs/permissions.md).

### Configuring Database Storage for policies

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