Links between RBAC Module and Other Modules

This document showcases the module links defined between the role-based access control (RBAC) Module and other Commerce Modules.

Summary#

The RBAC Module has the following links to other modules:

User Module#

You assign roles to admin users to control their access. Medusa stores each of these grants as an RbacRoleAssignment record, as explained in the RBAC Concepts guide.

Since the assignment stores the granted entity's type and ID, it isn't a stored link between two data models. Instead, Medusa defines read-only links that expose the roles of a User or an Invite from the User Module.

An admin user can have multiple roles, and a role can be assigned to multiple users. The user's effective policies are the union of the policies from all their unscoped role assignments. A scoped assignment only adds its role's policies to requests within that scope.

Retrieve with Query#

To retrieve the roles of an admin user with Query, pass rbac_roles.* in fields:

The rbac_roles field returns the roles of all the user's assignments, including scoped ones, without their scope. To retrieve each assignment's scope, pass user_role_assignments.* in fields instead:

const { data: users } = await query.graph({
  entity: "user",
  fields: [
    "user_role_assignments.*",
    "user_role_assignments.role.*",
  ],
})

// users[0].user_role_assignments[0].scope
// users[0].user_role_assignments[0].scope_id

Pass the rbac_roles.* field when querying the invite entity to retrieve the roles that an invite grants once the user accepts it. Use invite_role_assignments.* to retrieve the invite's assignments with their scope.

To find the entities that a role is assigned to, query the rbac_role_assignment entity instead:

const { data: assignments } = await query.graph({
  entity: "rbac_role_assignment",
  fields: ["reference", "reference_id"],
  filters: {
    role_id: "role_123",
    reference: "user",
  },
})

Manage Role Assignments#

To assign a role to an admin user, use the assignRolesWorkflow:

import {
  assignRolesWorkflow,
} from "@medusajs/medusa/core-flows"

await assignRolesWorkflow(container).run({
  input: {
    assignments: [
      {
        role_id: "role_123",
        reference: "user",
        reference_id: "user_123",
      },
    ],
    granting_actor_id: "user_456",
  },
})

Pass a scope object with the type and id properties in an assignment to restrict the role to that scope.

To remove a role from an admin user, use the unassignRolesWorkflow with the same input shape:

import {
  unassignRolesWorkflow,
} from "@medusajs/medusa/core-flows"

await unassignRolesWorkflow(container).run({
  input: {
    assignments: [
      {
        role_id: "role_123",
        reference: "user",
        reference_id: "user_123",
      },
    ],
    granting_actor_id: "user_456",
  },
})

Both workflows check that the actor in granting_actor_id already has all the policies of the roles being changed. If the actor is acting within a scope, pass it in the granting_scope property, and pass the actor's type in granting_actor if it isn't user.

When you omit the scope of an assignment, the unassignRolesWorkflow removes all the matching assignments, both scoped and unscoped. It also fails if the removal leaves no admin user with the unscoped Super Admin role. The deleteUsersWorkflow runs the same check before deleting users.