User Permissions
User Permissions in ERPNext give an option to limit user access to a particular document, so that users view and work with only the data specific to their responsibility or role without viewing and accessing irrelevant data.
Whereas role-based permissions provide extensive access to entire DocTypes (e.g., Sales Invoice, Sales Order, Quotation), user permissions provide more detailed control by restricting access to specific records within those DocTypes. This facilitates data confidentiality and operational control in multi-company, multi-branch, or multi-region environments.
For instance, if your company deals in more than one territory, you can limit specific Sales Users to view and create only Quotations or Sales Orders that fall within their respective territory. In the same way, Customer, Supplier, Customer Group, Supplier Group, Company, or other related documents' access can be restricted.
User Permissions can be used when restricting access of:
- Allowing a user to view the data only in one of the Companies or a few Companies.
- Accessing information on particular Customers, Suppliers or Groups through granting a user permission.
- Restricting the users to transact some Territories, Branches or Projects.
- Access separation of staff work in different business sections or units.
To view User Permissions, navigate:
1. Creating User Permissions
- Navigate to the User Permissions list and click on New.
- Choose the User on whose behalf you want to apply the rule.
- Choose the Document Type (e.g., "Company", "Customer", "Territory") on which you want to apply access restriction.
- In For Value, choose the particular item (e.g., "Unico Plastics Inc." as Company or "North America" as Territory) on which the user can be granted access.
- If you mark 'Is Default', the value you choose in For Value will be applied as default automatically for any new transactions created by this user. For instance, if Company "Unico Plastics Inc." is defined as default, it will be auto-filled in all new transactions created by the user.
- Save the User Permission.
Additional Notes:
- A single default user permission can only be assigned to a specific Document Type for a given user.
- You may have different permissions for the same user for different Document Types (e.g., Company, Territory, and Customer).
- Hierarchical restrictions are also possible under the User Permissions. As an example, when a Territory contains sub-territories, access is limited to either parent or child records depending on configuration.
- Such permissions may be used alongside role-based permissions to generate broad access control (such as roles) and fine-grained record-level limits (user permissions).
2. Additional User Permission Actions
ERPNext provides more sophisticated choices of how User Permissions are utilized thus administrators have greater flexibility and precision controlling the user access. These extra controls will not only limit permission by record level but to such things as organizational hierarchies as document types, and organizational structure, and any internal relationships.
2.1 Advanced Control
The Advanced Control options enable administrators to define where and how a User Permission is to be enforced. Rather than applying in a broad fashion across all relevant DocTypes, permissions can be applied to a particular instance, resulting in a tighter, more secure environment.
2.1.1 Applicable For
The Applicable For field allows you to define the precise DocType upon which the User Permission is to be applied. By default, user permissions are effective on all DocTypes that are associated with the chosen record, but you can limit them to a specific context.
- To do this, disable the Apply To All Document Types checkbox and choose the Document Type under the Applicable For field.
- It ensures that the permission is applied only to the chosen DocType and does not apply by default to all the related DocTypes.
Example: When you allow a user to view the tables where Company = Unico Plastics Inc, and you allow the user to view Sales Order where you specify Applicable For = Sales Order then the user will be able to view only Sales Order of Unico Plastics Inc. They will fail to get access to related Invoices, Quotations, or other documents related to the same company automatically.
Note: When Applicable For is unused the User Permission will apply to all the DocTypes in which that field is referenced.
2.1.2 Hide Descendants
While applying permissions to DocTypes utilizing a Tree Structure (such as Company, Customer Group, Territory, Item Group), ERPNext automatically applies the permission to child records (descendants) of the chosen value.
- The Hide Descendants choice provides administrators with control over not allowing this automatic extension.
- When this feature is turned on, the user will gain access only to the very record that was chosen in For Value, and not its child or descendant records.
Example:
- Provided that you pressed For Value = Frappe Partner. which has a child-firm called Frappe Toys.
- The user will automatically log in to two companies namely; Frappe Partner and Frappe Toys because the system assumes hierarchical access.
- When you have Hide Descendants switched on, the user will only be able to see Frappe Partner and cannot see Frappe Toys or make transactions with it.
This feature is especially useful when:
- A user needs to view data only for a particular branch, region, or subgroup, not having access to the full hierarchy.
- Companies wish to have a more rigorous separation of data visibility between divisions or sub-companies.
2.2 Overriding User Permissions for Specific Fields
It has been seen that there are cases where the organization required creating unlimited access to a particular field in a document where the user permission is at a point of classification. This can be done through a pre-setting override called Ignore User Permissions, on a field level with the functionality of Customize Form.
- If this option is selected for a field, the limitations set under User Permissions will not be imposed on the field.
- This ensures that users can at all times access or modify the value of that field regardless of roles- or user-based restrictions.
Example: You may not want Assets to be subject to company-based permissions; in that case, you can enter the Asset DocType on Customize Form and look at the Company field and tick the Ignore User Permissions checkbox. After doing that, all users will be able to see the company under Asset even though they have limited access under user permissions.
This feature is helpful for:
- Fields that will not be obscured either in operation or reporting.
- And any scenario in which the imposition of restrictions would impede or otherwise obstruct transparency or usability at a system-level.
2.3 Strict Permissions
ERPNext allows flexibility in how the user permissions should act if no particular restrictions are defined for a user. This is managed through the Apply Strict Permissions switch in System Settings.
When strict permissions are enabled, they guarantee that:
- If there are no explicit permissions set for a user, the system assumes no access permitted.
- This avoids unintended overexposure of documents and has a deny-by-default policy in place.
Disabled is the reverse of the above:
- If there are no explicit user permissions set, the system assumes full access permitted.
- This is in cases whereby organizations have open visibility as a default setting and only restrict certain instances.
Scenarios:
- Strict Permissions ON: Any user whose access is not defined on any Company will not see any records linked to companies.
- Strict Permissions OFF: A user with no permissions defined for companies will view all company-related records.
By default, administrators can select the interpretation that most closely follows their data security policies and compliance needs.
2.4 Verifying How User Permissions are Enforced
After establishing user permissions, one should check if they are functioning as expected. ERPNext offers an inbuilt facility known as the Permitted Documents for User report.
- The report enables administrators to choose a User and a DocType and see the precise records accessible to the user.
- It assists with checking if the User Permissions applied are limiting or providing access appropriately.
- By activating the Show Permissions feature, administrators will also be able to see the very specific levels of access like Read, Write, Create, Submit, Cancel, and Amend.
Example: As an example, suppose Bruce has a restriction of Company = Frappe Partner then the report will only display documents (Sales Orders, Invoices, etc.) that name Frappe Partner as a company. Bruce will end up failing to access documents of other companies.
This facility is particularly useful for:
- Checking of the newly implemented rules of permission.
- Debugging situations when users report lack of access or visibility they are not supposed to have.
- Being able to monitor employee compliance with security policies and segregation of duties of the company.
Note: In case a user fails to view a given DocType (say Sales Order) in this report, it is prudent to first ensure the user is appointed the right roles, in addition to the assigned user permissions.