Managing roles
On this page
This guide covers how to create roles, assign them to users, and check role membership. You will learn how to:
- Configure the
withRolesmixin - Create roles and assign permissions to them
- Assign, sync, and revoke roles on users
- Aggregate permissions from a user's roles
Overview
Section titled "Overview"Roles are the recommended way to manage permissions. Instead of assigning individual permissions to each user, you create roles like "editor", "admin", or "billing manager", assign permissions to those roles, and then assign roles to users. When a user's responsibilities change, you update their role assignments rather than editing individual permissions.
Permissions provides two mixins for this workflow:
withPermissionsgoes on the Role model and adds a JSON column for storing permission strings.withRolesgoes on the User model and adds a many-to-many relationship to the Role model through a pivot table.
Create the roles and user_roles tables, and apply withPermissions to the Role model and withRoles to the User model. The Quick start shows each step.
withRoles options
Section titled "withRoles options"roleModel() => RoleModelrequiredpivotTablestringrequiredpivotForeignKeystringuser_id).pivotRelatedForeignKeystringrole_id).Creating roles with permissions
Section titled "Creating roles with permissions"Create a role and assign permissions to it. Use permissions.getKey() for type-safe permission keys. Your editor will autocomplete the available keys and catch typos at compile time.
import { permissions } from '#start/permissions'
const editor = await Role.create({ name: 'editor' })
await editor.givePermissions([
permissions.getKey('product.create'),
permissions.getKey('product.update'),
])
const admin = await Role.create({ name: 'admin' })
await admin.syncPermissions(permissions.active())For a full reference on managing the permissions column (giving, syncing, revoking), see the Managing permissions guide.
Assigning roles to users
Section titled "Assigning roles to users"You can pass role instances or role IDs to all assignment methods.
await user.assignRole(editor)
await user.assignRoles([editor, moderatorRole])assignRole and assignRoles skip roles the user already holds. Other roles stay assigned.
Changing a user's roles
Section titled "Changing a user's roles"syncRoles replaces the user's roles with the list you pass. revokeRole and revokeRoles remove the roles you pass.
await user.syncRoles([admin])
await user.revokeRole(editor)
await user.revokeRoles([editor, moderatorRole])Reading a user's roles
Section titled "Reading a user's roles"hasRole compares the name you pass with the name column of each of the user's roles. getRoles returns the roles themselves.
await user.hasRole('editor') // true or false
const roles = await user.getRoles()The first call to getRoles loads the roles and keeps them on the model. Later calls, and calls after a preload('roles'), return that list without a query. Roles you assign after that show up when you fetch the user again.
Aggregating permissions
Section titled "Aggregating permissions"The getPermissions method on the user collects permissions from all assigned roles into a single deduplicated array. This is the method used by the Access class and Bouncer abilities to determine what a user can do.
const allPermissions = await user.getPermissions()
// Combines permissions from all roles