From 354fcf3a1ea6e3500039decbd7b896b8e732482f Mon Sep 17 00:00:00 2001 From: Boaz Poolman Date: Wed, 29 Oct 2025 14:34:06 +0100 Subject: [PATCH 1/9] docs: add documentation about using rbac from plugins --- .../guides/admin-permissions-for-plugins.md | 201 ++++++++++++++++++ docusaurus/sidebars.js | 1 + docusaurus/static/llms-full.txt | 113 ++++++++++ docusaurus/static/llms.txt | 1 + 4 files changed, 316 insertions(+) create mode 100644 docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md diff --git a/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md new file mode 100644 index 0000000000..a09ebb4519 --- /dev/null +++ b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md @@ -0,0 +1,201 @@ +--- +title: How to create admin permissions from plugins +description: Learn how to create and configure admin permissions for your plugin +sidebar_label: Create admin permissions for plugins +displayed_sidebar: cmsSidebar +tags: +- admin panel +- RBAC +- Role Based Access Control +- guides +- plugins +- plugins development guides +--- + +# How to create admin permissions from plugins + +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.. + +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. + +## Register the permissions server side + +Each individual permission has to registered in the bootstrap function of your plugin. You can do that as follows: + + + + + +```js title="/src/plugins/my-plugin/server/src/bootstrap.js" + +'use strict'; + +const bootstrap = ({ strapi }) => { + // Register permission actions. + const actions = [ + { + section: 'plugins', + displayName: 'Access the overview page', + uid: 'overview', + pluginName: 'my-plugin', + }, + { + section: 'plugins', + displayName: 'Access the content manager sidebar', + uid: 'sidebar', + pluginName: 'my-plugin', + }, + ]; + + strapi.admin.services.permission.actionProvider.registerMany(actions); +}; + +module.exports = bootstrap; +``` + + + + + +```js title="/src/plugins/my-plugin/server/src/bootstrap.ts" + +import type { Core } from '@strapi/strapi'; + +const bootstrap = ({ strapi }: { strapi: Core.Strapi }) => { + // Register permission actions. + const actions = [ + { + section: 'plugins', + displayName: 'Access the overview page', + uid: 'overview.access', + pluginName: 'my-plugin', + }, + { + section: 'plugins', + displayName: 'Access the content manager sidebar', + uid: 'sidebar.access', + pluginName: 'my-plugin', + }, + ]; + + strapi.admin.services.permission.actionProvider.registerMany(actions); +}; + +export default bootstrap; +``` + + + + + + +## Admin implementation + +Before we can implement our permissions on the admin 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: + +```js title="/src/plugins/my-plugin/admin/src/permissions.js|ts" +const pluginPermissions = { + 'accessOverview': [{ action: 'plugin::my-plugin.overview.access', subject: null }], + 'accessSidebar': [{ action: 'plugin::my-plugin.sidebar.access', subject: null }], +}; + +export default pluginPermissions; +``` + +### Page permissions + +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: + +```js title="/src/plugins/my-plugin/admin/src/pages/HomePage.jsx|tsx" {2,5,12,16} +import { Main } from '@strapi/design-system'; +import { Page } from '@strapi/strapi/admin'; +import { useIntl } from 'react-intl'; + +import pluginPermissions from '../permissions'; +import { getTranslation } from '../utils/getTranslation'; + +const HomePage = () => { + const { formatMessage } = useIntl(); + + return ( + +
+

Welcome to {formatMessage({ id: getTranslation('plugin.name') })}

+
+ + ); +}; + +export { HomePage }; +``` + +You can see how we use our permissions configuration file together with the `` component to require specific permissions in order to view this page. + + +### Menu link permissions + +The above 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: + +```js title="/src/plugins/my-plugin/admin/src/index.js|ts" {21-23,5} +import { getTranslation } from './utils/getTranslation'; +import { PLUGIN_ID } from './pluginId'; +import { Initializer } from './components/Initializer'; +import { PluginIcon } from './components/PluginIcon'; +import pluginPermissions from './permissions'; + +export default { + register(app) { + app.addMenuLink({ + to: `plugins/${PluginIcon}`, + icon: PluginIcon, + intlLabel: { + id: `${PLUGIN_ID}.plugin.name`, + defaultMessage: PLUGIN_ID, + }, + Component: async () => { + const { App } = await import('./pages/App'); + + return App; + }, + permissions: [ + pluginPermissions.accessOverview[0], + ], + }); + + app.registerPlugin({ + id: PLUGIN_ID, + initializer: Initializer, + isReady: false, + name: PLUGIN_ID, + }); + }, +}; + +``` + +### Custom permissions with the useRBAC hook + +If you have to have even more control over the permission of the admin user you can utilize the `useRBAC` hook. With that you can use the permissions validation just like you want. You can do that as follows: + +```js title="/src/plugins/my-plugin/admin/src/components/Sidebar.jsx|tsx" +import React from 'react'; +import { useRBAC } from '@strapi/strapi/admin'; + +import pluginPermissions from '../../permissions'; + +const Sidebar = () => { + const { + allowedActions: { canAccessSidebar }, + } = useRBAC(pluginPermissions); + + if (!canAccessSidebar) { + return null; + } + + return ( +
Sidebar component
+ ); +}; + +export default Sidebar; +``` diff --git a/docusaurus/sidebars.js b/docusaurus/sidebars.js index 9dc370f963..d6569a6f26 100644 --- a/docusaurus/sidebars.js +++ b/docusaurus/sidebars.js @@ -512,6 +512,7 @@ const sidebars = { 'cms/plugins-development/server-api', 'cms/plugins-development/plugins-extension', 'cms/plugins-development/guides/pass-data-from-server-to-admin', + 'cms/plugins-development/guides/admin-permissions-for-plugins', 'cms/plugins-development/guides/store-and-access-data', 'cms/plugins-development/guides/create-components-for-plugins', ], diff --git a/docusaurus/static/llms-full.txt b/docusaurus/static/llms-full.txt index 1311515615..539a8e1989 100644 --- a/docusaurus/static/llms-full.txt +++ b/docusaurus/static/llms-full.txt @@ -10225,6 +10225,119 @@ The can also include additional information useful while developing a Strapi pl +# How to create admin permissions from plugins +Source: https://docs.strapi.io/cms/plugins-development/guides/admin-permissions-for-plugins + +# How to create admin permissions from plugins + +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. + +To create components for your Strapi plugin, you'll need to follow a similar approach to creating content-types, but with some specific differences. + +## Register the permissions server side + +``` +// Register permission actions. +const actions = [ + { + section: 'plugins', + displayName: 'Access the overview page', + uid: 'settings.overview', + pluginName: 'webtools', + }, + { + section: 'plugins', + displayName: 'Access the URL alias list', + uid: 'settings.list', + pluginName: 'webtools', + }, + { + section: 'plugins', + displayName: 'Access the URL alias patterns', + uid: 'settings.patterns', + pluginName: 'webtools', + }, + { + section: 'plugins', + displayName: 'Access the URL alias sidebar', + uid: 'edit-view.sidebar', + pluginName: 'webtools', + }, +]; + +// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access +(strapi.admin.services.permission.actionProvider.registerMany as (a: any) => void)(actions); +``` + +## Creating components + +You can create components for your plugins in 2 different ways: using the Content-Type Builder (recommended way) or manually. + +### Using the Content-Type Builder + +The recommended way to create components for your plugin is through the Content-Type Builder in the admin panel. +The [Content-Type Builder documentation](/cms/features/content-type-builder#new-component) provides more details on this process. + +### Creating components manually + +If you prefer to create components manually, you'll need to: + +1. Create a component schema in your plugin's structure. +2. Make sure the component is properly registered. + +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)). + +For more detailed information about components in Strapi, you can refer to the [Model attributes documentation](/cms/backend-customization/models#components-json). + +## Reviewing the component structure + +Components in Strapi follow the following format in their definition: + +```javascript title="/my-plugin/server/components/category/component-name.json" +{ + "attributes": { + "myComponent": { + "type": "component", + "repeatable": true, + "component": "category.componentName" + } + } +} +``` + +## Making components visible in the admin panel + +To ensure your plugin's components are visible in the admin panel, you need to set the appropriate `pluginOptions` in your component schema: + +```javascript {9-16} +{ + "kind": "collectionType", + "collectionName": "my_plugin_components", + "info": { + "singularName": "my-plugin-component", + "pluralName": "my-plugin-components", + "displayName": "My Plugin Component" + }, + "pluginOptions": { + "content-manager": { + "visible": true + }, + "content-type-builder": { + "visible": true + } + }, + "attributes": { + "name": { + "type": "string" + } + } +} +``` + +This configuration ensures your components will be visible and editable in both the Content-Type Builder and Content Manager. + + + # How to create components for Strapi plugins Source: https://docs.strapi.io/cms/plugins-development/guides/create-components-for-plugins diff --git a/docusaurus/static/llms.txt b/docusaurus/static/llms.txt index e767db6b35..8bf8cea18d 100644 --- a/docusaurus/static/llms.txt +++ b/docusaurus/static/llms.txt @@ -106,6 +106,7 @@ - [Content Manager APIs](https://docs.strapi.io/cms/plugins-development/content-manager-apis): The Content Manager APIs reference lists the APIs available to plugins for adding actions and options to the Content Manager List view and Edit view. - [Plugin creation & setup](https://docs.strapi.io/cms/plugins-development/create-a-plugin): Learn how to use the Plugin SDK to build and publish a Strapi plugin - [Developing plugins](https://docs.strapi.io/cms/plugins-development/developing-plugins): Generation introduction about Strapi plugins development +- [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 - [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 - [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 - [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 From 5661ac0e10aaeefab16a06dfc694e6c7836d0404 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 30 Oct 2025 15:15:44 +0100 Subject: [PATCH 2/9] Fix typo --- .../plugins-development/guides/admin-permissions-for-plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md index a09ebb4519..aa90e9d791 100644 --- a/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md +++ b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md @@ -14,7 +14,7 @@ tags: # How to create admin permissions from plugins -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.. +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. 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. From b1aa48a5c2f821c29995947f6916b9f6942c9e70 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 30 Oct 2025 15:32:46 +0100 Subject: [PATCH 3/9] Update docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md --- .../plugins-development/guides/admin-permissions-for-plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md index aa90e9d791..6797574a3a 100644 --- a/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md +++ b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md @@ -20,7 +20,7 @@ To create admin permissions for your Strapi plugin, you'll need to register them ## Register the permissions server side -Each individual permission has to registered in the bootstrap function of your plugin. You can do that as follows: +Each individual permission has to registered in the bootstrap function of your plugin, as follows: From bf5aa59d4dcafe368b9a9609f51d12dd189e1466 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 30 Oct 2025 15:32:54 +0100 Subject: [PATCH 4/9] Update docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md --- .../plugins-development/guides/admin-permissions-for-plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md index 6797574a3a..c2834a0336 100644 --- a/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md +++ b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md @@ -104,7 +104,7 @@ export default pluginPermissions; ### Page permissions -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: +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: ```js title="/src/plugins/my-plugin/admin/src/pages/HomePage.jsx|tsx" {2,5,12,16} import { Main } from '@strapi/design-system'; From 3b79ea3d6d414e64dc03c05fe9262740d66d0a3c Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 30 Oct 2025 15:33:04 +0100 Subject: [PATCH 5/9] Update docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md --- .../plugins-development/guides/admin-permissions-for-plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md index c2834a0336..83dac2b5b1 100644 --- a/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md +++ b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md @@ -134,7 +134,7 @@ You can see how we use our permissions configuration file together with the ` Date: Thu, 30 Oct 2025 15:33:14 +0100 Subject: [PATCH 6/9] Update docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md --- .../plugins-development/guides/admin-permissions-for-plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md index 83dac2b5b1..1244b796e9 100644 --- a/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md +++ b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md @@ -173,7 +173,7 @@ export default { ``` -### Custom permissions with the useRBAC hook +### Custom permissions with the `useRBAC` hook If you have to have even more control over the permission of the admin user you can utilize the `useRBAC` hook. With that you can use the permissions validation just like you want. You can do that as follows: From 44ba09eb8e1a0a76d976f8fb8f658c46715a366e Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 30 Oct 2025 15:33:24 +0100 Subject: [PATCH 7/9] Update docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md --- .../plugins-development/guides/admin-permissions-for-plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md index 1244b796e9..1c81cf09cf 100644 --- a/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md +++ b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md @@ -175,7 +175,7 @@ export default { ### Custom permissions with the `useRBAC` hook -If you have to have even more control over the permission of the admin user you can utilize the `useRBAC` hook. With that you can use the permissions validation just like you want. You can do that as follows: +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: ```js title="/src/plugins/my-plugin/admin/src/components/Sidebar.jsx|tsx" import React from 'react'; From 97bdc171250afe80ce75854370bd7d48c74d18e0 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 30 Oct 2025 15:33:31 +0100 Subject: [PATCH 8/9] Update docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md --- .../plugins-development/guides/admin-permissions-for-plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md index 1c81cf09cf..28e365bac4 100644 --- a/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md +++ b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md @@ -89,7 +89,7 @@ export default bootstrap; -## Admin implementation +## Implement permissions on the admin panel side Before we can implement our permissions on the admin 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: From b71ce1529c674bcc17216ed2884b978ad5bad3f2 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 30 Oct 2025 15:33:37 +0100 Subject: [PATCH 9/9] Update docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md --- .../plugins-development/guides/admin-permissions-for-plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md index 28e365bac4..0c176a3c93 100644 --- a/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md +++ b/docusaurus/docs/cms/plugins-development/guides/admin-permissions-for-plugins.md @@ -91,7 +91,7 @@ export default bootstrap; ## Implement permissions on the admin panel side -Before we can implement our permissions on the admin 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: +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: ```js title="/src/plugins/my-plugin/admin/src/permissions.js|ts" const pluginPermissions = {