Add a guide about using RBAC from plugins

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:
+
+<Tabs groupId="js-ts">
+
+<TabItem value="js" label="JavaScript">
+
+```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;
+```
+
+</TabItem>
+
+<TabItem value="ts" label="TypeScript">
+
+```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;
+```
+
+</TabItem>
+
+</Tabs>
+
+
+## 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 (
+    <Page.Protect permissions={pluginPermissions.accessOverview}>
+      <Main>
+        <h1>Welcome to {formatMessage({ id: getTranslation('plugin.name') })}</h1>
+      </Main>
+    </Page.Protect>
+  );
+};
+
+export { HomePage };
+```
+
+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.
+
+
+### 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 (
+    <div>Sidebar component</div>
+  );
+};
+
+export default Sidebar;
+```

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',
           ],

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
 

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