ERPNext Module Gate

Module licensing and access control for ERPNext SaaS platforms

Author: Zeiad Madboly

What is ERPNext Module Gate?

ERPNext Module Gate allows you to sell ERPNext as modular packages. Instead of giving customers access to the entire ERPNext suite, you can control which modules they can access based on their purchase or license.

Key Features

• ✅ Module-based access control - Control which ERPNext modules users can access
• ✅ Automatic role management - Users automatically get the right roles for their licensed modules
• ✅ Workspace filtering - Unlicensed modules are hidden from navigation
• ✅ Custom module support - All custom modules (non-ERPNext) are accessible by default
• ✅ Secure - Even System Managers cannot bypass module restrictions
• ✅ Administrator bypass - Full access for Administrator account
• ✅ Easy integration - Works seamlessly with ERPNext SaaS registration workflows

Quick Start

1. Installation

cd /path/to/your/bench
bench get-app erpnext_module_gate
bench install-app erpnext_module_gate
bench migrate

2. Configure Licensed Modules

Option A: Via Registration Form (Recommended)

When users register through your SaaS platform, they can select which modules they want. The system automatically configures their site.

Option B: Manual Configuration

       # Set specific modules
       bench --site [site_name] execute erpnext_module_gate.erpnext_module_gate.set_modules.set_modules

       # Or grant full access (no restrictions)
       bench --site [site_name] execute erpnext_module_gate.erpnext_module_gate.set_all_modules.set_all

3. Verify It Works

   ```bash
   # Run automated tests
   bench --site [site_name] execute erpnext_module_gate.erpnext_module_gate.test_module_enforcement.run_tests
   ```

How It Works

For End Users

1. User registers and selects modules (or you configure them)
2. User logs in - System automatically assigns correct roles
3. User sees only licensed modules in the workspace navigation
4. User can only access doctypes from licensed ERPNext modules
5. Custom modules are always accessible regardless of licensing

For System Administrators

• ✅ Can manage users and permissions within licensed modules
• ✅ Can access Role Permission Manager (but only for licensed ERPNext modules)
• ✅ Can access all custom modules (non-ERPNext) without restrictions
• ❌ Cannot access unlicensed ERPNext module doctypes
• ❌ Cannot assign unlicensed ERPNext module roles
• ❌ Cannot bypass restrictions through any method

For Platform Administrators

• ✅ Full access to everything (Administrator account)
• ✅ Can modify site_config.json directly
• ✅ Can grant full access by setting licensed_modules to ["all"] or [] or ["Accounting",...]

Available Modules

• Accounts
• Selling
• Buying
• Stock
• Manufacturing
• Projects
• CRM
• Support
• Assets
• Maintenance
• Quality Management
• Subcontracting
• Setup (always included)

Common Tasks

Grant Full Access to a Site

       bench --site [site_name] execute erpnext_module_gate.erpnext_module_gate.set_all_modules.set_all

Change Licensed Modules

# Via bench console
bench --site [site_name] console

# Then in console:
from erpnext_module_gate.erpnext_module_gate.api import set_licensed_modules
set_licensed_modules(["Accounts", "Selling", "Stock"])

Check Current Licensed Modules

from erpnext_module_gate.erpnext_module_gate.api import get_licensed_modules
print(get_licensed_modules())

Troubleshooting

Users can access all modules

Check: Verify licensed_modules is set in site_config.json:

import frappe
print(frappe.conf.get("licensed_modules"))

Fix: Set modules using the methods above.

System Manager can still access unlicensed modules

Check: Verify the app is installed and hooks are loaded:

bench restart
bench --site [site_name] clear-cache

Administrator cannot access modules

Note: Administrator should always have full access. If not, check:

from erpnext_module_gate.erpnext_module_gate.api import is_administrator
print(is_administrator("Administrator"))  # Should be True

Integration with SaaS

The app automatically integrates with ERPNext SaaS registration workflows:

1. User selects modules during registration
2. Modules are stored in site_config.json
3. Permissions are enforced on first login
4. Workspaces are automatically filtered

Security

• Multi-layer protection - Three security layers prevent bypass attempts
• System Manager restrictions - Even System Managers cannot access unlicensed ERPNext modules
• Custom module support - All custom modules (non-ERPNext) are accessible by default
• Administrator bypass - Only Administrator account has full access
• Real-time enforcement - Restrictions are checked on every access attempt

Important Notes

Custom Modules

All custom modules outside ERPNext are accessible by default, regardless of licensing configuration. This includes:

• Modules from custom apps (e.g., custom_app)
• Modules that don't belong to the erpnext app
• Only ERPNext modules are restricted based on licensed_modules configuration

This means you don't need to add custom modules to the licensed modules list - they work automatically!

Support

For detailed technical documentation, see TECHNICAL.md

For implementation status and testing guides, see:

• IMPLEMENTATION_STATUS.md
• TESTING_GUIDE.md
• SECURITY_PROTECTIONS.md

License

MIT