RBAC Module

In this section of the documentation, you will find resources to learn more about the role-based access control (RBAC) Module and how to use it in your application.

Medusa has role-based access control features available through the RBAC Module. A module is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this RBAC Module.

The RBAC Module restricts what admin users can do based on the roles assigned to them. Each role grants a set of policies, where a policy allows an operation on a resource.

RBAC Features#

• Roles and Policies: Group policies into roles, then assign roles to admin users to control their access.
• Custom Policies: Define policies for your custom resources so they can be protected by RBAC.
• Scopes: Restrict a role to a single entity instance, such as one vendor on a marketplace.
• Admin Customization Checks: Show or hide content in your admin customizations based on the admin user's permissions and roles.

How to Use the RBAC Module#

1. Configure an Enterprise License Key#

The RBAC Module is an enterprise feature, so it only loads when you configure a license key that covers the rbac feature:

MEDUSA_LICENSE_KEY=your_license_key

If the key is missing or doesn't cover the rbac feature, the Medusa application exits at boot with an error. Learn how to obtain and configure a key in the Enterprise Features documentation.

2. Register the RBAC Module#

Medusa doesn't register the RBAC Module by default. To use it, add it to the modules array in medusa-config.ts:

module.exports = defineConfig({
  // ...
  modules: [
    {
      resolve: "@medusajs/medusa/rbac",
    },
  ],
})

Once you register the module, Medusa checks an admin user's roles before allowing an operation on its API routes.

You can also configure the RBAC Module and the actor types allowed on its API routes. Learn more in the Module Options guide.

3. Run Migrations#

After registering the module, run the migrations to create the RBAC tables in the database:

npx medusa db:migrate

The command also runs Medusa's migration scripts, which:

• Create a Super Admin role with full access, then assign it to your existing admin users so that they keep their access.
• Copy the role assignments of applications that used the incomplete version of RBAC before Medusa v2.21.0 into the new rbac_role_assignment table.

Then, every time the application starts, the RBAC Module syncs the policies of Medusa's commerce resources to the database. Learn more in the RBAC Concepts guide.

4. Use RBAC Features in Your Application#

In your Medusa application, you build flows around Commerce Modules. A flow is built as a Workflow, which is a special function composed of a series of steps that guarantees data consistency and a reliable roll-back mechanism.

For example, to resolve the RBAC Module's service in a step:

import {
  createWorkflow,
  WorkflowResponse,
  createStep,
  StepResponse,
} from "@medusajs/framework/workflows-sdk"
import { Modules } from "@medusajs/framework/utils"

const createRoleStep = createStep(
  "create-role",
  async ({}, { container }) => {
    const rbacModuleService = container.resolve(
      Modules.RBAC
    )

    const role = await rbacModuleService.createRbacRoles({
      name: "Product Manager",
      description: "Manages products and inventory",
    })

    return new StepResponse(role, role.id)
  },
  async (roleId, { container }) => {
    const rbacModuleService = container.resolve(
      Modules.RBAC
    )

    await rbacModuleService.deleteRbacRoles([roleId])
  }
)

export const createRoleWorkflow = createWorkflow(
  "create-role",
  () => {
    const role = createRoleStep()

    return new WorkflowResponse(role)
  }
)

Refer to the Workflows documentation to learn more.