ERPNext Security Model

Security in ERPNext is not implemented as a single feature, module, or configuration screen. It is a distributed architectural concern woven into every execution path of the system.

This document explains how ERPNext enforces security internally, how access decisions are made at runtime, and why security failures in ERP systems are almost always architectural rather than technical.

This is a system-level explanation. User interface behavior, screens, and navigation are intentionally excluded.

1. Security as a Core Architectural Guarantee

ERPNext treats security as a non-negotiable system guarantee. Every operation — whether triggered from the web UI, REST API, background worker, or scheduler — passes through the same permission enforcement pipeline.

There is no trusted execution path. No internal shortcut. No elevated internal context by default.

This design ensures that security behavior is predictable, auditable, and resistant to accidental bypass.

Security Enforcement Flow

Action requested
→ User context resolved
→ Roles evaluated
→ DocType permissions checked
→ Record-level filters applied
→ Operation allowed or rejected

Architectural Principle

• Security is enforced server-side only
• UI restrictions are advisory, not authoritative
• All execution paths converge on the same checks

2. Trust Boundaries in ERPNext

ERPNext is designed around explicit trust boundaries. A trust boundary defines where assumptions about identity and authority stop.

In ERPNext, the browser, API clients, and background jobs are all considered untrusted. Only the server-side permission engine is authoritative.

This prevents privilege escalation through indirect execution paths.

Trust Boundary Model

Client request
→ Untrusted input
→ Server-side validation
→ Controlled execution

Boundary Enforcement Rules

• No client-side permission assumptions
• No background task bypass
• No internal API exemptions

3. Authentication vs Authorization – Clear Separation

ERPNext strictly separates authentication from authorization. These two concerns are resolved independently and never conflated.

Authentication establishes identity. Authorization establishes capability. Permission checks always assume identity has already been verified.

Conceptual Separation

Concern	Responsibility
Authentication	Verify who the user is
Authorization	Verify what the user may do
Permissions	Enforce action-level access

Execution Order

Credentials verified
→ Session established
→ Roles loaded
→ Permissions evaluated dynamically

4. User Authentication and Session Architecture

Authentication in ERPNext establishes a session context that carries identity, role membership, and cached permission data.

Passwords are never stored in plain text. ERPNext uses secure hashing mechanisms with salting and iteration to resist offline attacks.

Authentication Execution Flow

Login request
→ Password hash verified
→ Session ID generated
→ Session stored in Redis
→ User context initialized

Core Tables Involved

Table	Purpose
tabUser	User identity and status
tabSessions	Active session tracking
__Auth	Password hash storage

5. Session Scope and Lifetime Control

Sessions in ERPNext are scoped to a specific user identity and are time-bound. They are not permanent credentials.

Session expiration, revocation, and invalidation are core security mechanisms, not optional features.

Session Lifecycle

Session created
→ Used for requests
→ Refreshed or expired
→ Destroyed explicitly or implicitly

Security Implication

• Compromised sessions have limited lifespan
• Role changes take effect immediately
• Inactive users lose access automatically

6. Role-Based Access Control (RBAC) Foundation

ERPNext uses strict role-based access control. Permissions are never assigned directly to users.

A user’s effective permissions are the union of all permissions granted by assigned roles.

This design supports scalability, auditability, and centralized governance.

RBAC Resolution Flow

User identified
→ Roles resolved
→ DocType permission rules evaluated
→ Effective permissions calculated

RBAC Advantages

• Predictable permission behavior
• Centralized policy changes
• Reduced configuration errors

7. Role Assignment and Inheritance Rules

Roles in ERPNext are flat and non-hierarchical. There is no implicit inheritance unless explicitly designed through role assignment.

This avoids hidden privilege escalation and makes permission reviews deterministic.

Role Resolution Rules

Rule	Effect
Multiple roles	Permissions are additive
No deny rules	Absence means no access
System Manager role	Overrides most restrictions

Governance Principle

• Roles must be function-based
• Users should have minimal roles
• High-privilege roles must be rare

8. DocType as the Primary Security Boundary

In ERPNext, the DocType is the primary unit of security enforcement. Every permission decision is evaluated in the context of a DocType.

DocTypes define what actions are possible, what data is stored, and how access is controlled.

DocType Security Scope

DocType defined
→ Actions declared
→ Permissions attached
→ Runtime enforcement applied

Security Implication

• No action exists outside a DocType
• Permissions are DocType-specific
• Custom DocTypes inherit the same guarantees

9. DocType Permission Matrix Design

Each DocType contains a permission matrix that maps roles to allowed actions.

These permissions are evaluated dynamically at runtime, not statically at login.

Permission Types

Permission	Meaning
Read	View records
Write	Modify records
Create	Create new records
Submit	Finalize transactions
Cancel	Reverse submission
Amend	Create revised documents

Storage

Permission rules are stored in tabDocPerm and evaluated on every request.

10. Permission Evaluation Order and Determinism

ERPNext permission evaluation follows a strict, deterministic order. There is no ambiguity, fallback, or heuristic behavior.

This determinism is critical for auditability and predictable enforcement.

Evaluation Order

Role permissions evaluated
→ User permissions applied
→ Match conditions enforced
→ Final access decision returned

Non-Negotiable Rule

• Permissions are evaluated on every request
• No permission result is cached blindly
• All denials are intentional and explainable

11. User Permissions and Data-Level Access Control

DocType permissions determine what actions a user may perform. User permissions determine which specific records a user may see or interact with.

This distinction is critical. Even if a user has full DocType access, user permissions can still restrict visibility to a subset of records.

User permissions implement row-level security inside ERPNext.

User Permission Enforcement Flow

Request executed
→ DocType permission validated
→ User permission filters applied
→ Query restricted
→ Result set returned

Storage Model

Table	Purpose
tabUser Permission	Record-level access rules

Security Principle

• User permissions narrow access, never widen it
• They apply to reads, writes, and reports
• They are enforced at query time

12. Query-Level Enforcement and SQL Generation

User permissions are enforced not after data is fetched, but during query construction. This ensures unauthorized data is never loaded into memory.

ERPNext injects permission conditions directly into SQL queries. This design prevents accidental leaks through reports or exports.

Conceptual SQL Enforcement

SELECT *
FROM tabSales Invoice
WHERE customer IN ('Allowed Customer')

Design Implication

• No post-filtering of data
• Reports inherit the same security
• Exported data is permission-safe

13. Match Conditions – Dynamic Permission Logic

Match conditions allow dynamic permission rules that cannot be expressed as static role permissions.

They are evaluated at runtime for every query execution.

Match conditions are powerful and dangerous if misused.

Execution Flow

Query requested
→ Match condition function executed
→ SQL condition returned
→ Condition injected into query

Example

def get_permission_query_conditions(user):
    return f"owner = '{user}'"

Governance Rule

• Must be deterministic
• Must never bypass ownership rules
• Must be performance-safe

14. Server-Side Validation as a Security Layer

ERPNext does not trust client-side controls. Buttons, fields, and UI states have no security authority.

All validations, including permissions, are enforced server-side.

Validation Execution Flow

Request received
→ Permission check
→ Business rule validation
→ Database write attempted
→ Commit or rollback

Example

def validate(self):
    if not frappe.has_permission(self.doctype, "write"):
        frappe.throw("Permission denied")

Security Guarantee

• APIs and UI behave identically
• Hidden fields provide no protection
• All writes are controlled centrally

15. API Security and Authentication Context

ERPNext APIs are not privileged. They are subject to the same authentication and authorization rules as UI requests.

API calls execute within a user or token context. There is no anonymous privilege escalation.

Supported Authentication Models

Method	Use Case
Session-based	Web UI
API Key & Secret	Integrations
OAuth2	External applications

API Execution Flow

Request received
→ Token validated
→ User context resolved
→ Permissions enforced
→ Response returned

16. Permission Scope for Background Jobs

Background jobs in ERPNext do not run with unlimited privileges. They execute within an explicitly defined user context.

This design prevents silent privilege escalation through asynchronous processing.

Background Job Flow

Job enqueued
→ User context attached
→ Permissions evaluated
→ Job executed

Security Rule

• Jobs inherit user permissions
• No implicit system user
• Failures surface permission issues

17. System Manager Role and Elevated Privileges

The System Manager role is a special construct with near-unrestricted access.

It exists for administration, not for daily operations. Overuse of this role is the most common security failure in ERPNext implementations.

Risk Profile

Aspect	Impact
Data access	Global
Configuration	Unrestricted
Audit risk	High

Governance Rule

• Limit System Manager users
• Never assign for convenience
• Audit usage regularly

18. Audit Trail and Change Tracking

ERPNext maintains a comprehensive audit trail for security, compliance, and forensic analysis.

Security decisions must be explainable after the fact. Audit logs provide that explanation.

Audit Tables

Table	Purpose
tabVersion	Field-level changes
tabActivity Log	User actions
tabComment	Contextual discussion

Audit Principle

• Logs are immutable
• Logs are never optional
• Logs enable compliance verification

19. Security in Multi-Company Environments

Multi-company setups introduce additional security complexity. Companies share a database but must remain operationally isolated.

ERPNext enforces company isolation using explicit company fields, user permissions, and role segregation.

Isolation Enforcement Flow

User request
→ Company access validated
→ Record-level filters applied
→ Cross-company access blocked

Security Rule

• Company access is mandatory
• Cross-company leakage is blocked
• Reports respect company boundaries

20. Determinism and Explainability in Security Decisions

ERPNext security decisions are deterministic. Given the same user, roles, and data, the result is always the same.

This determinism is essential for audits, debugging, and governance.

Decision Flow

Inputs fixed
→ Permission rules applied
→ User permissions evaluated
→ Match conditions enforced
→ Outcome produced

Final Rule

• No heuristic security behavior
• No silent overrides
• Every denial is explainable

21. Common Security Misconfigurations in ERPNext

Most ERPNext security failures are not caused by software defects. They are caused by misconfiguration, role misuse, or poor governance decisions.

These failures are often invisible until audits, data leaks, or operational incidents occur.

Frequent Misconfigurations

Misconfiguration	Impact
Overuse of System Manager	Unrestricted access
Everyone role misuse	Permission leakage
Missing user permissions	Cross-data visibility

Preventive Rule

• Review roles quarterly
• Remove privileges proactively
• Assume misconfiguration is inevitable

22. Role Explosion and Permission Sprawl

Role explosion occurs when roles are created per user, per exception, or per short-term need.

This makes security behavior opaque, unpredictable, and impossible to audit.

Failure Pattern

New requirement
→ New role created
→ Assigned to few users
→ Never removed
→ Security complexity increases

Governance Principle

• Roles represent functions, not people
• Temporary access must be time-bound
• Fewer roles improve security

23. Security and Compliance Requirements

ERPNext security architecture supports compliance requirements such as auditability, segregation of duties, and traceability.

However, compliance is achieved through configuration discipline, not default installation.

Compliance Mapping

Requirement	ERPNext Mechanism
Audit trail	Version and activity logs
Segregation of duties	Role design
Data isolation	User permissions

Compliance Rule

• Security design must be documented
• Permissions must be reviewable
• Auditors must have read-only access

24. Security in Custom Scripts and Extensions

Custom scripts are the most common way to unintentionally bypass security.

Server scripts, hooks, and custom apps must explicitly respect permission checks.

Risk Pattern

Custom logic added
→ Permission check omitted
→ Unauthorized write possible

Safe Coding Rule

• Always call has_permission()
• Never assume trusted context
• Review custom code periodically

25. Data Export, Reporting, and Security

Reports and exports are common data leakage vectors. ERPNext enforces permissions even during reporting operations.

Users cannot export what they cannot see.

Reporting Security Flow

Report requested
→ Permission filters applied
→ Query executed
→ Export generated

Design Rule

• Reports must never bypass filters
• Custom SQL must enforce permissions
• Exports are security-sensitive

26. Monitoring, Alerts, and Security Visibility

Security without visibility is operationally useless. ERPNext provides logs, but monitoring must be externalized for production environments.

Suspicious patterns should be detectable, not discovered after damage.

Monitoring Signals

Signal	Meaning
Repeated permission failures	Misuse or attack
Sudden role changes	Privilege escalation risk

Operational Rule

• Monitor logs continuously
• Alert on abnormal patterns
• Review security events regularly

27. Incident Response and Access Revocation

When security incidents occur, response speed matters. ERPNext allows immediate access revocation through user disablement and session invalidation.

Incident Response Flow

Incident detected
→ User disabled
→ Sessions invalidated
→ Audit review initiated

Response Principle

• Disable first, investigate second
• Preserve logs
• Document all actions

28. Security Testing and Permission Audits

Security must be tested, not assumed. Permission audits should be conducted regularly, especially after organizational changes.

ERPNext security behavior is testable through controlled user scenarios.

Audit Flow

Role review
→ User simulation
→ Permission verification
→ Findings documented

Audit Rule

• Test negative cases
• Assume least privilege
• Fix root causes, not symptoms

29. Governance Model for Long-Term Security

Security in ERPNext is a governance problem more than a technical one. Without ownership, even strong security models degrade.

Clear responsibility is required for role design, permission changes, and audits.

Governance Structure

Role	Responsibility
Business owner	Define access needs
System owner	Enforce configuration
Auditor	Review compliance

Governance Rule

• No anonymous changes
• All changes are reviewable
• Security decisions are documented

30. Security as a Long-Term Architectural Commitment

ERPNext security is not a setup task and not a one-time project. It is a long-term architectural commitment that evolves with the organization.

When designed correctly, it enables scale, compliance, and trust. When neglected, it becomes a systemic risk.

Architecture Lifecycle

Business structure defined
→ Security model designed
→ Permissions enforced
→ Audits performed continuously

Final Principle

• Security must be intentional
• Boundaries must be protected
• Governance sustains architecture