Skip to content

Commit

Permalink
docs(rbac): add documentation for api and known permissions (janus-id…
Browse files Browse the repository at this point in the history
  • Loading branch information
PatAKnight authored Dec 8, 2023
1 parent 63590cc commit 8f8133f
Show file tree
Hide file tree
Showing 3 changed files with 492 additions and 10 deletions.
37 changes: 27 additions & 10 deletions plugins/rbac-backend/README.md
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

0 comments on commit 8f8133f

Please sign in to comment.