Shopware Roles and Permissions | OpsBlu Docs

Shopware Roles and Permissions

Complete guide to Shopware's role-based access control system, permission levels, and security best practices

Shopware 6 uses a robust Access Control List (ACL) system with role-based permissions that provide granular control over user capabilities. Understanding these roles is essential for secure and efficient user management.

How Shopware Permissions Work

ACL System Overview

Shopware 6 introduces a comprehensive ACL (Access Control List) system:

  • Role: A named collection of permissions (e.g., Administrator, Editor, Viewer)
  • Permission: Specific action rights (read, write, delete) on resources
  • Resource: Shopware entities (products, orders, customers, etc.)
  • User: Assigned one or more roles that determine their capabilities
User → Assigned Roles → Permissions → Access to Resources

Permission Levels

Each resource can have up to four permission levels:

  • View: Read-only access to resource
  • Edit: Modify existing resources
  • Create: Create new resources
  • Delete: Remove resources

Example:

Product Resource:
├── View: See product list and details
├── Edit: Modify existing products
├── Create: Add new products
└── Delete: Remove products from catalog

Default Roles in Shopware 6

Administrator

Purpose: Full system access and control

Key Capabilities:

  • All permissions: Complete access to all resources
  • User management: Create, edit, delete users and roles
  • System settings: Modify shop configuration
  • Plugin management: Install, configure, uninstall plugins
  • Sales channels: Manage all sales channels
  • Integrations: Configure API access and webhooks
  • Theme editing: Customize shop appearance
  • Rule builder: Create complex business rules

Full Access Areas:

✓ Dashboard and analytics
✓ Orders and transactions
✓ Products and categories
✓ Customers and reviews
✓ Content (CMS, media)
✓ Marketing (promotions, newsletters)
✓ Settings (all areas)
✓ System (plugins, updates, cache)
✓ Users and permissions
✓ Rule builder
✓ Import/Export

Use Cases:

  • Store owner
  • Technical lead
  • Senior developers with full access needs
  • System administrators

Security Notes:

Editor (Content Manager)

Purpose: Manage content and products without system access

Key Capabilities:

  • Products: Full CRUD on products, variants, categories
  • Content: Create and edit CMS pages, layouts
  • Media: Upload and manage media library
  • Categories: Organize product hierarchy
  • Promotions: Create marketing campaigns
  • Cannot: Access system settings, manage users, install plugins

Permission Breakdown:

Products:
├── View: ✓
├── Edit: ✓
├── Create: ✓
└── Delete: ✓

Categories:
├── View: ✓
├── Edit: ✓
├── Create: ✓
└── Delete: ✓

Content (CMS):
├── View: ✓
├── Edit: ✓
├── Create: ✓
└── Delete: ✓

Media:
├── View: ✓
├── Edit: ✓
├── Create: ✓
└── Delete: ✓

Orders:
├── View: ✓
├── Edit: ✓
├── Create: ✗
└── Delete: ✗

Settings:
├── View: ✗
├── Edit: ✗

Use Cases:

  • Content managers
  • Marketing teams
  • Product catalog managers
  • E-commerce merchandisers

Viewer (Read-Only)

Purpose: Browse data without making changes

Key Capabilities:

  • View: Access to most resources in read-only mode
  • Dashboard: See reports and analytics
  • Orders: Review order details
  • Products: Browse catalog
  • Cannot: Edit, create, or delete anything

Permission Breakdown:

Products:
├── View: ✓
├── Edit: ✗
├── Create: ✗
└── Delete: ✗

Orders:
├── View: ✓
├── Edit: ✗
├── Create: ✗
└── Delete: ✗

Customers:
├── View: ✓
├── Edit: ✗
├── Create: ✗
└── Delete: ✗

Reports:
├── View: ✓
├── Export: ✗

Use Cases:

  • Auditors
  • Stakeholders needing visibility
  • Client access for reporting
  • Training accounts
  • Quality assurance teams

Order Manager

Purpose: Process orders and manage fulfillment

Key Capabilities:

  • Orders: Full access to order management
  • Customers: View and edit customer information
  • Shipping: Manage shipment tracking
  • Payments: Process transactions
  • Cannot: Manage products, settings, users

Permission Breakdown:

Orders:
├── View: ✓
├── Edit: ✓ (status, shipping)
├── Create: ✓ (manual orders)
└── Delete: ✗

Customers:
├── View: ✓
├── Edit: ✓
├── Create: ✓
└── Delete: ✗

Products:
├── View: ✓
├── Edit: ✗
├── Create: ✗
└── Delete: ✗

Use Cases:

  • Order fulfillment team
  • Customer service representatives
  • Warehouse managers
  • Shipping coordinators

Marketing Manager

Purpose: Manage promotions and marketing activities

Key Capabilities:

  • Promotions: Create discounts and campaigns
  • Newsletter: Manage email marketing
  • SEO: Edit meta information
  • Content: Edit CMS pages
  • Cannot: Access orders, system settings

Permission Breakdown:

Promotions:
├── View: ✓
├── Edit: ✓
├── Create: ✓
└── Delete: ✓

Content (CMS):
├── View: ✓
├── Edit: ✓
├── Create: ✓
└── Delete: ✓

Products (SEO only):
├── View: ✓
├── Edit: ✓ (meta only)
├── Create: ✗
└── Delete: ✗

Newsletter:
├── View: ✓
├── Edit: ✓
├── Create: ✓
└── Delete: ✓

Use Cases:

  • Marketing team members
  • SEO specialists
  • Campaign managers
  • Content marketers

Custom Roles

Creating Custom Roles

Access path:

Settings → System → User Roles → Add role

Screenshot reference: /screenshots/shopware-create-role.png

Step 1: Define Role Details

1. Click "Add role"
2. Enter role name: "Sales Representative"
3. Add description: "Access to orders and customers for sales team"
4. Save

Step 2: Configure Permissions

Select resources and permission levels:

Example: Sales Representative

Orders:
├── View: ✓
├── Edit: ✓ (update status)
├── Create: ✓ (create quotes)
└── Delete: ✗

Customers:
├── View: ✓
├── Edit: ✓
├── Create: ✓
└── Delete: ✗

Products:
├── View: ✓
├── Edit: ✗
├── Create: ✗
└── Delete: ✗

Reports:
├── View: ✓ (sales reports only)

Step 3: Test Role

Best practice:

  1. Create test user with new role
  2. Verify access to required resources
  3. Confirm restrictions work
  4. Adjust permissions as needed
  5. Document role purpose and scope

Common Custom Role Examples

Product Manager (Limited)

Purpose: Manage products but not prices or inventory

Products:
├── View: ✓
├── Edit: ✓ (descriptions, images, SEO)
├── Create: ✓
└── Delete: ✗ (requires approval)

Prices: ✗ (read-only)
Inventory: ✗ (read-only)
Categories: ✓ (full access)
Media: ✓ (full access)

Customer Support Agent

Purpose: Handle customer inquiries and basic order updates

Orders:
├── View: ✓
├── Edit: ✓ (status, notes only)
├── Create: ✗
└── Delete: ✗

Customers:
├── View: ✓
├── Edit: ✓ (contact info only)
├── Create: ✗
└── Delete: ✗

Products:
├── View: ✓
├── Edit: ✗

Returns: ✓ (full access)

Financial Controller

Purpose: Access financial data and reports

Orders:
├── View: ✓ (financial data)
├── Edit: ✗

Reports:
├── View: ✓ (all financial reports)
├── Export: ✓

Customers:
├── View: ✓
├── Edit: ✗

Products:
├── View: ✓ (pricing only)

Granular Permissions by Resource

Product Permissions

product:
├── read: View product list and details
├── update: Edit existing products
├── create: Add new products
└── delete: Remove products

product_manufacturer:
├── read: View brands
├── update: Edit brand information
├── create: Add new brands
└── delete: Remove brands

product_media:
├── read: View product images
├── update: Modify images
├── create: Upload new images
└── delete: Remove images

product_price:
├── read: See pricing
├── update: Modify prices
├── create: Add price rules
└── delete: Remove prices

Order Permissions

order:
├── read: View orders
├── update: Modify order details
├── create: Create manual orders
└── delete: Cancel/delete orders

order_transaction:
├── read: View payment info
├── update: Update payment status
├── create: Process payments
└── delete: Void transactions

order_delivery:
├── read: View shipping info
├── update: Update tracking
├── create: Create shipments
└── delete: Cancel shipments

Customer Permissions

customer:
├── read: View customer list
├── update: Edit customer data
├── create: Add new customers
└── delete: Remove customers

customer_address:
├── read: View addresses
├── update: Modify addresses
├── create: Add addresses
└── delete: Remove addresses

customer_group:
├── read: View customer groups
├── update: Edit groups
├── create: Create groups
└── delete: Remove groups

System Permissions

user:
├── read: View user list
├── update: Edit users
├── create: Add users
└── delete: Remove users

plugin:
├── read: View installed plugins
├── update: Configure plugins
├── create: Install plugins
└── delete: Uninstall plugins

sales_channel:
├── read: View sales channels
├── update: Edit channels
├── create: Add channels
└── delete: Remove channels

system_config:
├── read: View settings
├── update: Modify settings
├── create: N/A
└── delete: Reset settings

Content Permissions

cms_page:
├── read: View CMS pages
├── update: Edit pages
├── create: Create pages
└── delete: Remove pages

category:
├── read: View categories
├── update: Edit categories
├── create: Create categories
└── delete: Remove categories

media:
├── read: View media library
├── update: Edit metadata
├── create: Upload files
└── delete: Remove files

Permission Inheritance

Role Combination

Users can have multiple roles:

User: Sarah Johnson
Roles:
  - Editor (base permissions)
  - Order Manager (additional permissions)

Combined Permissions = Editor ∪ Order Manager

Permission resolution:

  • Permissions are additive (union)
  • Any role granting permission = user has permission
  • No negative permissions (can't explicitly deny)

Best Practices for Multiple Roles

Do:

  • ✓ Use base role + specialized role
  • ✓ Keep roles focused and specific
  • ✓ Document role combinations

Don't:

  • ✗ Create overlapping roles
  • ✗ Assign more than 3 roles per user
  • ✗ Use multiple roles when custom role better fits

API Permissions

Integration Authentication

Separate from user roles:

Settings → System → Integrations → Create integration

Integration scopes (different from user permissions):

  • read: GET requests
  • write: POST, PATCH requests
  • delete: DELETE requests
  • Scope limited to specific entities

Example integration:

{
  "label": "Mobile App Integration",
  "accessKey": "SWIARANDOMKEY",
  "secretAccessKey": "SECRET",
  "permissions": [
    {"resource": "product", "scope": "read"},
    {"resource": "order", "scope": "read"},
    {"resource": "order", "scope": "write"}
  ]
}

Store API Access

Frontend API (different permissions):

  • Customer login required
  • No admin permissions
  • Limited to customer-facing operations

Security Best Practices

Principle of Least Privilege

Grant minimum required permissions:

Bad practice:

Content intern → Administrator role
Reason: "They might need access later"

Good practice:

Content intern → Custom "Content Contributor" role
Permissions:
  - Products: View only
  - CMS: Create, Edit (not Delete)
  - Media: Upload, View
  - Review after 30 days

Dangerous Permissions

Restrict carefully:

Critical permissions:

  • plugin:create - Install code (security risk)
  • plugin:delete - Remove plugins (availability risk)
  • user:delete - Remove users (audit trail)
  • system_config:update - Change settings (business risk)
  • import_export:create - Data exfiltration risk

Recommendation:

  • Limit to 1-2 administrators
  • Require approval workflow (if possible)
  • Log all uses
  • Enable two-factor authentication

Permission Audit

Regular review checklist:

# Generate user permission report
bin/console user:list --with-roles

# Review administrators
SELECT * FROM user WHERE admin = 1;

# Find users with plugin permissions
# Check ACL role assignments

Quarterly audit:

  • List all custom roles
  • Review permission scope
  • Identify over-permissioned users
  • Remove unused roles
  • Update documentation

Advanced Permission Scenarios

Multi-Store Permissions

Sales channel restrictions:

User: Regional Manager (Europe)
Roles: Editor
Sales Channel Access:
  ✓ EU Store (English)
  ✓ EU Store (German)
  ✗ US Store
  ✗ APAC Store

How it works:

  • User can only see/edit products in assigned channels
  • Orders filtered by sales channel
  • Content restricted to channel

Time-Based Permissions

Plugin required for temporal access:

Example use case:

Seasonal worker: Holiday Support Agent
Role: Customer Support Agent
Active: Nov 1 - Jan 15
Auto-disable: Jan 16

Implementation:

// Custom plugin code
if ($user->getStartDate() > new \DateTime() ||
    $user->getEndDate() < new \DateTime()) {
    $user->setActive(false);
}

Workflow-Based Permissions

Approval workflows (requires plugin):

Example:

Product Editor: Can create products
Status: Draft (awaiting approval)

Product Approver: Can publish products
Status: Active (visible in store)

Programmatic Permission Checks

Check User Permissions in Code

use Shopware\Core\Framework\Context;

// Check if user has permission
if ($context->getSource() instanceof AdminApiSource) {
    $permissions = $context->getSource()->getPermissions();

    if (in_array('product:create', $permissions)) {
        // User can create products
    }
}

// Check specific resource permission
use Shopware\Core\Framework\Api\Acl\Role\AclRoleDefinition;

$aclRoleRepository->search(
    $criteria->addFilter(
        new EqualsFilter('privileges', 'product:read')
    ),
    $context
);

Custom Permission Validation

use Shopware\Core\Framework\Api\Acl\Resource\AclResourceDefinition;

class CustomPermissionValidator
{
    public function validateAccess(Context $context, string $resource, string $privilege): bool
    {
        if (!$context->getSource() instanceof AdminApiSource) {
            return false;
        }

        $permissions = $context->getSource()->getPermissions();
        $requiredPermission = $resource . ':' . $privilege;

        return in_array($requiredPermission, $permissions);
    }
}

// Usage
if (!$validator->validateAccess($context, 'product', 'delete')) {
    throw new MissingPrivilegeException(['product:delete']);
}

Migration from Shopware 5

Key Differences

Shopware 5:

  • Basic role system
  • Limited permission granularity
  • Backend modules only

Shopware 6:

  • ACL system with granular permissions
  • Resource-based access control
  • API-first permissions

Migration Strategy

1. Map old roles to new:

SW5 Backend User → SW6 Editor
SW5 Admin → SW6 Administrator
SW5 Custom → SW6 Custom Role (rebuild)

2. Recreate custom roles:

  • List SW5 permissions
  • Map to SW6 resources
  • Create equivalent SW6 role
  • Test thoroughly

3. User migration:

# Export SW5 users
# Import to SW6 with role mapping
bin/console user:create --import=users.csv

Troubleshooting

User Can't Access Expected Resource

Debug steps:

  1. Check assigned roles
  2. Verify role permissions
  3. Check sales channel access
  4. Clear cache: bin/console cache:clear
  5. Review error logs

Common issues:

  • Role doesn't include required permission
  • Multiple roles conflicting (shouldn't happen, but check)
  • Sales channel restriction
  • Plugin interference

Permission Changes Don't Take Effect

Solutions:

  • Clear cache: bin/console cache:clear
  • User logout and login
  • Check database: ACL tables updated?
  • Verify role-user assignment

Cannot Modify System Roles

Issue: Default roles (Administrator, Viewer) not editable

Solution: Clone role and customize:

1. Create new role: "Custom Administrator"
2. Copy Administrator permissions
3. Modify as needed
4. Assign to users

Next Steps

Back to top