Roles and access
Access in Insurance Broker Core has two layers. Roles decide which DocTypes, reports, and pages a user may use. A Company user permission decides which ERPNext Company the user may work in. This page shows how to set up both for a new user and what the system does when one of them is missing. The complete role-to-DocType table is in the role matrix.
Who does this
A user who may edit users in ERPNext, normally your ERPNext system administrator. User, role, and User Permission administration are standard ERPNext functions, not part of this app; this guide does not document who may perform them. Roles named in the contract for setup work are Insurance Broker Administrator and Insurance Broker Setup Manager.
Before you start
- The app is installed. Installation creates the broker roles and does not rename or remove existing ones; see Installation.
- The ERPNext Company exists and has an Insurance Broker Company Settings record; see First steps and activation.
- You know the maker and checker for each approval-based task. Assign maker and checker roles to different people.
The broker roles
The role set is pinned by the contract file contracts/security/roles_baseline_v1.json (view it).
| Role | Purpose |
|---|---|
Insurance Broker Administrator | Setup, activation, and technical administration |
Insurance Broker Setup Manager | Setup and technical configuration; cannot activate Company Settings |
Insurance Broker Manager | Overall operational management of broker business records |
Insurance Broker Advisor | Advisory and recommendation workflows |
Insurance Broker Operations | Mandates, policies, and operational cases |
Insurance Broker Claims | Claim and complaint case handling |
Insurance Broker Sensitive Claims | Explicit access to sensitive or restricted claim records |
Insurance Broker Commission Reconciler | Commission reconciliation maker |
Insurance Broker Commission Approver | Independent commission approval checker |
Insurance Broker Accounting Draft Creator | Creates accounting draft records |
Insurance Broker Privacy Officer | Privacy rights, data subject requests, and legal holds |
Insurance Broker Compliance | Disclosure, privacy, and compliance evidence |
Insurance Broker Auditor | Read-only audit access, including ledger records |
Insurance Broker Import Operator | Import batch, import line, and quarantine processing |
Insurance Broker Read Only | Read-only viewer for all non-restricted records |
Insurance Broker Reconciler, Insurance Broker Approver, Insurance Broker Accounting Approver | Earlier generic role names, preserved and still used in permissions and approvals |
Regulatory Reviewer | Reviews and submits regulatory rule contracts |
The Insurance Broker Setup Manager can prepare and read configuration but cannot activate Company Settings. Only Insurance Broker Administrator can call the activation and readiness endpoints.
Roles used in the first working chapters
| Task | Create and edit | Read only |
|---|---|---|
| Insurance Broker Party Identity | Insurance Broker Administrator, Insurance Broker Operations | Insurance Broker Compliance, Insurance Broker Auditor, Insurance Broker Read Only |
| Insurance Broker Mandate | Insurance Broker Administrator, Insurance Broker Operations, Insurance Broker Manager (Compliance may edit but not create) | Insurance Broker Auditor, Insurance Broker Read Only |
| Insurance Broker Product Class | Insurance Broker Administrator | Insurance Broker Operations, Insurance Broker Auditor, Insurance Broker Read Only |
Steps
1. Create or open the user
Open the user in the standard ERPNext User form. The user needs a normal, enabled ERPNext account.
2. Add the roles
In the roles section of the User form, tick the broker roles the person needs. Grant the least privilege that fits the job: for example Insurance Broker Operations for someone who maintains parties and mandates, or Insurance Broker Read Only for a viewer. Save the user.
3. Add the Company user permission
Create a standard Frappe User Permission for the user that restricts the Company document type to the company the person works in. Add one permission per company. The app reads exactly these permissions to decide which companies a user may use.
Two users are exempt from this rule: the Administrator user and every user with the System Manager role are treated as trusted and are not limited to a list of companies.
4. Check the result
Ask the user to sign in and open the Insurance Broker Cockpit page (Getting started). The Company dropdown must list the permitted companies, and the Open claims card must show a number or Restricted according to the roles. Test lists, reports, exports, print, and file downloads with a real role, not only as Administrator.
What happens when something is missing
| Situation | Result |
|---|---|
| The user has no role that grants a DocType | the DocType is not usable for that user; the standard ERPNext permission error applies |
| The user holds none of the nine cockpit roles | the cockpit and the broker reports reject the request with "You do not have permission to run this insurance report." (the native reports behind the sidebar need Administrator, Operations, or Compliance) |
| The user has a role but no Company user permission | the cockpit company list stays empty; reports and command endpoints refuse the user with "You do not have access to this company." or the code IBC-ACL-COMPANY-001 |
| The user has a Company user permission for company A and opens a record of company B | the record is not listed and a direct read is refused; company-gated endpoints answer IBC-ACL-COMPANY-001 |
Important: a user with a role and no Company user permission receives no rows from company- or case-bound list views, and a direct read of such a record (form, REST) is refused. The company-gated surfaces (cockpit, reports, command endpoints) also fail closed. Administrators and System Managers keep their documented trusted access; ordinary ERPNext semantics apply only to doctypes that are not company- or case-bound. Always add the Company user permission for every user who is not an administrator. The security background is in Security and privacy.
Parties are scoped through the Insurance Broker Company Party Scope record: a company-restricted user sees a party identity only if a scope record links that party to one of the user's companies. See Parties.
What this page does not cover
- Break-glass access rules; the architecture decision treats such access as time-bound and justified.
- The commission maker-checker roles in detail; they belong to the commissions chapter.
- Assigning roles through role profiles or automation; the repository documents none.
- One site serves one security tenant. Separate, mutually unauthorised broker organisations need separate sites; multi-company use on one site is meant only for controlled related legal entities.