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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Add Permissions Customization section
Damian Legawiec6bd44988afb0
diff --git a/guides/src/content/developer/customization/permissions.md b/guides/src/content/developer/customization/permissions.mdnew file mode 100644index 0000000000..6a17c12476--- /dev/null+++ b/guides/src/content/developer/customization/permissions.md@@ -0,0 +1,108 @@+---+title: 'Permissions Customization'+section: customization+order: 5+---++## Overview++## User and 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.:++```ruby+Spree::Role.find_or_create_by(name: 'customer_service')+```++Same with assigning a role, you can do it in the Admin Panel or from the console:++```ruby+Spree.user_class.find_by(email: '[email protected]').spree_roles << Spree::Role.find_or_create_by(name: 'customer_service')+```++## Ability class++For authorization Spree uses [CanCanCan](https://github.com/CanCanCommunity/cancancan). The main ability class by default is [Spree::Ability](https://github.com/spree/spree/blob/master/core/app/models/spree/ability.rb).++## Adding custom permissions++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/my_project/customer_service_ability.rb`++```ruby+module MyProject+ 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+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/my_project/spree/ability_decorator.rb` with contents:++```ruby+module MyProject+ module Spree+ module AbilityDecorator+ def abilities_to_register+ [CustomerServiceAbility]+ end+ end+ end+end++::Spree::Ability.prepend(MyProject::Spree::AbilityDecorator)+```++## Replacing all permissions++As we've mentioned earlier, Spree uses main Ability class. But you can change that to use your own custom Ability class via [Dependencies](/developer/customization/dependencies.html) in Spree initializer (`config/initializers/spree.rb`), eg.++```ruby+Spree::Dependencies.ability_class = 'MyProject::Ability'+```++Now, let's define that new class in `app/models/my_project/ability.rb`++```ruby+module MyProject+ class Ability < ::Spree::Ability+ def initialize(user)+ alias_cancan_delete_action++ user ||= Spree.user_class.new++ 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)+ end++ protect_admin_role+ end++ protected++ def apply_customer_service_permissions(user)+ can :manage, ::Spree::Order+ end+ end+end+```++Now your can restart your rails server and observe new permissions being implemented in the application.++Leter permission changes should be automatically picked up in development and should not require application restarts.