How EspoCRM customer portal roles and access protect customer data
A portal lets customers sign in and see their own cases and documents without seeing the rest of your CRM. In EspoCRM, that separation depends on portal users and portal roles, which are configured separately from the roles your internal staff use. A portal user is an external account that signs in to a portal rather than to the main CRM interface. Because portal roles are their own permission set, you can grant a customer access to a narrow slice of records, such as cases linked to their account, without giving them any of the internal permissions your sales and service staff hold. Treat the portal role as the primary control for customer data and test it before any customer receives a login.
A portal is worth the effort when customers need ongoing, self-service access to records that belong to them, such as tracking open tickets, reviewing shared documents or checking order status. If customers only need an occasional reply or a one-time file, email or a helpdesk link may be simpler, and it avoids issuing accounts at all. Each portal user is an identity you must onboard, support and eventually deprovision, so the decision should weigh that recurring work against the value of self-service. Also decide early whether one portal serves every customer group or whether separate portals suit different audiences, because that choice shapes the roles you need.
Before you rely on any portal role setting, confirm the exact behavior for your EspoCRM version in the current docs, including how account and contact level access is evaluated, which tabs a portal user can see and how case and knowledge base visibility is handled. Then run a practical check: sign in as a test portal user linked to a sample account, confirm that records from other accounts are invisible, and confirm that internal-only fields and tabs do not appear. The EspoCRM security documentation is a useful starting point for the broader hardening settings that sit alongside portal access.
Portal access options and when each fits
This table compares the five controls that decide what a portal user can see in EspoCRM: portal role permissions, account and contact scope, tab lists, case visibility and knowledge base visibility. Read each row as a question to answer for your audience, then confirm the exact behavior in the EspoCRM documentation or a test portal before you lock the design. The main takeaway is that no single setting protects data on its own, so the controls should be tested together with a user who holds the portal role.
| Control | What it governs | Typical fit and what to confirm |
|---|---|---|
| Portal role permissions | Which entities a portal user can read, create, edit or delete, and at what scope | Fits any portal where the audience needs a fixed set of actions. Confirm how each entity scope applies to portal users in the docs and test every entity separately. |
| Account and contact scope | Which account and contact records a portal user sees, based on the link between their contact and the account | Fits business-to-business portals where several contacts share one account. Confirm which records are visible when a contact has no linked account and how shared accounts behave. |
| Tab lists | Which tabs appear in the portal navigation for a given portal | Fits simplifying the portal so customers see only support or order areas. Confirm that a hidden tab does not still expose records through direct URLs or related panels. |
| Case visibility | Which cases a portal user can view, comment on or create, and how cases link to accounts and contacts | Fits customer support portals where each customer should see only their own tickets. Confirm the ownership or account rule that filters cases in a test portal with two customer accounts. |
| Knowledge base visibility | Which knowledge base articles appear to portal users, usually by publication status or portal assignment | Fits self-service portals that publish help content to customers. Confirm how draft, internal and portal-specific articles are filtered and whether attachments follow the article rules. |
| Separate portals per audience | Distinct portal URLs, roles and tab lists for partners, customers or other groups | Fits cases where two audiences need different data sets and branding. Confirm that a user in one portal cannot reach the other portal's roles or data through the same login. |
How account and contact scope decide which records a customer sees
In EspoCRM, a portal user is tied to a contact record, and that contact belongs to an account. The contact is the person who logs in, and the account is the company they work for. Because portal visibility follows these links, the account and contact structure is the first thing to design for a multi-customer business. If your records do not reflect who belongs to which customer, no role setting will show the right cases and knowledge base articles to the right people. Before you touch portal roles, write down your customer hierarchy: which companies you serve, which contacts sit under each one, which contacts may be partners or agents of more than one company, and who must never see another customer's data.
Scope in this model is a choice between two postures. Account-wide visibility lets portal users see records linked to their account, which suits customers where several contacts share cases, tickets and documents. It is simpler to run because a new contact at an existing customer gets the same view without manual work. Contact-only visibility is stricter: each user sees only the records linked to their own contact. It fits customers where departments or individuals must stay separated, or where a contact handles confidential matters, but it requires more setup for each record, and shared cases must be assigned or linked by hand. Many businesses choose account-wide scope for most customers and contact-only for a small group of sensitive accounts, but that mix should be decided, not inherited from defaults.
Test the design before any customer logs in. Create sample users in a non-production instance: one contact per account, two contacts at the same account, a contact linked to two accounts, and a contact with no account. For each user, log in through the portal and check which cases, knowledge base articles and related records appear, and confirm that a record from another account never shows. Repeat the test after any change to the account hierarchy or the portal role. Illustrative example: a partner contact who manages two customers should be checked for leakage between both accounts. Confirm with your own team how your contact data is maintained, because records created by imports or integrations can link contacts to the wrong account.
One portal or separate portals per audience
End customers are usually the audience with the widest exposure, so their portal should show only their own accounts, contacts, cases and published knowledge articles. A separate customer portal makes it easier to keep the tab list short, publish customer-facing help content and apply customer branding without affecting staff views. The cost is a second set of portal roles, layouts and test cases that must be maintained whenever the data model changes.
- Tab list: Limit tabs to cases, knowledge base and the customer's own records, so no internal modules appear in the navigation.
- Knowledge base: Publish a customer-only article set that is separate from internal runbooks and draft content.
- Branding and domain: Use a dedicated portal domain and theme for customers, which requires DNS and TLS work described in the deployment group.
- Configuration cost: Each portal needs its own portal role, layouts and access tests, which adds effort at build and at every upgrade.
- Testing cost: Verify with real customer test accounts that they cannot reach other accounts' cases.
Before build, confirm which customer records and attachments must be visible and whether the customer audience justifies its own domain.
Channel partners and suppliers need access to deal registrations, shared orders or service tickets, but their visibility usually differs from end customers and from internal staff. A separate partner portal lets you show partner-specific tabs, a partner knowledge base such as product certification or pricing guides, and partner branding. The trade-off is that partner records often overlap with customer records, so the access model must be tested carefully to prevent partners from seeing each other's accounts.
- Tab list: Expose only the modules partners use, such as opportunities they registered and the support cases they raised.
- Knowledge base: Keep partner-only guides, price-list references and certification material apart from customer articles.
- Record overlap: Partners and customers may share accounts, so confirm how account-level access applies when one account is linked to several audiences.
- Configuration cost: Partner portal roles must be designed against the account and contact hierarchy, which often takes more analysis than the customer portal.
- Testing cost: Test with at least two partner accounts to confirm that one partner cannot see another partner's deals.
If partners and customers share accounts, decide the separation rule before building, because it is difficult to correct after data has been migrated.
Some internal teams, such as finance, field technicians or contractors working in the company, need a narrower view than full staff users. A separate internal portal can give them a short tab list and only the records their function needs, without changing the main CRM roles used by sales and service. This is often the lowest-risk split because the users are known, but it still adds a separate portal to configure, maintain and test.
- Tab list: Give each internal group only the modules needed for its task, which keeps the navigation focused.
- Shared content: Decide whether internal knowledge articles belong in this portal or remain in the main CRM.
- Identity: Confirm how these users sign in, since portal users and internal users may follow different login policies. Check the identity guidance in the security group before deciding.
- Configuration cost: A separate portal duplicates some role and layout work that could be handled by team-based roles in the main CRM.
- Testing cost: Verify that the limited view does not expose fields or records through related lists or search.
Ask whether a team-based role in the main CRM would meet the need before creating a separate portal for internal users.
Each portal that needs its own address requires a domain or subdomain, DNS records, TLS certificates and a reverse proxy configuration. Portal domain setup is covered in the EspoCRM deployment and hosting group, so this tab focuses on the design decision. Every additional portal adds a hostname to certify, monitor and keep consistent with the proxy and any IP restrictions.
- Hostname planning: Choose one domain per audience or a shared domain with different paths, and record the decision before build.
- Certificates: Each hostname needs a valid certificate and a renewal process, which recurs over the life of the system.
- Proxy and network rules: Confirm how portal traffic reaches the instance and how IP restrictions apply to portal users.
- Operations: More portals mean more hostnames to check after upgrades and infrastructure changes.
- Decision timing: The number of portals affects roles, layouts and domains, so changing it after build is costly.
Ask your infrastructure team which hostnames they can provision and maintain before committing to a portal count.
How to set up portal roles in a sequence you can test
This sequence takes a portal from audience definitions to verified access, so each portal user sees only the accounts, contacts, cases and articles meant for them. Each step closes with a check that the team can repeat after every change.
Define audiences and the data each one needs
The sales or service lead, with the portal owner, lists each audience that will log in, such as customers of one product line, partners, or contractors, and writes down the records each one must see and the records it must never see. The output is a short matrix of audience, data needed, and data excluded, reviewed by the business owner before any configuration starts. Check: every audience has at least one required record type and one explicit exclusion, and the matrix is signed off. If the audiences overlap, decide now whether they share a portal or get separate portals, since that choice shapes every later step.
Map customers to accounts and contacts
The data owner confirms how each person who logs in is linked to an account and a contact record, and how contacts that serve several accounts are handled. Portal visibility in EspoCRM depends on these links, so a contact with no account or the wrong account will show too little or too much. Export a sample of contacts with their account links and review them against the matrix. Check: every planned portal user maps to exactly one contact, and every contact that should see shared records is linked to the correct account. Keep this mapping as a reviewed sheet so later test users can be built from it.
Create portal roles starting from the narrowest permissions
The administrator creates one portal role per audience in the Portal Roles area, starting with no access and adding only the scopes the matrix requires. Record and field-level access is set per entity, and the default should stay restrictive so that each later grant is deliberate and traceable. Confirm the current permission levels, portal role options, and how they apply to Account, Contact, Case and Knowledge Base in the EspoCRM security and portal documentation before you save. Check: each role's permission sheet matches the matrix line by line, and no role grants access to entities that its audience does not need.
Assign portal roles and set the tab list and layouts
The administrator attaches each role to its portal and sets the tab list so that a portal user sees only the menu items for their audience. Layouts are then reduced to the fields that audience should read, hiding internal notes, margins, and internal assignment fields. Confirm in the current docs how portal tab lists and layout scoping are configured for each portal. Check: a screenshot or export of each portal's navigation and detail layouts is compared with the matrix, and any field or tab not on the matrix is removed before testing.
Configure case and knowledge base visibility
The service owner sets how cases are shared with portal users, for example by linking cases to the account or contact that raised them, and decides which knowledge base articles are published to which audience. Articles that are internal or intended for a single audience should be scoped so they do not appear in the wrong portal. Confirm the case and knowledge base visibility options available in your EspoCRM version, since these settings differ by release. Check: a case created for one account is visible only to that account's users, and an article marked for one audience does not appear for another.
Create one test portal user per role
The administrator creates a dedicated test user for each portal role, linked to a test contact and account that exist only for testing. Test users should not be real customers, and their passwords and any two-factor settings should follow the organization's login policy. Keep a register of test users, their role, and the records they are meant to see. Check: each test user can sign in to the correct portal and the register matches the role assignments exactly, with no shared test accounts.
Verify each test user against the access checklist
The tester signs in as each test user and works through a written checklist: records on the matrix are visible, excluded records are not visible through the list view, search, direct URL, or related panels, and tabs and fields match the layout. Any unexpected visibility is logged, traced to the role, link, or layout that caused it, fixed, and retested. The output is a signed test record with the date, EspoCRM version, and results per user. Check: every checklist item passes for every test user, and any failed item has a recorded fix and a passing retest before the portal goes live.
Security considerations for customer-facing access
A portal exposes part of your CRM to people outside your organization, so the same records can be reached through a different door. The cards below cover the controls that keep portal users inside their own data, starting from the EspoCRM security documentation and ending with how you will know it is working.
Confirm portal users cannot reach internal entities
Portal roles hide tabs and menus, but hidden navigation is not access control. Test whether a portal user can open internal-only entities by typing a URL, or call the REST API directly with the portal user's credentials. Confirm that every entity without a portal grant returns a denial, not an empty list that still reveals record counts. Repeat the check after each layout or role change, because a new entity added later may inherit broader permissions than you intended.
Apply the password and session policy to portals
Portal logins are separate from staff logins in how you configure them, so confirm the password strength rules, recovery link lifetimes and auth token idle time and lifetime apply to customer accounts as well. Customers often reuse weak passwords and sign in from shared devices, which makes short session lifetimes more important here than for staff. Ask your admin to confirm these settings in the administration panel and to test a login on a fresh session.
Decide where customers need stronger sign-in
Not every portal needs two-factor authentication, but portals that show invoices, contracts or support cases for regulated or high-value accounts usually do. Where you already run an identity provider, confirm how it handles MFA, because EspoCRM's own 2FA is not compatible with OIDC. Document the decision per portal so an auditor can see why a given audience got a given sign-in method.
Keep admin accounts out of portal testing
Testing a portal while logged in as an administrator shows what the admin can see, not what a customer can see. Create a dedicated test portal user with a role matching the audience, and log in as that user for every check. Confirm that admin recovery and other admin-only settings are not reachable from the test account, and remove test users once the review is complete.
Separate test data from production
Portal testing needs records that look real, but copying production contacts and accounts into a test instance exposes customer data to the people who build and test the portal. Use synthetic records in a separate instance, and confirm that test portal users, email settings and integrations cannot send messages or sync with live customers. Ask your admin to confirm which environment holds the portal domain and whether test domains are isolated from production.
Log and review portal access
Confirm where EspoCRM records portal logins and failed attempts on your server, and who receives those logs. Review portal activity on a set schedule, looking for unusual login times, repeated failures and users viewing records outside their account. Agree in advance who acts on a finding, and how a suspected exposure is escalated to the data owner.
Questions buyers ask before setting up EspoCRM portal access
How much effort does one EspoCRM portal take compared with several portals?
A single portal is mostly a matter of defining one portal role, the tabs and fields it can see, and how its users link to accounts and contacts. Each additional portal adds its own role set, its own visibility rules, its own tab list and its own testing pass, so effort grows with the number of audiences rather than with the number of users. Ask any partner to price the work per portal and to name which portals share a role, a domain or a knowledge base. Separate portals on separate domains also add reverse proxy and TLS work, which should appear as a line item in the written scope.
What drives the portal work up in an EspoCRM project?
The main drivers are the number of customer hierarchies (for example, parent accounts with subsidiaries and contacts beneath them), the number of distinct audiences, the amount of case workflow and the size of the knowledge base content that must be filtered by audience. Each hierarchy needs a visibility rule that is tested, and each audience needs its own tab list and layout. Cases that route through assignment, approvals or email-to-case add more configuration and more test paths. Ask the partner to list these counts in the scope so that the estimate rests on numbers both sides have agreed.
Can an in-house admin set up EspoCRM portal access without outside help?
Yes, a capable in-house administrator can configure portal roles, tab lists and basic account-level visibility, since these are set in the EspoCRM admin interface. The harder part is deciding what each audience may see and proving that a portal user cannot reach records outside that scope. That requires a clear access design, a test plan with test portal users, and someone who reviews role settings against the design before go-live. Teams often succeed by writing the access matrix first, then configuring, then having a second person test each portal user type. Confirm that your admin has time for the testing pass, not only the configuration.
What does the customer team need to provide for portal access work?
The work needs three inputs from your side. First, sample data: representative accounts, contacts and cases, ideally from a non-production copy, so that visibility rules can be tested on realistic shapes of data. Second, a customer hierarchy map that shows which contacts belong to which accounts, including shared contacts, partners and subsidiaries. Third, a written sign-off on which fields, related records, cases and knowledge base articles each audience may see. Ask the partner to confirm in writing who signs off, how changes after sign-off are handled and how long reviews may take on your side.
How is EspoCRM portal access tested before go-live?
Testing should run against test portal users for every role, using accounts and contacts that cover the edge cases in the hierarchy map. Each test confirms what the user can list, open, edit and search, and it checks that records outside the scope do not appear in lists, related panels, search results or case views. Knowledge base articles should be checked for each audience, and portal login should be tested with the password and session policy and any IP restrictions that apply to portal users. Ask for the test cases in writing, the pass criteria, and a record of the results before launch.
What recurs after an EspoCRM portal goes live?
Access needs ongoing attention because customer structures change. New accounts, new contacts, mergers, and new product lines all affect who should see what. Recurring work includes reviewing portal user lists, removing access for contacts who leave a customer, checking that new fields added to layouts are not exposed by accident, and rerunning the test pass after an EspoCRM upgrade or extension change. Ask whether the scope covers these reviews as a one-time handover or as a retainer, and who owns the access matrix after handover.
What should a written scope for EspoCRM portal access include?
A written scope should name each portal and its audience, the portal roles and tab lists it uses, the account and contact visibility rules, the case and knowledge base areas it can reach, and the test cases and sign-off steps. It should state which records and fields are out of scope, how the portal domain and login methods are handled, and what the customer team must supply and when. Deliverables should include the access matrix, the configured roles, the test results and a handover note for your administrators. Ask for these items in the quote so that you can compare proposals on the same basis.
Limits to confirm in your EspoCRM version and environment
Portal access in EspoCRM depends on the exact version, the sign-in method, the domain layout, and any extensions you add. The cards below list the points to confirm with your own environment before you commit to a portal design, since each one can change which data a portal user actually sees.
Portal options by version
Confirm that the portal settings, role fields and tab list options you plan to use exist and behave the same way in the EspoCRM version you run. The documentation changes across major versions, and 10.0 is a current major release, so a configuration copied from older guidance may not match. Ask whether any portal setting changed between your current version and the target, and test each role in a staging copy before production. Read the portal behavior notes for your exact version before you design roles.
External sign-in for portal users
Determine whether portal users will sign in with local EspoCRM accounts or through OpenID Connect or another external provider. EspoCRM's own two-factor authentication is not compatible with OIDC, so portal users would rely on the identity provider's controls instead. Confirm how user creation on first login, group-to-team mapping and the fallback login method behave for portal accounts, since a mapping error can place an external customer in the wrong access scope.
Portal domain and TLS setup
Check that your portal domain, certificate and reverse proxy configuration match the EspoCRM deployment guide for your web server. Portal traffic often uses a separate hostname from the internal CRM, so routing, cookie scope and certificate names must be planned together. Ask who owns DNS and certificate renewal for the portal hostname, and whether the proxy forwards the client address correctly, because IP-based rules for API users and other exceptions depend on it.
Extensions for cases and workflows
Confirm which parts of the case handling and workflow design require the Advanced Pack or other official extensions in your plan. The Advanced Pack provides workflows and Business Process Management and is included in all EspoCRM Cloud plans, but self-hosted deployments need their own decision about installing it. Ask whether a portal customer submitting a case will trigger automation that depends on an extension, and whether that extension is licensed and supported for your version.
Large customer hierarchies
Test how portal list views perform when a single customer account has many contacts, cases or knowledge base articles. Access rules that filter by account can be expensive when the hierarchy is deep or the record count is high. Ask for a load test with realistic record volumes, and confirm which indexes and background jobs your database and cron setup need. Slow lists often appear only after data migration, so include imported records in the test.
Custom entities in portal visibility
Verify how each custom entity you add appears to portal users, since portal visibility is not automatic for entities created after the initial design. Check whether a custom entity can be exposed in the portal tab list, whether its fields follow the same access checks as standard records, and whether a portal user can see linked records through a relationship they should not reach. Document the expected result for each entity and test it with a sample portal account before go-live.
How DeployOpen scopes and delivers EspoCRM portal access
DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside your own infrastructure. For EspoCRM portal access, we start from a written list of which audiences need which records, then build and verify each portal role against that list before anything reaches customers.
How we scope
- We map each portal audience to the accounts, contacts, cases and knowledge base articles it may see.
- We confirm which portal tabs, layouts and fields each audience needs, and which must stay hidden.
- We record whether one portal or several separate portals fit your customers, and why.
- Engagements are fixed-scope, so the written scope states the portal roles, test cases and deliverables covered.
How we build
- We create portal roles with explicit account and contact level permissions, starting from the least access each audience needs.
- We configure tab lists and layouts so portal users see only the fields and sections their role allows.
- We set up cases and knowledge base visibility rules and test them with sample portal accounts for each audience.
- We check the portal domain and login settings with your team, confirming them in your own environment before go-live.
How we hand over
- You receive a role matrix showing each portal role, the records it can read and the actions it can take.
- We document how to add a portal user, assign an account and review access as your customer structure changes.
- We walk your administrators through the test results and the remaining decisions that still belong to your business owners.
- Handover includes the configuration steps your team needs to repeat for new portals or audiences.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Retainer work can re-run portal access tests after EspoCRM upgrades or changes to customer structure.
- We can review portal role changes requested by your team and confirm their effect before release.
- Confirm with your team which person approves portal access changes and how requests are logged.
