VitNode

Permissions for Admin

How to create permissions for Admin

Development only

This guide requires Dev Server to be running.

We're setting up permissions for the admin role to help you control who can access specific parts of the admin panel.

Structure of Permissions

Permissions are divided into groups, and each group contains a set of permissions.

For example, there's a group called settings, which includes permissions like can_manage_settings_email or can_edit_email.

Each navigation item in the Admin Control Panel (AdminCP) has a permission formatted as can_manage_{your_nav_id}. This prefix also applies to groups.

Example:

GroupPermissionsAdminCP Navigation ItemDescription
settingscan_manage_settings_email{your_plugin} => Settings => EmailPermission to show the email settings.
settingscan_manage_settings_general{your_plugin} => Settings => GeneralPermission to show the general settings.
can_manage_settings-{your_plugin} => SettingsPermission to show the settings group.
settingscan_edit_emailN/AOwn [permission to edit the email settings.

Explanation:

  • Group: The category under which permissions are organized (e.g., settings).
  • Permission: Specific actions that can be allowed or denied (e.g., can_manage_settings_email).
  • AdminCP Navigation Item: The path in the admin panel where the permission applies.
  • Description: Details about what the permission allows.

By configuring these permissions, you can precisely manage admin access to various sections of the admin panel.

Create Permissions

First we need to create a permission for our plugin.

Plugin Configuration

Edit the permissions_admin in the config.json file from your plugin.

config.json
{
  "$schema": "https://api.vitnode.com/public/vitnode/plugin.schema.json",
  "name": "Welcome",
  "description": "Basic plugin with default page.",
  "version": "1.0.0",
  "version_code": 1,
  "code": "welcome",
  "author": "VitNode",
  "author_url": "https://vitnode.com/",
  "support_url": "https://github.com/VitNode/vitnode/issues",

  "permissions_admin": [

    {

      "id": "settings",

      "permissions": [

        "can_manage_settings_email",

        "can_edit_email",

        "can_manage_categories"

      ]

    }

  ]
}

Internationalization (i18n)

Now we need to add the language key inside the langs folder in apps/frontend/src/plugins/{your_plugin_code}/langs/en.json file in the frontend.

en.json

Default language is English en. If you have more then one language, you need to add the language key in other languages as well.

Based on our example above, we need to add the following keys:

apps/frontend/src/plugins/{your_plugin_code}/langs/en.json
{
  "{your_plugin_code}": {},
  "admin_{your_plugin_code}": {
    "nav": {
      "title": "Commerce",
      "settings": "Settings",
      "settings_email": "Email",
      "categories": "Categories"
    },
    "admin_permissions": {
      "settings": "Settings", 
      "can_manage_settings_email": "Can manage email settings?", 
      "can_edit_email": "Can edit email?", 
      "can_manage_categories": "Can manage categories?"
    }
  }
}

Usage

Frontend

To check if admin has a specific permission, you can use the checkAdminPermissionPage(permission) for page.

page.tsx

import { checkAdminPermissionPage } from 'vitnode-frontend/api/get-session-admin-data';
 

const permission = {
  plugin_code: '{your_plugin_code}', 
  group: '{your_group}', 
  permission: '{your_permission}', 
}; 
 
export const ExampleView = async () => {
  const perm = await checkAdminPermissionPage(permission); 
  if (perm) return perm; 
 
  return <div>Hi!</div>;
};

Build-in catch error feature in NextJS

When backend throws an error with 403 code using throw new ForbiddenException(), NextJS will render 403 page. You don't need to handle this error in your page. Use checkAdminPermissionPage() to check if admin has a specific permission when you haven't API endpoint.

Permissions in Metadata

To check if admin has a specific permission, you can use the checkAdminPermissionPageMetadata(permission) for metadata.

page.tsx

import { checkAdminPermissionPageMetadata } from 'vitnode-frontend/api/get-session-admin-data';
 
const permission = {
  plugin_code: '{your_plugin_code}',
  group: '{your_group}',
  permission: '{your_permission}',
};
 
export const generateMetadata = async () => {
  const perm = await checkAdminPermissionPageMetadata(permission); 
  if (perm) return perm; 
 
  return {
    title: 'Page Title',
    description: 'Page Description',
  };
};

Permissions in Component

To check if admin has a specific permission to display a component, you can use the isInAdminPermission(permission).


import { isInAdminPermission } from 'vitnode-frontend/api/get-session-admin-data';
 
export const ServerComponent = async () => {

  const isAllowed = await isInAdminPermission({
    plugin_code: '{your_plugin_code}', 
    group: '{your_group}', 
    permission: '{your_permission}', 

  });
 
  return <div>{isAllowed ? 'Allowed' : 'Not Allowed'}</div>;
};

Backend

To check if admin has a specific permission, you can use the @AdminPermission() decorator.

test.controller.ts

import { AdminPermission } from 'vitnode-backend/helpers/auth/admin-permission.decorator';
 
@Controllers({
  plugin_name: 'Welcome',
  plugin_code: 'welcome',
  isAdmin: true, 
})
export class SettingsWelcomeAdminController {
  constructor(private readonly showService: ShowSettingsWelcomeAdminService) {}
 

  @AdminPermission({

    plugin_code: 'welcome',

    group: 'settings',

    permission: 'can_manage_settings',

  })
  @ApiOkResponse({
    type: ShowSettingsWelcomeAdminObj,
    description: 'Show settings for welcome plugin.',
  })
  @Get()
  show(): ShowSettingsWelcomeAdminObj {
    return this.showService.show();
  }
}

Admin required

@AdminPermission() decorator will not work if route is not protected for admins. See more how to protect routes for admins.

Edit on GitHub

Previous

Plugin Pages

Next

Modules

On this page