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..0c176a3c93 --- /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, 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; +``` + + + + + + +## Implement permissions on the admin panel side + +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 = { + '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 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: + +```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 + +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'; +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