Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

[Skip CI] Document new permission sets (#13325)

Damian Legawiec1b79b766f3c5
diff --git a/docs/developer/admin/admin.mdx b/docs/developer/admin/admin.mdx
index 0453bb3907..558b717b21 100644
--- a/docs/developer/admin/admin.mdx
+++ b/docs/developer/admin/admin.mdx
@@ -215,7 +215,7 @@ authorize! :update, @product
```
<Info>
- See [Permissions](/developer/admin/permissions) for defining custom abilities.
+ See [Permissions](/developer/customization/permissions) for defining custom abilities.
</Info>
## Next Steps
diff --git a/docs/developer/admin/navigation.mdx b/docs/developer/admin/navigation.mdx
index ee318578fa..5ceb6a1e4e 100644
--- a/docs/developer/admin/navigation.mdx
+++ b/docs/developer/admin/navigation.mdx
@@ -820,4 +820,4 @@ Register with:
- [Extending Admin UI](/developer/admin/extending-ui) - Learn about other UI injection points
- [Helper Methods](/developer/admin/helper-methods) - Explore other admin helper methods
-- [Permissions](/developer/admin/permissions) - Understand the authorization system
+- [Permissions](/developer/customization/permissions) - Understand the authorization system
diff --git a/docs/developer/admin/permissions.mdx b/docs/developer/admin/permissions.mdx
deleted file mode 100644
index a583bab3e6..0000000000
--- a/docs/developer/admin/permissions.mdx
+++ /dev/null
@@ -1,54 +0,0 @@
----
-title: Admin Dashboard Permissions
-sidebarTitle: Permissions
----
-
-## Overview
-
-Admin Dashboard utilizes [Spree's authorization system](/developer/customization/permissions) to control access to the different pages.
-
-## Restricting access to certain pages
-
-Let's assume you would like to add a new Role `customer_service` with some limited access to Admin Panel only Orders section.
-
-Create a new file called `app/models/customer_service_ability.rb`
-
-```ruby
-class CustomerServiceAbility
- include CanCan::Ability
-
- def initialize(user)
- if user.respond_to?(:has_spree_role?) && user.has_spree_role?('customer_service')
- can :manage, Spree::Order
- end
- end
-end
-```
-
-Please familiarize yourself with [CanCanCan](https://github.com/CanCanCommunity/cancancan) syntax to understand `can/cannot` methods more.
-
-Now we need to inform Spree to use this ability, create another file `app/models/spree/ability_decorator.rb` with contents:
-
-```ruby
-module Spree
- module AbilityDecorator
- def abilities_to_register
- [CustomerServiceAbility]
- end
- end
-
- Ability.prepend(AbilityDecorator)
-end
-```
-
-This will automatically remove all other pages/navigation items from the sidebar for the `customer_service` role.
-
-You can be even more granular with the permissions by using the `can` method.
-
-```ruby
-can :manage, Spree::Order
-can :read, Spree::Product
-can :update, Spree::Product
-```
-
-This will restrict the access to the `customer_service` role to only the Orders and Products pages. However they won't be able to delete products or add new ones, just update existing ones.
\ No newline at end of file
diff --git a/docs/developer/customization/permissions.mdx b/docs/developer/customization/permissions.mdx
index 283389a5e0..0b85f53590 100644
--- a/docs/developer/customization/permissions.mdx
+++ b/docs/developer/customization/permissions.mdx
@@ -2,29 +2,183 @@
title: Permissions
---
-## User and Roles
+Spree uses [CanCanCan](https://github.com/CanCanCommunity/cancancan) for authorization. The permission system allows you to define granular access control for different user roles.
-Spree by default comes with `admin` and `user` roles. You can create more roles in the Admin Panel UI or rails console / seed, eg.:
+## Permission Sets (Recommended)
+
+Permission Sets provide a clean, modular way to manage permissions. Each permission set is a reusable group of permissions that can be assigned to roles.
+
+### How It Works
+
+1. **Roles** - Determine which permission sets govern a user's access (e.g., `admin`, `customer_service`)
+2. **Permission Sets** - Contain the logic defining what actions users can perform on resources
+3. **Role Configuration** - Associates roles with their corresponding permission sets
+
+### Configuring Roles
+
+In your `config/initializers/spree.rb`, configure which permission sets are assigned to each role:
+
+```ruby
+Rails.application.config.after_initialize do
+ # Default permissions for all users (guests and logged-in customers)
+ Spree.permissions.assign(:default, [Spree::PermissionSets::DefaultCustomer])
+
+ # Full admin access
+ Spree.permissions.assign(:admin, [Spree::PermissionSets::SuperUser])
+
+ # Custom role with specific permissions
+ Spree.permissions.assign(:customer_service, [
+ Spree::PermissionSets::DashboardDisplay,
+ Spree::PermissionSets::OrderManagement,
+ Spree::PermissionSets::UserDisplay
+ ])
+
+ # Merchandiser role for product management
+ Spree.permissions.assign(:merchandiser, [
+ Spree::PermissionSets::DashboardDisplay,
+ Spree::PermissionSets::ProductManagement,
+ Spree::PermissionSets::StockManagement
+ ])
+end
+```
+
+### Built-in Permission Sets
+
+| Permission Set | Description |
+|---------------|-------------|
+| `SuperUser` | Full admin access with safety restrictions |
+| `DefaultCustomer` | Basic storefront permissions (browse, checkout, manage own account) |
+| `DashboardDisplay` | View admin dashboard |
+| `OrderDisplay` | Read-only access to orders |
+| `OrderManagement` | Full order management (view, edit, refund, etc.) |
+| `ProductDisplay` | Read-only access to products and catalog |
+| `ProductManagement` | Full catalog management (products, variants, taxonomies) |
+| `UserDisplay` | Read-only access to users |
+| `UserManagement` | Full user management |
+| `StockDisplay` | Read-only access to inventory |
+| `StockManagement` | Full inventory management |
+| `PromotionManagement` | Manage promotions and coupon codes |
+| `ConfigurationManagement` | Manage store settings, shipping, taxes, etc. |
+| `RoleManagement` | Manage roles (except the protected admin role) |
+
+### Creating Custom Permission Sets
+
+Create a new permission set in `app/models/spree/permission_sets/`:
+
+```ruby
+# app/models/spree/permission_sets/warehouse_management.rb
+module Spree
+ module PermissionSets
+ class WarehouseManagement < Base
+ def activate!
+ can :manage, Spree::StockItem
+ can :manage, Spree::StockLocation
+ can :manage, Spree::StockMovement
+ can :manage, Spree::Shipment
+ can [:read, :admin], Spree::Order
+ end
+ end
+ end
+end
+```
+
+Then assign it to a role:
+
+```ruby
+Spree.permissions.assign(:warehouse_staff, [
+ Spree::PermissionSets::DashboardDisplay,
+ Spree::PermissionSets::WarehouseManagement
+])
+```
+
+### Permission Set API
+
+Within a permission set, you have access to:
+
+- `can(action, subject, conditions = {})` - Grant permission
+- `cannot(action, subject, conditions = {})` - Deny permission
+- `can?(action, subject)` - Check if permission exists
+- `user` - The current user
+- `store` - The current store (for multi-store setups)
+
+```ruby
+module Spree
+ module PermissionSets
+ class OrderManagementForOwnOrders < Base
+ def activate!
+ # Users can only manage orders they created
+ can :manage, Spree::Order, created_by_id: user.id
+
+ # But cannot cancel any order
+ cannot :cancel, Spree::Order
+
+ # Unless it's cancellable
+ can :cancel, Spree::Order, &:allow_cancel?
+ end
+ end
+ end
+end
+```
+
+### Managing Permission Configuration
+
+```ruby
+# Assign permission sets to a role
+Spree.permissions.assign(:customer_service, [
+ Spree::PermissionSets::OrderDisplay,
+ Spree::PermissionSets::UserManagement
+])
+
+# Add more permission sets to an existing role
+Spree.permissions.assign(:customer_service, [
+ Spree::PermissionSets::StockDisplay
+])
+
+# Clear all permission sets from a role
+Spree.permissions.clear(:customer_service)
+
+# Check what permission sets a role has
+Spree.permissions.permission_sets_for(:customer_service)
+# => [Spree::PermissionSets::OrderDisplay, ...]
+
+# Check if a role is configured
+Spree.permissions.role_configured?(:customer_service)
+# => true
+```
+
+## Users and Roles
+
+Spree comes with an `admin` role by default. You can create more roles in the Admin Panel or via Rails console:
```ruby
Spree::Role.find_or_create_by(name: 'customer_service')
+Spree::Role.find_or_create_by(name: 'merchandiser')
+Spree::Role.find_or_create_by(name: 'warehouse_staff')
```
-Same with assigning a role, you can do it in the Admin Panel or from the console:
+Assign a role to a user:
```ruby
-Spree.user_class.find_by(email: '[email protected]').spree_roles << Spree::Role.find_or_create_by(name: 'customer_service')
+user = Spree.user_class.find_by(email: '[email protected]')
+role = Spree::Role.find_by(name: 'customer_service')
+user.spree_roles << role
```
-## Ability class
+### Default Role Behavior
+
+- Users with **no roles assigned** automatically get the `:default` role permissions
+- No `RoleUser` records are created for regular customers
+- Only users with special permissions need explicit role assignments
-For authorization Spree uses [CanCanCan](https://github.com/CanCanCommunity/cancancan) library. The main ability class by default is [Spree::Ability](https://github.com/spree/spree/blob/main/core/app/models/spree/ability.rb).
+## Legacy Approach: Custom Ability Classes
-## Adding custom permissions
+<Note>
+The permission sets approach above is recommended for new projects. The legacy approach below is supported for backward compatibility.
+</Note>
-Let's assume you would like to add a new Role `customer_service` with some limited access to Admin Panel only Orders section.
+### Adding Custom Permissions via Decorator
-Create a new file called `app/models/customer_service_ability.rb`
+Create a new ability class in `app/models/customer_service_ability.rb`:
```ruby
class CustomerServiceAbility
@@ -38,9 +192,7 @@ class CustomerServiceAbility
end
```
-Please familiarize yourself with [CanCanCan](https://github.com/CanCanCommunity/cancancan) syntax to understand `can/cannot` methods more.
-
-Now we need to inform Spree to use this ability, create another file `app/models/spree/ability_decorator.rb` with contents:
+Register it via a decorator in `app/models/spree/ability_decorator.rb`:
```ruby
module Spree
@@ -54,32 +206,30 @@ module Spree
end
```
-## Replacing all permissions
+### Replacing the Ability Class
-As we've mentioned earlier, Spree uses the main Ability class. You can change that to use your own custom Ability class via [Dependencies](dependencies) in Spree initializer `config/initializers/spree.rb`, eg.
+You can replace the entire ability class via [Dependencies](/developer/customization/dependencies):
```ruby
+# config/initializers/spree.rb
Spree::Dependencies.ability_class = 'CustomAbility'
```
-Now, let's define that new class in `app/models/custom_ability.rb`
-
```ruby
+# app/models/custom_ability.rb
class CustomAbility < Spree::Ability
- def initialize(user)
+ def initialize(user, options = {})
alias_cancan_delete_action
- user ||= Spree.user_class.new
+ @user = user || Spree.user_class.new
+ @store = options[:store] || Spree::Current.store
- if user.respond_to?(:has_spree_role?) && user.has_spree_role?('admin')
- apply_admin_permissions(user)
- # add some more permissions here for the admin role
- else
- if user.respond_to?(:has_spree_role?) && user.has_spree_role?(:customer_service)
- apply_customer_service_permissions(user)
- end
-
- apply_user_permissions(user)
+ if @user.respond_to?(:has_spree_role?) && @user.has_spree_role?('admin')
+ apply_admin_permissions(@user, options)
+ elsif @user.respond_to?(:has_spree_role?) && @user.has_spree_role?(:customer_service)
+ apply_customer_service_permissions(@user)
+ else
+ apply_user_permissions(@user, options)
end
protect_admin_role
@@ -89,10 +239,29 @@ class CustomAbility < Spree::Ability
def apply_customer_service_permissions(user)
can :manage, Spree::Order
+ can [:read, :admin], Spree.user_class
end
end
```
-After restarting the rails server you observe new permissions being recognized in the application.
+## CanCanCan Reference
+
+Spree's permission system is built on CanCanCan. Key concepts:
+
+- `can :action, Subject` - Grant permission
+- `can :manage, Subject` - Grant all actions (create, read, update, destroy)
+- `cannot :action, Subject` - Explicitly deny permission
+- `can :action, Subject, conditions` - Conditional permission
+
+```ruby
+# Examples
+can :read, Spree::Product # Can read any product
+can :manage, Spree::Order, user_id: user.id # Can manage own orders
+can :update, Spree::Order do |order| # Block conditions
+ order.user == user && !order.completed?
+end
+cannot :destroy, Spree::Order # Cannot destroy any order
+can :destroy, Spree::Order, &:can_be_deleted? # Unless it's deletable
+```
-Further permission changes should be automatically picked up in development and should not require application restarts.
+See the [CanCanCan documentation](https://github.com/CanCanCommunity/cancancan) for more details.
diff --git a/docs/docs.json b/docs/docs.json
index faf9787eaf..165d070b1a 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -31,6 +31,10 @@
{
"source": "/developer/storefront/images",
"destination": "/developer/core-concepts/images-assets"
+ },
+ {
+ "source": "/developer/admin/permissions",
+ "destination": "/developer/customization/permissions"
}
],
"contextual": {
@@ -112,7 +116,6 @@
"developer/admin/components",
"developer/admin/helper-methods",
"developer/admin/authentication",
- "developer/admin/permissions",
"developer/admin/custom-javascript",
"developer/admin/custom-css"
]