Skip to content

Commit c9ee1af

Browse files
boazpoolmanpwizla
boazpoolman
and
pwizla
authored
Add a guide about using RBAC from plugins (#2788)
* docs: add documentation about using rbac from plugins * Fix typo * Update docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md * Update docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md * Update docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md * Update docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md * Update docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md * Update docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md * Update docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md --------- Co-authored-by: Pierre Wizla <pwizla+github@gmail.com>
1 parent d864aec commit c9ee1af

File tree

4 files changed

+316
-0
lines changed

4 files changed

+316
-0
lines changed

‎docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
---
2+
title: How to create admin permissions from plugins
3+
description: Learn how to create and configure admin permissions for your plugin
4+
sidebar_label: Create admin permissions for plugins
5+
displayed_sidebar: cmsSidebar
6+
tags:
7+
- admin panel
8+
- RBAC
9+
- Role Based Access Control
10+
- guides
11+
- plugins
12+
- plugins development guides
13+
---
14+
15+
# How to create admin permissions from plugins
16+
17+
When [developing a Strapi plugin](/cms/plugins-development/developing-plugins), you might want to create admin permissions for your plugin. By doing that you can hook in to the [RBAC system](/cms/features/rbac) of Strapi to selectively grant permissions to certain pieces of your plugin.
18+
19+
To create admin permissions for your Strapi plugin, you'll need to register them on the server side before implementing them on the admin side.
20+
21+
## Register the permissions server side
22+
23+
Each individual permission has to registered in the bootstrap function of your plugin, as follows:
24+
25+
<Tabs groupId="js-ts">
26+
27+
<TabItem value="js" label="JavaScript">
28+
29+
```js title="/src/plugins/my-plugin/server/src/bootstrap.js"
30+
31+
'use strict';
32+
33+
const bootstrap = ({ strapi }) => {
34+
// Register permission actions.
35+
const actions = [
36+
{
37+
section: 'plugins',
38+
displayName: 'Access the overview page',
39+
uid: 'overview',
40+
pluginName: 'my-plugin',
41+
},
42+
{
43+
section: 'plugins',
44+
displayName: 'Access the content manager sidebar',
45+
uid: 'sidebar',
46+
pluginName: 'my-plugin',
47+
},
48+
];
49+
50+
strapi.admin.services.permission.actionProvider.registerMany(actions);
51+
};
52+
53+
module.exports = bootstrap;
54+
```
55+
56+
</TabItem>
57+
58+
<TabItem value="ts" label="TypeScript">
59+
60+
```js title="/src/plugins/my-plugin/server/src/bootstrap.ts"
61+
62+
import type { Core } from '@strapi/strapi';
63+
64+
const bootstrap = ({ strapi }: { strapi: Core.Strapi }) => {
65+
// Register permission actions.
66+
const actions = [
67+
{
68+
section: 'plugins',
69+
displayName: 'Access the overview page',
70+
uid: 'overview.access',
71+
pluginName: 'my-plugin',
72+
},
73+
{
74+
section: 'plugins',
75+
displayName: 'Access the content manager sidebar',
76+
uid: 'sidebar.access',
77+
pluginName: 'my-plugin',
78+
},
79+
];
80+
81+
strapi.admin.services.permission.actionProvider.registerMany(actions);
82+
};
83+
84+
export default bootstrap;
85+
```
86+
87+
</TabItem>
88+
89+
</Tabs>
90+
91+
92+
## Implement permissions on the admin panel side
93+
94+
Before we can implement our permissions on the admin panel side we have to define them in a reusable configuration file. This file can be stored anywhere in your plugin admin code. You can do that as follows:
95+
96+
```js title="/src/plugins/my-plugin/admin/src/permissions.js|ts"
97+
const pluginPermissions = {
98+
'accessOverview': [{ action: 'plugin::my-plugin.overview.access', subject: null }],
99+
'accessSidebar': [{ action: 'plugin::my-plugin.sidebar.access', subject: null }],
100+
};
101+
102+
export default pluginPermissions;
103+
```
104+
105+
### Page permissions
106+
107+
Once you've created the configuration file you are ready to implement your permissions. If you've bootstrapped your plugin using the [plugin SDK init command](/cms/plugins-development/plugin-sdk#npx-strapisdk-plugin-init), you will have an example `HomePage.tsx` file. To implement page permissions you can do the following:
108+
109+
```js title="/src/plugins/my-plugin/admin/src/pages/HomePage.jsx|tsx" {2,5,12,16}
110+
import { Main } from '@strapi/design-system';
111+
import { Page } from '@strapi/strapi/admin';
112+
import { useIntl } from 'react-intl';
113+
114+
import pluginPermissions from '../permissions';
115+
import { getTranslation } from '../utils/getTranslation';
116+
117+
const HomePage = () => {
118+
const { formatMessage } = useIntl();
119+
120+
return (
121+
<Page.Protect permissions={pluginPermissions.accessOverview}>
122+
<Main>
123+
<h1>Welcome to {formatMessage({ id: getTranslation('plugin.name') })}</h1>
124+
</Main>
125+
</Page.Protect>
126+
);
127+
};
128+
129+
export { HomePage };
130+
```
131+
132+
You can see how we use our permissions configuration file together with the `<Page.Protect>` component to require specific permissions in order to view this page.
133+
134+
135+
### Menu link permissions
136+
137+
The previous example makes sure that the permissions of a user that visits your page directly will be validated. However, you might want to remove the menu link to that page as well. To do that, you'll have to make a change to the `addMenuLink` implementation. You can do as follows:
138+
139+
```js title="/src/plugins/my-plugin/admin/src/index.js|ts" {21-23,5}
140+
import { getTranslation } from './utils/getTranslation';
141+
import { PLUGIN_ID } from './pluginId';
142+
import { Initializer } from './components/Initializer';
143+
import { PluginIcon } from './components/PluginIcon';
144+
import pluginPermissions from './permissions';
145+
146+
export default {
147+
register(app) {
148+
app.addMenuLink({
149+
to: `plugins/${PluginIcon}`,
150+
icon: PluginIcon,
151+
intlLabel: {
152+
id: `${PLUGIN_ID}.plugin.name`,
153+
defaultMessage: PLUGIN_ID,
154+
},
155+
Component: async () => {
156+
const { App } = await import('./pages/App');
157+
158+
return App;
159+
},
160+
permissions: [
161+
pluginPermissions.accessOverview[0],
162+
],
163+
});
164+
165+
app.registerPlugin({
166+
id: PLUGIN_ID,
167+
initializer: Initializer,
168+
isReady: false,
169+
name: PLUGIN_ID,
170+
});
171+
},
172+
};
173+
174+
```
175+
176+
### Custom permissions with the `useRBAC` hook
177+
178+
To get even more control over the permission of the admin user you can use the `useRBAC` hook. With this hook you can use the permissions validation just like you want, as in the following example:
179+
180+
```js title="/src/plugins/my-plugin/admin/src/components/Sidebar.jsx|tsx"
181+
import React from 'react';
182+
import { useRBAC } from '@strapi/strapi/admin';
183+
184+
import pluginPermissions from '../../permissions';
185+
186+
const Sidebar = () => {
187+
const {
188+
allowedActions: { canAccessSidebar },
189+
} = useRBAC(pluginPermissions);
190+
191+
if (!canAccessSidebar) {
192+
return null;
193+
}
194+
195+
return (
196+
<div>Sidebar component</div>
197+
);
198+
};
199+
200+
export default Sidebar;
201+
```

‎docusaurus/sidebars.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -515,6 +515,7 @@ const sidebars = {
515515
'cms/plugins-development/server-api',
516516
'cms/plugins-development/plugins-extension',
517517
'cms/plugins-development/guides/pass-data-from-server-to-admin',
518+
'cms/plugins-development/guides/admin-permissions-for-plugins',
518519
'cms/plugins-development/guides/store-and-access-data',
519520
'cms/plugins-development/guides/create-components-for-plugins',
520521
],

‎docusaurus/static/llms-full.txt‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10321,6 +10321,119 @@ The can also include additional information useful while developing a Strapi pl
1032110321

1032210322

1032310323

10324+
# How to create admin permissions from plugins
10325+
Source: https://docs.strapi.io/cms/plugins-development/guides/admin-permissions-for-plugins
10326+
10327+
# How to create admin permissions from plugins
10328+
10329+
When [developing a Strapi plugin](/cms/plugins-development/developing-plugins), you might want to create reusable components for your plugin. Components in Strapi are reusable data structures that can be used across different content-types.
10330+
10331+
To create components for your Strapi plugin, you'll need to follow a similar approach to creating content-types, but with some specific differences.
10332+
10333+
## Register the permissions server side
10334+
10335+
```
10336+
// Register permission actions.
10337+
const actions = [
10338+
{
10339+
section: 'plugins',
10340+
displayName: 'Access the overview page',
10341+
uid: 'settings.overview',
10342+
pluginName: 'webtools',
10343+
},
10344+
{
10345+
section: 'plugins',
10346+
displayName: 'Access the URL alias list',
10347+
uid: 'settings.list',
10348+
pluginName: 'webtools',
10349+
},
10350+
{
10351+
section: 'plugins',
10352+
displayName: 'Access the URL alias patterns',
10353+
uid: 'settings.patterns',
10354+
pluginName: 'webtools',
10355+
},
10356+
{
10357+
section: 'plugins',
10358+
displayName: 'Access the URL alias sidebar',
10359+
uid: 'edit-view.sidebar',
10360+
pluginName: 'webtools',
10361+
},
10362+
];
10363+
10364+
// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
10365+
(strapi.admin.services.permission.actionProvider.registerMany as (a: any) => void)(actions);
10366+
```
10367+
10368+
## Creating components
10369+
10370+
You can create components for your plugins in 2 different ways: using the Content-Type Builder (recommended way) or manually.
10371+
10372+
### Using the Content-Type Builder
10373+
10374+
The recommended way to create components for your plugin is through the Content-Type Builder in the admin panel.
10375+
The [Content-Type Builder documentation](/cms/features/content-type-builder#new-component) provides more details on this process.
10376+
10377+
### Creating components manually
10378+
10379+
If you prefer to create components manually, you'll need to:
10380+
10381+
1. Create a component schema in your plugin's structure.
10382+
2. Make sure the component is properly registered.
10383+
10384+
Components for plugins should be placed in the appropriate directory within your plugin structure. You would typically create them within the server part of your plugin (see [plugin structure documentation](/cms/plugins-development/plugin-structure)).
10385+
10386+
For more detailed information about components in Strapi, you can refer to the [Model attributes documentation](/cms/backend-customization/models#components-json).
10387+
10388+
## Reviewing the component structure
10389+
10390+
Components in Strapi follow the following format in their definition:
10391+
10392+
```javascript title="/my-plugin/server/components/category/component-name.json"
10393+
{
10394+
"attributes": {
10395+
"myComponent": {
10396+
"type": "component",
10397+
"repeatable": true,
10398+
"component": "category.componentName"
10399+
}
10400+
}
10401+
}
10402+
```
10403+
10404+
## Making components visible in the admin panel
10405+
10406+
To ensure your plugin's components are visible in the admin panel, you need to set the appropriate `pluginOptions` in your component schema:
10407+
10408+
```javascript {9-16}
10409+
{
10410+
"kind": "collectionType",
10411+
"collectionName": "my_plugin_components",
10412+
"info": {
10413+
"singularName": "my-plugin-component",
10414+
"pluralName": "my-plugin-components",
10415+
"displayName": "My Plugin Component"
10416+
},
10417+
"pluginOptions": {
10418+
"content-manager": {
10419+
"visible": true
10420+
},
10421+
"content-type-builder": {
10422+
"visible": true
10423+
}
10424+
},
10425+
"attributes": {
10426+
"name": {
10427+
"type": "string"
10428+
}
10429+
}
10430+
}
10431+
```
10432+
10433+
This configuration ensures your components will be visible and editable in both the Content-Type Builder and Content Manager.
10434+
10435+
10436+
1032410437
# How to create components for Strapi plugins
1032510438
Source: https://docs.strapi.io/cms/plugins-development/guides/create-components-for-plugins
1032610439

‎docusaurus/static/llms.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,7 @@
106106
- [Content Manager APIs](https://docs.strapi.io/cms/plugins-development/content-manager-apis): Content Manager APIs add panels and actions to list or edit views through addEditViewSidePanel, addDocumentAction, addDocumentHeaderAction, or addBulkAction. Each API accepts component functions with typed contexts, enabling precise control over document-aware UI injections.
107107
- [Plugin creation & setup](https://docs.strapi.io/cms/plugins-development/create-a-plugin): The Plugin SDK generates plugins without a Strapi project and links them to an existing app with watch:link and yalc. In this documentation: build and verify commands to bundle the plugin for npm or marketplace publishing, and information for monorepos and local setups.
108108
- [Developing plugins](https://docs.strapi.io/cms/plugins-development/developing-plugins): Generation introduction about Strapi plugins development
109+
- [How to create admin permissions from plugins](https://docs.strapi.io/cms/plugins-development/guides/admin-permissions-for-plugins): Learn how to create and configure admin permissions for your plugin
109110
- [How to create components for Strapi plugins](https://docs.strapi.io/cms/plugins-development/guides/create-components-for-plugins): Learn how to create and configure components for your Strapi plugins
110111
- [How to pass data from server to admin panel with a Strapi plugin](https://docs.strapi.io/cms/plugins-development/guides/pass-data-from-server-to-admin): Learn how to pass data from server to admin panel with a Strapi plugin
111112
- [How to store and access data from a Strapi plugin](https://docs.strapi.io/cms/plugins-development/guides/store-and-access-data): Learn how to store and access data from a Strapi plugin

0 commit comments

Comments
 (0)