Understanding Frappe User Permissions: A Comprehensive Guide

In any business application, managing who can access what is critical for security, compliance, and operational efficiency. Frappe, the open-source framework behind ERPNext, offers a robust and flexible permission system that allows administrators to fine-tune access controls. Let's dive into the details of how Frappe's permission system works.

The Permission Hierarchy

Frappe's permission system is built on several interconnected components:

1. Users - Individual accounts that access the system
2. Roles - Collections of permissions assigned to users
3. Role Profiles - Bundles of roles for easier assignment
4. Permissions - Rules defining what actions can be performed on which documents
5. User Permissions - Data-level restrictions on what records a user can access

User Management

User Types

Frappe allows you to classify users into different types, each with its own set of default permissions:

• System User - Staff members who need full access to the backend system
• Website User - External users who only interact with the portal interface
• Administrator - Users with complete system access

Each user type has predefined role assignments that can be further customized.

User Setup

When creating a new user, you'll define:

• Basic profile information
• User type
• Role assignments
• Initial password
• Email settings
• Security settings (like login devices, session duration)

Role-Based Access Control

Roles

Roles are the cornerstone of Frappe's permission system. A role is a collection of permissions that define what actions a user can perform on specific DocTypes (database tables).

Standard roles in Frappe include:

• System Manager
• HR Manager
• HR User
• Accounts Manager
• Accounts User
• Sales Manager
• Purchase Manager
• Item Manager
• etc.

Role Profiles

Role profiles streamline user setup by bundling multiple roles together. For example, you might create:

• "Finance Executive" profile with Accounts User and Report Viewer roles
• "HR Manager" profile with HR Manager, Employee, and Leave Approver roles

This allows quick assignment of multiple roles to new users in one step.

Permission Settings

Role Permissions

Role permissions define what actions (Create, Read, Write, Delete, Submit, Cancel, Amend, Print, Email, Report, Import, Export, Share) a role can perform on a specific DocType.

To set up role permissions:

1. Go to Setup > Permissions > Role Permissions Manager
2. Select the DocType you want to configure
3. Add or modify permissions for different roles

These permissions apply system-wide to all documents of the selected DocType.

Permission Rules

For each role-doctype combination, you can set:

• Level - Determines permission hierarchy (0-9), with higher levels overriding lower ones
• Applicable For - Restricts permissions to specific document states (like "Not Submitted" or "Cancelled")
• If Owner - Permissions that apply only to documents created by the user
• Apply User Permissions - Whether user permissions filter should apply

Field-Level Permissions

Frappe also supports field-level permissions, allowing you to hide specific fields from certain roles.

To set field permissions:

1. Go to Customize Form
2. Select the DocType
3. Find the field in question
4. Set the "Perm Level" (0-9)
5. Ensure the role has read/write permission for that level

For example, you might set salary fields to perm level 2, and only give the HR Manager role permission at level 2.

User Permissions

While role permissions define what actions users can perform, user permissions restrict which specific records they can access.

Setting Up User Permissions

1. Navigate to User Permissions page
2. Click "Add User Permission"
3. Select: User to apply the permission to Document Type to restrict Specific document/value to allow Whether this should apply to all applicable DocTypes

For example, if you set user permission for a specific Department, the user will only see records linked to that department across all DocTypes with Department fields.

User Permission Configuration

You can further configure how user permissions work via:

• User Permission DocType - Define which DocTypes can be used in user permissions
• User Permission for DocType - Configure how permissions apply across related DocTypes
• Ignore User Permissions For - Exempt specific DocTypes from user permission filtering

Advanced Permission Features

Document Share

The Share feature allows temporary permission grants on specific documents without changing the underlying permission system.

Permitted Documents for User

This report (available under Setup > Permissions) shows which documents a specific user can access, helping administrators troubleshoot permission issues.

Role Permission for Page and Report

Beyond DocTypes, Frappe also manages permissions for:

• Pages - UI sections like dashboards or setup pages
• Reports - Both standard and custom reports

You can configure these from the "Role Permission for Page and Report" page.

Permission System Best Practices

1. Layer permissions properly
2. Use role profiles for consistency
3. Regularly audit permissions
4. Implement the principle of least privilege

Troubleshooting Permission Issues

When users can't access documents they should:

1. Check their role assignments
2. Verify role permissions for the DocType
3. Look for restrictive user permissions
4. Examine if field-level permissions are blocking access
5. Verify document states (e.g., if permissions only apply to submitted documents)

Conclusion

Frappe's permission system provides granular control over who can access what in your organization. By properly configuring users, roles, and permissions, you can create a secure environment where users have exactly the access they need—no more, no less.

Mastering this system takes time, but the investment pays off in improved security, better compliance, and more efficient workflows as your organization grows.